lume-js 2.2.1 → 2.3.1

package/llms.txt

@@ -0,0 +1,89 @@
+# Lume.js
+
+> Minimal reactive state management using only standard JavaScript and HTML —
+> no custom syntax, no build step, no framework lock-in. 1.46 KB universal
+> core (state/batch), 2.66 KB with DOM binding (bindDom/effect). Reactivity
+> that follows web standards: stores are Proxies over plain objects, DOM
+> binding is declarative via valid data-* attributes, updates are
+> microtask-batched per store with an explicit batch() escape hatch for
+> cross-store writes.
+
+Version: 2.3.1. Install: `npm install lume-js` or import from
+`https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs`.
+
+Key facts agents get wrong without reading the docs: arrays and nested
+objects must be REPLACED, never mutated in place (reference equality);
+nested objects need explicit state() wrapping; updates flush on the next
+microtask, not synchronously; effects only track keys read synchronously;
+data-* attribute values are state keys, never expressions.
+
+## Start here
+
+- [AGENT_GUIDE.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/AGENT_GUIDE.md): Distilled rules, pitfalls, and patterns for coding agents
+- [README.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/README.md): Pitch, installation, quick start, API overview
+
+## Guides
+
+- [docs/guides/installation.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/installation.md): CDN, npm, and import options
+- [docs/guides/quick-start.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/quick-start.md): First app in five minutes
+- [docs/guides/core-concepts.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/core-concepts.md): Stores, effects, bindings
+- [docs/guides/reactivity.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/reactivity.md): How the Proxy, tracking, and microtask flush work
+- [docs/guides/choosing-reactive-primitives.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/choosing-reactive-primitives.md): effect vs computed vs watch
+- [docs/guides/two-way-binding.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/two-way-binding.md): Inputs and data-bind
+- [docs/guides/lists.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/lists.md): Rendering arrays
+- [docs/guides/forms.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/forms.md): Form patterns
+- [docs/guides/handlers.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/handlers.md): Extending bindDom with new data-* attributes
+- [docs/guides/cleanup-and-dispose.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/cleanup-and-dispose.md): Tearing down effects and bindings
+- [docs/guides/performance.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/performance.md): Batching and update costs
+- [docs/guides/animations.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/animations.md): Animating on state change
+- [docs/guides/routing.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/routing.md): Client-side routing patterns
+- [docs/guides/ssr-hydration.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/ssr-hydration.md): Server-rendered HTML with reactive hydration
+- [docs/guides/universal-core.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/universal-core.md): Using lume-js/state without a DOM
+- [docs/guides/testing.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/testing.md): Testing stores and bindings
+- [docs/guides/migration.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/migration.md): Migrating between versions
+- [docs/guides/faq.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/guides/faq.md): Frequently asked questions
+
+## Tutorials
+
+- [docs/tutorials/build-todo-app.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/tutorials/build-todo-app.md): Todo app walkthrough
+- [docs/tutorials/working-with-arrays.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/tutorials/working-with-arrays.md): Immutable array updates — the golden rule
+- [docs/tutorials/build-tic-tac-toe.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/tutorials/build-tic-tac-toe.md): Game with history and computed winner
+
+## API reference — core
+
+- [docs/api/core/state.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/core/state.md): state() reactive stores
+- [docs/api/core/effect.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/core/effect.md): effect() auto-tracking and explicit deps
+- [docs/api/core/bindDom.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/core/bindDom.md): bindDom() DOM binding
+- [docs/api/core/batch.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/core/batch.md): batch() cross-store write grouping
+- [docs/api/core/handlers.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/core/handlers.md): Handler system — the { attr, apply } extension contract
+
+## API reference — handlers
+
+- [docs/api/handlers/show.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/show.md): Conditional visibility
+- [docs/api/handlers/className.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/className.md): Full class attribute from state
+- [docs/api/handlers/boolAttr.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/boolAttr.md): Boolean attributes (disabled, hidden, …)
+- [docs/api/handlers/ariaAttr.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/ariaAttr.md): ARIA attributes from state
+- [docs/api/handlers/classToggle.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/classToggle.md): Toggle a single class
+- [docs/api/handlers/stringAttr.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/stringAttr.md): String attributes (href, src, title, …)
+- [docs/api/handlers/on.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/on.md): Declarative event wiring via data-on*
+- [docs/api/handlers/htmlAttrs.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/handlers/htmlAttrs.md): Preset bundle of common attributes
+
+## API reference — addons
+
+- [docs/api/addons/computed.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/computed.md): Derived read-only values
+- [docs/api/addons/watch.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/watch.md): Single-key observation
+- [docs/api/addons/repeat.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/repeat.md): Keyed list rendering
+- [docs/api/addons/persist.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/persist.md): localStorage/sessionStorage sync
+- [docs/api/addons/hydrateState.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/hydrateState.md): SSR hydration
+- [docs/api/addons/createCleanupGroup.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/createCleanupGroup.md): Grouped disposal
+- [docs/api/addons/debug.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/debug.md): Write/flush logging
+- [docs/api/addons/withPlugins.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/withPlugins.md): State extension system
+- [docs/api/addons/isReactive.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/api/addons/isReactive.md): Reactive brand detection
+
+## Design
+
+- [docs/design/design-decisions.md](https://raw.githubusercontent.com/sathvikc/lume-js/main/docs/design/design-decisions.md): Ratified decisions and their reasoning
+
+## Optional
+
+- [llms-full.txt](https://raw.githubusercontent.com/sathvikc/lume-js/main/llms-full.txt): every file above concatenated into one document

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lume-js",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -14,6 +14,10 @@
       "import": "./dist/index.mjs",
       "types": "./src/index.d.ts"
     },
+    "./state": {
+      "import": "./dist/state.mjs",
+      "types": "./src/state.d.ts"
+    },
     "./addons": {
       "import": "./dist/addons.mjs",
       "types": "./src/addons/index.d.ts"
@@ -39,13 +43,18 @@
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run build && node scripts/check-size.js && node scripts/complexity.js && npm run lint && npm run typecheck && npm run coverage",
+    "llms": "node scripts/build-llms.js",
+    "llms:check": "node scripts/build-llms.js --check",
+    "validate": "npm run build && node scripts/check-size.js && node scripts/complexity.js && npm run lint && npm run typecheck && npm run coverage && node scripts/build-llms.js --check",
     "prepublishOnly": "npm run validate"
   },
   "files": [
     "dist",
     "src",
     "README.md",
+    "AGENT_GUIDE.md",
+    "llms.txt",
+    "llms-full.txt",
     "LICENSE"
   ],
   "keywords": [

package/src/addons/index.d.ts

@@ -153,9 +153,11 @@ export interface RepeatOptions<T> {
 
   /**
    * Function called ONCE when element is created (for DOM structure setup)
-   * Recommended for event listeners and innerHTML setup
+   * Recommended for event listeners and innerHTML setup.
+   * May return a cleanup function — it is called automatically when the
+   * element is removed (by list update or full cleanup).
    */
-  create?: (item: T, element: HTMLElement, index: number) => void;
+  create?: (item: T, element: HTMLElement, index: number) => void | (() => void);
 
   /**
    * Function called on every update for data binding
@@ -163,7 +165,32 @@ export interface RepeatOptions<T> {
    */
   update?: (item: T, element: HTMLElement, index: number, context: UpdateContext) => void;
 
-  /** Element tag name or factory function (default: 'div') */
+  /**
+   * Additional cleanup when an element is removed. Called after any cleanup
+   * function returned by create(). Prefer returning a cleanup from create()
+   * for automatic lifecycle management.
+   */
+  remove?: (item: T, element: HTMLElement) => void;
+
+  /**
+   * Declarative item structure from a standard <template> element.
+   * - true: use the first <template> inside the container
+   * - string: CSS selector resolving to a <template>
+   * - HTMLTemplateElement: use directly
+   *
+   * The template must contain exactly one root element. It is cloned per
+   * item, and its [data-bind] paths are bound against the ITEM on every
+   * update: "name" → item.name, "user.city" → item.user.city,
+   * "$item" → the item itself, "$index" → current index.
+   * Inputs receive .value/.checked; other elements receive textContent
+   * (same semantics as bindDom's data-bind). One-way snapshot bindings.
+   *
+   * When set: options.element is ignored, options.render is ignored (with
+   * a console warning); create/update still run on top of the bindings.
+   */
+  template?: true | string | HTMLTemplateElement;
+
+  /** Element tag name or factory function (default: 'div'; ignored when template is set) */
   element?: string | (() => HTMLElement);
 
   /** 
@@ -396,7 +423,8 @@ export const debug: Debug;
 
 /**
  * Returns true if the value is a Lume reactive proxy created by state().
- * Uses duck-typing: checks for the presence of $subscribe.
+ * Checks the shared reactive brand symbol first (Symbol.for('lume.reactive')),
+ * then falls back to duck-typing ($subscribe) for older stores.
  * This is a type guard that narrows the type to ReactiveState.
  * 
  * @param obj - Value to check
@@ -439,6 +467,9 @@ export interface Plugin {
  * Wrap a reactive state proxy with plugin hooks.
  * Plugins can intercept get/set/notify/subscribe operations.
  *
+ * The returned proxy additionally exposes $dispose(), which removes the
+ * plugin layer's flush hook and clears its pending notifications.
+ *
  * @param store - A reactive proxy from state()
  * @param plugins - Array of plugin objects
  * @returns A new proxy wrapping the store with plugin behavior
@@ -449,9 +480,13 @@ export interface Plugin {
  * import { withPlugins, createDebugPlugin } from 'lume-js/addons';
  *
  * const store = withPlugins(state({ count: 0 }), [createDebugPlugin({ label: 'counter' })]);
+ * store.$dispose(); // detach the plugin layer when done
  * ```
  */
-export function withPlugins<T extends object>(store: ReactiveState<T>, plugins: Plugin[]): ReactiveState<T>;
+export function withPlugins<T extends object>(
+  store: ReactiveState<T>,
+  plugins: Plugin[]
+): ReactiveState<T> & { $dispose(): void };
 
 /**
  * A group that collects cleanup/unsubscribe functions and can dispose them all at once.
@@ -489,7 +524,9 @@ export function createCleanupGroup(): CleanupGroup;
  * embedded in the server-rendered HTML.
  *
  * @param selector - CSS selector for the script element (default: '#__LUME_DATA__')
- * @returns Parsed JSON object, or empty object if not found or invalid
+ * @param validate - Optional validator: (data) => boolean. If it returns
+ *   false, hydrateState returns {} instead of the parsed data.
+ * @returns Parsed JSON object, or empty object if not found, invalid, or rejected
  *
  * @example
  * ```typescript
@@ -497,7 +534,62 @@ export function createCleanupGroup(): CleanupGroup;
  * import { hydrateState } from 'lume-js/addons';
  *
  * const store = state(hydrateState());
+ *
+ * // With schema validation
+ * const data = hydrateState('#__LUME_DATA__', d =>
+ *   typeof (d as any).title === 'string'
+ * );
  * ```
  */
-export function hydrateState(selector?: string): object;
+export function hydrateState(selector?: string, validate?: (data: unknown) => boolean): object;
+
+/**
+ * Options for persist()
+ */
+export interface PersistOptions {
+  /**
+   * Keys to persist. Default: all own non-$ keys of the store at call time.
+   * An explicit empty array is respected: persists and hydrates nothing.
+   */
+  keys?: string[];
+  /**
+   * Storage object (localStorage, sessionStorage, or any Storage-like
+   * object with getItem/setItem). Default: localStorage.
+   */
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
+}
+
+/**
+ * Keep selected store keys in sync with localStorage/sessionStorage:
+ * hydrates them on call, then saves on change.
+ *
+ * - Hydration assigns stored values through the proxy (subscribers fire).
+ * - Saves coalesce to one storage write per microtask and are skipped when
+ *   the serialized snapshot is unchanged.
+ * - Storage failures (quota, corrupted JSON, unserializable values) warn
+ *   on the console — never throw.
+ * - With no storage available (SSR), persistence is disabled with a warning.
+ *
+ * @param store - Reactive store created with state()
+ * @param storageKey - The storage entry name to read/write
+ * @param options - Persist options
+ * @returns Dispose function — stops watching and saving
+ * @throws {Error} If store is not reactive or storageKey is empty
+ *
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { persist } from 'lume-js/addons';
+ *
+ * const store = state({ todos: [], filter: 'all', draft: '' });
+ *
+ * // Hydrate + auto-save todos/filter; draft stays in-memory only
+ * const stop = persist(store, 'my-app', { keys: ['todos', 'filter'] });
+ * ```
+ */
+export function persist(
+  store: ReactiveState<any>,
+  storageKey: string,
+  options?: PersistOptions
+): Unsubscribe;
 

package/src/addons/index.js

@@ -1,3 +1,5 @@
+import { REACTIVE_BRAND } from "../core/state.js";
+
 export { computed } from "./computed.js";
 export { watch } from "./watch.js";
 export { repeat, defaultFocusPreservation, defaultScrollPreservation } from "./repeat.js";
@@ -5,13 +7,22 @@ export { createDebugPlugin, debug } from "./debug.js";
 export { withPlugins } from "./withPlugins.js";
 export { createCleanupGroup } from "./cleanupGroup.js";
 export { hydrateState } from "./hydrateState.js";
+export { persist } from "./persist.js";
 
 /**
  * Returns true if the value is a Lume reactive proxy created by state().
- * Uses duck-typing: checks for the presence of $subscribe.
+ *
+ * Checks the shared reactive brand first (a registry symbol stamped by
+ * state(), reliable across module copies), then falls back to duck-typing
+ * ($subscribe) for proxies from older lume-js versions whose brand was not
+ * shared. The brand check uses the `in` operator, which does not pass
+ * through the proxy `get` trap — calling isReactive inside an effect does
+ * not create a spurious dependency.
+ *
  * @param {any} obj
  * @returns {boolean}
  */
 export function isReactive(obj) {
-  return !!(obj && typeof obj === 'object' && typeof obj.$subscribe === 'function');
+  return !!(obj && typeof obj === 'object' &&
+    (REACTIVE_BRAND in obj || typeof obj.$subscribe === 'function'));
 }

package/src/addons/persist.js

@@ -0,0 +1,190 @@
+/**
+ * Lume-JS Persist Addon
+ *
+ * Keeps selected store keys in sync with localStorage/sessionStorage (or
+ * any Storage-like object): hydrates them on call, then saves on change.
+ *
+ * Usage:
+ *   import { state } from "lume-js";
+ *   import { persist } from "lume-js/addons";
+ *
+ *   const store = state({ todos: [], filter: 'all', draft: '' });
+ *
+ *   // Hydrate + auto-save todos/filter; draft stays in-memory only
+ *   const stop = persist(store, 'my-app', { keys: ['todos', 'filter'] });
+ *
+ * Behavior:
+ * - Hydration assigns stored values through the proxy, so subscribers and
+ *   bindings see them like any other write.
+ * - Saves are coalesced to one storage write per microtask, and skipped
+ *   entirely when the serialized snapshot is unchanged.
+ * - Storage failures (quota, unavailable, corrupted JSON, unserializable
+ *   values) are contained: a console warning, never a throw.
+ *
+ * @security Storage is same-origin but survives schema changes — hydration
+ * only assigns keys you watch (never unknown keys from storage), and the
+ * core set trap independently blocks prototype-polluting keys.
+ *
+ * @module addons/persist
+ */
+
+import { logWarn } from '../utils/log.js';
+
+/**
+ * Read and parse the stored JSON blob. Returns a plain object, or null
+ * when missing, corrupted, or not an object (warns on read errors).
+ */
+function readStored(storage, storageKey) {
+  try {
+    const raw = storage.getItem(storageKey);
+    if (!raw) return null;
+    const data = JSON.parse(raw);
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
+  } catch {
+    logWarn(`[Lume.js] persist(): could not read "${storageKey}" — starting fresh`);
+    return null;
+  }
+}
+
+/** Serialize the watched subset of the store. May throw (circular refs). */
+function serializeKeys(store, watched) {
+  const out = {};
+  for (const k of watched) out[k] = store[k];
+  return JSON.stringify(out);
+}
+
+// storage object → Set of storage keys currently managed by a persist()
+// instance. Two instances on one entry silently overwrite each other's
+// subsets (each serializes only its own watched keys over the whole blob),
+// so the second registration gets a loud warning.
+const activeEntries = new WeakMap();
+
+/**
+ * Default storage resolution. Wrapped because accessing localStorage can
+ * THROW (SecurityError) in cookie-blocked iframes and some privacy modes —
+ * persist() must degrade to a warning, never crash the app at setup.
+ */
+function defaultStorage() {
+  try {
+    return typeof localStorage !== 'undefined' ? localStorage : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Sync store keys with a Storage object.
+ *
+ * @param {object} store - Reactive store created with state()
+ * @param {string} storageKey - The storage entry name to read/write
+ * @param {object} [options]
+ * @param {string[]} [options.keys] - Keys to persist. Default: all own
+ *   non-$ keys of the store at call time.
+ * @param {Storage} [options.storage] - Storage object. Default: localStorage.
+ *   Pass sessionStorage for per-tab persistence.
+ * @returns {function} Dispose function — stops watching and saving.
+ */
+export function persist(store, storageKey, options = {}) {
+  if (!store || typeof store.$subscribe !== 'function') {
+    throw new Error('[Lume.js] persist() requires a reactive store from state()');
+  }
+  if (typeof storageKey !== 'string' || storageKey.length === 0) {
+    throw new Error('[Lume.js] persist() requires a non-empty storage key');
+  }
+
+  const storage = options.storage !== undefined
+    ? options.storage
+    : defaultStorage();
+
+  if (!storage || typeof storage.getItem !== 'function') {
+    logWarn('[Lume.js] persist(): no storage available — persistence disabled');
+    return () => {};
+  }
+
+  // An explicit array is respected as-is — including [] (persist nothing).
+  // Only an absent/non-array option falls back to all own non-$ keys.
+  const watched = Array.isArray(options.keys)
+    ? options.keys.slice()
+    : Object.keys(store).filter(k => !k.startsWith('$'));
+
+  // Warn when another live persist() already manages this storage entry
+  let entrySet = activeEntries.get(storage);
+  if (!entrySet) {
+    entrySet = new Set();
+    activeEntries.set(storage, entrySet);
+  }
+  const ownsEntry = !entrySet.has(storageKey);
+  if (ownsEntry) {
+    entrySet.add(storageKey);
+  } else {
+    logWarn(
+      `[Lume.js] persist(): "${storageKey}" is already managed by another persist() on this storage — ` +
+      'instances will overwrite each other\'s data. Use a distinct key per store.'
+    );
+  }
+
+  // ── Hydrate ────────────────────────────────────────────────────────────
+  // Only watched keys are assigned — stale storage can't inject others.
+  const stored = readStored(storage, storageKey);
+  if (stored) {
+    for (const k of watched) {
+      if (Object.prototype.hasOwnProperty.call(stored, k)) {
+        store[k] = stored[k];
+      }
+    }
+  }
+
+  // ── Save on change ─────────────────────────────────────────────────────
+  // Remember what storage holds (post-hydration) so unchanged flushes —
+  // including the hydration echo itself — skip the write.
+  let lastWritten = null;
+  try {
+    lastWritten = serializeKeys(store, watched);
+  } catch {
+    // Unserializable initial state: first save attempt will warn.
+  }
+
+  let scheduled = false;
+  let disposed = false;
+
+  const flushSave = () => {
+    scheduled = false;
+    if (disposed) return;
+
+    let json;
+    try {
+      json = serializeKeys(store, watched);
+    } catch (err) {
+      logWarn('[Lume.js] persist(): state not serializable — skipping save', err);
+      return;
+    }
+    if (json === lastWritten) return;
+
+    try {
+      storage.setItem(storageKey, json);
+      lastWritten = json;
+    } catch (err) {
+      logWarn('[Lume.js] persist(): could not write — storage full or unavailable?', err);
+    }
+  };
+
+  const save = () => {
+    if (scheduled) return;
+    scheduled = true;
+    queueMicrotask(flushSave);
+  };
+
+  const unsubs = watched.map(k => {
+    let first = true;
+    return store.$subscribe(k, () => {
+      if (first) { first = false; return; } // skip $subscribe's immediate call
+      save();
+    });
+  });
+
+  return () => {
+    disposed = true;
+    if (ownsEntry) entrySet.delete(storageKey);
+    while (unsubs.length) unsubs.pop()();
+  };
+}