lume-js 2.2.0 → 2.3.0

package/README.md

@@ -1,17 +1,28 @@
-# Lume.js
-
-**Reactivity that follows web standards.**
-
-Minimal reactive state management using only standard JavaScript and HTML. No custom syntax, no build step required, no framework lock-in.
-
-> **Current Release:** v2.2.0
-> Install: `npm install lume-js`  
-> Bundle size: ~2.09KB gzipped | 348 tests passing
+<div align="center">
+  <img src="lume-logo.png" alt="Lume.js" width="128"><br><br>
+  <h3>Lume.js</h3>
+  <p><strong>Reactivity that follows web standards.</strong></p>
+  <p>
+    Minimal reactive state management using only standard JavaScript and HTML.<br>
+    No custom syntax &nbsp;·&nbsp; No build step &nbsp;·&nbsp; No framework lock-in.<br>
+    <strong>1.45 KB universal core</strong> &nbsp;·&nbsp; <strong>2.66 KB with DOM</strong>
+  </p>
+  <p>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+    &nbsp;
+    <a href="package.json"><img src="https://img.shields.io/badge/version-2.3.0-orange.svg" alt="v2.3.0"></a>
+    &nbsp;
+    <a href="tests/"><img src="https://img.shields.io/badge/tests-425%20passing-brightgreen.svg" alt="425 tests"></a>
+    &nbsp;
+    <a href="scripts/check-size.js"><img src="https://img.shields.io/badge/universal%20core-1.45KB-blue.svg" alt="universal core 1.45KB"></a>
+    &nbsp;
+    <a href="scripts/check-size.js"><img src="https://img.shields.io/badge/core%20%2B%20DOM-2.66KB-blue.svg" alt="core + DOM 2.66KB"></a>
+  </p>
+  <p><code>npm install lume-js</code></p>
+  <p><a href="https://sathvikc.github.io/lume-js/"><strong>Docs & live examples →</strong></a></p>
+</div>
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-2.2.0-orange.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-348%20passing-brightgreen.svg)](tests/)
-[![Size](https://img.shields.io/badge/core-2.09KB-blue.svg)](scripts/check-size.js)
+---
 
 ## Why Lume.js?
 
@@ -19,7 +30,7 @@ Minimal reactive state management using only standard JavaScript and HTML. No cu
 |---------|---------|-----------|-----|-------|
 | Custom Syntax | ❌ No | ✅ `x-data` | ✅ `v-bind` | ✅ JSX |
 | Build Step | ❌ Optional | ❌ Optional | ⚠️ Recommended | ✅ Required |
-| Bundle Size | ~2.09KB | ~15KB | ~35KB | ~45KB |
+| Bundle Size | 1.45–2.66KB | ~15KB | ~35KB | ~45KB |
 | HTML Validation | ✅ Pass | ⚠️ Warnings | ⚠️ Warnings | ❌ JSX |
 | Extensible Handlers | ✅ | ❌ Built-in only | ❌ Built-in only | N/A |
 
@@ -29,6 +40,15 @@ Minimal reactive state management using only standard JavaScript and HTML. No cu
 
 ## Installation
 
+### Pick your entry
+
+| Entry | Size (gz) | Contents | For |
+|-------|-----------|----------|-----|
+| `lume-js/state` | **1.45 KB** | `state`, `batch`, `withReadObserver` | Node, Deno, Bun, workers, CLI — anywhere without a DOM |
+| `lume-js` | **2.66 KB** | + `bindDom`, `effect` | Browsers |
+| `lume-js/addons` | pay per import | `computed`, `watch`, `repeat`, `persist`, … | Optional patterns |
+| `lume-js/handlers` | pay per import | `show`, `classToggle`, `on`, … | Extra reactive attributes |
+
 ### Via CDN (Recommended for simple projects)
 
 ```html
@@ -37,6 +57,14 @@ Minimal reactive state management using only standard JavaScript and HTML. No cu
 </script>
 ```
 
+DOM-free kernel only (servers, workers, embedded):
+
+```html
+<script type="module">
+  import { state, batch } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/state.min.mjs';
+</script>
+```
+
 ### Via NPM (Recommended for bundlers)
 
 ```bash
@@ -44,9 +72,13 @@ npm install lume-js
 ```
 
 ```javascript
-import { state, bindDom } from 'lume-js';
+import { state, bindDom } from 'lume-js';        // browser: full core
+import { state, batch } from 'lume-js/state';    // Node/CLI/workers: 1.45 KB kernel
 ```
 
+> **→ Using Lume without a DOM?** See the [Universal core guide](docs/guides/universal-core.md).
+
+
 ### Browser Support
 
 | Browser | Minimum version |
@@ -81,6 +113,37 @@ bindDom(document.body, store);
 
 That's it — two-way binding, no build step, valid HTML.
 
+### Lists? Also just HTML.
+
+```html
+<ul id="todos">
+  <template>
+    <li><span data-bind="title"></span> <em data-bind="$index"></em></li>
+  </template>
+</ul>
+```
+
+```javascript
+import { repeat } from 'lume-js/addons';
+
+repeat('#todos', store, 'todos', { key: t => t.id, template: true });
+```
+
+The row structure is a standard `<template>` element — no `createElement`, no JSX, no custom syntax.
+
+### Multiple stores? Batch them.
+
+```javascript
+import { batch } from 'lume-js';
+
+batch(() => {
+  cart.items = [...cart.items, item];
+  totals.sum += item.price;
+  ui.message = 'Added!';
+});
+// effects depending on several stores ran exactly ONCE, synchronously
+```
+
 ---
 
 ## Built-in Reactive Attributes
@@ -142,6 +205,7 @@ bindDom(document.body, store, {
 | `ariaAttr(name)` | `data-aria-pressed="key"` | Sets ARIA attribute to "true"/"false" |
 | `classToggle(...names)` | `data-class-active="key"` | Toggles individual CSS classes |
 | `stringAttr(name)` | `data-href="key"` | Sets string attributes (removes on null) |
+| `on(...types)` | `data-onclick="key"` | Wires the function at that state key as an event listener |
 | `htmlAttrs()` | *(all of the above)* | One-import preset — all standard HTML + ARIA attrs |
 
 ### Presets
@@ -181,7 +245,10 @@ import { computed, watch, repeat } from 'lume-js/addons';
 | `effect(fn)` *(core)* | Write derived values back into the store, or trigger side effects on state change |
 | `computed(fn)` | Derive a read-only value from state to consume *outside* the store (templates, display logic) |
 | `watch(store, key, fn)` | React to a *specific* key changing — DOM updates, analytics, syncing external state |
-| `repeat(container, store, key, opts)` | Render a keyed list with element reuse (no full re-render on change) |
+| `repeat(container, store, key, opts)` | Render a keyed list with element reuse — incl. declarative `template:` mode bound straight from a `<template>` element |
+| `persist(store, key, opts)` | Sync selected keys with localStorage/sessionStorage — hydrate on call, auto-save on change |
+| `createCleanupGroup()` | Collect multiple cleanup/unsubscribe functions and dispose them all at once |
+| `hydrateState(selector?)` | Read initial state from a `<script type="application/json">` tag (SSR hydration) |
 
 **Quick rule:** `effect` for writing back into state → `computed` for reading outside state → `watch` for observing a single key → `repeat` for arrays in the DOM.
 
@@ -221,7 +288,7 @@ watch(store, 'count', (val) => {
 
 ## Documentation
 
-Full documentation is available in the [docs/](docs/) directory:
+Browse the full docs at **[sathvikc.github.io/lume-js](https://sathvikc.github.io/lume-js/)**, or read the source markdown in the [docs/](docs/) directory:
 
 - **Tutorials**
     - [Build a Todo App](docs/tutorials/build-todo-app.md)
@@ -231,11 +298,15 @@ Full documentation is available in the [docs/](docs/) directory:
     - [state()](docs/api/core/state.md) — Reactive state
     - [bindDom()](docs/api/core/bindDom.md) — DOM binding
     - [effect()](docs/api/core/effect.md) — Reactive effects
+    - [batch()](docs/api/core/batch.md) — Cross-store write batching
     - [Handlers](docs/api/core/handlers.md) — Extensible attribute handlers
-    - [Plugins](docs/api/core/plugins.md) — State extension system
-    - [Addons](docs/api/addons/computed.md) — computed, watch, repeat, debug
+    - [Plugins](docs/api/addons/withPlugins.md) — State extension system
+    - [Addons](docs/api/addons/computed.md) — computed, watch, repeat, persist, createCleanupGroup, hydrateState
 - **Guides**
+    - [Universal core (Node, CLI, workers)](docs/guides/universal-core.md) — using `lume-js/state` without a DOM
     - [Choosing reactive primitives](docs/guides/choosing-reactive-primitives.md) — when to use effect vs computed vs watch
+    - [Cleanup & Disposal](docs/guides/cleanup-and-dispose.md) — tearing down effects, bindings, and subscriptions
+    - [SSR & Hydration](docs/guides/ssr-hydration.md) — server-rendered HTML with reactive hydration
 - **Design**
     - [Design Decisions](docs/design/design-decisions.md)
 

package/dist/addons.min.mjs

@@ -1 +1 @@
-function e(e,...t){void 0!==console&&"function"==typeof console.warn&&console.warn(e,...t)}function t(e,...t){void 0!==console&&"function"==typeof console.error&&console.error(e,...t)}const o=new Set;function n(e,t){o.add(e);try{return t()}finally{o.delete(e)}}let r=null;function c(e,o){if("function"!=typeof e)throw Error("effect() requires a function");const c=[];let s=!1;const i=()=>{if(!s){s=!0;try{e()}catch(e){throw t("[Lume.js effect] Error in effect:",e),e}finally{s=!1}}};if(Array.isArray(o)){for(const e of o)if(Array.isArray(e)&&e.length>=2){const[t,...o]=e;if(t&&"function"==typeof t.$subscribe)for(const e of o){let o=!0;const n=t.$subscribe(e,()=>{o?o=!1:i()});c.push(n)}}i()}else{const o=()=>{if(s)return;const i=c.splice(0),l={fn:e,cleanups:c,execute:o,tracking:{}},f=r;r=l,s=!0;try{n((e,t,o)=>{r===l&&(l.tracking[t]||(l.tracking[t]=!0,l.cleanups.push(o(t,l.execute))))},e)}catch(e){throw c.length=0,c.push(...i),t("[Lume.js effect] Error in effect:",e),e}finally{r=f,s=!1}if(c.length>0)for(const e of i)e();else c.push(...i)};o()}return()=>{for(;c.length;)c.pop()()}}function s(e){if("function"!=typeof e)throw Error("computed() requires a function");let o,n=!1,r=!1,s=!1;const i=[],l=c(()=>{if(!r&&!s){r=!0;try{const t=e();n&&Object.is(t,o)||(o=t,n=!0,i.forEach(e=>e(o)))}catch(e){t("[Lume.js computed] Error in computation:",e),n&&void 0===o||(o=void 0,n=!0,i.forEach(e=>e(o)))}finally{queueMicrotask(()=>{s||(r=!1)})}}});return{get value(){if(!n)throw Error("Computed value accessed before initialization");return o},subscribe(e){if("function"!=typeof e)throw Error("subscribe() requires a function");return i.push(e),n&&e(o),()=>{const t=i.indexOf(e);t>-1&&i.splice(t,1)}},dispose(){s=!0,l(),i.length=0,n=!1,r=!1}}}function i(e,t,o,{immediate:n=!0}={}){if(!e.$subscribe)throw Error("store must be created with state()");if(!n){let n=!1;return e.$subscribe(t,e=>{n?o(e):n=!0})}return e.$subscribe(t,o)}function l(e){const t=document.activeElement;if(!e.contains(t))return null;let o=null,n=null;return"INPUT"!==t.tagName&&"TEXTAREA"!==t.tagName||(o=t.selectionStart,n=t.selectionEnd),()=>{document.body.contains(t)&&(t.focus(),null!==o&&null!==n&&t.setSelectionRange(o,n))}}function f(e,t={}){const{isReorder:o=!1}=t,n=e.scrollTop;if(0===n)return()=>{e.scrollTop=0};let r=null,c=0;if(!o){const t=e.getBoundingClientRect();for(let o=e.firstElementChild;o;o=o.nextElementSibling){const e=o.getBoundingClientRect();if(e.bottom>t.top){r=o,c=e.top-t.top;break}}}return()=>{if(r&&document.body.contains(r)){const t=r.getBoundingClientRect(),o=e.getBoundingClientRect(),n=t.top-o.top-c;e.scrollTop=e.scrollTop+n}else e.scrollTop=n}}function u(o,n,r,c){const{key:s,render:i,create:u,update:a,remove:g,element:p="div",preserveFocus:d=l,preserveScroll:b=f}=c,h="string"==typeof o?document.querySelector(o):o;if(!h)return e(`[Lume.js] repeat(): container "${o}" not found`),()=>{};if("function"!=typeof s)throw Error("[Lume.js] repeat(): options.key must be a function");if("function"!=typeof i&&"function"!=typeof u)throw Error("[Lume.js] repeat(): options.render or options.create must be a function");const y=new Map,m=new Map,$=new Map,w=new Map,E=new Set;function j(){return"function"==typeof p?p():document.createElement(p)}function S(){const o=n[r];if(!Array.isArray(o))return void e(`[Lume.js] repeat(): store.${r} is not an array`);let c=!1;if(b&&y.size===o.length){c=!0;for(let e=0;e<o.length;e++)if(!y.has(s(o[e]))){c=!1;break}}E.clear();const l=[];for(let n=0;n<o.length;n++){const r=o[n],c=s(r);if(E.has(c)){e(`[Lume.js] repeat(): duplicate key "${c}"`);continue}E.add(c);let f=y.get(c);const g=!f;g&&(f=j(),y.set(c,f));try{if(g&&u){const e=u(r,f,n);"function"==typeof e&&w.set(c,e)}const e=m.get(c),t=$.get(c);a?e===r&&t===n||a(r,f,n,{isFirstRender:g}):i&&i(r,f,n),m.set(c,r),$.set(c,n)}catch(e){t(`[Lume.js] repeat(): error rendering key "${c}":`,e)}l.push(f)}!function(e,o,n){const r=document.body.contains(e),c=r&&d?d(e):null,s=r&&b?b(e,{isReorder:n}):null;(()=>{if(function(e,t){let o=e.firstChild;for(let n=0;n<t.length;n++){const r=t[n];o!==r?e.insertBefore(r,o):o=o.nextSibling}for(;o;){const t=o.nextSibling;e.removeChild(o),o=t}}(h,l),y.size!==E.size)for(const e of y.keys())if(!E.has(e)){const o=y.get(e),n=m.get(e),r=w.get(e);if("function"==typeof r)try{r()}catch(o){t(`[Lume.js] repeat(): cleanup error for key "${e}":`,o)}"function"==typeof g&&o&&g(n,o),y.delete(e),m.delete(e),$.delete(e),w.delete(e)}})(),c&&c(),s&&s()}(h,0,c)}let L;if("function"==typeof n.$subscribe)L=n.$subscribe(r,S);else{if("function"!=typeof n.subscribe)return S(),e("[Lume.js] repeat(): store is not reactive (no $subscribe or subscribe method)"),()=>{for(const[e,o]of y){const n=m.get(e),r=w.get(e);if("function"==typeof r)try{r()}catch(o){t(`[Lume.js] repeat(): cleanup error for key "${e}":`,o)}"function"==typeof g&&g(n,o)}h.replaceChildren(),y.clear(),m.clear(),$.clear(),w.clear(),E.clear()};{const e=n.subscribe(()=>S());S(),L="function"==typeof e?e:()=>{e?.unsubscribe?.()}}}return()=>{"function"==typeof L&&L();for(const[e,o]of y){const n=m.get(e),r=w.get(e);if("function"==typeof r)try{r()}catch(o){t(`[Lume.js] repeat(): cleanup error for key "${e}":`,o)}"function"==typeof g&&g(n,o)}h.replaceChildren(),y.clear(),m.clear(),$.clear(),w.clear(),E.clear()}}let a=!0,g=null;const p=new Map;function d(e){return null===g||("string"==typeof g?e.includes(g):!(g instanceof RegExp)||g.test(e))}function b(e){return p.has(e)||p.set(e,{gets:new Map,sets:new Map,notifies:new Map}),p.get(e)}function h(e,t,o){const n=b(e)[t];n.set(o,(n.get(o)||0)+1)}const y=100,m=97;function $(e){try{const t=JSON.stringify(e);return t.length>y?t.slice(0,m)+"...":t}catch{return e+""}}function w(e={}){const t=e.label??"store",o=(t,o)=>{const n=e[t];return void 0!==n?n:o};return{name:"debug:"+t,onInit:()=>{a&&console.log(`%c[${t}]%c initialized`,"color: #888; font-weight: bold","color: inherit")},onGet:(e,n)=>("string"==typeof e&&e.startsWith("$")||(h(t,"gets",e),a&&o("logGet",!1)&&d(e)&&console.log(`%c[${t}]%c GET %c${e}%c = ${$(n)}`,"color: #888; font-weight: bold","color: #4CAF50","color: #2196F3; font-weight: bold","color: inherit")),n),onSet:(e,n,r)=>("string"==typeof e&&e.startsWith("$")||(h(t,"sets",e),a&&o("logSet",!0)&&d(e)&&(console.log(`%c[${t}]%c SET %c${e}%c: ${$(r)} → ${$(n)}`,"color: #888; font-weight: bold","color: #FF9800","color: #2196F3; font-weight: bold","color: inherit"),o("trace",!1)&&console.trace(`%c[${t}] Stack trace for ${e}`,"color: #888"))),n),onSubscribe:e=>{a&&d(e)&&console.log(`%c[${t}]%c SUBSCRIBE %c${e}`,"color: #888; font-weight: bold","color: #9C27B0","color: #2196F3; font-weight: bold")},onNotify:(e,n)=>{"string"==typeof e&&e.startsWith("$")||(h(t,"notifies",e),a&&o("logNotify",!0)&&d(e)&&console.log(`%c[${t}]%c NOTIFY %c${e}%c = ${$(n)}`,"color: #888; font-weight: bold","color: #E91E63","color: #2196F3; font-weight: bold","color: inherit"))}}}const E={enable(){a=!0,console.log("%c[lume-debug]%c Logging enabled","color: #888; font-weight: bold","color: #4CAF50")},disable(){a=!1,console.log("%c[lume-debug]%c Logging disabled","color: #888; font-weight: bold","color: #F44336")},isEnabled:()=>a,filter(e){g=e,console.log(null===e?"%c[lume-debug]%c Filter cleared":"%c[lume-debug]%c Filter set: "+e,"color: #888; font-weight: bold","color: inherit")},getFilter:()=>g,stats(){const e={};for(const[t,o]of p)e[t]={gets:Object.fromEntries(o.gets),sets:Object.fromEntries(o.sets),notifies:Object.fromEntries(o.notifies)};return e},logStats(){const e=this.stats();if(0===Object.keys(e).length)return console.log("%c[lume-debug]%c No stats collected yet","color: #888; font-weight: bold","color: inherit"),e;console.group("%c[lume-debug] Statistics","color: #888; font-weight: bold");for(const[t,o]of Object.entries(e)){console.group("%c"+t,"color: #2196F3; font-weight: bold");const e=[],n=new Set([...Object.keys(o.gets),...Object.keys(o.sets),...Object.keys(o.notifies)]);for(const t of n)e.push({key:t,gets:o.gets[t]||0,sets:o.sets[t]||0,notifies:o.notifies[t]||0});e.length>0&&console.table(e),console.groupEnd()}return console.groupEnd(),e},resetStats(){p.clear(),console.log("%c[lume-debug]%c Stats reset","color: #888; font-weight: bold","color: inherit")}};function j(e,o=[]){if(!o.length)return e;for(const e of o)try{e.onInit?.()}catch(o){t(`[Lume.js] Plugin "${e.name}" error in onInit:`,o)}const n=new Map;let r;return"function"==typeof e.$beforeFlush&&(r=e.$beforeFlush(function(){for(const[e,r]of n)for(const n of o)try{n.onNotify?.(e,r)}catch(e){t(`[Lume.js] Plugin "${n.name}" error in onNotify:`,e)}n.clear()})),new Proxy(e,{get(e,c){if("$dispose"===c)return()=>{r&&r(),n.clear()};if("string"==typeof c&&c.startsWith("$")){const n=e[c];return"$subscribe"===c&&"function"==typeof n?(e,r)=>{for(const n of o)try{n.onSubscribe?.(e)}catch(e){t(`[Lume.js] Plugin "${n.name}" error in onSubscribe:`,e)}return n(e,r)}:n}let s=e[c];for(const e of o)try{const t=e.onGet?.(c,s);void 0!==t&&(s=t)}catch(o){t(`[Lume.js] Plugin "${e.name}" error in onGet:`,o)}return s},set(e,r,c){const s=e[r];let i=c;for(const e of o)try{const t=e.onSet?.(r,i,s);void 0!==t&&(i=t)}catch(o){t(`[Lume.js] Plugin "${e.name}" error in onSet:`,o)}return Object.is(i,s)||n.set(r,i),e[r]=i,!0}})}function S(){const e=[];return{add(t){"function"==typeof t&&e.push(t)},dispose(){for(;e.length;){const t=e.pop();try{t()}catch(e){}}}}}function L(e="#__LUME_DATA__"){const t="undefined"!=typeof document?document.querySelector(e):null;if(!t)return{};try{return JSON.parse(t.textContent)}catch{return{}}}function k(e){return!(!e||"object"!=typeof e||"function"!=typeof e.$subscribe)}export{s as computed,S as createCleanupGroup,w as createDebugPlugin,E as debug,l as defaultFocusPreservation,f as defaultScrollPreservation,L as hydrateState,k as isReactive,u as repeat,i as watch,j as withPlugins};
+function e(e,...t){void 0!==console&&"function"==typeof console.warn&&console.warn(e,...t)}function t(e,...t){void 0!==console&&"function"==typeof console.error&&console.error(e,...t)}const o=new Set,n=Symbol.for("lume.reactive");function r(e,t){o.add(e);try{return t()}finally{o.delete(e)}}let c=null;function s(e,o){if("function"!=typeof e)throw Error("effect() requires a function");const n=[];let s=!1;const i=()=>{if(!s){s=!0;try{e()}catch(e){throw t("[Lume.js effect] Error in effect:",e),e}finally{s=!1}}};if(Array.isArray(o)){let e=!1,t=!1;n.push(()=>{t=!0});const r=()=>{e||(e=!0,queueMicrotask(()=>{if(e=!1,!t)try{i()}catch{}}))};for(const e of o)if(Array.isArray(e)&&e.length>=2){const[t,...o]=e;if(t&&"function"==typeof t.$subscribe)for(const e of o){let o=!0;const c=t.$subscribe(e,()=>{o?o=!1:r()});n.push(c)}}i()}else{const o=()=>{if(s)return;const i=n.splice(0),l={fn:e,cleanups:n,execute:o,tracking:new WeakMap},u=c;c=l,s=!0;try{r((e,t,o)=>{if(c!==l)return;let n=l.tracking.get(e);n||(n=new Set,l.tracking.set(e,n)),n.has(t)||(n.add(t),l.cleanups.push(o(t,l.execute)))},e)}catch(e){throw n.length=0,n.push(...i),t("[Lume.js effect] Error in effect:",e),e}finally{c=u,s=!1}if(n.length>0)for(const e of i)e();else n.push(...i)};o()}return()=>{for(;n.length;)n.pop()()}}function i(e){if("function"!=typeof e)throw Error("computed() requires a function");let o,n=!1,r=!1,c=!1;const i=[],l=s(()=>{if(!r&&!c){r=!0;try{const t=e();n&&Object.is(t,o)||(o=t,n=!0,i.forEach(e=>e(o)))}catch(e){t("[Lume.js computed] Error in computation:",e),n&&void 0===o||(o=void 0,n=!0,i.forEach(e=>e(o)))}finally{queueMicrotask(()=>{c||(r=!1)})}}});return{get value(){if(!n)throw Error("Computed value accessed before initialization");return o},subscribe(e){if("function"!=typeof e)throw Error("subscribe() requires a function");return i.push(e),n&&e(o),()=>{const t=i.indexOf(e);t>-1&&i.splice(t,1)}},dispose(){c=!0,l(),i.length=0,n=!1,r=!1}}}function l(e,t,o,{immediate:n=!0}={}){if(!e.$subscribe)throw Error("store must be created with state()");if(!n){let n=!1;return e.$subscribe(t,e=>{n?o(e):n=!0})}return e.$subscribe(t,o)}function u(e,t){"INPUT"===e.tagName?"checkbox"===e.type?e.checked=!!t:"radio"===e.type?e.checked=e.value===t+"":e.value=t??"":"TEXTAREA"===e.tagName||"SELECT"===e.tagName?e.value=t??"":e.textContent=t??""}function f(e,t){let o=e;if(!0===e?o=t.querySelector("template"):"string"==typeof e&&(o=document.querySelector(e)),!o||"TEMPLATE"!==o.tagName)throw Error("[Lume.js] repeat(): template not found or not a <template> element");if(1!==o.content.children.length)throw Error("[Lume.js] repeat(): template must contain exactly one root element");return o.content.firstElementChild}function a(e){const t=[],o=e=>{const o=e.getAttribute("data-bind");t.push({node:e,path:o,keys:"$item"===o||"$index"===o?null:o.split(".")})};e.hasAttribute("data-bind")&&o(e);for(const t of e.querySelectorAll("[data-bind]"))o(t);return t}function p(e,t,o){for(const n of e){let e;if("$index"===n.path)e=o;else if("$item"===n.path)e=t;else{e=t;for(let t=0;t<n.keys.length&&null!=e;t++)e=e[n.keys[t]]}u(n.node,e)}}function g(e){const t=document.activeElement;if(!e.contains(t))return null;let o=null,n=null;return"INPUT"!==t.tagName&&"TEXTAREA"!==t.tagName||(o=t.selectionStart,n=t.selectionEnd),()=>{document.body.contains(t)&&(t.focus(),null!==o&&null!==n&&t.setSelectionRange(o,n))}}function d(e,t={}){const{isReorder:o=!1}=t,n=e.scrollTop;if(0===n)return()=>{e.scrollTop=0};let r=null,c=0;if(!o){const t=e.getBoundingClientRect();for(let o=e.firstElementChild;o;o=o.nextElementSibling){const e=o.getBoundingClientRect();if(e.bottom>t.top){r=o,c=e.top-t.top;break}}}return()=>{if(r&&document.body.contains(r)){const t=r.getBoundingClientRect(),o=e.getBoundingClientRect(),n=t.top-o.top-c;e.scrollTop=e.scrollTop+n}else e.scrollTop=n}}function y(o,n,r,c){const{key:s,render:i,create:l,update:u,remove:y,template:h=null,element:b="div",preserveFocus:m=g,preserveScroll:$=d}=c,w="string"==typeof o?document.querySelector(o):o;if(!w)return e(`[Lume.js] repeat(): container "${o}" not found`),()=>{};if("function"!=typeof s)throw Error("[Lume.js] repeat(): options.key must be a function");const j=h?f(h,w):null;if(j&&"function"==typeof i&&e("[Lume.js] repeat(): options.render is ignored when options.template is set — use create/update instead"),!j&&"function"!=typeof i&&"function"!=typeof l)throw Error("[Lume.js] repeat(): options.render or options.create must be a function");const E=new Map,S=new Map,k=new Map,L=new Map,v=new Map,A=new Set;function N(){return j?j.cloneNode(!0):"function"==typeof b?b():document.createElement(b)}function O(){const o=n[r];if(!Array.isArray(o))return void e(`[Lume.js] repeat(): store.${r} is not an array`);let c=!1;if($&&E.size===o.length){c=!0;for(let e=0;e<o.length;e++)if(!E.has(s(o[e]))){c=!1;break}}A.clear();const f=[];for(let n=0;n<o.length;n++){const r=o[n],c=s(r);if(A.has(c)){e(`[Lume.js] repeat(): duplicate key "${c}"`);continue}A.add(c);let g=E.get(c);const d=!g;d&&(g=N(),E.set(c,g),j&&v.set(c,a(g)));try{if(d&&l){const e=l(r,g,n);"function"==typeof e&&L.set(c,e)}const e=S.get(c),t=k.get(c);j?e===r&&t===n||(p(v.get(c),r,n),u&&u(r,g,n,{isFirstRender:d})):u?e===r&&t===n||u(r,g,n,{isFirstRender:d}):i&&i(r,g,n),S.set(c,r),k.set(c,n)}catch(e){t(`[Lume.js] repeat(): error rendering key "${c}":`,e)}f.push(g)}!function(e,o,n){const r=document.body.contains(e),c=r&&m?m(e):null,s=r&&$?$(e,{isReorder:n}):null;(()=>{if(function(e,t){let o=e.firstChild;for(let n=0;n<t.length;n++){const r=t[n];o!==r?e.insertBefore(r,o):o=o.nextSibling}for(;o;){const t=o.nextSibling;e.removeChild(o),o=t}}(w,f),E.size!==A.size)for(const e of E.keys())if(!A.has(e)){const o=E.get(e),n=S.get(e),r=L.get(e);if("function"==typeof r)try{r()}catch(o){t(`[Lume.js] repeat(): cleanup error for key "${e}":`,o)}"function"==typeof y&&o&&y(n,o),E.delete(e),S.delete(e),k.delete(e),L.delete(e),v.delete(e)}})(),c&&c(),s&&s()}(w,0,c)}let T;if("function"==typeof n.$subscribe)T=n.$subscribe(r,O);else{if("function"!=typeof n.subscribe)return O(),e("[Lume.js] repeat(): store is not reactive (no $subscribe or subscribe method)"),()=>{for(const[e,o]of E){const n=S.get(e),r=L.get(e);if("function"==typeof r)try{r()}catch(o){t(`[Lume.js] repeat(): cleanup error for key "${e}":`,o)}"function"==typeof y&&y(n,o)}w.replaceChildren(),E.clear(),S.clear(),k.clear(),L.clear(),v.clear(),A.clear()};{const e=n.subscribe(()=>O());O(),T="function"==typeof e?e:()=>{e?.unsubscribe?.()}}}return()=>{"function"==typeof T&&T();for(const[e,o]of E){const n=S.get(e),r=L.get(e);if("function"==typeof r)try{r()}catch(o){t(`[Lume.js] repeat(): cleanup error for key "${e}":`,o)}"function"==typeof y&&y(n,o)}w.replaceChildren(),E.clear(),S.clear(),k.clear(),L.clear(),v.clear(),A.clear()}}let h=!0,b=null;const m=new Map;function $(e){return null===b||("string"==typeof b?e.includes(b):!(b instanceof RegExp)||b.test(e))}function w(e){return m.has(e)||m.set(e,{gets:new Map,sets:new Map,notifies:new Map}),m.get(e)}function j(e,t,o){const n=w(e)[t];n.set(o,(n.get(o)||0)+1)}const E=100,S=97;function k(e){try{const t=JSON.stringify(e);return t.length>E?t.slice(0,S)+"...":t}catch{return e+""}}function L(e={}){const t=e.label??"store",o=(t,o)=>{const n=e[t];return void 0!==n?n:o};return{name:"debug:"+t,onInit:()=>{h&&console.log(`%c[${t}]%c initialized`,"color: #888; font-weight: bold","color: inherit")},onGet:(e,n)=>("string"==typeof e&&e.startsWith("$")||(j(t,"gets",e),h&&o("logGet",!1)&&$(e)&&console.log(`%c[${t}]%c GET %c${e}%c = ${k(n)}`,"color: #888; font-weight: bold","color: #4CAF50","color: #2196F3; font-weight: bold","color: inherit")),n),onSet:(e,n,r)=>("string"==typeof e&&e.startsWith("$")||(j(t,"sets",e),h&&o("logSet",!0)&&$(e)&&(console.log(`%c[${t}]%c SET %c${e}%c: ${k(r)} → ${k(n)}`,"color: #888; font-weight: bold","color: #FF9800","color: #2196F3; font-weight: bold","color: inherit"),o("trace",!1)&&console.trace(`%c[${t}] Stack trace for ${e}`,"color: #888"))),n),onSubscribe:e=>{h&&$(e)&&console.log(`%c[${t}]%c SUBSCRIBE %c${e}`,"color: #888; font-weight: bold","color: #9C27B0","color: #2196F3; font-weight: bold")},onNotify:(e,n)=>{"string"==typeof e&&e.startsWith("$")||(j(t,"notifies",e),h&&o("logNotify",!0)&&$(e)&&console.log(`%c[${t}]%c NOTIFY %c${e}%c = ${k(n)}`,"color: #888; font-weight: bold","color: #E91E63","color: #2196F3; font-weight: bold","color: inherit"))}}}const v={enable(){h=!0,console.log("%c[lume-debug]%c Logging enabled","color: #888; font-weight: bold","color: #4CAF50")},disable(){h=!1,console.log("%c[lume-debug]%c Logging disabled","color: #888; font-weight: bold","color: #F44336")},isEnabled:()=>h,filter(e){b=e,console.log(null===e?"%c[lume-debug]%c Filter cleared":"%c[lume-debug]%c Filter set: "+e,"color: #888; font-weight: bold","color: inherit")},getFilter:()=>b,stats(){const e={};for(const[t,o]of m)e[t]={gets:Object.fromEntries(o.gets),sets:Object.fromEntries(o.sets),notifies:Object.fromEntries(o.notifies)};return e},logStats(){const e=this.stats();if(0===Object.keys(e).length)return console.log("%c[lume-debug]%c No stats collected yet","color: #888; font-weight: bold","color: inherit"),e;console.group("%c[lume-debug] Statistics","color: #888; font-weight: bold");for(const[t,o]of Object.entries(e)){console.group("%c"+t,"color: #2196F3; font-weight: bold");const e=[],n=new Set([...Object.keys(o.gets),...Object.keys(o.sets),...Object.keys(o.notifies)]);for(const t of n)e.push({key:t,gets:o.gets[t]||0,sets:o.sets[t]||0,notifies:o.notifies[t]||0});e.length>0&&console.table(e),console.groupEnd()}return console.groupEnd(),e},resetStats(){m.clear(),console.log("%c[lume-debug]%c Stats reset","color: #888; font-weight: bold","color: inherit")}};function A(e,o=[]){if(!o.length)return e;for(const e of o){try{e.onInit?.()}catch(o){t(`[Lume.js] Plugin "${e.name}" error in onInit:`,o)}Object.freeze(e)}const n=new Map;let r;return"function"==typeof e.$beforeFlush&&(r=e.$beforeFlush(function(){for(const[e,r]of n)for(const n of o)try{n.onNotify?.(e,r)}catch(e){t(`[Lume.js] Plugin "${n.name}" error in onNotify:`,e)}n.clear()})),new Proxy(e,{get(e,c){if("$dispose"===c)return()=>{r&&r(),n.clear()};if("string"==typeof c&&c.startsWith("$")){const n=e[c];return"$subscribe"===c&&"function"==typeof n?(e,r)=>{for(const n of o)try{n.onSubscribe?.(e)}catch(e){t(`[Lume.js] Plugin "${n.name}" error in onSubscribe:`,e)}return n(e,r)}:n}let s=e[c];for(const e of o)try{const t=e.onGet?.(c,s);void 0!==t&&(s=t)}catch(o){t(`[Lume.js] Plugin "${e.name}" error in onGet:`,o)}return s},set(e,r,c){const s=e[r];let i=c;for(const e of o)try{const t=e.onSet?.(r,i,s);void 0!==t&&(i=t)}catch(o){t(`[Lume.js] Plugin "${e.name}" error in onSet:`,o)}return Object.is(i,s)||n.set(r,i),e[r]=i,!0}})}function N(){const e=[];return{add(t){"function"==typeof t&&e.push(t)},dispose(){for(;e.length;){const t=e.pop();try{t()}catch(e){}}}}}function O(e="#__LUME_DATA__",t){const o="undefined"!=typeof document?document.querySelector(e):null;if(!o)return{};if("SCRIPT"!==o.tagName||"application/json"!==o.type)return{};let n;try{n=JSON.parse(o.textContent)}catch{return{}}return"function"!=typeof t||t(n)?n:{}}function T(t,o){try{const e=t.getItem(o);if(!e)return null;const n=JSON.parse(e);return n&&"object"==typeof n&&!Array.isArray(n)?n:null}catch{return e(`[Lume.js] persist(): could not read "${o}" — starting fresh`),null}}function C(e,t){const o={};for(const n of t)o[n]=e[n];return JSON.stringify(o)}function F(t,o,n={}){if(!t||"function"!=typeof t.$subscribe)throw Error("[Lume.js] persist() requires a reactive store from state()");if("string"!=typeof o||0===o.length)throw Error("[Lume.js] persist() requires a non-empty storage key");const r=void 0!==n.storage?n.storage:globalThis.localStorage;if(!r||"function"!=typeof r.getItem)return e("[Lume.js] persist(): no storage available — persistence disabled"),()=>{};const c=Array.isArray(n.keys)&&n.keys.length>0?n.keys.slice():Object.keys(t).filter(e=>!e.startsWith("$")),s=T(r,o);if(s)for(const e of c)Object.prototype.hasOwnProperty.call(s,e)&&(t[e]=s[e]);let i=null;try{i=C(t,c)}catch{}let l=!1,u=!1;const f=()=>{if(l=!1,u)return;let n;try{n=C(t,c)}catch(t){return void e("[Lume.js] persist(): state not serializable — skipping save",t)}if(n!==i)try{r.setItem(o,n),i=n}catch(t){e("[Lume.js] persist(): could not write — storage full or unavailable?",t)}},a=c.map(e=>{let o=!0;return t.$subscribe(e,()=>{o?o=!1:l||(l=!0,queueMicrotask(f))})});return()=>{for(u=!0;a.length;)a.pop()()}}function M(e){return!(!e||"object"!=typeof e||!(n in e)&&"function"!=typeof e.$subscribe)}export{i as computed,N as createCleanupGroup,L as createDebugPlugin,v as debug,g as defaultFocusPreservation,d as defaultScrollPreservation,O as hydrateState,M as isReactive,F as persist,y as repeat,l as watch,A as withPlugins};

package/dist/addons.mjs

@@ -1,4 +1,6 @@
-import { e as effect, a as logError, l as logWarn } from "./shared-Dcokqj5a.mjs";
+import { R as REACTIVE_BRAND } from "./shared-Bk_gndPJ.mjs";
+import { e as effect, a as applyBindValue } from "./shared-DNe4ez8V.mjs";
+import { l as logError, a as logWarn } from "./shared-DmpHYKx7.mjs";
 function computed(fn) {
   if (typeof fn !== "function") {
     throw new Error("computed() requires a function");
@@ -92,6 +94,47 @@ function watch(store, key, callback, { immediate = true } = {}) {
   }
   return store.$subscribe(key, callback);
 }
+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;
+}
+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);
+  }
+}
 function defaultFocusPreservation(container) {
   const activeEl = document.activeElement;
   const shouldRestore = container.contains(activeEl);
@@ -151,6 +194,7 @@ function repeat(container, store, arrayKey, options) {
     create,
     update,
     remove,
+    template = null,
     element = "div",
     preserveFocus = defaultFocusPreservation,
     preserveScroll = defaultScrollPreservation
@@ -164,15 +208,21 @@ function repeat(container, store, arrayKey, options) {
   if (typeof key !== "function") {
     throw new Error("[Lume.js] repeat(): options.key must be a function");
   }
-  if (typeof render !== "function" && typeof create !== "function") {
+  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");
   }
   const elementsByKey = /* @__PURE__ */ new Map();
   const prevItemsByKey = /* @__PURE__ */ new Map();
   const prevIndexByKey = /* @__PURE__ */ new Map();
   const cleanupByKey = /* @__PURE__ */ new Map();
+  const bindingsByKey = /* @__PURE__ */ new Map();
   const seenKeys = /* @__PURE__ */ new Set();
   function createElement() {
+    if (templateRoot) return templateRoot.cloneNode(true);
     return typeof element === "function" ? element() : document.createElement(element);
   }
   function reconcileDOM(container2, nextEls) {
@@ -230,6 +280,9 @@ function repeat(container, store, arrayKey, options) {
       if (isFirstRender) {
         el = createElement();
         elementsByKey.set(k, el);
+        if (templateRoot) {
+          bindingsByKey.set(k, collectItemBindings(el));
+        }
       }
       try {
         if (isFirstRender && create) {
@@ -240,7 +293,12 @@ function repeat(container, store, arrayKey, options) {
         }
         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);
+            if (update) update(item, el, i, { isFirstRender });
+          }
+        } else if (update) {
           if (prevItem !== item || prevIndex !== i) {
             update(item, el, i, { isFirstRender });
           }
@@ -276,6 +334,7 @@ function repeat(container, store, arrayKey, options) {
             prevItemsByKey.delete(k);
             prevIndexByKey.delete(k);
             cleanupByKey.delete(k);
+            bindingsByKey.delete(k);
           }
         }
       }
@@ -313,6 +372,7 @@ function repeat(container, store, arrayKey, options) {
       prevItemsByKey.clear();
       prevIndexByKey.clear();
       cleanupByKey.clear();
+      bindingsByKey.clear();
       seenKeys.clear();
     };
   }
@@ -339,6 +399,7 @@ function repeat(container, store, arrayKey, options) {
     prevItemsByKey.clear();
     prevIndexByKey.clear();
     cleanupByKey.clear();
+    bindingsByKey.clear();
     seenKeys.clear();
   };
 }
@@ -566,6 +627,7 @@ function withPlugins(store, plugins = []) {
     } catch (e) {
       logError(`[Lume.js] Plugin "${p.name}" error in onInit:`, e);
     }
+    Object.freeze(p);
   }
   const pendingNotifications = /* @__PURE__ */ new Map();
   function runNotifyHooks() {
@@ -664,17 +726,108 @@ function createCleanupGroup() {
     }
   };
 }
-function hydrateState(selector = "#__LUME_DATA__") {
+function hydrateState(selector = "#__LUME_DATA__", validate) {
   const el = typeof document !== "undefined" ? document.querySelector(selector) : null;
   if (!el) return {};
+  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;
+}
+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;
+  }
+}
+function serializeKeys(store, watched) {
+  const out = {};
+  for (const k of watched) out[k] = store[k];
+  return JSON.stringify(out);
+}
+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 !== void 0 ? 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("$"));
+  const stored = readStored(storage, storageKey);
+  if (stored) {
+    for (const k of watched) {
+      if (Object.prototype.hasOwnProperty.call(stored, k)) {
+        store[k] = stored[k];
+      }
+    }
+  }
+  let lastWritten = null;
+  try {
+    lastWritten = serializeKeys(store, watched);
+  } catch {
+  }
+  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;
+      }
+      save();
+    });
+  });
+  return () => {
+    disposed = true;
+    while (unsubs.length) unsubs.pop()();
+  };
 }
 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"));
 }
 export {
   computed,
@@ -685,6 +838,7 @@ export {
   defaultScrollPreservation,
   hydrateState,
   isReactive,
+  persist,
   repeat,
   watch,
   withPlugins