npm - lume-js - Versions diffs - 0.4.0 → 0.5.0 - Mend

lume-js 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -5,7 +5,7 @@
 Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required, no framework lock-in.
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.4.0-green.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.5.0-green.svg)](package.json)
 ## Why Lume.js?
@@ -29,6 +29,8 @@ Minimal reactive state management using only standard JavaScript and HTML - no c
 **Lume.js is essentially "Modern Knockout.js" - standards-only reactivity for 2025.**
+📖 **New to the project?** Read [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) to understand our design philosophy and why certain choices were made.
 ---
 ## Installation
@@ -164,17 +166,29 @@ cleanup(); // Stop the effect
 **How it works:** Effects use `globalThis.__LUME_CURRENT_EFFECT__` to track which state properties are accessed during execution. When any tracked property changes, the effect is queued in that state's pending effects set and runs once in the next microtask.
-### `bindDom(root, store)`
+### `bindDom(root, store, options?)`
 Binds reactive state to DOM elements with `data-bind` attributes.
+**Automatically waits for DOMContentLoaded** if the document is still loading, making it safe to call from anywhere (even in `<head>`).
 ```javascript
+// Default: Auto-waits for DOM (safe anywhere)
 const cleanup = bindDom(document.body, store);
+// Advanced: Force immediate binding (no auto-wait)
+const cleanup = bindDom(myElement, store, { immediate: true });
 // Later: cleanup all bindings
 cleanup();
 ```
+**Parameters:**
+- `root` (HTMLElement) - Root element to scan for `[data-bind]` attributes
+- `store` (Object) - Reactive state object
+- `options` (Object, optional)
+  - `immediate` (Boolean) - Skip auto-wait, bind immediately. Default: `false`
 **Supports:**
 - ✅ Text content: `<span data-bind="count"></span>`
 - ✅ Input values: `<input data-bind="name">`
@@ -185,12 +199,108 @@ cleanup();
 - ✅ Radio buttons: `<input type="radio" data-bind="choice">`
 - ✅ Nested paths: `<span data-bind="user.name"></span>`
+**Multiple Checkboxes Pattern:**
+For multiple checkboxes, use nested state instead of arrays:
+```javascript
+// ✅ Recommended: Nested state objects
+const store = state({
+  tags: state({
+    javascript: true,
+    python: false,
+    go: true
+  })
+});
+```
+```html
+<input type="checkbox" data-bind="tags.javascript"> JavaScript
+<input type="checkbox" data-bind="tags.python"> Python
+<input type="checkbox" data-bind="tags.go"> Go
+```
+Nested state is **more explicit and easier to validate** than array-based bindings. See [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md#why-nested-state-for-multiple-checkboxes-instead-of-arrays) for the full rationale.
 **Features:**
+- ✅ Auto-waits for DOM if needed (no timing issues!)
 - ✅ Returns cleanup function
 - ✅ Better error messages with `[Lume.js]` prefix
 - ✅ Handles edge cases (empty bindings, invalid paths)
 - ✅ Two-way binding for form inputs
+### `isReactive(obj)`
+Checks whether a value is a reactive proxy created by `state()`.
+```javascript
+import { state, isReactive } from 'lume-js';
+const original = { count: 1 };
+const store = state(original);
+isReactive(store);    // true
+isReactive(original); // false
+isReactive(null);     // false
+```
+**How it works:**
+Lume.js uses an internal `Symbol` checked via the Proxy `get` trap rather than mutating the proxy or storing external WeakSet state. Accessing `obj[REACTIVE_SYMBOL]` returns `true` only for reactive proxies, and the symbol is not enumerable or visible via `Object.getOwnPropertySymbols`.
+**Characteristics:**
+- ✅ Zero mutation of the proxy
+- ✅ Invisible to enumeration and reflection
+- ✅ Fast: single symbol identity check in the `get` path
+- ✅ Supports nested reactive states naturally
+- ✅ Skips tracking meta `$`-prefixed methods (e.g. `$subscribe`)
+**When to use:** Utility/debugging, conditional wrapping patterns like:
+```javascript
+function ensureReactive(val) {
+  return isReactive(val) ? val : state(val);
+}
+```
+**Why Auto-Ready?**
+Works seamlessly regardless of script placement:
+```html
+<!-- ✅ Works in <head> -->
+<script type="module">
+  import { state, bindDom } from 'lume-js';
+  const store = state({ count: 0 });
+  bindDom(document.body, store); // Auto-waits for DOM!
+</script>
+<!-- ✅ Works inline in <body> -->
+<body>
+  <span data-bind="count"></span>
+  <script type="module">
+    // bindDom() waits for DOMContentLoaded automatically
+  </script>
+</body>
+<!-- ✅ Works with defer -->
+<script type="module" defer>
+  // Already loaded, executes immediately
+</script>
+```
+**When to use `immediate: true`:**
+Rare scenarios where you're dynamically creating DOM or need precise control:
+```javascript
+// Dynamic DOM injection
+const container = document.createElement('div');
+container.innerHTML = '<span data-bind="count"></span>';
+document.body.appendChild(container);
+// Bind immediately (DOM already exists)
+bindDom(container, store, { immediate: true });
+```
 ### `$subscribe(key, callback)`
 Manually subscribe to state changes. Calls callback immediately with current value, then on every change.
@@ -277,6 +387,70 @@ unwatch();
 ---
+## Choosing the Right Reactive Pattern
+Lume.js provides three ways to react to state changes. Here's when to use each:
+| Pattern | Use When | Pros | Cons |
+|---------|----------|------|------|
+| **`bindDom()`** | Syncing state ↔ DOM | Zero code, declarative HTML | DOM-only, no custom logic |
+| **`$subscribe()`** | Listening to specific keys | Explicit, immediate, simple | Manual dependency tracking |
+| **`effect()`** | Auto-run code on any state access | Automatic dependencies, concise | Microtask delay, can infinite loop |
+| **`computed()`** | Deriving values from state | Cached, automatic recompute | Addon import, slight overhead |
+**Quick Decision Tree:**
+```
+Need to update DOM?
+├─ Yes, just sync form/text → Use bindDom()
+└─ No, custom logic needed
+   ├─ Watch single key? → Use $subscribe()
+   ├─ Watch multiple keys dynamically? → Use effect()
+   └─ Derive a value? → Use computed()
+```
+**Examples:**
+```javascript
+// 1. bindDom - Zero code DOM sync
+<span data-bind="count"></span>
+bindDom(document.body, store);
+// 2. $subscribe - Specific key, immediate execution
+store.$subscribe('count', (val) => {
+  if (val > 10) showNotification('High!');
+});
+// 3. effect - Multiple keys, automatic tracking
+effect(() => {
+  document.title = `${store.user.name}: ${store.count}`;
+  // Tracks both user.name and count automatically
+});
+// 4. computed - Derive cached value
+import { computed } from 'lume-js/addons';
+const total = computed(() => store.items.reduce((sum, i) => sum + i.price, 0));
+console.log(total.value);
+```
+**Gotchas:**
+- ⚠️ **effect()** runs in next microtask (~0.002ms delay). Use `$subscribe()` for immediate execution.
+- ⚠️ **Don't mutate tracked state inside effect** - causes infinite loops:
+  ```javascript
+  // ❌ BAD - Infinite loop
+  effect(() => {
+    store.count++; // Writes to what it reads!
+  });
+  // ✅ GOOD - Read-only or separate keys
+  effect(() => {
+    store.displayCount = store.count * 2; // Different keys
+  });
+  ```
+---
 ## Examples
 ### Basic Counter
@@ -619,17 +793,47 @@ resolve: {
 **Current coverage:**
 - 100% statements, functions, and lines
 - 100% branches (including edge-case paths)
-- 37 tests covering core behavior, addons, inputs (text/checkbox/radio/number/range/select/textarea), nested state, and cleanup semantics
+- 114 tests covering core behavior, addons, inputs (text/checkbox/radio/number/range/select/textarea), nested state, reactive identity, and cleanup semantics
 ---
+### `repeat(container, store, key, options)`
+**@experimental** - API may change in future versions.
+Efficiently renders lists with element reuse and automatic subscription.
+```javascript
+import { repeat } from 'lume-js/addons/repeat.js';
+// ⚠️ IMPORTANT: Arrays must be updated immutably!
+// store.items.push(newItem);       // ❌ Won't trigger update
+// store.items = [...store.items, newItem]; // ✅ Triggers update
+repeat('#list', store, 'items', {
+  key: item => item.id,
+  render: (item, el) => {
+    el.textContent = item.name;
+  }
+});
+```
+**Features:**
+- ✅ **Element Reuse** - Reuses DOM nodes by key (no full re-renders)
+- ✅ **Focus Preservation** - Maintains active element and selection during updates
+- ✅ **Scroll Preservation** - Maintains scroll position during updates
+- ✅ **Automatic Subscription** - Subscribes to the array key automatically
 ## Contributing
 We welcome contributions! Please:
 1. **Focus on:** Examples, documentation, bug fixes, performance
 2. **Avoid:** Adding core features without discussion (keep it minimal!)
-3. **Check:** Project specification for philosophy
+3. **Read:** [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) to understand our philosophy and why certain choices were made
+4. **Propose alternatives:** If you think a design decision should be reconsidered, open an issue with your reasoning
+Before suggesting new features, check if they align with Lume's core principles: standards-only, minimal API, no build step required.
 ---

package/package.json CHANGED Viewed

@@ -1,10 +1,21 @@
 {
   "name": "lume-js",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./addons": {
+      "import": "./src/addons/index.js",
+      "types": "./src/addons/index.d.ts"
+    }
+  },
   "scripts": {
     "dev": "vite",
     "build": "echo 'No build step needed - zero-runtime library!'",

package/src/addons/index.d.ts ADDED Viewed

@@ -0,0 +1,258 @@
+/**
+ * Lume.js Addons TypeScript Definitions
+ *
+ * Optional utilities for advanced reactive patterns.
+ * Import from "lume-js/addons" for tree-shaking.
+ */
+import type { Unsubscribe, Subscriber, ReactiveState } from '../index.js';
+/**
+ * Computed value container returned by computed().
+ * T is the computed result type; when an error occurs the value becomes undefined.
+ */
+export interface Computed<T> {
+  /** Current computed value (undefined if computation threw). */
+  readonly value: T | undefined;
+  /** Subscribe to changes; immediate invocation with current value (may be undefined). */
+  subscribe(callback: Subscriber<T | undefined>): Unsubscribe;
+  /** Dispose computed value and stop tracking dependencies. */
+  dispose(): void;
+}
+/**
+ * Create a computed value that automatically re-evaluates when accessed reactive state keys change.
+ * Uses effect() internally for dependency tracking.
+ *
+ * @param fn - Pure function that derives a value from reactive state.
+ * @returns Computed value container with .value, .subscribe(), and .dispose()
+ * @throws {Error} If fn is not a function
+ *
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { computed } from 'lume-js/addons';
+ *
+ * const store = state({ count: 5 });
+ * const doubled = computed(() => store.count * 2);
+ *
+ * console.log(doubled.value); // 10
+ *
+ * store.count = 10;
+ * // After microtask:
+ * console.log(doubled.value); // 20 (auto-updated)
+ *
+ * // Subscribe to changes
+ * const unsub = doubled.subscribe(value => {
+ *   console.log('Doubled:', value);
+ * });
+ *
+ * // Cleanup
+ * doubled.dispose();
+ * unsub();
+ * ```
+ */
+export function computed<T>(fn: () => T): Computed<T>;
+/**
+ * Watch a single key on a reactive state object; convenience wrapper around $subscribe.
+ *
+ * @param store - Reactive state object created with state().
+ * @param key - Property key to observe.
+ * @param callback - Invoked immediately and on subsequent changes.
+ * @returns Unsubscribe function for cleanup
+ * @throws {Error} If store is not a reactive state object
+ *
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { watch } from 'lume-js/addons';
+ *
+ * const store = state({ count: 0 });
+ *
+ * const unwatch = watch(store, 'count', (value) => {
+ *   console.log('Count is now:', value);
+ * });
+ *
+ * // Cleanup
+ * unwatch();
+ * ```
+ */
+export function watch<T extends object, K extends keyof T>(
+  store: ReactiveState<T>,
+  key: K,
+  callback: Subscriber<T[K]>
+): Unsubscribe;
+/**
+ * Context passed to preservation functions
+ */
+export interface PreservationContext {
+  /** Whether this update is a reorder (vs add/remove) */
+  isReorder?: boolean;
+}
+/**
+ * Focus preservation function signature
+ *
+ * @param container - The list container element
+ * @returns Restore function to call after DOM updates, or null if nothing to restore
+ */
+export type FocusPreservation = (container: HTMLElement) => (() => void) | null;
+/**
+ * Scroll preservation function signature
+ *
+ * @param container - The list container element
+ * @param context - Additional context about the update
+ * @returns Restore function to call after DOM updates
+ */
+export type ScrollPreservation = (container: HTMLElement, context?: PreservationContext) => () => void;
+/**
+ * Options for the repeat() function
+ */
+export interface RepeatOptions<T> {
+  /** Function to extract unique key from item */
+  key: (item: T) => string | number;
+  /** Function to render/update an item's element */
+  render: (item: T, element: HTMLElement, index: number) => void;
+  /** Element tag name or factory function (default: 'div') */
+  element?: string | (() => HTMLElement);
+  /**
+   * Focus preservation strategy (default: defaultFocusPreservation)
+   * Set to null to disable focus preservation
+   */
+  preserveFocus?: FocusPreservation | null;
+  /**
+   * Scroll preservation strategy (default: defaultScrollPreservation)
+   * Set to null to disable scroll preservation
+   */
+  preserveScroll?: ScrollPreservation | null;
+}
+/**
+ * Default focus preservation strategy
+ * Saves activeElement and selection state before DOM updates
+ *
+ * @param container - The list container element
+ * @returns Restore function or null
+ *
+ * @example
+ * ```typescript
+ * import { defaultFocusPreservation } from 'lume-js/addons';
+ *
+ * // Use in custom preservation wrapper
+ * const myPreservation = (container) => {
+ *   console.log('Saving focus...');
+ *   const restore = defaultFocusPreservation(container);
+ *   return restore ? () => {
+ *     restore();
+ *     console.log('Focus restored!');
+ *   } : null;
+ * };
+ * ```
+ */
+export function defaultFocusPreservation(container: HTMLElement): (() => void) | null;
+/**
+ * Default scroll preservation strategy
+ * Uses anchor-based preservation for add/remove, pixel position for reorder
+ *
+ * @param container - The list container element
+ * @param context - Additional context about the update
+ * @returns Restore function
+ *
+ * @example
+ * ```typescript
+ * import { defaultScrollPreservation } from 'lume-js/addons';
+ *
+ * // Wrap default behavior
+ * const myScrollPreservation = (container, context) => {
+ *   const restore = defaultScrollPreservation(container, context);
+ *   return () => {
+ *     restore();
+ *     console.log('Scroll position restored');
+ *   };
+ * };
+ * ```
+ */
+export function defaultScrollPreservation(container: HTMLElement, context?: PreservationContext): () => void;
+/**
+ * Efficiently render a list with element reuse by key.
+ *
+ * Features:
+ * - Element reuse (same DOM nodes, not recreated)
+ * - Minimal DOM operations (only updates what changed)
+ * - Optional focus preservation (maintains activeElement and selection)
+ * - Optional scroll preservation (intelligent positioning)
+ * - Fully customizable preservation strategies
+ *
+ * @param container - Container element or CSS selector
+ * @param store - Reactive state object
+ * @param arrayKey - Key in store containing the array
+ * @param options - Configuration options
+ * @returns Cleanup function
+ *
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { repeat } from 'lume-js/addons';
+ *
+ * const store = state({
+ *   todos: [
+ *     { id: 1, text: 'Learn Lume.js' },
+ *     { id: 2, text: 'Build an app' }
+ *   ]
+ * });
+ *
+ * // Basic usage (preservation enabled by default)
+ * const cleanup = repeat('#todo-list', store, 'todos', {
+ *   key: todo => todo.id,
+ *   render: (todo, el) => {
+ *     if (!el.dataset.init) {
+ *       el.innerHTML = `<input value="${todo.text}">`;
+ *       el.dataset.init = 'true';
+ *     }
+ *   }
+ * });
+ *
+ * // Disable preservation (bare-bones)
+ * repeat('#list', store, 'todos', {
+ *   key: todo => todo.id,
+ *   render: (todo, el) => { el.textContent = todo.text; },
+ *   preserveFocus: null,
+ *   preserveScroll: null
+ * });
+ *
+ * // Custom preservation
+ * import { defaultFocusPreservation } from 'lume-js/addons';
+ *
+ * repeat('#list', store, 'todos', {
+ *   key: todo => todo.id,
+ *   render: (todo, el) => { ... },
+ *   preserveFocus: (container) => {
+ *     // Custom logic
+ *     const restore = defaultFocusPreservation(container);
+ *     return () => {
+ *       restore?.();
+ *       console.log('Focus restored');
+ *     };
+ *   }
+ * });
+ *
+ * // Cleanup
+ * cleanup();
+ * ```
+ */
+export function repeat<T>(
+  container: string | HTMLElement,
+  store: ReactiveState<any>,
+  arrayKey: string,
+  options: RepeatOptions<T>
+): Unsubscribe;

package/src/addons/index.js CHANGED Viewed

@@ -1,2 +1,3 @@
 export { computed } from "./computed.js";
-export { watch } from "./watch.js";
+export { watch } from "./watch.js";
+export { repeat } from "./repeat.js";

package/src/addons/repeat.js ADDED Viewed

@@ -0,0 +1,342 @@
+/**
+ * Lume-JS List Rendering (Addon)
+ * @experimental
+ *
+ * Renders lists with automatic subscription and element reuse by key.
+ *
+ * Core guarantees:
+ * ✅ Element reuse by key (same DOM nodes, not recreated)
+ * ✅ Minimal DOM operations (only updates what changed)
+ * ✅ Memory efficiency (cleanup on remove)
+ *
+ * Default behavior (can be disabled/customized):
+ * ✅ Focus preservation (maintains activeElement and selection)
+ * ✅ Scroll preservation (intelligent positioning for add/remove/reorder)
+ *
+ * Philosophy: No artificial limitations
+ * - All preservation logic is overridable via options
+ * - Set to null/false to disable, or provide custom functions
+ * - Export utilities so you can wrap/extend them
+ *
+ * Usage:
+ *   import { repeat } from "lume-js/addons/repeat.js";
+ *
+ *   // ⚠️ IMPORTANT: Arrays must be updated immutably!
+ *   // store.items.push(x)      // ❌ Won't trigger update
+ *   // store.items = [...items] // ✅ Triggers update
+ *
+ *   // Basic usage (focus & scroll preservation enabled by default)
+ *   repeat('#list', store, 'todos', {
+ *     key: todo => todo.id,
+ *     render: (todo, el) => {
+ *       if (!el.dataset.init) {
+ *         el.innerHTML = `<input value="${todo.text}">`;
+ *         el.dataset.init = 'true';
+ *       }
+ *     }
+ *   });
+ *
+ *   // Disable all preservation (bare-bones repeat)
+ *   repeat('#list', store, 'items', {
+ *     key: item => item.id,
+ *     render: (item, el) => { el.textContent = item.name; },
+ *     preserveFocus: null,
+ *     preserveScroll: null
+ *   });
+ *
+ *   // Custom focus preservation
+ *   repeat('#list', store, 'items', {
+ *     key: item => item.id,
+ *     render: (item, el) => { ... },
+ *     preserveFocus: (container) => {
+ *       // Your custom logic
+ *       const state = { focused: document.activeElement };
+ *       return () => state.focused?.focus();
+ *     }
+ *   });
+ *
+ *   // Mix built-in and custom
+ *   import { defaultFocusPreservation, defaultScrollPreservation } from "lume-js/addons/repeat.js";
+ *
+ *   repeat('#list', store, 'items', {
+ *     key: item => item.id,
+ *     render: (item, el) => { ... },
+ *     preserveFocus: defaultFocusPreservation, // use built-in
+ *     preserveScroll: (container, context) => {
+ *       // wrap/extend built-in
+ *       const restore = defaultScrollPreservation(container, context);
+ *       return () => {
+ *         restore();
+ *         console.log('Scroll restored!');
+ *       };
+ *     }
+ *   });
+ */
+// ============================================================================
+// PRESERVATION UTILITIES (Exported for customization)
+// ============================================================================
+/**
+ * Default focus preservation strategy
+ * Saves activeElement and selection state before DOM updates
+ *
+ * @param {HTMLElement} container - The list container
+ * @returns {Function|null} Restore function, or null if nothing to restore
+ */
+export function defaultFocusPreservation(container) {
+  const activeEl = document.activeElement;
+  const shouldRestore = container.contains(activeEl);
+  if (!shouldRestore) return null;
+  let selectionStart = null;
+  let selectionEnd = null;
+  if (activeEl.tagName === 'INPUT' || activeEl.tagName === 'TEXTAREA') {
+    selectionStart = activeEl.selectionStart;
+    selectionEnd = activeEl.selectionEnd;
+  }
+  return () => {
+    if (document.body.contains(activeEl)) {
+      activeEl.focus();
+      if (selectionStart !== null && selectionEnd !== null) {
+        activeEl.setSelectionRange(selectionStart, selectionEnd);
+      }
+    }
+  };
+}
+/**
+ * Default scroll preservation strategy
+ * Uses anchor-based preservation for add/remove, pixel position for reorder
+ *
+ * @param {HTMLElement} container - The list container
+ * @param {Object} context - Additional context
+ * @param {boolean} context.isReorder - Whether this is a reorder operation
+ * @returns {Function} Restore function
+ */
+export function defaultScrollPreservation(container, context = {}) {
+  const { isReorder = false } = context;
+  const scrollTop = container.scrollTop;
+  // Early return if no scroll
+  if (scrollTop === 0) {
+    return () => { container.scrollTop = 0; };
+  }
+  let anchorElement = null;
+  let anchorOffset = 0;
+  // Only use anchor-based preservation for add/remove, not reorder
+  if (!isReorder) {
+    const containerRect = container.getBoundingClientRect();
+    // Avoid Array.from - iterate children directly
+    for (let child = container.firstElementChild; child; child = child.nextElementSibling) {
+      const rect = child.getBoundingClientRect();
+      if (rect.bottom > containerRect.top) {
+        anchorElement = child;
+        anchorOffset = rect.top - containerRect.top;
+        break;
+      }
+    }
+  }
+  return () => {
+    if (anchorElement && document.body.contains(anchorElement)) {
+      const newRect = anchorElement.getBoundingClientRect();
+      const containerRect = container.getBoundingClientRect();
+      const currentOffset = newRect.top - containerRect.top;
+      const scrollAdjustment = currentOffset - anchorOffset;
+      container.scrollTop = container.scrollTop + scrollAdjustment;
+    } else {
+      container.scrollTop = scrollTop;
+    }
+  };
+}
+// ============================================================================
+// MAIN REPEAT FUNCTION
+// ============================================================================
+/**
+ * Efficiently render a list with element reuse
+ *
+ * @param {string|HTMLElement} container - Container element or selector
+ * @param {Object} store - Reactive state object
+ * @param {string} arrayKey - Key in store containing the array
+ * @param {Object} options - Configuration
+ * @param {Function} options.key - Function to extract unique key: (item) => key
+ * @param {Function} options.render - Function to render item: (item, element, index) => void
+ * @param {string|Function} [options.element='div'] - Element tag name or factory function
+ * @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
+ */
+export function repeat(container, store, arrayKey, options) {
+  const {
+    key,
+    render,
+    element = 'div',
+    preserveFocus = defaultFocusPreservation,
+    preserveScroll = defaultScrollPreservation
+  } = options;
+  // Resolve container
+  const containerEl =
+    typeof container === 'string'
+      ? document.querySelector(container)
+      : container;
+  if (!containerEl) {
+    console.warn(`[Lume.js] repeat(): container "${container}" not found`);
+    return () => { };
+  }
+  if (typeof key !== 'function') {
+    throw new Error('[Lume.js] repeat(): options.key must be a function');
+  }
+  if (typeof render !== 'function') {
+    throw new Error('[Lume.js] repeat(): options.render must be a function');
+  }
+  // key -> HTMLElement
+  const elementsByKey = new Map();
+  const seenKeys = new Set();
+  function createElement() {
+    return typeof element === 'function'
+      ? element()
+      : document.createElement(element);
+  }
+  function updateList() {
+    const items = store[arrayKey];
+    if (!Array.isArray(items)) {
+      console.warn(`[Lume.js] repeat(): store.${arrayKey} is not an array`);
+      return;
+    }
+    // Skip preservation if container is not in document (performance optimization)
+    const shouldPreserve = document.body.contains(containerEl);
+    // Only compute isReorder if scroll preservation needs it
+    let isReorder = false;
+    if (shouldPreserve && preserveScroll) {
+      const previousKeys = new Set(elementsByKey.keys());
+      const currentKeys = new Set(items.map(item => key(item)));
+      isReorder = previousKeys.size === currentKeys.size &&
+        [...previousKeys].every(k => currentKeys.has(k));
+    }
+    // Save state before DOM manipulation
+    const restoreFocus = shouldPreserve && preserveFocus ? preserveFocus(containerEl) : null;
+    const restoreScroll = shouldPreserve && preserveScroll ? preserveScroll(containerEl, { isReorder }) : null;
+    seenKeys.clear();
+    const nextKeys = new Set();
+    const nextEls = [];
+    // Build ordered list of DOM nodes (created or reused)
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const k = key(item);
+      if (seenKeys.has(k)) {
+        console.warn(`[Lume.js] repeat(): duplicate key "${k}"`);
+      }
+      seenKeys.add(k);
+      nextKeys.add(k);
+      let el = elementsByKey.get(k);
+      const isNew = !el;
+      if (isNew) {
+        el = createElement();
+        elementsByKey.set(k, el);
+      }
+      try {
+        if (isNew) {
+          el.__lume_new = true;
+        }
+        render(item, el, i);
+      } catch (err) {
+        console.error(`[Lume.js] repeat(): error rendering key "${k}"`, err);
+      } finally {
+        delete el.__lume_new;
+      }
+      nextEls.push(el);
+    }
+    // Reconcile actual DOM ordering
+    let ptr = containerEl.firstChild;
+    for (let i = 0; i < nextEls.length; i++) {
+      const desired = nextEls[i];
+      if (ptr === desired) {
+        ptr = ptr.nextSibling;
+        continue;
+      }
+      containerEl.insertBefore(desired, ptr);
+    }
+    // Remove leftover children not in nextEls
+    while (ptr) {
+      const next = ptr.nextSibling;
+      containerEl.removeChild(ptr);
+      ptr = next;
+    }
+    // Clean map: remove keys not in nextKeys
+    // Iterate over elementsByKey entries and delete if not in nextKeys
+    if (elementsByKey.size !== nextKeys.size) {
+      for (const k of elementsByKey.keys()) {
+        if (!nextKeys.has(k)) {
+          elementsByKey.delete(k);
+        }
+      }
+    }
+    // Restore state after DOM manipulation
+    if (restoreFocus) restoreFocus();
+    if (restoreScroll) restoreScroll();
+  }
+  // Initial render
+  updateList();
+  // Subscription
+  let unsubscribe;
+  if (typeof store.$subscribe === 'function') {
+    unsubscribe = store.$subscribe(arrayKey, updateList);
+  } else if (typeof store.subscribe === 'function') {
+    // Generic subscribe (e.g. computed)
+    unsubscribe = store.subscribe(() => updateList());
+  } else {
+    console.warn('[Lume.js] repeat(): store is not reactive (no $subscribe or subscribe method)');
+    return () => {
+      containerEl.replaceChildren();
+      elementsByKey.clear();
+      seenKeys.clear();
+    };
+  }
+  return () => {
+    unsubscribe();
+    // Clear DOM elements (replaceChildren is faster than loop)
+    containerEl.replaceChildren();
+    elementsByKey.clear();
+    seenKeys.clear();
+  };
+}

package/src/core/bindDom.js CHANGED Viewed

@@ -4,10 +4,19 @@
  *
  * Binds reactive state to DOM elements using [data-bind].
  * Supports two-way binding for INPUT/TEXTAREA/SELECT.
+ *
+ * Automatically waits for DOMContentLoaded if the document is still loading,
+ * ensuring safe binding regardless of when the function is called.
  *
  * Usage:
  *   import { bindDom } from "lume-js";
+ *
+ *   // Default: Auto-waits for DOM (safe anywhere)
  *   const cleanup = bindDom(document.body, store);
+ *
+ *   // Advanced: Force immediate binding (no auto-wait)
+ *   const cleanup = bindDom(myElement, store, { immediate: true });
+ *
  *   // Later: cleanup();
  *
  * HTML:
@@ -23,9 +32,11 @@ import { resolvePath } from "./utils.js";
  *
  * @param {HTMLElement} root - Root element to scan for [data-bind]
  * @param {object} store - Reactive state object
+ * @param {object} [options] - Optional configuration
+ * @param {boolean} [options.immediate=false] - Skip auto-wait, bind immediately
  * @returns {function} Cleanup function to remove all bindings
  */
-export function bindDom(root, store) {
+export function bindDom(root, store, options = {}) {
   if (!(root instanceof HTMLElement)) {
     throw new Error('bindDom() requires a valid HTMLElement as root');
   }
@@ -34,52 +45,79 @@ export function bindDom(root, store) {
     throw new Error('bindDom() requires a reactive state object');
   }
-  const nodes = root.querySelectorAll("[data-bind]");
-  const cleanups = [];
+  const { immediate = false } = options;
-  nodes.forEach(el => {
-    const bindPath = el.getAttribute("data-bind");
-    if (!bindPath) {
-      console.warn('[Lume.js] Empty data-bind attribute found', el);
-      return;
-    }
+  // Core binding logic extracted to separate function
+  const performBinding = () => {
+    const nodes = root.querySelectorAll("[data-bind]");
+    const cleanups = [];
-    const pathArr = bindPath.split(".");
-    const lastKey = pathArr.pop();
+    nodes.forEach(el => {
+      const bindPath = el.getAttribute("data-bind");
+      if (!bindPath) {
+        console.warn('[Lume.js] Empty data-bind attribute found', el);
+        return;
+      }
-    let target;
-    try {
-      target = resolvePath(store, pathArr);
-    } catch (err) {
-      console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
-      return;
-    }
+      const pathArr = bindPath.split(".");
+      const lastKey = pathArr.pop();
-    if (!target || typeof target.$subscribe !== 'function') {
-      console.warn(`[Lume.js] Target for "${bindPath}" is not a reactive state object`);
-      return;
-    }
+      let target;
+      try {
+        target = resolvePath(store, pathArr);
+      } catch (err) {
+        console.warn(`[Lume.js] Invalid binding path "${bindPath}":`, err.message);
+        return;
+      }
+      if (!target || typeof target.$subscribe !== 'function') {
+        console.warn(`[Lume.js] Target for "${bindPath}" is not a reactive state object`);
+        return;
+      }
-    // Subscribe to changes - receives already-batched notifications
-    const unsubscribe = target.$subscribe(lastKey, val => {
-      updateElement(el, val);
+      // Subscribe to changes - receives already-batched notifications
+      const unsubscribe = target.$subscribe(lastKey, val => {
+        updateElement(el, val);
+      });
+      cleanups.push(unsubscribe);
+      // Two-way binding for form inputs
+      if (isFormInput(el)) {
+        const handler = e => {
+          target[lastKey] = getInputValue(e.target);
+        };
+        el.addEventListener("input", handler);
+        cleanups.push(() => el.removeEventListener("input", handler));
+      }
     });
-    cleanups.push(unsubscribe);
-    // Two-way binding for form inputs
-    if (isFormInput(el)) {
-      const handler = e => {
-        target[lastKey] = getInputValue(e.target);
-      };
-      el.addEventListener("input", handler);
-      cleanups.push(() => el.removeEventListener("input", handler));
-    }
-  });
-  return () => {
-    cleanups.forEach(cleanup => cleanup());
+    return () => {
+      cleanups.forEach(cleanup => cleanup());
+    };
   };
+  // Auto-wait for DOM if needed (unless immediate flag is set)
+  if (!immediate && document.readyState === 'loading') {
+    let cleanup = null;
+    const onReady = () => {
+      cleanup = performBinding();
+    };
+    document.addEventListener('DOMContentLoaded', onReady, { once: true });
+    // Return cleanup function that handles both cases
+    return () => {
+      if (cleanup) {
+        cleanup();
+      } else {
+        // If cleanup hasn't been created yet, remove the event listener
+        document.removeEventListener('DOMContentLoaded', onReady);
+      }
+    };
+  }
+  // Immediate binding (DOM already ready or immediate flag set)
+  return performBinding();
 }
 /**
@@ -89,8 +127,13 @@ export function bindDom(root, store) {
 function updateElement(el, val) {
   if (el.tagName === "INPUT") {
     if (el.type === "checkbox") {
+      // Single checkbox: bind to boolean value
+      // For multiple checkboxes, use nested state objects:
+      //   <input data-bind="tags.javascript"> → state({ tags: state({ javascript: true }) })
       el.checked = Boolean(val);
     } else if (el.type === "radio") {
+      // Radio: checked when el.value matches state value
+      // String() handles null/undefined gracefully (no radio selected)
       el.checked = el.value === String(val);
     } else {
       el.value = val ?? '';

package/src/core/state.js CHANGED Viewed

@@ -29,6 +29,9 @@
  * @param {Object} obj - Initial state object
  * @returns {Proxy} Reactive proxy with $subscribe method
  */
+// Internal symbol used to mark reactive proxies (non-enumerable via Proxy trap)
+const REACTIVE_MARKER = Symbol('__LUME_REACTIVE__');
 export function state(obj) {
   // Validate input
   if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
@@ -59,9 +62,11 @@ export function state(obj) {
       flushScheduled = false;
       // Notify all subscribers of changed keys
+      // Snapshot listeners array to handle unsubscribes during iteration
       for (const [key, value] of pendingNotifications) {
         if (listeners[key]) {
-          listeners[key].forEach(fn => fn(value));
+          const subscribersSnapshot = Array.from(listeners[key]);
+          subscribersSnapshot.forEach(fn => fn(value));
         }
       }
@@ -76,6 +81,12 @@ export function state(obj) {
   const proxy = new Proxy(obj, {
     get(target, key) {
+      // Reactive marker check (avoid tracking for internal symbol)
+      if (key === REACTIVE_MARKER) return true;
+      // Skip effect tracking for internal meta methods (e.g. $subscribe)
+      if (typeof key === 'string' && key.startsWith('$')) {
+        return target[key];
+      }
       // Support effect tracking
       // Check if we're inside an effect context
       if (typeof globalThis.__LUME_CURRENT_EFFECT__ !== 'undefined') {
@@ -156,4 +167,14 @@ export function state(obj) {
   };
   return proxy;
+}
+/**
+ * Determine if an object is a Lume reactive proxy.
+ * Defensive: ensures object and marker presence.
+ * @param {any} obj
+ * @returns {boolean}
+ */
+export function isReactive(obj) {
+  return !!(obj && typeof obj === 'object' && obj[REACTIVE_MARKER]);
 }

package/src/index.d.ts CHANGED Viewed

@@ -58,20 +58,39 @@ export type ReactiveState<T extends object> = T & {
  */
 export function state<T extends object>(obj: T): ReactiveState<T>;
+/**
+ * Options for bindDom function
+ */
+export interface BindDomOptions {
+  /**
+   * Skip auto-wait for DOM, bind immediately
+   * @default false
+   */
+  immediate?: boolean;
+}
 /**
  * Bind reactive state to DOM elements
  *
+ * Automatically waits for DOMContentLoaded if the document is still loading,
+ * ensuring safe binding regardless of when the function is called.
+ *
  * @param root - Root element to scan for [data-bind] attributes
  * @param store - Reactive state object
+ * @param options - Optional configuration
  * @returns Cleanup function to remove all bindings
  * @throws {Error} If root is not an HTMLElement
  * @throws {Error} If store is not a reactive state object
  *
  * @example
  * ```typescript
+ * // Default: Auto-waits for DOM (safe anywhere)
  * const store = state({ count: 0 });
  * const cleanup = bindDom(document.body, store);
  *
+ * // Advanced: Force immediate binding (no auto-wait)
+ * const cleanup = bindDom(myElement, store, { immediate: true });
+ *
  * // Later: cleanup all bindings
  * cleanup();
  * ```
@@ -84,7 +103,8 @@ export function state<T extends object>(obj: T): ReactiveState<T>;
  */
 export function bindDom(
   root: HTMLElement,
-  store: ReactiveState<any>
+  store: ReactiveState<any>,
+  options?: BindDomOptions
 ): Unsubscribe;
 /**
@@ -112,4 +132,11 @@ export function bindDom(
  * cleanup(); // Stop the effect
  * ```
  */
-export function effect(fn: () => void): Unsubscribe;
+export function effect(fn: () => void): Unsubscribe;
+/**
+ * Check if a value is a Lume reactive proxy produced by state().
+ * Returns true only for objects created by state().
+ * @param obj - Value to check
+ */
+export function isReactive(obj: any): boolean;

package/src/index.js CHANGED Viewed

@@ -10,6 +10,6 @@
  *   import { state, bindDom, effect } from "lume-js";
  */
-export { state } from "./core/state.js";
+export { state, isReactive } from "./core/state.js";
 export { bindDom } from "./core/bindDom.js";
 export { effect } from "./core/effect.js";