lume-js 2.2.0 → 2.3.0

package/src/addons/hydrateState.js

@@ -2,8 +2,16 @@
  * Reads initial state from a `<script type="application/json">` element
  * embedded in the server-rendered HTML. Useful for SSR / hydration patterns.
  *
+ * @security Hydration trusts the DOM. An attacker who can inject HTML before
+ * the legitimate script (DOM clobbering) can control the parsed data. The
+ * element must be a real `<script type="application/json">` tag; non-script
+ * elements are rejected. Use the optional `validate` parameter to enforce a
+ * schema (e.g., whitelist allowed keys) before passing to `state()`.
+ *
  * @param {string} [selector='#__LUME_DATA__'] - CSS selector for the script element
- * @returns {object} Parsed JSON object, or empty object if not found / invalid
+ * @param {function} [validate] - Optional validator: (data) => boolean. If it
+ *   returns false, hydrateState returns {} instead of the parsed data.
+ * @returns {object} Parsed JSON object, or empty object if not found / invalid / rejected
  *
  * @example
  * ```html
@@ -16,15 +24,35 @@
  * import { state } from 'lume-js';
  * import { hydrateState } from 'lume-js/addons';
  *
- * const store = state(hydrateState());
+ * // With optional schema validation
+ * const data = hydrateState('#__LUME_DATA__', d =>
+ *   typeof d.title === 'string' && typeof d.count === 'number'
+ * );
+ * const store = state(data);
  * ```
  */
-export function hydrateState(selector = '#__LUME_DATA__') {
+export function hydrateState(selector = '#__LUME_DATA__', validate) {
   const el = typeof document !== 'undefined' ? document.querySelector(selector) : null;
   if (!el) return {};
+
+  // Reject non-script elements or scripts without the correct type.
+  // This mitigates DOM clobbering where an attacker injects a matching
+  // element with a different tag name (e.g., a div or a script with
+  // a different type that would still match querySelector by id).
+  if (el.tagName !== 'SCRIPT' || el.type !== 'application/json') {
+    return {};
+  }
+
+  let data;
   try {
-    return JSON.parse(el.textContent);
+    data = JSON.parse(el.textContent);
   } catch {
     return {};
   }
+
+  if (typeof validate === 'function' && !validate(data)) {
+    return {};
+  }
+
+  return data;
 }

package/src/addons/index.d.ts

@@ -163,7 +163,25 @@ export interface RepeatOptions<T> {
    */
   update?: (item: T, element: HTMLElement, index: number, context: UpdateContext) => void;
 
-  /** Element tag name or factory function (default: 'div') */
+  /**
+   * 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 +414,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
@@ -501,3 +520,52 @@ export function createCleanupGroup(): CleanupGroup;
  */
 export function hydrateState(selector?: string): object;
 
+/**
+ * Options for persist()
+ */
+export interface PersistOptions {
+  /**
+   * Keys to persist. Default: all own non-$ keys of the store at call time.
+   */
+  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,152 @@
+/**
+ * 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);
+}
+
+/**
+ * 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
+    : globalThis.localStorage;
+
+  if (!storage || typeof storage.getItem !== 'function') {
+    logWarn('[Lume.js] persist(): no storage available — persistence disabled');
+    return () => {};
+  }
+
+  const watched = Array.isArray(options.keys) && options.keys.length > 0
+    ? options.keys.slice()
+    : Object.keys(store).filter(k => !k.startsWith('$'));
+
+  // ── 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;
+    while (unsubs.length) unsubs.pop()();
+  };
+}

package/src/addons/repeat.js

@@ -22,6 +22,38 @@
  * store.items = [...items] // ✅ Triggers update
  * 
  * ═══════════════════════════════════════════════════════════════════════
+ * PATTERN 0: Template-based (recommended) — declarative, zero DOM code
+ * ═══════════════════════════════════════════════════════════════════════
+ *
+ *   HTML — a standard <template> element, valid HTML, no custom syntax:
+ *
+ *   <ul id="list">
+ *     <template>
+ *       <li>
+ *         <strong data-bind="name"></strong>
+ *         <span data-bind="role"></span>
+ *         <em data-bind="$index"></em>
+ *       </li>
+ *     </template>
+ *   </ul>
+ *
+ *   JS:
+ *
+ *   repeat('#list', store, 'people', {
+ *     key: p => p.id,
+ *     template: true   // use the <template> inside the container
+ *   });
+ *
+ *   data-bind paths resolve against EACH ITEM: "name" → item.name,
+ *   "user.city" → item.user.city, "$item" → the item itself (primitive
+ *   arrays), "$index" → current index. Inputs get .value/.checked, other
+ *   elements get textContent — identical semantics to bindDom's data-bind.
+ *   These are one-way snapshot bindings re-applied per list update (items
+ *   are plain objects, not stores). Combine with create/update for event
+ *   listeners or extra binding. template also accepts a CSS selector or an
+ *   HTMLTemplateElement.
+ *
+ * ═══════════════════════════════════════════════════════════════════════
  * PATTERN 1: Simple (render only) - for simple cases or backward compat
  * ═══════════════════════════════════════════════════════════════════════
  * 
@@ -79,6 +111,64 @@
  *   });
  */
 import { logWarn, logError } from '../utils/log.js';
+import { applyBindValue } from '../core/bindDom.js';
+
+/**
+ * Resolve the template option to its single root element.
+ * Accepts true (first <template> inside the container), a CSS selector,
+ * or an HTMLTemplateElement directly.
+ */
+function resolveTemplateRoot(template, containerEl) {
+  let templateEl = template;
+  if (template === true) {
+    templateEl = containerEl.querySelector('template');
+  } else if (typeof template === 'string') {
+    templateEl = document.querySelector(template);
+  }
+  if (!templateEl || templateEl.tagName !== 'TEMPLATE') {
+    throw new Error('[Lume.js] repeat(): template not found or not a <template> element');
+  }
+  if (templateEl.content.children.length !== 1) {
+    throw new Error('[Lume.js] repeat(): template must contain exactly one root element');
+  }
+  return templateEl.content.firstElementChild;
+}
+
+/**
+ * Collect [data-bind] nodes of a cloned item element into a compiled
+ * binding list. Paths are resolved against the ITEM (not the store):
+ *   data-bind="name"      → item.name
+ *   data-bind="user.city" → item.user.city
+ *   data-bind="$item"     → the item itself (for primitive arrays)
+ *   data-bind="$index"    → the item's current index
+ */
+function collectItemBindings(el) {
+  const bindings = [];
+  const add = (node) => {
+    const path = node.getAttribute('data-bind');
+    bindings.push({ node, path, keys: path === '$item' || path === '$index' ? null : path.split('.') });
+  };
+  if (el.hasAttribute('data-bind')) add(el);
+  for (const node of el.querySelectorAll('[data-bind]')) add(node);
+  return bindings;
+}
+
+function applyItemBindings(bindings, item, index) {
+  for (const b of bindings) {
+    let val;
+    if (b.path === '$index') {
+      val = index;
+    } else if (b.path === '$item') {
+      val = item;
+    } else {
+      val = item;
+      for (let i = 0; i < b.keys.length && val != null; i++) {
+        val = val[b.keys[i]];
+      }
+    }
+    applyBindValue(b.node, val);
+  }
+}
 
 /**
  * Default focus preservation strategy
@@ -173,7 +263,8 @@ export function defaultScrollPreservation(container, context = {}) {
  * @param {Function} [options.create] - Function for new elements only: (item, element, index) => void | Function. If a function is returned, it is registered as the element's cleanup and called automatically when the element is removed (by list update or full cleanup).
  * @param {Function} [options.update] - Function for data binding: (item, element, index, { isFirstRender }) => void. Skipped if same item reference AND same index.
  * @param {Function} [options.remove] - Additional cleanup when element is removed: (item, element) => void. Called after any cleanup function returned by create(). Optional — prefer returning a cleanup from create() for automatic lifecycle management.
- * @param {string|Function} [options.element='div'] - Element tag name or factory function
+ * @param {true|string|HTMLTemplateElement} [options.template] - Declarative item structure from a <template> element: true = first <template> inside the container, string = CSS selector, or the element itself. The template must have exactly one root element; it is cloned per item and its [data-bind] paths are bound to the item on every update ("name", "user.city", "$item", "$index"). When set, options.element is ignored and options.render is ignored (with a warning); create/update remain available on top.
+ * @param {string|Function} [options.element='div'] - Element tag name or factory function (ignored when options.template is set)
  * @param {Function|null} [options.preserveFocus=defaultFocusPreservation] - Focus preservation strategy (null to disable)
  * @param {Function|null} [options.preserveScroll=defaultScrollPreservation] - Scroll preservation strategy (null to disable)
  * @returns {Function} Cleanup function
@@ -186,6 +277,7 @@ export function repeat(container, store, arrayKey, options) {
     create,
     update,
     remove,
+    template = null,
     element = 'div',
     preserveFocus = defaultFocusPreservation,
     preserveScroll = defaultScrollPreservation
@@ -206,7 +298,15 @@ export function repeat(container, store, arrayKey, options) {
     throw new Error('[Lume.js] repeat(): options.key must be a function');
   }
 
-  if (typeof render !== 'function' && typeof create !== 'function') {
+  // Template mode: structure and data binding come from the <template>;
+  // render/create/update are all optional on top of it.
+  const templateRoot = template ? resolveTemplateRoot(template, containerEl) : null;
+
+  if (templateRoot && typeof render === 'function') {
+    logWarn('[Lume.js] repeat(): options.render is ignored when options.template is set — use create/update instead');
+  }
+
+  if (!templateRoot && typeof render !== 'function' && typeof create !== 'function') {
     throw new Error('[Lume.js] repeat(): options.render or options.create must be a function');
   }
 
@@ -218,9 +318,12 @@ export function repeat(container, store, arrayKey, options) {
   const prevIndexByKey = new Map();
   // key -> cleanup function returned by create()
   const cleanupByKey = new Map();
+  // key -> compiled [data-bind] nodes of the clone (template mode only)
+  const bindingsByKey = new Map();
   const seenKeys = new Set();
 
   function createElement() {
+    if (templateRoot) return templateRoot.cloneNode(true);
     return typeof element === 'function'
       ? element()
       : document.createElement(element);
@@ -298,10 +401,13 @@ export function repeat(container, store, arrayKey, options) {
       if (isFirstRender) {
         el = createElement();
         elementsByKey.set(k, el);
+        if (templateRoot) {
+          bindingsByKey.set(k, collectItemBindings(el));
+        }
       }
 
       try {
-        // Call create for new elements (DOM structure)
+        // Call create for new elements (DOM structure / event listeners)
         if (isFirstRender && create) {
           const cleanup = create(item, el, i);
           if (typeof cleanup === 'function') {
@@ -309,11 +415,17 @@ export function repeat(container, store, arrayKey, options) {
           }
         }
 
-        // Call update for data binding (new and existing elements)
+        // Data binding (new and existing elements)
         // Skip if same item reference AND same index (optimization)
         const prevItem = prevItemsByKey.get(k);
         const prevIndex = prevIndexByKey.get(k);
-        if (update) {
+        if (templateRoot) {
+          if (prevItem !== item || prevIndex !== i) {
+            applyItemBindings(bindingsByKey.get(k), item, i);
+            // update is optional extra binding on top of the template
+            if (update) update(item, el, i, { isFirstRender });
+          }
+        } else if (update) {
           if (prevItem !== item || prevIndex !== i) {
             update(item, el, i, { isFirstRender });
           }
@@ -359,6 +471,7 @@ export function repeat(container, store, arrayKey, options) {
             prevItemsByKey.delete(k);
             prevIndexByKey.delete(k);
             cleanupByKey.delete(k);
+            bindingsByKey.delete(k);
           }
         }
       }
@@ -402,6 +515,7 @@ export function repeat(container, store, arrayKey, options) {
       prevItemsByKey.clear();
       prevIndexByKey.clear();
       cleanupByKey.clear();
+      bindingsByKey.clear();
       seenKeys.clear();
     };
   }
@@ -431,6 +545,7 @@ export function repeat(container, store, arrayKey, options) {
     prevItemsByKey.clear();
     prevIndexByKey.clear();
     cleanupByKey.clear();
+    bindingsByKey.clear();
     seenKeys.clear();
   };
 }

package/src/addons/withPlugins.js

@@ -24,6 +24,10 @@
  *   onNotify(key, value)             — called before subscribers are notified
  *   onSubscribe(key)                 — called when $subscribe is invoked
  *
+ * @security Plugins run with full application privilege. A plugin can read
+ * all state, alter any write, or suppress mutations. Only pass trusted objects.
+ * Plugin objects are frozen after registration to prevent post-init mutation.
+ *
  * @param {object} store - A reactive proxy from state()
  * @param {Array<object>} plugins - Array of plugin objects
  * @returns {Proxy} A new proxy wrapping the store with plugin behavior
@@ -33,13 +37,15 @@ import { logError } from '../utils/log.js';
 export function withPlugins(store, plugins = []) {
   if (!plugins.length) return store;
 
-  // Call onInit hooks once at wrap time
+  // Call onInit hooks once at wrap time, then freeze each plugin to prevent
+  // post-registration mutation of its hooks (defense-in-depth).
   for (const p of plugins) {
     try {
       p.onInit?.();
     } catch (e) {
       logError(`[Lume.js] Plugin "${p.name}" error in onInit:`, e);
     }
+    Object.freeze(p);
   }
 
   // Track pending notifications for onNotify hooks.