# Lume.js

> Minimal reactive state management using only standard JavaScript and HTML —
> no custom syntax, no build step, no framework lock-in. 1.46 KB universal
> core (state/batch), 2.66 KB with DOM binding (bindDom/effect). Reactivity
> that follows web standards: stores are Proxies over plain objects, DOM
> binding is declarative via valid data-* attributes, updates are
> microtask-batched per store with an explicit batch() escape hatch for
> cross-store writes.

Version: 2.4.0. Install: `npm install lume-js` or import from
`https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs`.

Key facts agents get wrong without reading the docs: arrays and nested
objects must be REPLACED, never mutated in place (reference equality);
nested objects need explicit state() wrapping; updates flush on the next
microtask, not synchronously; effects only track keys read synchronously;
data-* attribute values are state keys, never expressions.

This file is the full documentation bundle: every guide, tutorial, and
API page concatenated. Generated by scripts/build-llms.js — do not edit.


========================================================================
FILE: AGENT_GUIDE.md
========================================================================

# Lume.js — Agent Guide

Instructions for AI coding agents (and fast-moving humans) **using Lume.js in an application**. Read this before writing any Lume code. For developing Lume.js itself, see `AGENTS.md` instead.

- Machine-readable doc bundle: `llms.txt` (index) and `llms-full.txt` (this guide + every guide, tutorial, and API page in one file) ship with the npm package and live at the repo root.
- Full human docs: <https://github.com/sathvikc/lume-js/tree/main/docs>

## Mental model (30 seconds)

Lume is **standards-only reactivity**: a `Proxy`-based store (`state`), auto-tracking side effects (`effect`), and declarative DOM binding through plain `data-*` attributes (`bindDom`). No components, no virtual DOM, no compiler, no build step. HTML stays valid HTML; JavaScript stays standard JavaScript. You own the DOM structure; Lume keeps it in sync with state.

```javascript
import { state, effect, bindDom, batch } from 'lume-js';

const store = state({ name: 'World', count: 0 });
bindDom(document.body, store);          // wires all data-* attrs under body
effect(() => {                          // auto-tracks store.count
  document.title = `Count: ${store.count}`;
});
store.count++;                          // DOM + title update on next microtask
```

```html
<h1>Hello, <span data-bind="name"></span>!</h1>
<input data-bind="name">   <!-- two-way on inputs, one-way on text elements -->
```

## Package entries — import from the right place

| Import | Size (gz) | Gives you | Use in |
|---|---|---|---|
| `lume-js` | 2.77 KB | `state`, `effect`, `bindDom`, `batch`, `withReadObserver` | browsers |
| `lume-js/state` | 1.49 KB | `state`, `batch`, `withReadObserver` (no DOM code) | Node, workers, CLI, SSR |
| `lume-js/addons` | pay per import | `computed`, `watch`, `repeat`, `persist`, `hydrateState`, `createCleanupGroup`, `debug` | optional patterns |
| `lume-js/handlers` | pay per import | `show`, `classToggle`, `boolAttr`, `ariaAttr`, `stringAttr`, `className`, `on`, `htmlAttrs`, presets | extra `data-*` attributes |

CDN (no build): `https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs` (also `/dist/state.min.mjs`, `/dist/addons.min.mjs`, `/dist/handlers.min.mjs`).

## The rules — violating any of these produces silently broken code

1. **Never mutate arrays or nested objects in place. Replace them.** Lume detects changes with reference equality (`Object.is`) on top-level keys only.
   ```javascript
   store.items.push(x);                  // ❌ silent — no update ever fires
   store.items = [...store.items, x];    // ✅
   store.items = store.items.filter(t => t.id !== id);          // ✅ remove
   store.items = store.items.map(t => t.id === id ? { ...t, done: true } : t); // ✅ update
   store.items = [...store.items].sort(cmp);                    // ✅ sort (copy first!)
   ```

2. **Nested objects are not reactive unless explicitly wrapped.**
   ```javascript
   const s = state({ user: { name: 'Ada' } });
   s.user.name = 'Z';                          // ❌ silent
   const s2 = state({ user: state({ name: 'Ada' }) });
   s2.user.name = 'Z';                         // ✅ notifies
   // or replace the whole object:
   s.user = { ...s.user, name: 'Z' };          // ✅ notifies subscribers of 'user'
   ```

3. **Updates are asynchronous (microtask-batched per store).** After a write, the DOM updates on the next microtask, not synchronously. In tests, flush before asserting:
   ```javascript
   store.count = 5;
   await Promise.resolve();     // or await new Promise(r => setTimeout(r))
   expect(el.textContent).toBe('5');
   ```
   Multiple writes to the same store in one tick coalesce into one flush, and subscribers see only the final value of each key.

4. **Effects track only what they read synchronously.** Reads after an `await`, inside `setTimeout`, or inside event callbacks are NOT tracked. Read every dependency at the top of the effect body. Conditional reads re-track on every run (only the branch actually taken is tracked). Writes inside an effect do not create subscriptions — only reads do.

5. **Keep and call the dispose functions.** `effect()`, `bindDom()`, `watch()`, `repeat()`, `persist()`, `$subscribe()`, and `computed().subscribe()` all return a cleanup/unsubscribe function. Call it when the UI section goes away, or collect them:
   ```javascript
   import { createCleanupGroup } from 'lume-js/addons';
   const group = createCleanupGroup();
   group.add(effect(() => { /* … */ }));
   group.add(bindDom(panel, store));
   group.dispose();   // dispose everything at once
   ```
   Creating effects/subscriptions in a loop without cleanup eventually hits the per-key subscriber cap (1000) and logs a console error.

6. **Writing several stores from one event? Wrap it in `batch()`.** Per-store microtask batching already dedupes same-store writes; an effect reading N stores mutated in the same tick still runs once per store. `batch(fn)` flushes synchronously when the outermost batch ends, running cross-store effects exactly once. `fn` must be synchronous — writes after an `await` inside it are NOT batched.
   ```javascript
   batch(() => {
     cart.items = [...cart.items, item];
     totals.sum += item.price;
     ui.message = 'Added!';
   });
   ```

7. **Stores hold plain objects.** `state()` throws on non-objects, arrays, and frozen/sealed objects at the top level. `Map`/`Set` are not reactive (use arrays/objects). Class instances mostly work but private fields bypass the proxy. Functions stored on state stay plain (usable with the `on()` handler). Keys starting with `$` are reserved meta API (`$subscribe`, `$beforeFlush`); writes to `__proto__`/`constructor`/ `prototype` are blocked.

8. **`data-*` attribute values are state keys, never expressions.** `data-bind="user.name"`, `data-show="count > 0"` — ❌ not supported. Derive a flat key in JS instead:
   ```javascript
   effect(() => { store.hasItems = store.items.length > 0; });
   ```
   ```html
   <div data-show="hasItems">…</div>
   ```

## Choosing the right primitive

| You want to… | Use |
|---|---|
| Derive a value **into the store** (for `data-bind`) | `effect(() => { store.full = store.a + store.b; })` |
| Derive a read-only value consumed **outside** the store | `computed(() => store.a * 2)` → `.value`, `.subscribe(fn)`, `.dispose()` |
| React to **one specific key** (analytics, localStorage, manual DOM) | `watch(store, 'key', fn)` — options `{ immediate: false }` to skip the initial call |
| Run side effects when **anything read** changes | `effect(fn)` (auto-tracking) |
| Side effect with **no magic tracking** | `effect(fn, [[store, 'key1', 'key2'], [other, 'k']])` (explicit deps, coalesced to one run per microtask) |
| Render an **array** as DOM elements | `repeat(container, store, 'items', { key: it => it.id, … })` |
| Low-level single-key subscription (no tracking) | `store.$subscribe('key', fn)` — calls immediately with current value |

Anti-pattern: calling `$subscribe` for a key inside an `effect` that also reads that key — the logic runs twice. Pick one mechanism.

## Built-in `data-*` attributes (core `bindDom`)

```html
<input data-bind="name">                  <!-- two-way: input/checkbox/radio/select/textarea -->
<span data-bind="name"></span>            <!-- one-way textContent -->
<div  data-hidden="isLoading">…</div>     <!-- boolean attrs: hidden/disabled/checked/required -->
<button data-disabled="isSubmitting">Go</button>
<button data-aria-expanded="menuOpen">Menu</button>  <!-- ARIA: "true"/"false" strings -->
```

More attributes are opt-in handlers, passed to `bindDom`:

```javascript
import { show, classToggle, stringAttr, on } from 'lume-js/handlers';
bindDom(root, store, { handlers: [show, classToggle('active'), stringAttr('href'), on('click')] });
```

```html
<span data-show="isVisible">…</span>            <!-- el.hidden = !truthy -->
<div data-class-active="isActive">…</div>       <!-- toggles the 'active' class -->
<a data-href="profileUrl">Profile</a>           <!-- string attr, removed on null -->
<button data-onclick="addItem">Add</button>     <!-- store.addItem wired as listener -->
```

Custom handlers are plain objects: `{ attr: 'data-tooltip', apply(el, val) { el.title = val ?? ''; } }`. `htmlAttrs()` is the one-import preset covering standard HTML + ARIA attrs.

## Lists with `repeat()` (keyed, element-reusing)

```html
<ul id="todos">
  <template>   <!-- row structure is a standard <template>; $index is provided -->
    <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 });
```

Imperative variant when you need custom DOM per row:

```javascript
repeat(listEl, store, 'items', {
  element: 'li',
  key: it => it.id,
  create: (it, el) => { /* build row structure once */ },
  update: (it, el) => { /* sync data on every change */ },
});
```

`repeat` diffs by `key` against the previous array — which is why rule #1 (immutable array updates) is non-negotiable.

## Canonical app skeleton

```html
<!DOCTYPE html>
<html lang="en">
<body>
  <input data-bind="query" placeholder="Search">
  <p data-show="loading">Loading…</p>
  <ul id="results"><template><li data-bind="title"></li></template></ul>
  <script type="module" src="./app.js"></script>
</body>
</html>
```

```javascript
import { state, effect, bindDom, batch } from 'lume-js';
import { repeat, watch, persist, createCleanupGroup } from 'lume-js/addons';
import { show } from 'lume-js/handlers';

const store = state({ query: '', loading: false, results: [] });
const group = createCleanupGroup();

group.add(bindDom(document.body, store, { handlers: [show] }));
group.add(repeat('#results', store, 'results', { key: r => r.id, template: true }));
group.add(persist(store, 'my-app', { keys: ['query'] }));  // localStorage sync

group.add(watch(store, 'query', async (q) => {
  store.loading = true;
  const results = await fetchResults(q);
  batch(() => {                 // one flush for both writes
    store.results = results;    // replace, never mutate
    store.loading = false;
  });
}, { immediate: false }));
```

## Debugging & testing

- Write/read logging is a plugin:
  ```javascript
  import { withPlugins, createDebugPlugin, debug } from 'lume-js/addons';
  const store = withPlugins(state({ count: 0 }), [createDebugPlugin({ label: 'cart' })]);
  debug.enable();          // global on/off switch; also debug.filter('key'), debug.stats()
  ```
- Nothing updates? Check, in order: (1) mutated an array/nested object in place (rule 1/2), (2) asserted synchronously before the microtask flush (rule 3), (3) the read happened after an `await` inside an effect (rule 4), (4) `bindDom` was called before the element existed, or on a root that doesn't contain it.
- Effect runs too often? Reading many stores in one effect while writing them separately — wrap the writes in `batch()` (rule 6).
- Console error about subscriber limit (1000/key) or max flush iterations (100) = subscription leak in a loop, or an effect writing a key it also reads (infinite cascade).
- Tests: jsdom + vitest work fine. Write state → `await Promise.resolve()` → assert DOM. See `docs/guides/testing.md`.

## SSR / no-DOM environments

Import `state`/`batch` from `lume-js/state` (1.49 KB, zero DOM references) in Node/workers/CLI. For server-rendered pages, inline initial state as `<script type="application/json">` and hydrate with `hydrateState()` (`lume-js/addons`), then call `bindDom` as usual.

## Keeping agents up to date

`llms.txt` and `llms-full.txt` are regenerated from this guide plus the docs tree by `npm run llms`, and CI fails when they drift — whatever version of `lume-js` is installed, the bundled files match its actual behavior. In a consuming project, add one line to your agent config (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, …):

> Before writing any code that uses lume-js, read `node_modules/lume-js/AGENT_GUIDE.md`. For API details beyond the guide, consult `node_modules/lume-js/llms-full.txt`.


========================================================================
FILE: README.md
========================================================================

<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.49 KB universal core</strong> &nbsp;·&nbsp; <strong>2.77 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.4.0-orange.svg" alt="v2.4.0"></a>
    &nbsp;
<a href="tests/"><img src="https://img.shields.io/badge/tests-475%20passing-brightgreen.svg" alt="475 tests"></a>
    &nbsp;
<a href="scripts/check-size.js"><img src="https://img.shields.io/badge/universal%20core-1.49KB-blue.svg" alt="universal core 1.49KB"></a>
    &nbsp;
<a href="scripts/check-size.js"><img src="https://img.shields.io/badge/core%20%2B%20DOM-2.77KB-blue.svg" alt="core + DOM 2.77KB"></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>

---

## Why Lume.js?

| Feature | Lume.js | Alpine.js | Vue | React |
|---------|---------|-----------|-----|-------|
| Custom Syntax | ❌ No | ✅ `x-data` | ✅ `v-bind` | ✅ JSX |
| Build Step | ❌ Optional | ❌ Optional | ⚠️ Recommended | ✅ Required |
| Bundle Size | 1.49–2.77KB | ~15KB | ~35KB | ~45KB |
| HTML Validation | ✅ Pass | ⚠️ Warnings | ⚠️ Warnings | ❌ JSX |
| Extensible Handlers | ✅ | ❌ Built-in only | ❌ Built-in only | N/A |

**Lume.js is "Modern Knockout.js" — standards-only reactivity for the modern web.**

---

## Installation

### Pick your entry

| Entry | Size (gz) | Contents | For |
|-------|-----------|----------|-----|
| `lume-js/state` | **1.49 KB** | `state`, `batch`, `withReadObserver` | Node, Deno, Bun, workers, CLI — anywhere without a DOM |
| `lume-js` | **2.77 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
<script type="module">
  import { state, bindDom, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
</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
npm install lume-js
```

```javascript
import { state, bindDom } from 'lume-js';        // browser: full core
import { state, batch } from 'lume-js/state';    // Node/CLI/workers: 1.49 KB kernel
```

> **→ Using Lume without a DOM?** See the [Universal core guide](docs/guides/universal-core.md).


### Browser Support

| Browser | Minimum version |
|---------|-----------------|
| Chrome  | 80+             |
| Firefox | 74+             |
| Safari  | 13.1+           |
| Edge    | 80+             |
| IE11    | ❌ Not supported |

The floor comes from optional chaining / nullish coalescing (ES2020) used in the source — shipped un-transpiled, true to no-build. IE11 cannot be polyfilled regardless: Lume uses `Proxy`.

---

## Quick Start

**HTML:**
```html
<div>
  <h1>Hello, <span data-bind="name"></span>!</h1>
  <input data-bind="name" placeholder="Enter your name">
</div>
```

**JavaScript:**
```javascript
import { state, bindDom } from 'lume-js';

const store = state({ name: 'World' });
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

`bindDom()` supports these `data-*` attributes out of the box:

```html
<!-- Two-way binding (inputs) / one-way (text elements) -->
<input data-bind="name">
<span data-bind="name"></span>

<!-- Boolean attributes -->
<div data-hidden="isLoading">Content</div>
<button data-disabled="isSubmitting">Submit</button>
<input data-checked="isAgreed" type="checkbox">
<input data-required="fieldRequired">

<!-- ARIA attributes -->
<button data-aria-expanded="menuOpen">Menu</button>
<div data-aria-hidden="isCollapsed">Panel</div>
```

---

## Extensible Handler System

**Handlers** are plain objects that teach `bindDom()` how to interpret new `data-*` attributes. They live in `lume-js/handlers` and are entirely optional — import only the ones you use. You can also write your own with just an `attr` string and an `apply` function.

Need more reactive attributes? Import handlers or create your own — no core modification needed.

```javascript
import { state, bindDom } from 'lume-js';
import { show, classToggle, stringAttr } from 'lume-js/handlers';

const store = state({
  isVisible: true,
  isActive: false,
  profileUrl: '/user/alice'
});

bindDom(document.body, store, {
  handlers: [show, classToggle('active'), stringAttr('href')]
});
```

```html
<span data-show="isVisible">Visible when truthy</span>
<div data-class-active="isActive">Toggles 'active' class</div>
<a data-href="profileUrl">Profile</a>
```

### Available Handlers (`lume-js/handlers`)

| Handler | HTML Example | Effect |
|---------|-------------|--------|
| `show` | `data-show="key"` | Shows element when truthy (`el.hidden = !val`) |
| `className` | `data-classname="key"` | Replaces full class string (`el.className = val`) |
| `boolAttr(name)` | `data-readonly="key"` | Toggles any boolean attribute |
| `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

```javascript
import { formHandlers, a11yHandlers } from 'lume-js/handlers';

// formHandlers: [boolAttr('readonly')]
// a11yHandlers: [ariaAttr('pressed'), ariaAttr('selected'), ariaAttr('disabled')]
```

### Custom Handlers

Any plain object with `attr` and `apply` works:

```javascript
const tooltip = {
  attr: 'data-tooltip',
  apply(el, val) { el.title = val ?? ''; }
};

bindDom(root, store, { handlers: [tooltip] });
```

---

## Addons

**Addons** are optional reactive pattern helpers that build on the core primitives. They handle common use cases that would otherwise require boilerplate — derived values, key observation, list rendering. Import only what you need from `lume-js/addons`; none are loaded by default.

```javascript
import { computed, watch, repeat } from 'lume-js/addons';
```

| Addon | When to use |
|-------|-------------|
| `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 — 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?, validate?)` | Read initial state from a `<script type="application/json">` tag (SSR hydration), with optional schema validation |

**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.

### `effect()` vs `computed()` vs `watch()`

```javascript
import { state, effect } from 'lume-js';
import { computed, watch } from 'lume-js/addons';

const store = state({ firstName: 'Ada', lastName: 'Lovelace', count: 0 });

// effect() — derives a value and writes it back into the store
// Use when the result lives in state and drives the DOM via data-bind
effect(() => {
  store.fullName = `${store.firstName} ${store.lastName}`;
});

// computed() — derives a value to read externally (e.g. display, logging)
// Use when the result is consumed outside the store
const doubled = computed(() => store.count * 2);
console.log(doubled.value); // 10
doubled.subscribe(val => document.title = `Count × 2: ${val}`);

// watch() — reacts to a single key changing
// Use for side effects tied to one property: analytics, localStorage, DOM sync
watch(store, 'count', (val) => {
  localStorage.setItem('count', val);
});

// watch() with { immediate: false } — skip the initial call
watch(store, 'count', (val) => {
  sendAnalytics('count_changed', val); // only on actual changes
}, { immediate: false });
```

---

## Using Lume.js with AI agents

Lume ships agent-ready documentation **inside the npm package**, regenerated from the docs on every change (CI-enforced), so it always matches the installed version:

| File | What it is |
|------|-----------|
| [`AGENT_GUIDE.md`](AGENT_GUIDE.md) | Distilled rules, pitfalls, and canonical patterns — one read teaches an agent to write correct Lume code |
| [`llms.txt`](llms.txt) | [llmstxt.org](https://llmstxt.org) index of all docs, for web-browsing agents |
| [`llms-full.txt`](llms-full.txt) | Every guide, tutorial, and API page in one file |

In a project that uses Lume, add one line to your agent config (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, …):

```markdown
Before writing any code that uses lume-js, read node_modules/lume-js/AGENT_GUIDE.md.
For API details beyond the guide, consult node_modules/lume-js/llms-full.txt.
```

No install? Point the agent at the hosted copies: `https://raw.githubusercontent.com/sathvikc/lume-js/main/AGENT_GUIDE.md` and `…/llms-full.txt`.

---

## Documentation

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)
    - [Build Tic-Tac-Toe](docs/tutorials/build-tic-tac-toe.md)
    - [Working with Arrays](docs/tutorials/working-with-arrays.md)
- **API Reference**
    - [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/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)

---

## Contributing

We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT © [Sathvik C](https://github.com/sathvikc)


========================================================================
FILE: docs/guides/installation.md
========================================================================

# Installation

Lume.js ships as ES modules with TypeScript declarations. The simplest way to get started is a CDN import — no npm, no build tool, nothing to install. If your project already uses a bundler, npm works too.

## Via CDN — no build step

Drop a `<script type="module">` into any HTML file and you're done:

```html
<script type="module">
  import { state, bindDom, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
</script>
```

### Pin the version

For production, pin to an exact version so your page can't break on a new release. Omitting a tag gives the latest stable.

```html
<!-- exact version (recommended for production) -->
'https://cdn.jsdelivr.net/npm/lume-js@2.4.0/dist/index.min.mjs'

<!-- latest stable -->
'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs'
```

### Import map (recommended for CDN projects)

If your page imports from more than one Lume subpath, an import map removes the long URLs from your code and keeps everything readable:

```html
<script type="importmap">
{
  "imports": {
    "lume-js":          "https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs",
    "lume-js/addons":   "https://cdn.jsdelivr.net/npm/lume-js/dist/addons.min.mjs",
    "lume-js/handlers": "https://cdn.jsdelivr.net/npm/lume-js/dist/handlers.min.mjs"
  }
}
</script>
<script type="module">
  import { state, bindDom } from 'lume-js';
  import { watch, computed } from 'lume-js/addons';
  import { classToggle }    from 'lume-js/handlers';
</script>
```

## Via npm

If you're working in a project with a bundler (Vite, Rollup, esbuild, webpack):

```bash
npm install lume-js
# or
pnpm add lume-js
# or
yarn add lume-js
```

Then import as usual:

```js
import { state, bindDom } from 'lume-js';
import { watch, computed } from 'lume-js/addons';
import { show, classToggle, stringAttr } from 'lume-js/handlers';
```

## Package exports

| Subpath | What's inside |
|---------|---------------|
| `lume-js` | `state`, `bindDom`, `effect`, `batch` |
| `lume-js/state` | `state`, `batch`, `withReadObserver` — DOM-free universal kernel |
| `lume-js/addons` | `watch`, `computed`, `repeat`, `persist`, `hydrateState`, `createCleanupGroup`, `withPlugins`, `createDebugPlugin`, `debug`, `isReactive`, `defaultFocusPreservation`, `defaultScrollPreservation` |
| `lume-js/handlers` | `show`, `className`, `classToggle`, `stringAttr`, `boolAttr`, `ariaAttr`, `on`, `htmlAttrs`, `formHandlers`, `a11yHandlers` |

## Browser support

Lume targets evergreen browsers: Chrome 80+, Firefox 74+, Safari 13.1+, Edge 80+ (the source uses ES2020 syntax — optional chaining, nullish coalescing — shipped un-transpiled). IE11 is **not** supported. Lume uses `Proxy` for reactivity, and `Proxy` cannot be polyfilled.

## TypeScript

Type declarations ship with the package — no separate `@types/` install needed. Stores infer their shape from the object you pass to `state()`:

```ts
import { state } from 'lume-js';

const store = state({ count: 0, name: 'Ada' });
store.count = 'two'; // ✗ Type 'string' is not assignable to type 'number'
store.unknown;       // ✗ Property 'unknown' does not exist
```

---

**← Previous: [Introduction](../README.md)** | **Next: [Quick start](quick-start.md) →**


========================================================================
FILE: docs/guides/quick-start.md
========================================================================

# Quick start

Five minutes from nothing to a working reactive app. Every line is explained.

## Step 1 — Plain HTML

Write HTML the way you always would. No custom elements, no special syntax. The only Lume-specific thing is the `data-bind` attribute — and it's a standard `data-*` attribute, so validators won't complain.

```html
<div id="app">
  <h1>Hello, <span data-bind="name"></span>!</h1>
  <input data-bind="name">
  <p>You've clicked <span data-bind="count"></span> times.</p>
  <button onclick="store.count++">Click</button>
</div>
```

## Step 2 — Create a store

```js
import { state } from 'lume-js';
const store = state({ name: 'World', count: 0 });
```

`state()` returns a **reactive proxy**. Reading a property inside an effect subscribes to it; writing a property notifies subscribers. To make a nested object reactive, wrap it in its own `state()` call.

## Step 3 — Bind to the DOM

```js
import { bindDom } from 'lume-js';
bindDom(document.getElementById('app'), store);
```

`bindDom()` walks the root element, finds every `data-bind`, and wires it up. On form controls (`<input>`, `<textarea>`, `<select>`, checkboxes, radios) the binding is two-way — user input updates the store, and store changes update the element. On everything else it sets `textContent`.

## Step 4 — Expose the store (optional)

The `onclick="store.count++"` in Step 1 needs `store` to be accessible inline. Put it on `window` to make that work:

```js
window.store = store;
```

Prefer to keep things tidy? Use `addEventListener` and keep the store in a closure. Either approach works fine.

## Step 5 — Open it in a browser

No build step needed. Open the HTML file directly. Type in the input — the heading updates live. Click the button — the counter increments. That's the complete reactive loop.

> **This is all you need for most apps.** Lists, conditionals, classes, styles, and custom attributes are opt-in additions on top of this base.

## What's next

- [Core concepts](core-concepts.md) — the three primitives (state, bindings, effects).
- [How reactivity works](reactivity.md) — under the hood.
- [Build a Todo app](../tutorials/build-todo-app.md) — applies everything so far to a real app.

---

**← Previous: [Installation](installation.md)** | **Next: [Core concepts](core-concepts.md) →**


========================================================================
FILE: docs/guides/core-concepts.md
========================================================================

# Core concepts

Lume has three building blocks. Learn them once and you understand the whole library.

## 1. State

A **store** holds your app's data. Create one by passing a plain object to `state()`:

```js
import { state } from 'lume-js';

const store = state({ count: 0, name: 'World' });
```

Read and write it exactly like a normal JavaScript object:

```js
store.count;       // read
store.count = 5;   // write — Lume notifies everything watching this key
```

Lume only watches **top-level keys** of the store. If you need a nested object to be reactive too, wrap it in its own `state()` call:

```js
const store = state({
  user: state({ name: 'Ada' })
});

store.user.name = 'Grace'; // works — user is its own reactive store
```

> **→ Why not auto-proxy nested objects?** Explicit wrapping keeps performance predictable and ownership clear — [see the design decision.](../design/design-decisions.md#why-nested-state-must-be-explicitly-wrapped)

## 2. Bindings

`bindDom()` connects your store to the DOM. It scans for `data-*` attributes and keeps them live — when the store changes, the page updates automatically.

The built-in `data-bind` attribute is **two-way** on form controls and **one-way** (text content) on everything else:

```html
<span data-bind="count"></span>              <!-- displays store.count -->
<input data-bind="name">                     <!-- reads and writes store.name -->
<input type="checkbox" data-bind="agreed">   <!-- reads and writes store.agreed -->
```

For visibility, classes, attributes, and more, use **handlers** — or write your own. A handler is just a plain object with `attr` and `apply`. See [Handlers](handlers.md).

> **→ Why one `data-bind` attribute?** [Why `data-bind` only, not `data-model` or `data-text`](../design/design-decisions.md#why-data-bind-only-not-data-model-or-data-text)

## 3. Effects

An **effect** runs a function immediately and re-runs it whenever the store data it read changes. You never list dependencies — Lume tracks them automatically.

```js
import { effect } from 'lume-js';

effect(() => {
  document.title = `${store.count} unread`;
});
// Runs once now, then again every time store.count changes.
```

The `lume-js/addons` package adds two more options when you need more control:

**`watch(store, key, fn)`** — subscribe to a single key explicitly:

```js
import { watch } from 'lume-js/addons';

watch(store, 'theme', (theme) => {
  document.documentElement.dataset.theme = theme;
});
```

**`computed(fn)`** — a cached value that updates when its dependencies change:

```js
import { computed } from 'lume-js/addons';

const remaining = computed(() =>
  store.todos.filter(t => !t.done).length
);

remaining.value; // always current, only recalculates when needed
```

## How it fits together

Your store sits in the middle. Bindings and effects subscribe to it. When you change a store key, every subscriber for that key updates — and nothing else.

```
           you write store.count = 5
                      │
          ┌───────────┴───────────┐
          │                       │
    DOM bindings             effect(fn)
   (spans, inputs…)         (re-runs fn)
```

No virtual DOM, no component tree, no build step required.

> **→ Why no virtual DOM?** Direct DOM writes are faster for small-to-medium UIs and keep the library tiny — [see the design decision.](../design/design-decisions.md#why-no-virtual-dom)

---

**← Previous: [Quick start](quick-start.md)** | **Next: [How reactivity works](reactivity.md) →**


========================================================================
FILE: docs/guides/reactivity.md
========================================================================

# How reactivity works

Lume's reactivity is a thin layer over JavaScript's built-in `Proxy`. This page explains exactly what happens on a read, a write, and inside an effect. You don't need to know this to use Lume, but understanding it helps when debugging unexpected behavior.

## The Proxy

`state(obj)` returns `new Proxy(obj, handlers)`. The handlers intercept two traps:

> **→ Why only objects?** `state()` only accepts plain objects, never primitives — [see the design decision.](../design/design-decisions.md#why-only-objects-in-state-not-primitives)

```js
// Simplified pseudocode of what state() does
function state(target) {
  return new Proxy(target, {
    get(obj, key) {
      track(obj, key);           // register current effect
      return obj[key];           // return raw value (no auto-nested proxy)
    },
    set(obj, key, value) {
      const prev = obj[key];
      if (Object.is(prev, value)) return true;  // no-op on identity
      obj[key] = value;
      scheduleFlush(obj, key, value);  // notify via queueMicrotask
      return true;
    }
  });
}
```

## Tracking

When an effect starts running, Lume sets a module-scoped context variable to point at that effect. On every property read, the proxy checks for an active context and registers the effect as a subscriber for that key.

```js
effect(() => {
  //        │
  //        ├─ current effect context set
  //        │
  console.log(store.a + store.b);
  //                ▲          ▲
  //                │          └─ track: register effect as listener for 'b'
  //                └─ track: register effect as listener for 'a'
  //
  //  current effect context cleared
});
```

After the function finishes, the context is cleared. Writing to a store key inside an effect does not register a new subscription — only reads do.

## Triggering

On write, Lume queues the notification with `queueMicrotask`. On the next microtask, it calls every subscriber registered for that key. DOM updates therefore happen after the current synchronous JavaScript task finishes.

> **→ Why microtasks?** Batching writes lets multiple property changes collapse into one DOM update — [see the design decision.](../design/design-decisions.md#why-microtask-batching-instead-of-synchronous-updates)

## Nested objects

Nested objects are **not** automatically reactive. The `get` trap returns `target[key]` directly without wrapping it in a new proxy. To make a nested object reactive, wrap it in its own `state()` call:

```js
// ❌ NOT reactive — nested write will NOT notify
const bad = state({ user: { name: 'Ada' } });
bad.user.name = 'Z'; // silent: no notification

// ✅ Reactive — user is its own proxy
const good = state({ user: state({ name: 'Ada' }) });
good.user.name = 'Z'; // notifies subscribers of 'name'
```

Arrays stored on the store are reactive at the top level — replacing the array key triggers subscribers. Mutations *inside* the array (such as `push`) do **not** trigger, because the proxy only watches the key on the parent object, not the contents of the value:

```js
const store = state({ todos: [] });

// ✅ Reactive — replaces the top-level key
store.todos = [...store.todos, { text: 'buy milk' }];

// ❌ NOT reactive — mutates the raw array directly
store.todos.push({ text: 'buy milk' }); // subscribers NOT notified
```

> **→ Why no auto-nested reactivity?** Explicit wrapping keeps performance predictable and ownership clear — [see the design decision.](../design/design-decisions.md#why-nested-state-must-be-explicitly-wrapped)

## What is not reactive

- **`Map` and `Set`** — not supported. Use plain arrays instead of `Set`, and plain objects instead of `Map`.
- **Class instances** with private fields — the Proxy wraps the instance, but internal `this` references may read the private backing store directly and bypass the proxy.
- **Functions stored on the store** — methods stay plain and are not proxied.

## Anti-patterns

### `$subscribe` inside an auto-tracking effect
Calling `store.$subscribe(key, fn)` inside an `effect()` that already auto-tracks that same key will cause the logic to execute twice: once for the auto-tracking re-run and once for the manual subscription.

```js
// ❌ ANTI-PATTERN — double notification
effect(() => {
  void store.count; // auto-tracks
  store.$subscribe('count', () => { ... }); // also tracks
});
```

Instead, use `watch` for single-key reactions or let the `effect` handle all tracking automatically.

## Cleanup

Both `effect` and `bindDom` return a dispose function. Call it when the associated component or UI section is removed from the page to prevent memory leaks.

```js
const stop = effect(() => { /* … */ });
stop();     // unsubscribes and stops re-running

const cleanup = bindDom(root, store);
cleanup(); // removes ALL bindings inside root
```

---

**← Previous: [Core concepts](core-concepts.md)** | **Next: [Universal core (Node, CLI, workers)](universal-core.md) →**


========================================================================
FILE: docs/guides/universal-core.md
========================================================================

# The Universal Core (`lume-js/state`)

Lume's kernel — `state()`, `batch()`, `withReadObserver()` — has no DOM dependency at all. The `lume-js/state` entry ships exactly that kernel: **1.49 KB gzipped**, runs in Node, Deno, Bun, workers, CLI tools, and browsers alike.

```js
import { state, batch } from 'lume-js/state';
```

If you're building for the browser and want DOM binding, use the full core instead — same `state`, plus `bindDom` and `effect`:

```js
import { state, bindDom, effect, batch } from 'lume-js';   // 2.77 KB
```

Both entries share one implementation — `lume-js/state` is not a fork, it's a smaller slice of the same modules.

## A complete Node example

Save as `watcher.mjs` and run with `node watcher.mjs` — no DOM, no build:

```js
import { state, batch } from 'lume-js/state';

// Reactive state on the server: a build pipeline's status
const build = state({
  step: 'idle',
  filesDone: 0,
  filesTotal: 0,
  errors: 0,
});

// Subscriptions work exactly as in the browser
build.$subscribe('step', step => {
  console.log(`→ ${step}`);
});

const progress = () =>
  build.filesTotal > 0
    ? `${build.filesDone}/${build.filesTotal}`
    : 'n/a';

// Simulate a pipeline
build.step = 'compiling';
batch(() => {
  build.filesTotal = 120;
  build.filesDone = 0;
});

for (let i = 1; i <= 120; i++) {
  build.filesDone = i;   // microtask-batched: no log spam, final value wins
}
build.step = 'done';

queueMicrotask(() => {
  console.log(`finished: ${progress()}, errors: ${build.errors}`);
});
```

## Why `batch()` shines outside the browser

In the browser, microtask batching usually does the right thing on its own. In **tests and server code**, you often want the flush to have happened *on the next line* — that's exactly what `batch()` guarantees:

```js
import { state, batch } from 'lume-js/state';
import assert from 'node:assert';

const order = state({ items: 0, total: 0 });
const audit = [];
order.$subscribe('total', t => audit.push(t));

batch(() => {
  order.items = 3;
  order.total = 42;
});

// No `await Promise.resolve()` dance — the flush already ran:
assert.deepStrictEqual(audit, [0, 42]);
```

## What's *not* in the kernel

| Not included | Why | Where it lives |
|--------------|-----|----------------|
| `bindDom` | DOM-only by definition | `lume-js` |
| `effect` | auto-tracking is a UI-leaning pattern; in server code, explicit `$subscribe` is usually clearer | `lume-js` |
| addons (`computed`, `watch`, `persist`, …) | optional patterns | `lume-js/addons` |

Note that `watch()` and `computed()` from `lume-js/addons` are themselves DOM-free and work fine in Node — they're just not part of the 1.49 KB kernel. (`computed` pulls in `effect` internally.)

## Building reactive primitives on the kernel

`withReadObserver(onRead, fn)` is the seam `effect()` itself is built on — it reports every store read during `fn`'s synchronous execution. If you're building your own primitive (a memo, a logger, a dependency visualizer), you get the same machinery the library uses:

```js
import { state, withReadObserver } from 'lume-js/state';

const store = state({ a: 1, b: 2 });

const deps = [];
const sum = withReadObserver(
  (proxy, key) => deps.push(key),
  () => store.a + store.b
);

console.log(sum, deps);   // 3, ['a', 'b']
```

## CDN usage (no npm, no build)

```html
<script type="module">
  import { state, batch } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/state.min.mjs';
</script>
```

## Size accounting

| Entry | Gzipped | CI budget |
|-------|---------|-----------|
| `lume-js/state` (`dist/state.min.mjs`) | 1.49 KB | ≤ 1.75 KB |
| `lume-js` (`dist/index.min.mjs`) | 2.77 KB | ≤ 3.00 KB |

Both numbers are enforced by `scripts/check-size.js` on every CI run — they can't silently drift.

## See also

- [state()](../api/core/state.md) · [batch()](../api/core/batch.md)
- [SSR & Hydration](ssr-hydration.md) — server-rendered HTML with reactive hydration
- Design rationale: [Why a `lume-js/state` entry](../design/design-decisions.md#why-a-lume-jsstate-entry-instead-of-demoting-binddomeffect-v23)

---

**← Previous: [How reactivity works](reactivity.md)** | **Next: [Choosing reactive primitives](choosing-reactive-primitives.md) →**


========================================================================
FILE: docs/guides/choosing-reactive-primitives.md
========================================================================

# Choosing the right reactive primitive

Lume has three reactive primitives: `effect()`, `computed()`, and `watch()`. They overlap in capability but each has a clear sweet spot. Use this page to pick the right one quickly.

## Decision tree

```
Do you need the result in the DOM via data-bind?
  ├─ Yes, and it's derived from other state → effect() to write it back into the store
  └─ No — it lives outside the store
       ├─ Is it a derived read-only value (display, logging)? → computed()
       └─ Is it a side effect for one specific key? → watch()
```

## Quick reference

| Primitive | Where result lives | Tracks | Fires immediately |
|-----------|--------------------|--------|-------------------|
| `effect(fn)` | Back into the store, or any side effect | Auto — all reads inside fn | Yes (on first call) |
| `computed(fn)` | Outside the store (`.value`, `.subscribe`) | Auto — all reads inside fn | Yes (`.value` is available immediately) |
| `watch(store, key, fn)` | Wherever you put it | Explicit — one key only | Yes (default), or skip with `{ immediate: false }` |

## `effect()` — derived store state and side effects

Use `effect()` when the result needs to live back in the store (so the DOM can bind to it via `data-bind`) or when you need a reactive side effect that reads multiple keys.

```js
import { state, effect } from 'lume-js';

const store = state({
  firstName: 'Ada',
  lastName: 'Lovelace',
  fullName: '',        // will be derived
  isLoading: false,
  hasData: false,
  hasError: false,
  showWeather: false,  // derived from the three above
});

// Derive fullName from first + last and write it back into state
effect(() => {
  store.fullName = `${store.firstName} ${store.lastName}`;
});

// Derive visibility flag — reads three keys, writes one
effect(() => {
  store.showWeather = store.hasData && !store.isLoading && !store.hasError;
});
```

The HTML can then bind to `fullName` and `showWeather` via `data-bind` and `data-show` — no extra wiring needed.

**Avoid reading and writing the same key in one effect** — that causes an infinite loop.

## `computed()` — read-only derived values outside the store

Use `computed()` when you need a value derived from state but consumed *outside* the store — in templates rendered by another system, in logging, or in display logic that lives in JavaScript rather than the DOM.

```js
import { state } from 'lume-js';
import { computed } from 'lume-js/addons';

const store = state({ price: 100, taxRate: 0.2 });

const total = computed(() => store.price * (1 + store.taxRate));

console.log(total.value); // 120

// Subscribe to changes
total.subscribe(val => {
  document.getElementById('total').textContent = `$${val.toFixed(2)}`;
});

// Cleanup when done
total.dispose();
```

**Anti-pattern**: using `computed().subscribe()` to write back into the store is the same as `effect()` but with extra steps.

```js
// ❌ Unnecessary — use effect() instead
computed(() => store.a + store.b).subscribe(val => { store.sum = val; });

// ✅ Simpler
effect(() => { store.sum = store.a + store.b; });
```

## `watch()` — react to a single key changing

Use `watch()` for side effects tied to exactly one property: persisting to localStorage, syncing external state, firing analytics events. Because it only watches one key there is no risk of accidentally subscribing to extra reads.

```js
import { state } from 'lume-js';
import { watch } from 'lume-js/addons';

const store = state({ theme: 'light', userId: null });

// Persist theme to localStorage on every change
watch(store, 'theme', (theme) => {
  localStorage.setItem('theme', theme);
});

// Identify user in analytics — only on future changes, not initial null
watch(store, 'userId', (id) => {
  if (id) analytics.identify(id);
}, { immediate: false });

// Stop watching
const stop = watch(store, 'count', (val) => {
  if (val >= 10) stop();
});
```

### `{ immediate: false }`

By default `watch` fires immediately with the current value (same as `$subscribe`). Pass `{ immediate: false }` to skip the initial call and only react to future changes.

## `$subscribe` — low-level, when you need maximum control

`store.$subscribe(key, fn)` is the primitive under `watch`. Prefer `watch` — it validates the store and will gain future options. Use `$subscribe` directly only when writing library code or a custom addon.

## Summary

| I want to… | Use |
|------------|-----|
| Derive a store value that drives the DOM | `effect()` |
| Expose a derived value to external code | `computed()` |
| Run a side effect when one key changes | `watch()` |
| Skip the initial call | `watch(…, { immediate: false })` |
| React to multiple keys with auto-tracking | `effect()` |

---

**← Previous: [Universal core (Node, CLI, workers)](universal-core.md)** | **Next: [Handlers](handlers.md) →**


========================================================================
FILE: docs/guides/handlers.md
========================================================================

# Handlers

`bindDom` handles `data-bind`, `data-hidden`, `data-disabled`, and a handful of other built-in attributes. For anything else — showing elements, toggling classes, setting `href` or `src`, or any custom behavior — you use a **handler**.

A handler is a plain object with two things: the attribute name it responds to, and a function that applies the reactive value to an element. That's the entire API.

## Anatomy

```js
const myHandler = {
  attr: 'data-tooltip',
  apply(el, value) {
    el.title = value ?? '';
  }
};
```

When `bindDom` scans the DOM and finds an element with `data-tooltip="someKey"`:

1. It subscribes to `store.someKey`.
2. It calls `apply(el, store.someKey)` immediately, then again on every subsequent change.

> **→ Why `data-*` attributes?** [See the design decision.](../design/design-decisions.md#why-data-attr-for-reactive-html-attributes)

## Built-in handlers

The handlers below are exported from `lume-js/handlers`. They are opt-in — import only the ones you need.

### `show` — `data-show`

Sets `el.hidden = !Boolean(val)`: hides the element (via the `hidden` attribute) when the value is falsy.

```js
import { show } from 'lume-js/handlers';
bindDom(root, store, { handlers: [show] });

// HTML:
// <div data-show="isVisible">Only when truthy</div>
```

### `classToggle(name)` — `data-class-{name}`

Toggles a CSS class based on a truthy value. Factory — returns a handler for a specific class.

```js
import { classToggle } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [classToggle('active'), classToggle('error')]
});

// HTML:
// <li data-class-active="isSelected">…</li>
// <input data-class-error="hasError">
```

### `stringAttr(name)` — `data-{name}` → `{name}`

Mirrors a reactive value to a string attribute. Perfect for `href`, `src`, `alt`, `title`. Removes the attribute when the value is `null` or `undefined`.

```js
import { stringAttr } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [stringAttr('href'), stringAttr('src')]
});

// HTML:
// <a data-href="profileUrl">Profile</a>
// <img data-src="avatarUrl" alt="Avatar">
```

### `className` — `data-classname`

Replaces the element's entire class string. Use when reactive state holds a full class string rather than toggling individual classes.

```js
import { className } from 'lume-js/handlers';

bindDom(root, store, { handlers: [className] });

// HTML:
// <div data-classname="cardClasses">Card</div>
```

### `boolAttr(name)` — `data-{name}` → boolean attribute

Toggles any HTML boolean attribute by name. Works with any attribute `toggleAttribute()` supports.

```js
import { boolAttr } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [boolAttr('readonly'), boolAttr('open')]
});

// HTML:
// <input data-readonly="isLocked">
// <details data-open="isExpanded">...</details>
```

> The built-in `data-hidden`, `data-disabled`, `data-checked`, and `data-required` use direct property assignment. `boolAttr()` uses `toggleAttribute()` — correct for all attribute names.

### `ariaAttr(name)` — `data-aria-{name}` → `"true"`/`"false"`

Sets a boolean ARIA attribute, coercing the value to the string `"true"` or `"false"`. Use `stringAttr('aria-label')` for string-valued ARIA attributes.

```js
import { ariaAttr } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [ariaAttr('pressed'), ariaAttr('selected')]
});

// HTML:
// <button data-aria-pressed="isPressed">Toggle</button>
```

### `htmlAttrs()` — batteries-included preset

Returns a flat array of handlers covering all standard HTML boolean attributes, string attributes, and ARIA attributes. Ideal for prototyping or apps that need many different `data-*` bindings without per-handler imports.

```js
import { htmlAttrs } from 'lume-js/handlers';

bindDom(document.body, store, { handlers: [htmlAttrs()] });

// Now works without additional imports:
// <input data-readonly="isLocked" data-placeholder="hint" />
// <a data-href="url" data-title="tooltip">Link</a>
// <button data-aria-pressed="active" data-aria-label="btnLabel">…</button>
// <div data-show="isVisible">…</div>
```

> **Note:** `htmlAttrs()` is a function that returns an array — use `[htmlAttrs()]` (not `htmlAttrs` directly) so `bindDom` can flatten it. For production bundles, cherry-pick individual handlers to keep the import minimal.

## Writing your own

Any behavior you can describe as "this attribute controls this element property based on a reactive value" is a handler. The three examples below cover the most common patterns.

### Example 1 — `data-disabled`

```js
const disabled = {
  attr: 'data-disabled',
  apply(el, value) {
    el.toggleAttribute('disabled', Boolean(value));
  }
};
```

### Example 2 — `data-style-color`

```js
function styleProp(prop) {
  return {
    attr: `data-style-${prop}`,
    apply(el, value) {
      el.style.setProperty(prop, value ?? '');
    }
  };
}

bindDom(root, store, {
  handlers: [styleProp('color'), styleProp('background-color')]
});
```

### Example 3 — `data-format-currency`

```js
const formatCurrency = {
  attr: 'data-format-currency',
  apply(el, value) {
    el.textContent = new Intl.NumberFormat('en-US', {
      style: 'currency', currency: 'USD'
    }).format(value ?? 0);
  }
};

// HTML:
// <span data-format-currency="price"></span>
```

## Handler ordering

Handlers are applied in the order you pass them. If two handlers share the same `attr` name, the last one wins — it replaces the earlier one. This is how you override a built-in handler: pass your replacement after the built-in in the `handlers` array.

---

**← Previous: [Choosing reactive primitives](choosing-reactive-primitives.md)** | **Next: [Two-way binding](two-way-binding.md) →**


========================================================================
FILE: docs/guides/two-way-binding.md
========================================================================

# Two-way binding

A single `data-bind` attribute handles all form controls. Lume inspects the element type and wires the correct DOM property and event automatically — you don't need to configure anything.

> **→ Why one attribute?** [Why `data-bind` only, not `data-model` or `data-text`](../design/design-decisions.md#why-data-bind-only-not-data-model-or-data-text)

## The rules

| Element | Property | Event |
|---------|----------|-------|
| `<input>` (text, email, password, search, tel, url) | `value` | `input` |
| `<input type="checkbox">` | `checked` | `input` |
| `<input type="radio">` | `checked` (by value) | `input` |
| `<input type="number">` | `valueAsNumber` | `input` |
| `<input type="range">` | `valueAsNumber` | `input` |
| `<input type="date">` | `value` | `input` |
| `<textarea>` | `value` | `input` |
| `<select>` | `value` | `input` |
| Anything else | `textContent` | (one-way) |

## Text inputs

```html
<input data-bind="username" placeholder="Username">
<input data-bind="email" type="email">
<textarea data-bind="bio"></textarea>
```

## Checkboxes

```html
<input type="checkbox" data-bind="agreed">
<!-- store.agreed === true | false -->
```

## Radio groups

```html
<input type="radio" name="size" data-bind="size" value="sm"> Small
<input type="radio" name="size" data-bind="size" value="md"> Medium
<input type="radio" name="size" data-bind="size" value="lg"> Large
<!-- store.size === 'md' -->
```

## Selects

```html
<select data-bind="country">
  <option value="us">United States</option>
  <option value="gb">United Kingdom</option>
  <option value="jp">Japan</option>
</select>
```

## Number inputs

Lume binds number inputs to `valueAsNumber`, so store values stay numbers — no manual parsing needed:

```html
<input type="number" data-bind="age">
<!-- store.age === 42  (a number, not the string '42') -->
```

## One-way bindings

Any element that is not a form control gets `textContent` set from the store. No event is attached — the element never writes back.

```html
<h1 data-bind="title"></h1>
<p>Count: <span data-bind="count"></span></p>
```

To set an HTML attribute (like `href` or `src`) reactively, use the [`stringAttr`](../api/handlers/stringAttr.md) handler instead.

---

**← Previous: [Handlers](handlers.md)** | **Next: [Lists & repeat](lists.md) →**


========================================================================
FILE: docs/guides/lists.md
========================================================================

# Lists & repeat

The `repeat` addon renders a reactive array into the DOM. Rather than rebuilding the list on every change, it keys each element by a stable ID and only touches what actually changed. This keeps long lists fast and preserves focus and input state across updates.

## Basic usage

```js
import { state } from 'lume-js';
import { repeat } from 'lume-js/addons';

const store = state({
  todos: [
    { id: 1, text: 'Buy milk', done: false },
    { id: 2, text: 'Walk dog', done: true  },
  ]
});

repeat(document.getElementById('todo-list'), store, 'todos', {
  key: (todo) => todo.id,
  element: 'li',
  render: (todo, el) => {
    el.textContent = todo.text;           // mutate el directly
    el.classList.toggle('done', todo.done);
  }
});
```

The `render` function receives `(item, el, index)` and should mutate `el` directly. It is called once when the element is first created, and again whenever that item's data changes.

## Options

| Option | Required | Notes |
|--------|----------|-------|
| `key` | ✅ | `(item) => string | number` — returns a stable unique ID per item. Use a database ID, never array index. |
| `render` | One of | `(item, el, index) => void` — simple pattern, mutates `el` for new and updated items. |
| `create` | One of | `(item, el, index) => void` — called once when an element is created. Set DOM structure and event listeners here. |
| `update` | One of | `(item, el, index, { isFirstRender }) => void` — called on every data change. Bind data here. |
| `element` | — | Tag name or factory for the wrapper element. Default: `'div'`. |

Use `render` alone for simple, read-only lists. Use `create` + `update` for lists that have interactive elements (buttons, checkboxes) — `create` runs once per DOM element so you only attach listeners once, and `update` runs on every data change to keep the display in sync.

## Updating the list

`repeat` subscribes to the array key on the store. To trigger a re-render, **replace the array** with a new reference — in-place mutations like `push` or `splice` are invisible to Lume because the array reference does not change:

> **→ Why immutable updates?** Reference-equality checks are instant and require no Array monkey-patching — [see the design decision.](../design/design-decisions.md#why-no-loop-rendering-in-core-v-for-x-for)

```js
// ❌ Mutations — NOT reactive, repeat() will not re-render
store.todos.push(newTodo);
store.todos.splice(0, 1);

// ✅ Immutable replacement — triggers repeat() to re-render
store.todos = [...store.todos, newTodo];           // append
store.todos = store.todos.filter(t => t.id !== id); // remove
store.todos = store.todos.map(t =>                  // update item
  t.id === id ? { ...t, done: true } : t
);
```

When the new array is set, `repeat` diffs by key and performs minimal DOM operations:

| Change | DOM effect |
|----------|-----------|
| New key added | New element appended/inserted |
| Key removed | Element removed |
| Same keys, reordered | Existing nodes moved, `update` fires (index changed) |
| Same key, item ref changed | `update` callback fires for that row |

## Caveats

- **Keys must be unique.** Duplicate keys log a warning and cause two items to share one DOM element, which produces incorrect rendering.
- **Each rendered item must have exactly one root element.** Wrap multi-element fragments in a `<li>` or `<div>`.

> **See it running →** [Todo app tutorial](../tutorials/build-todo-app.md) and [Tic-Tac-Toe tutorial](../tutorials/build-tic-tac-toe.md) both use `repeat`.

## See also

- [repeat() API reference](../api/addons/repeat.md) — full signature, create+update pattern, array operations table
- [computed()](../api/addons/computed.md) — pass a computed as the store to filter a list reactively
- [Performance](performance.md) — why `repeat` beats `innerHTML` for dynamic lists

---

**← Previous: [Two-way binding](two-way-binding.md)** | **Next: [Forms](forms.md) →**


========================================================================
FILE: docs/guides/forms.md
========================================================================

# Forms

Lume handles form state through the same `data-bind` attribute used everywhere else. There is no special form API — bindings are two-way on form controls by default.

## Basic inputs

Add `data-bind` to any form control and `bindDom` wires it up automatically.

```html
<input data-bind="name">
<textarea data-bind="bio"></textarea>
<select data-bind="role">
  <option value="user">User</option>
  <option value="admin">Admin</option>
</select>
```

```js
const store = state({
  name: '',
  bio: '',
  role: 'user'
});

bindDom(document.body, store);
```

## Checkboxes and radios

Checkboxes bind to a boolean. Radio groups bind to a string value — whichever radio's `value` attribute matches the store value gets checked.

```html
<!-- Single checkbox — store.acceptedTerms === true | false -->
<input type="checkbox" data-bind="acceptedTerms">

<!-- Radio group — store.theme === 'light' | 'dark' -->
<input type="radio" name="theme" value="light" data-bind="theme">
<input type="radio" name="theme" value="dark" data-bind="theme">
```

## Known Limitations

### `select multiple`
The `data-bind` attribute does not currently support `<select multiple>`. Multi-select requires an array-based state model, while `data-bind` is designed for scalar values. If you need multi-select, manage the state manually using `addEventListener` and `watch`.

## Validation

Use `watch` to run validation logic whenever a specific field changes. Write the result back to an error key in the store.

```js
import { watch } from 'lume-js/addons';

const store = state({
  email: '',
  error: ''
});

watch(store, 'email', (email) => {
  store.error = email.includes('@') ? '' : 'Invalid email';
});
```

```html
<input data-bind="email" type="email">
<span data-bind="error"></span>
```

## Submitting

Use a standard `submit` event. The store already holds the current values — read them directly.

```js
document.querySelector('form').addEventListener('submit', (e) => {
  e.preventDefault();
  console.log('Submitting:', store.name, store.email);
});
```

## Reactive form attributes

The built-in `data-hidden` and `data-disabled` attributes let you control form state reactively without extra imports:

```html
<button data-disabled="isSubmitting">Submit</button>
<div data-hidden="isSubmitting">Form content</div>
```

For `readonly` and other form attributes not covered by the built-ins, import `formHandlers`:

```js
import { formHandlers } from 'lume-js/handlers';

bindDom(root, store, { handlers: formHandlers });
```

```html
<input data-bind="name" data-readonly="isLocked">
```

---

**← Previous: [Lists & repeat](lists.md)** | **Next: [Routing](routing.md) →**


========================================================================
FILE: docs/guides/routing.md
========================================================================

# Routing

Lume does not include a router, and it does not need to. Routing is just state — store the current route in a `state()` object and react to it with `effect()`. Two patterns cover most use cases.

## Hash-based routing

The simplest approach uses the URL hash (`#`). No server configuration required.

```javascript
const store = state({
  route: 'home'
});

function handleHash() {
  const hash = window.location.hash.replace('#', '') || 'home';
  store.route = hash;
}

window.addEventListener('hashchange', handleHash);
handleHash(); // sync with the URL on first load
```

Then use `effect()` to show or hide content based on the current route:

```javascript
effect(() => {
  document.getElementById('home-page').style.display =
    store.route === 'home' ? 'block' : 'none';

  document.getElementById('about-page').style.display =
    store.route === 'about' ? 'block' : 'none';
});
```

Navigating to `#about` sets `store.route = 'about'` and the effect re-runs automatically.

## History API (clean URLs)

For URLs without a `#`, use the History API. You need to intercept link clicks to prevent a full page reload, and handle the browser back button via `popstate`.

```javascript
document.addEventListener('click', (e) => {
  if (e.target.matches('a')) {
    e.preventDefault();
    const href = e.target.getAttribute('href');
    history.pushState(null, '', href);
    store.route = href;
  }
});

window.addEventListener('popstate', () => {
  store.route = window.location.pathname;
});
```

Your server must return the same HTML file for all routes so that a direct visit or page refresh still works. This is a standard requirement for any single-page app using the History API.

---

**← Previous: [Forms](forms.md)** | **Next: [Animations](animations.md) →**


========================================================================
FILE: docs/guides/animations.md
========================================================================

# Animations

Lume pairs well with CSS transitions and animation libraries like [GSAP](https://greensock.com/gsap/). Because state changes are plain property writes and effects are plain functions, there is nothing special to learn — hook in wherever you would normally trigger an animation.

## CSS Transitions

The lightest approach: toggle a class in an `effect` and let CSS do the rest.

```javascript
const store = state({ isOpen: false });

effect(() => {
  document.getElementById('menu').classList.toggle('open', store.isOpen);
});
```

```css
#menu {
  transition: transform 0.3s;
  transform: translateX(-100%);
}
#menu.open {
  transform: translateX(0);
}
```

Set `store.isOpen = true` and the menu slides in. No extra API to learn.

## GSAP

Use `effect()` or `watch()` to trigger GSAP animations when state changes. `watch` is the cleaner choice when you need to react to a single key:

```javascript
import gsap from 'gsap';
import { watch } from 'lume-js/addons';

const store = state({ x: 0 });

watch(store, 'x', (newX) => {
  gsap.to('.box', { x: newX, duration: 0.5 });
});
```

Any other GSAP method (`gsap.from`, `gsap.timeline`, etc.) works the same way — just call it inside the callback.

---

**← Previous: [Routing](routing.md)** | **Next: [Testing](testing.md) →**


========================================================================
FILE: docs/guides/testing.md
========================================================================

# Testing

Lume uses standard JavaScript objects and the standard DOM, so testing requires no special setup. Unit tests run without a DOM, and DOM tests work with any environment that provides one (Vitest ships with jsdom).

## Unit testing state

State logic is plain JavaScript — test it directly without touching the DOM.

```javascript
import { state } from 'lume-js';
import { test, expect } from 'vitest';

test('increment count', () => {
  const store = state({ count: 0 });
  store.count++;
  expect(store.count).toBe(1);
});
```

## Testing DOM updates

Lume batches DOM updates via `queueMicrotask`, so after writing to the store you need to yield to the microtask queue before asserting. A zero-millisecond `setTimeout` is the simplest way to do this.

```javascript
import { state, bindDom } from 'lume-js';
import { test, expect } from 'vitest';

test('updates DOM', async () => {
  document.body.innerHTML = '<span data-bind="text"></span>';
  const store = state({ text: 'Hello' });
  bindDom(document.body, store);

  expect(document.querySelector('span').textContent).toBe('Hello');

  store.text = 'World';

  // Wait for the microtask flush
  await new Promise(resolve => setTimeout(resolve, 0));

  expect(document.querySelector('span').textContent).toBe('World');
});
```

---

**← Previous: [Animations](animations.md)** | **Next: [Performance](performance.md) →**


========================================================================
FILE: docs/guides/performance.md
========================================================================

# Performance

Lume's update model is O(subscribers) — only the effects that read a changed key re-run, nothing else. The patterns below keep that guarantee working well as your app grows.

> **→ Why no virtual DOM?** Direct DOM writes are faster for small-to-medium UIs and keep the library tiny — [see the design decision.](../design/design-decisions.md#why-no-virtual-dom)

## Use `repeat` for lists

`innerHTML` rebuilds the entire list on every change — event listeners, focus state, and scroll position are all destroyed. `repeat` keys elements by ID and only touches what changed.

```js
import { repeat } from 'lume-js/addons';

// Keyed DOM reuse — only changed rows re-render
repeat(listEl, store, 'todos', {
  key: todo => todo.id,
  render: (todo, el) => { el.textContent = todo.text; }
});

// Destroys and recreates every node on every update
effect(() => {
  listEl.innerHTML = store.todos.map(t => `<li>${t.text}</li>`).join('');
});
```

## Use `computed` for expensive derivations

`computed` caches its result and only re-evaluates when its dependencies change. If multiple effects read the same derived value, the underlying function runs once, not once per effect.

```js
import { computed } from 'lume-js/addons';

// Filters once, caches until todos changes
const remaining = computed(() => store.todos.filter(t => !t.done).length);

// Re-filters inside every effect that reads it
effect(() => {
  const count = store.todos.filter(t => !t.done).length;
  badge.textContent = count;
});
```

## Keep state flat

Lume does **not** auto-proxy nested objects — only top-level keys on a `state()` proxy trigger subscribers. Deep nesting means you must wrap each nested object in its own `state()` call for reactivity, which adds overhead and complexity.

```js
// Flat — easy to subscribe precisely
const store = state({
  userId: 1,
  userName: 'Ada',
  userEmail: 'ada@example.com',
});

// Deep — fine for nested data, avoid for hot-path state
const store = state({
  user: { profile: { contact: { email: 'ada@example.com' } } }
});
```

## Scope `bindDom` narrowly

`bindDom` scans the subtree with `querySelectorAll`. Binding a small component root is faster than binding `document.body` for a large page.

```js
// Only scans the modal subtree
bindDom(document.getElementById('modal'), store);

// Scans the entire document
bindDom(document.body, store);
```

## Event delegation is automatic

`bindDom` attaches a single `input` event listener at the root — not one per form control. One hundred inputs cost one listener. There is nothing to configure.

```js
// All 100 inputs share one listener — nothing extra to do
bindDom(formRoot, store);
```

## Cleanup when done

Every `effect` and `bindDom` call returns a dispose function. Call it when the component unmounts to prevent memory leaks.

```js
const stopEffect = effect(() => { /* … */ });
const cleanupDom = bindDom(el, store);

// When tearing down:
stopEffect();
cleanupDom();
```

---

**← Previous: [Testing](testing.md)** | **Next: [Cleanup & Dispose](cleanup-and-dispose.md) →**


========================================================================
FILE: docs/guides/cleanup-and-dispose.md
========================================================================

# Cleanup & Dispose Patterns

Every Lume API that creates subscriptions or listeners returns a cleanup function. This guide shows how to manage them efficiently, especially when swapping views or tearing down components.

## What Returns a Cleanup?

| API | Returns | What it cleans up |
|-----|---------|-----------------|
| `bindDom(root, store)` | `() => void` | All subscriptions + event delegation listener |
| `effect(fn)` | `() => void` | All tracked subscriptions |
| `store.$subscribe(key, fn)` | `() => void` | That single subscription |
| `repeat(...)` | `() => void` | DOM elements + subscriptions |
| `computed(...).dispose()` | — | Internal effect + subscriptions |

## The Array Pattern (Zero Overhead)

For simple cases, a plain array is enough:

```js
const cleanups = [];

cleanups.push(bindDom(root, store));
cleanups.push(effect(() => { ... }));
cleanups.push(store.$subscribe('key', fn));

// Dispose everything
while (cleanups.length) cleanups.pop()();
```

**Why this works:** `pop()` removes items in reverse order, so nested teardown happens safely. Zero library code, idiomatic JavaScript.

## The CleanupGroup Addon

For apps with many teardown points, `createCleanupGroup()` provides a `.dispose()` method:

```js
import { createCleanupGroup } from 'lume-js/addons';

const group = createCleanupGroup();

group.add(bindDom(root, store));
group.add(effect(() => { ... }));
group.add(store.$subscribe('key', fn));

// Later — one call disposes everything
group.dispose();
```

**Features:**
- Ignores non-function values passed to `add()`
- Safe to call `dispose()` multiple times
- One failing cleanup doesn't block the rest
- Can be reused after `dispose()`

## Re-initialization (Page / Route Swaps)

`bindDom` supports re-init naturally. Clean up the old binding, then bind to new DOM:

```js
let cleanup = bindDom(document.getElementById('app'), store);

function swapPage(newRoot, newStore) {
  cleanup();           // remove old subscriptions
  cleanup = bindDom(newRoot, newStore);
}
```

With a cleanup group:

```js
let group = createCleanupGroup();
group.add(bindDom(root, store));
group.add(effect(() => { ... }));

function swapPage(newRoot, newStore) {
  group.dispose();
  group = createCleanupGroup();
  group.add(bindDom(newRoot, newStore));
  group.add(effect(() => { ... }));
}
```

## When to Use What

| Situation | Recommendation |
|-----------|----------------|
| Single `bindDom` call | Just use the returned cleanup directly |
| A few effects + subscriptions | Array pattern is fine |
| Complex page with many teardowns | `createCleanupGroup` for ergonomics |
| Route / page swaps | Group + re-create pattern |

---

**← Previous: [Performance](performance.md)** | **Next: [SSR & Hydration](ssr-hydration.md) →**


========================================================================
FILE: docs/guides/ssr-hydration.md
========================================================================

# SSR & Hydration

Lume has no compiler, no virtual DOM, and no server-side rendering framework. But it **is** hydration-friendly: you can render static HTML on the server and bind Lume to it on the client.

## How It Works

`bindDom()` calls `$subscribe()` immediately with the current value. If the server-rendered text already matches the store, there is no visible flash.

```html
<!-- Server renders static HTML with data-* attributes -->
<div id="app">
  <h1 data-bind="title">Welcome to My App</h1>
  <span data-bind="count">0</span>
  <button data-disabled="isLoading">Submit</button>
</div>

<script type="module">
  import { state, bindDom } from 'lume-js';

  const store = state({
    title: 'Welcome to My App',
    count: 0,
    isLoading: false
  });

  bindDom(document.getElementById('app'), store);
  <!-- Elements already have correct content — no flash -->
</script>
```

## Passing Initial State from Server

Embed the server state as JSON in the HTML:

```html
<script id="__LUME_DATA__" type="application/json">
  {"title": "Welcome", "count": 42}
</script>

<script type="module">
  import { state, bindDom } from 'lume-js';
  import { hydrateState } from 'lume-js/addons';

  const store = state(hydrateState());
  bindDom(document.getElementById('app'), store);
</script>
```

`hydrateState(selector)` reads a `<script type="application/json">` element, parses it, and returns the object. It falls back to `{}` if the element is missing or contains invalid JSON.

You can also do it manually without the addon:

```js
const raw = document.getElementById('__LUME_DATA__')?.textContent;
const initial = raw ? JSON.parse(raw) : {};
const store = state(initial);
```

## What Lume Does NOT Do

- No server-side JavaScript execution — that's your framework's job (Express, Django, etc.)
- No virtual DOM diffing or hydration mismatch detection
- No hydration reconciliation — if the server HTML differs from the store, the store wins

## Progressive Enhancement

Because content is in the HTML from the start, the page is readable before JavaScript loads. If JS fails entirely, the static content is still there.

## SEO

Crawlers see the server-rendered HTML. No special rendering mode needed.

---

**← Previous: [Cleanup & Dispose](cleanup-and-dispose.md)** | **Next: [state()](../api/core/state.md) →**


========================================================================
FILE: docs/api/core/state.md
========================================================================

# state(initialValue)

Creates a reactive proxy of a plain object.

## Signature

```ts
function state<T extends object>(initialValue: T): ReactiveState<T>
```

## Parameters

- `initialValue` — A plain object. Must not be a primitive, class instance, `Map`, or `Set`.

## Returns

A `Proxy` of `initialValue` with identical shape. Reads inside an `effect` are tracked; writes notify subscribers.

## Description

`state()` wraps the object in a `Proxy` that intercepts `get` and `set`. The `get` trap returns `target[key]` directly — it does **not** auto-wrap nested objects in a new proxy. Writes are batched via `queueMicrotask` and flush on the next microtask.

```js
import { state } from 'lume-js';

const store = state({ count: 0 });

store.count;     // read — tracked inside an effect
store.count = 5; // write — notification queued via microtask
```

Writes to a store that nothing observes take a fast path: with no subscribers on any key and no `$beforeFlush` hooks registered, a write stores the value and stops — no notification is queued and no flush is scheduled. This makes `state()` cheap enough for high-churn data layers that are read back by polling (e.g. a render loop sweeping `store.value` each frame) instead of subscriptions. Nothing is missed: a later `$subscribe` still receives the current value immediately, and effects subscribe before they can depend on a key.

## Nested reactivity

Nested objects are **not** automatically reactive. The `get` trap returns the raw value — it does not wrap sub-objects in a proxy. To make a nested object reactive, wrap it in its own `state()` call:

```js
// NOT reactive — nested write is silent
const store = state({
  settings: { theme: 'dark', lang: 'en' }
});
store.settings.theme = 'light'; // subscribers NOT notified

// Reactive — settings is its own proxy
const store = state({
  settings: state({ theme: 'dark', lang: 'en' })
});
store.settings.theme = 'light'; // notifies subscribers of 'theme'
```

> **→ Why not auto-proxy nested objects?** Explicit wrapping keeps performance predictable and ownership clear — [see the design decision.](../../design/design-decisions.md#why-nested-state-must-be-explicitly-wrapped)

## What's not reactive

| Type | Supported | Notes |
|------|-----------|-------|
| Plain objects (top-level keys) | Yes | Fully reactive |
| Nested plain objects | Partial | Must be wrapped in `state()` for reactivity |
| Arrays | Partial | Replacing the array key triggers; `push`/`splice` do not |
| `Map` / `Set` | No | Use plain objects / arrays instead |
| Class instances | Partial | Proxy wraps them, but private fields bypass reactivity |
| Functions | No | Not proxied — store methods stay plain |

## See also

- [How reactivity works](../../guides/reactivity.md) — detailed explanation of the proxy internals
- [effect()](effect.md) — auto-tracked side-effects
- [watch()](../addons/watch.md) — explicit single-key watcher

---

**← Previous: [SSR & Hydration](../../guides/ssr-hydration.md)** | **Next: [bindDom()](bindDom.md) →**


========================================================================
FILE: docs/api/core/bindDom.md
========================================================================

# bindDom(root, store, options?)

Scans a DOM subtree for `data-*` attributes and wires them reactively to a store.

## Signature

```ts
function bindDom(
  root: HTMLElement,
  store: object,
  options?: {
    immediate?: boolean;
    handlers?: Handler[];
  }
): () => void
```

## Parameters

- `root` — The root element to scan. All descendants are included.
- `store` — A reactive store created by `state()`.
- `options.immediate` — If `true`, binds immediately instead of waiting for `DOMContentLoaded`. Default: `false` — [see why.](../../design/design-decisions.md#why-auto-ready-binddom-by-default)
- `options.handlers` — Additional handler objects. See [Handlers](../../guides/handlers.md).

## Returns

A cleanup function. Call it to remove all bindings and event listeners created by this call.

## Built-in bindings

### `data-bind` — two-way for forms, one-way for everything else

> **→ Why one attribute?** [Why `data-bind` only, not `data-model` or `data-text`](../../design/design-decisions.md#why-data-bind-only-not-data-model-or-data-text)

| Element | Property | Event |
|---------|----------|-------|
| `<input type="text">` and friends | `value` | `input` |
| `<input type="checkbox">` | `checked` | `input` |
| `<input type="radio">` | `checked` (by value) | `input` |
| `<input type="number">` | `valueAsNumber` | `input` |
| `<input type="range">` | `valueAsNumber` | `input` |
| `<input type="date">` | `value` | `input` |
| `<textarea>` | `value` | `input` |
| `<select>` | `value` | `input` |
| Anything else | `textContent` | — (one-way) |

### Boolean attributes

| Attribute | Effect |
|-----------|--------|
| `data-hidden="key"` | `el.hidden = Boolean(val)` |
| `data-disabled="key"` | `el.disabled = Boolean(val)` |
| `data-checked="key"` | `el.checked = Boolean(val)` |
| `data-required="key"` | `el.required = Boolean(val)` |

### ARIA attributes

| Attribute | Effect |
|-----------|--------|
| `data-aria-expanded="key"` | `el.setAttribute('aria-expanded', 'true'/'false')` |
| `data-aria-hidden="key"` | `el.setAttribute('aria-hidden', 'true'/'false')` |

## Examples

### Basic

```html
<div id="app">
  <h1 data-bind="title"></h1>
  <input data-bind="title" placeholder="Title">
  <button data-disabled="saving">Save</button>
</div>
```

```js
import { state, bindDom } from 'lume-js';

const store = state({ title: 'Hello', saving: false });
const cleanup = bindDom(document.getElementById('app'), store);
```

### With handlers

```js
import { state, bindDom } from 'lume-js';
import { show, classToggle, stringAttr } from 'lume-js/handlers';

const store = state({ visible: true, active: false, url: '/profile' });

bindDom(document.body, store, {
  handlers: [show, classToggle('active'), stringAttr('href')]
});
```

```html
<div data-show="visible">Content</div>
<li data-class-active="active">Item</li>
<a data-href="url">Profile</a>
```

### Cleanup

`bindDom()` returns a cleanup function. You **must** call it before removing or rebinding the same DOM tree.

```js
const cleanup = bindDom(root, store);

// Later — before re-binding or navigating away
cleanup();
```

**What cleanup removes:**
- Per-element reactive subscriptions (all handlers, `data-bind`)
- The global `input` event delegation listener on the root element

**What cleanup does NOT remove:**
- The DOM elements themselves
- Any state values or stores

**Memory safety:**
- Handler subscriptions are held in closures within the cleanup array. Calling `cleanup()` releases them.
- If you discard the cleanup function without calling it, subscriptions remain active until the root element is garbage-collected.
- Re-binding the same root without cleaning up first creates duplicate listeners — always call `cleanup()` before re-binding.

```js
// SPA route change — bind new page content
const cleanup = bindDom(document.getElementById('app'), store);

// On route change:
cleanup();
// ... swap DOM ...
cleanup = bindDom(document.getElementById('app'), store);
```

## Performance notes

- Uses a single event listener at `root` (event delegation) for all form inputs — 100 inputs cost 1 listener.
- Runs a single `querySelectorAll` combining all handler attribute selectors.

## See also

- [Handlers guide](../../guides/handlers.md) — writing custom handlers
- [Two-way binding guide](../../guides/two-way-binding.md) — full form control reference
- [show](../handlers/show.md), [classToggle](../handlers/classToggle.md), [stringAttr](../handlers/stringAttr.md)

---

**← Previous: [state()](state.md)** | **Next: [effect()](effect.md) →**


========================================================================
FILE: docs/api/core/effect.md
========================================================================

# effect(fn)

Runs a function immediately and re-runs it whenever any store key it reads changes.

## Signature

```ts
function effect(
  fn: () => void,
  deps?: Array<[store: object, ...keys: string[]]>
): () => void
```

Imported from `lume-js`.

## Parameters

- `fn` — The function to run reactively. Must be synchronous. Return value is ignored.

## Returns

A dispose function. Call it to stop the effect and free its subscriptions.

## How it works

`effect` sets a global tracking context, runs `fn`, then clears it. Every store `get` that fires during the run registers the current effect as a subscriber for that key. On any subsequent write to a tracked key, the effect is queued in a microtask and re-runs. Subscriptions persist across runs: a re-run that reads the same keys makes no subscribe or unsubscribe calls at all (each dependency is just stamped with the run's generation), and dependencies the run stopped reading are swept afterwards — so stale dependencies are still dropped automatically, without rebuilding the stable ones.

You can also pass an explicit `deps` array of `[store, ...keys]` tuples to skip auto-tracking and subscribe to specific keys only. Explicit-deps notifications are coalesced: however many tracked keys (or stores) change in the same tick, the effect re-runs exactly once, on the next microtask.

> **→ Why support explicit deps?** [See the design decision.](../../design/design-decisions.md#why-support-explicit-dependencies-in-effect)

```js
import { state, effect } from 'lume-js';

const store = state({ count: 0, name: 'Ada' });

const stop = effect(() => {
  console.log(`Count: ${store.count}`);
  // store.name is NOT read, so it is NOT a dependency
});

store.count++;    // logs "Count: 1"
store.name = 'Z'; // nothing — name is not tracked
stop();           // effect stops
store.count++;    // nothing — disposed
```

## Conditional dependencies

Dependencies are determined by which keys are **actually read** in a given run. If a read is behind a condition, the subscription only exists while that branch is active.

```js
const store = state({ show: true, value: 42 });

effect(() => {
  if (store.show) {
    console.log(store.value); // only subscribed when show is true
  }
});
```

## Avoiding infinite loops

Writing to a store key inside an effect that reads the same key causes an infinite loop. If you need to derive a value, use [`computed`](../addons/computed.md) instead. Reading one key and writing a different key is fine:

```js
// Reads store.a, writes store.b — no loop
effect(() => {
  store.b = store.a * 2;
});

// Reads and writes store.count — infinite loop
effect(() => {
  store.count = store.count + 1;
});
```

## Cleanup

The dispose function returned by `effect()` tears down all subscriptions. Call it to stop the effect:

```js
const stop = effect(() => {
  document.title = `Count: ${store.count}`;
});

// Later:
stop(); // unsubscribes and stops re-running
```

## See also

- [watch()](../addons/watch.md) — explicit single-key subscription (no auto-tracking)
- [computed()](../addons/computed.md) — cached derived value
- [How reactivity works](../../guides/reactivity.md)

---

**← Previous: [bindDom()](bindDom.md)** | **Next: [batch()](batch.md) →**


========================================================================
FILE: docs/api/core/batch.md
========================================================================

# batch(fn)

Groups multiple state writes and flushes them together, synchronously, when the outermost `batch()` returns.

## Signature

```ts
function batch<T>(fn: () => T): T
```

Imported from `lume-js`.

## Parameters

- `fn` — A **synchronous** function performing state writes. Its return value is passed through.

## Returns

The return value of `fn`.

## Why batch?

Lume batches writes per store via microtasks. That is usually what you want — but it is *per store*. An effect that reads three stores runs three times when all three change:

```js
const a = state({ value: 1 });
const b = state({ value: 2 });
const c = state({ value: 3 });

effect(() => {
  render(a.value + b.value + c.value);
});

a.value = 10;
b.value = 20;
c.value = 30;
// → render() runs 3 times (once per store's flush)
```

Wrap the writes in `batch()` and the effect runs exactly once, synchronously, seeing all final values:

```js
import { state, effect, batch } from 'lume-js';

batch(() => {
  a.value = 10;
  b.value = 20;
  c.value = 30;
});
// → render() ran ONCE, seeing 60 — and it already ran (no await needed)
```

## Guarantees

| Behavior | Detail |
|----------|--------|
| Coalescing | Subscribers see only the **final** value of each key written in the batch |
| Cross-store dedupe | An effect depending on N mutated stores runs **once**, not N times |
| Synchronous flush | Everything has flushed by the time `batch()` returns |
| Nesting | Inner `batch()` calls are absorbed; one flush at the outermost end |
| Errors | If `fn` throws, writes made before the throw still flush, then the error propagates |
| Cascades | Writes made *by* subscribers/effects during the flush join the same batch (capped at 100 waves, then a console error) |

## Order of operations

When the outermost `batch()` ends, for each wave: every mutated store runs its `$beforeFlush` hooks and notifies its subscribers (in the order stores were first written), then the union of queued effects runs once each. Writes made during the wave start the next wave.

## Async functions are not batched

`fn` must be synchronous. Writes after an `await` happen after `batch()` already flushed and fall back to normal per-store microtask batching. Passing an async function logs a console warning:

```js
batch(async () => {
  store.a = 1;            // batched
  await fetch('/save');
  store.b = 2;            // NOT batched — normal microtask flush
});
```

## When not to use it

Single-store updates are already batched by the microtask scheduler — `batch()` adds nothing there. Reach for it when one user action mutates **multiple stores** and you want derived effects to run once, or when you need the DOM updated synchronously before the next line of code.

## See also

- [state()](state.md) — per-store microtask batching
- [effect()](effect.md) — reactive effects
- [Performance guide](../../guides/performance.md)

---

**← Previous: [effect()](effect.md)** | **Next: [watch()](../addons/watch.md) →**


========================================================================
FILE: docs/api/addons/watch.md
========================================================================

# watch(store, key, fn, options?)

Subscribes to a single store key. More explicit than `effect` — no auto-tracking, and the callback always receives the new value directly.

## Signature

```ts
function watch(
  store: object,
  key: string,
  fn: (newValue: any) => void,
  options?: { immediate?: boolean }
): () => void
```

Imported from `lume-js/addons`.

## Parameters

- `store` — A reactive store created by `state()`.
- `key` — The property name to watch.
- `fn` — Called with the new value on every change.
- `options.immediate` — Whether to call `fn` immediately with the current value (default: `true`).

## Returns

An unsubscribe function. Call it to stop watching.

## Examples

### Basic

```js
import { state } from 'lume-js';
import { watch } from 'lume-js/addons';

const store = state({ theme: 'light', count: 0 });

watch(store, 'theme', (newTheme) => {
  document.documentElement.dataset.theme = newTheme;
});
// Called immediately with 'light', then again on every change

store.theme = 'dark'; // callback fires with 'dark'
```

### One-time watcher

```js
const stop = watch(store, 'count', (val) => {
  if (val >= 10) {
    console.log('Reached 10!');
    stop(); // unsubscribe after the condition is met
  }
});
```

### Side effects (localStorage, analytics)

`watch` is the right tool for side effects that should react to exactly one key. Unlike auto-tracking `effect`, there is no risk of accidentally subscribing to extra keys.

```js
watch(store, 'theme', (theme) => {
  localStorage.setItem('theme', theme);
});

watch(store, 'userId', (id) => {
  analytics.identify(id);
});
```

### Skip the initial call with `{ immediate: false }`

By default `watch` fires immediately so you get the current value on subscribe. Pass `{ immediate: false }` to only react to future changes.

```js
// fires immediately with current value, then on every change
watch(store, 'count', (val) => console.log('count:', val));

// only fires on future changes — initial value is NOT logged
watch(store, 'count', (val) => {
  sendAnalytics('count_changed', val);
}, { immediate: false });
```

## Compared to `effect`

| | `effect(fn)` | `watch(store, key, fn)` |
|--|--------------|------------------------|
| Dependency tracking | Auto — all reads inside fn | Explicit — one key only |
| Callback args | none | `(newValue)` |
| Runs immediately | Yes (on first call) | Yes (always, on subscribe) |
| Best for | UI bindings, rendering | Side effects, persistence |

## See also

- [effect()](../core/effect.md)
- [computed()](computed.md)

---

**← Previous: [batch()](../core/batch.md)** | **Next: [computed()](computed.md) →**


========================================================================
FILE: docs/api/addons/computed.md
========================================================================

# computed(fn)

Creates a cached, read-only reactive value derived from store state.

## Signature

```ts
function computed<T>(fn: () => T): {
  readonly value: T;
  subscribe(callback: (value: T) => void): () => void;
  dispose(): void;
}
```

Imported from `lume-js/addons`.

## Parameters

- `fn` — A getter function. Must be synchronous. Should have no side effects.

## Returns

An object with:
- `value` — The current computed result. Re-evaluated only when dependencies change.
- `subscribe(callback)` — Subscribes to value changes. Calls `callback` immediately with the current value, then again on every subsequent change. Returns an unsubscribe function.
- `dispose()` — Stops the computation and frees subscriptions.

## Description

> **→ Why is `computed` an addon and not part of core?** [See the design decision.](../../design/design-decisions.md#why-no-computed-properties-in-core)

`computed` uses the same auto-tracking as `effect`: all store reads inside `fn` become dependencies. When any dependency changes, `fn` re-runs on the next microtask flush. The result is cached — `fn` never runs more than once per dependency change, no matter how many places read `computed.value`.

```js
import { state } from 'lume-js';
import { computed } from 'lume-js/addons';

const store = state({ price: 1.5, qty: 2 });

const total = computed(() => store.price * store.qty);

console.log(total.value); // 3

store.qty = 4;
// After microtask:
console.log(total.value); // 6
```

## Filtering lists

```js
const store = state({ todos: [...], filter: 'all' });

const visible = computed(() => {
  if (store.filter === 'active')    return store.todos.filter(t => !t.done);
  if (store.filter === 'completed') return store.todos.filter(t => t.done);
  return store.todos;
});

// Use in effects or templates:
effect(() => {
  badge.textContent = visible.value.length;
});
```

## With `repeat`

Pass a computed as the store to `repeat`, with `'value'` as the key:

```js
import { repeat } from 'lume-js/addons';

repeat(listEl, visible, 'value', {
  key: todo => todo.id,
  render: (todo, el) => { el.textContent = todo.text; }
});
```

## Cleanup

`computed` creates an internal `effect`. Call `dispose()` when the computed is no longer needed:

```js
const c = computed(() => store.x * 2);
// … later
c.dispose();
```

## See also

- [effect()](../core/effect.md)
- [watch()](watch.md)
- [Lists & repeat](../../guides/lists.md)

---

**← Previous: [watch()](watch.md)** | **Next: [repeat()](repeat.md) →**


========================================================================
FILE: docs/api/addons/repeat.md
========================================================================

# repeat(container, store, key, options)

The right tool for any list that changes. `repeat` renders a keyed list from a reactive array and reuses existing DOM nodes across updates — so adding, removing, or reordering items only touches what actually changed.

## Signature

```ts
function repeat(
  container: HTMLElement | string,
  store: object,
  key: string,
  options: {
    key: (item: any) => string | number;
    render?: (item: any, el: HTMLElement, index: number) => void;
    create?: (item: any, el: HTMLElement, index: number) => void;
    update?: (item: any, el: HTMLElement, index: number, ctx: { isFirstRender: boolean }) => void;
    template?: true | string | HTMLTemplateElement;
    element?: string | (() => HTMLElement);
    preserveFocus?: Function | null;
    preserveScroll?: Function | null;
  }
): () => void
```

Imported from `lume-js/addons`.

## Parameters

- `container` — The element (or CSS selector string) to render into.
- `store` — A reactive store or computed whose key holds the array.
- `key` — The property name of the array in `store`.
- `options.key` — **Required.** Returns a stable unique identifier per item. Used to match DOM nodes across updates.
- `options.render` — Mutates the element directly. (Return value is ignored). Called for new and updated items.
- `options.create` — Called once when a new DOM element is created. Use for DOM structure and event listeners.
- `options.update` — Called for data binding. Receives `{ isFirstRender }` so you can animate only on updates. **Skipped when the item reference and index are both unchanged from the previous render** (optimization). Use `render` instead if you always need to re-apply data regardless of reference equality.
- `options.template` — Declarative item structure from a standard `<template>` element: `true` (first `<template>` inside the container), a CSS selector, or the element itself. See [Pattern 0](#pattern-0--template-recommended-for-declarative-html).
- `options.element` — Tag name or factory for the wrapper element. Default: `'div'`. Ignored when `template` is set.
- `options.preserveFocus` — Optional strategy for preserving focus during re-renders. Default: `defaultFocusPreservation`.
- `options.preserveScroll` — Optional strategy for preserving scroll position during re-renders. Default: `defaultScrollPreservation`.

Use `render` alone for simple read-only lists. Use `create + update` for lists with event listeners — `create` runs once when the element is created, `update` runs on every data change.

> **→ Why `create` + `update` instead of a single `render`?** [See the design decision.](../../design/design-decisions.md#why-create--update-instead-of-just-render)

## Returns

A cleanup function.

## Pattern 0 — Template (recommended for declarative HTML)

The item's structure lives in your HTML as a standard `<template>` element — valid HTML, inert until cloned, no custom syntax. `data-bind` paths inside the template resolve against **each item**.

```html
<ul id="list">
  <template>
    <li>
      <strong data-bind="name"></strong>
      <span data-bind="user.city"></span>
      <em data-bind="$index"></em>
    </li>
  </template>
</ul>
```

```js
import { state } from 'lume-js';
import { repeat } from 'lume-js/addons';

const store = state({
  people: [
    { id: 1, name: 'Ada',   user: { city: 'London' } },
    { id: 2, name: 'Grace', user: { city: 'New York' } },
  ]
});

repeat('#list', store, 'people', {
  key: p => p.id,
  template: true   // the <template> inside #list
});
```

That's the whole list — no `createElement`, no `innerHTML`, no manual `textContent`.

**Binding paths** (identical value semantics to `bindDom`'s `data-bind` — inputs get `.value`/`.checked`, everything else gets `textContent`):

| Path | Resolves to |
|------|-------------|
| `data-bind="name"` | `item.name` |
| `data-bind="user.city"` | `item.user.city` |
| `data-bind="$item"` | the item itself (primitive arrays) |
| `data-bind="$index"` | the item's current index |

Bindings are **one-way snapshots**, re-applied on each list update (items are plain objects, not stores — update arrays immutably as usual). For event listeners or extra binding, add `create`/`update` on top:

```js
repeat('#list', store, 'people', {
  key: p => p.id,
  template: true,
  create: (p, el) => {
    el.querySelector('button.delete').onclick = () => {
      store.people = store.people.filter(x => x.id !== p.id);
    };
  }
});
```

The template must contain exactly **one root element**. `render` is ignored (with a warning) in template mode; `element` is ignored. The source `<template>` element is **preserved** — reconciliation and cleanup never remove it from your markup, so unmounting and re-binding with `template: true` works.

## Pattern 1 — Simple (render only)

Best for read-only lists where no event listeners are needed on items.

```js
import { state } from 'lume-js';
import { repeat } from 'lume-js/addons';

const store = state({
  todos: [
    { id: 1, text: 'Buy milk', done: false },
    { id: 2, text: 'Walk dog', done: true  },
  ]
});

repeat(document.getElementById('list'), store, 'todos', {
  key: todo => todo.id,
  element: 'li',
  render: (todo, el) => {
    el.className = todo.done ? 'done' : '';
    el.textContent = todo.text;
  }
});
```

## Pattern 2 — create + update (recommended)

Best for items with event listeners. `create` runs once per DOM element; `update` runs on every data change.

```js
repeat('#todo-list', store, 'todos', {
  key: todo => todo.id,
  element: 'li',

  create: (todo, el) => {
    el.innerHTML = `
      <input type="checkbox" class="toggle">
      <span class="text"></span>
      <button class="delete">×</button>
    `;
    el.querySelector('.toggle').onchange = () => {
      store.todos = store.todos.map(t =>
        t.id === todo.id ? { ...t, done: !t.done } : t
      );
    };
    el.querySelector('.delete').onclick = () => {
      store.todos = store.todos.filter(t => t.id !== todo.id);
    };
  },

  update: (todo, el, index, { isFirstRender }) => {
    el.querySelector('.toggle').checked = todo.done;
    el.querySelector('.text').textContent = todo.text;
    el.classList.toggle('done', todo.done);
    if (!isFirstRender) el.classList.add('updated'); // animate on change
  }
});
```

## Array operations

| Array change | DOM effect |
|--------------|------------|
| New key added (immutable replace) | Appends/inserts new row |
| Key removed (immutable replace) | Removes row, moves nothing else |
| Reorder — same keys (immutable replace) | Moves only nodes out of relative order, `update` fires (index changed) |
| Same key, item ref changed | Only that row's `update` fires |

Reorders are minimal-move: reconciliation keeps the longest stable chain of surviving rows in place (longest increasing subsequence over previous positions) and re-inserts only the rest, so a k-item change costs O(k) `insertBefore` calls — a far 2-item swap moves 2 nodes, not everything between them. Rows that don't move keep their live state (playing `<video>`, `<iframe>` documents, running CSS transitions).

> **→ Why check both reference AND index to skip `update`?** [See the design decision.](../../design/design-decisions.md#why-check-both-reference-and-index-for-update-skip)

## Using with `computed`

Pass a `computed` as the store and `'value'` as the key:

```js
import { computed } from 'lume-js/addons';

const filtered = computed(() =>
  store.todos.filter(t => store.filter === 'all' || !t.done)
);

repeat(listEl, filtered, 'value', {
  key: t => t.id,
  render: (t, el) => { el.textContent = t.text; }
});
```

## Caveats

- **Keys must be unique.** Duplicate keys log a warning; both items end up sharing the same DOM element, which produces incorrect rendering.
- **Each rendered element must have exactly one root.** Wrap fragments in a `<div>` or `<li>`.

## See also

- [Lists & repeat guide](../../guides/lists.md)
- [computed()](computed.md)
- [Todo app tutorial](../../tutorials/build-todo-app.md)

---

**← Previous: [computed()](computed.md)** | **Next: [persist()](persist.md) →**


========================================================================
FILE: docs/api/addons/persist.md
========================================================================

# persist(store, storageKey, options?)

Keeps selected store keys in sync with `localStorage` (or any Storage-like object): hydrates them when called, then saves automatically on change.

## Signature

```ts
function persist(
  store: ReactiveState<any>,
  storageKey: string,
  options?: {
    keys?: string[];
    storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
  }
): () => void
```

Imported from `lume-js/addons`.

## Parameters

- `store` — A reactive store created with `state()`.
- `storageKey` — The storage entry name to read/write (one JSON blob per `persist()` call).
- `options.keys` — Which keys to persist. Default: all own non-`$` keys of the store at call time.
- `options.storage` — `localStorage` (default), `sessionStorage`, or any object with `getItem`/`setItem`.

## Returns

A dispose function. Call it to stop watching and saving.

## Example

```js
import { state, bindDom } from 'lume-js';
import { persist } from 'lume-js/addons';

const store = state({
  todos: [],
  filter: 'all',
  draft: '',          // transient — excluded below
});

// Hydrates todos/filter from storage, then saves them on every change
const stop = persist(store, 'todo-app', { keys: ['todos', 'filter'] });

bindDom(document.body, store);
```

That replaces the usual hand-rolled pair of `JSON.parse(localStorage.getItem(...))` at startup and `localStorage.setItem(...)` sprinkled through every mutation site.

## Behavior

| Concern | Behavior |
|---------|----------|
| Hydration | Stored values are assigned **through the proxy**, so subscribers and DOM bindings see them like any other write |
| Unknown keys in storage | Ignored — only watched keys are ever assigned (stale storage can't inject state) |
| Save timing | Coalesced to **one** storage write per microtask, no matter how many keys changed |
| Unchanged data | Skipped — if the serialized snapshot equals what storage already holds, no write happens |
| Corrupted JSON | Console warning, starts fresh |
| Unserializable state (circular refs, etc.) | Console warning, save skipped |
| Quota exceeded / write failure | Console warning, app keeps running |
| No storage (SSR, locked-down browsers) | Console warning, persistence disabled, returned dispose is a safe no-op |
| `keys: []` | Respected — persists and hydrates nothing (only an *absent* option falls back to all keys) |
| Same `storageKey` managed twice | Console warning on the second `persist()` — instances would overwrite each other's data |

## Per-tab persistence

```js
persist(store, 'wizard-progress', { storage: sessionStorage });
```

## Multiple stores

Each call owns one storage entry — give each store its own key (a second `persist()` on an already-managed key logs a warning, since the instances would overwrite each other):

```js
persist(settingsStore, 'app:settings');
persist(cartStore, 'app:cart', { keys: ['items'] });
```

## What it doesn't do

- **No cross-tab sync** — it doesn't listen to the `storage` event. (Candidate for a future option.)
- **No serialization of functions/Symbols** — values pass through `JSON.stringify`; keep persisted keys to plain data.
- **No versioning/migrations** — pair it with [`hydrateState`](hydrateState.md)-style validation if your schema evolves: read, validate, then `persist()`.

## See also

- [hydrateState()](hydrateState.md) — initial state from server-rendered JSON
- [watch()](watch.md) — the manual building block this replaces

---

**← Previous: [repeat()](repeat.md)** | **Next: [createCleanupGroup()](createCleanupGroup.md) →**


========================================================================
FILE: docs/api/addons/createCleanupGroup.md
========================================================================

# createCleanupGroup()

Creates a cleanup group that collects multiple cleanup/unsubscribe functions and disposes them all at once.

## Signature

```ts
function createCleanupGroup(): {
  add(fn: () => void): void;
  dispose(): void;
}
```

Imported from `lume-js/addons`.

## Returns

An object with:
- `add(fn)` — Registers a cleanup function. Non-functions are silently ignored.
- `dispose()` — Calls all registered cleanup functions in reverse order, then clears the group.

## Description

`createCleanupGroup` solves the problem of tracking many cleanup functions across a component or view lifecycle. Each Lume primitive returns an unsubscribe/cleanup function — `bindDom`, `effect`, `watch`, `computed`, `store.$subscribe`. Instead of keeping references to each individually, add them to a group and call `dispose()` once.

```js
import { state, bindDom, effect } from 'lume-js';
import { createCleanupGroup, watch } from 'lume-js/addons';

const store = state({ name: 'World', count: 0 });
const group = createCleanupGroup();

group.add(bindDom(document.body, store));
group.add(effect(() => { store.doubled = store.count * 2; }));
group.add(watch(store, 'count', val => localStorage.setItem('count', val)));

// Later — dispose everything at once
group.dispose();
```

## Component teardown

The most common use case is tearing down all reactivity when a view or component is removed:

```js
function mountUserCard(container, store) {
  const group = createCleanupGroup();

  group.add(bindDom(container, store));
  group.add(store.$subscribe('profile', render));

  return () => group.dispose(); // return teardown function
}

const teardown = mountUserCard(el, store);
// When the component unmounts:
teardown();
```

## Error handling

Errors thrown by individual cleanup functions are caught and swallowed so that one broken cleanup does not prevent the others from running.

## See also

- [effect()](../core/effect.md)
- [watch()](watch.md)
- [bindDom()](../core/bindDom.md)
- [Cleanup & Disposal guide](../../guides/cleanup-and-dispose.md)

---

**← Previous: [persist()](persist.md)** | **Next: [hydrateState()](hydrateState.md) →**


========================================================================
FILE: docs/api/addons/hydrateState.md
========================================================================

# hydrateState()

Reads initial state from a `<script type="application/json">` element embedded in server-rendered HTML.

## Signature

```ts
function hydrateState(selector?: string): object
```

Imported from `lume-js/addons`.

## Parameters

- `selector` — CSS selector for the script element. Defaults to `'#__LUME_DATA__'`.

## Returns

The parsed JSON object from the selected element, or an empty object `{}` if the element is not found or the JSON is invalid.

## Description

`hydrateState` enables SSR hydration: the server embeds the page's initial data as JSON in the HTML, and the client reads it to initialize reactive state without a separate API request.

**Server (any language/framework):**
```html
<script id="__LUME_DATA__" type="application/json">
  {"title": "Welcome", "user": "Ada", "count": 42}
</script>
```

**Client:**
```js
import { state, bindDom } from 'lume-js';
import { hydrateState } from 'lume-js/addons';

const store = state(hydrateState());
bindDom(document.body, store);
```

The store is initialized with `{ title: 'Welcome', user: 'Ada', count: 42 }` immediately — no async, no flash of empty content.

## Custom selector

Use a different selector when embedding multiple data blocks on one page:

```html
<script id="sidebar-data" type="application/json">{"open": false}</script>
<script id="cart-data"    type="application/json">{"items": [], "total": 0}</script>
```

```js
const sidebar = state(hydrateState('#sidebar-data'));
const cart    = state(hydrateState('#cart-data'));
```

## Safe fallback

`hydrateState` always returns an object. If the selector matches nothing, or the JSON is malformed, you get `{}` — which merges cleanly with default state:

```js
const store = state({
  count: 0,          // default
  ...hydrateState(), // server overrides
});
```

## Non-browser environments

When `document` is not defined (Node.js, Workers), `hydrateState` returns `{}` safely.

## See also

- [state()](../core/state.md)
- [createCleanupGroup()](createCleanupGroup.md)

---

**← Previous: [createCleanupGroup()](createCleanupGroup.md)** | **Next: [createDebugPlugin() / debug](debug.md) →**


========================================================================
FILE: docs/api/addons/debug.md
========================================================================

# createDebugPlugin(options)

`createDebugPlugin` logs every read, write, and notification on a store to the console. Use it during development to see exactly which state changes triggered which updates — and which keys are being read more than you expect.

## Import

```javascript
import { state } from 'lume-js';
import { withPlugins, createDebugPlugin, debug } from 'lume-js/addons';
```

## createDebugPlugin(options)

Creates a debug plugin object. Wrap it with `withPlugins()` to apply it to a store.

### Signature

```typescript
function createDebugPlugin(options?: DebugPluginOptions): Plugin;

interface DebugPluginOptions {
  label?: string;       // Label for log messages (default: 'store')
  logGet?: boolean;     // Log property reads (default: false)
  logSet?: boolean;     // Log property writes (default: true)
  logNotify?: boolean;  // Log subscriber notifications (default: true)
  trace?: boolean;      // Show stack trace for SET operations (default: false)
}
```

### Example

```javascript
import { state } from 'lume-js';
import { withPlugins, createDebugPlugin } from 'lume-js/addons';

const store = withPlugins(state({ count: 0 }), [
  createDebugPlugin({ 
    label: 'counter',
    logGet: true,
    logSet: true,
    logNotify: true,
    trace: true  // Show stack traces for debugging
  })
]);

store.count++;
// Console: [counter] SET count: 0 → 1
// Console: [counter] Stack trace for count (if trace: true)
```

### Dynamic Options

Options can use getters for runtime toggling:

```javascript
const config = { logGet: false };

const store = withPlugins(state({ count: 0 }), [
  createDebugPlugin({ 
    label: 'myStore',
    get logGet() { return config.logGet; }
  })
]);

// Toggle at runtime
config.logGet = true;  // Now GET operations will log
```

## debug (Global Controls)

`debug` is a global object that controls all active debug plugins at once. Use it to toggle logging, filter by key name, or inspect operation counts without touching each store individually.

### Methods

| Method | Description |
|--------|-------------|
| `debug.enable()` | Enable debug logging globally |
| `debug.disable()` | Disable debug logging globally |
| `debug.isEnabled()` | Check if logging is enabled |
| `debug.filter(pattern)` | Filter by key (string, RegExp, or null) |
| `debug.getFilter()` | Get current filter pattern |
| `debug.stats()` | Get statistics data (silent) |
| `debug.logStats()` | Log statistics to console with table |
| `debug.resetStats()` | Clear all statistics |

### Example

```javascript
import { debug } from 'lume-js/addons';

debug.enable();           // Turn on logging
debug.filter('count');    // Only log keys containing 'count'
debug.filter(/^user/);    // Only log keys starting with 'user'
debug.filter(null);       // Clear filter

const stats = debug.stats();  // Get stats data (silent)
debug.logStats();             // Log stats to console with formatting
debug.resetStats();           // Clear stats
```

## Statistics

The debug addon tracks operation counts for each store:

```javascript
const stats = debug.stats();
// {
//   counter: {
//     gets: { count: 5 },
//     sets: { count: 3 },
//     notifies: { count: 3 }
//   },
//   user: {
//     gets: { name: 2, age: 1 },
//     sets: { name: 1 },
//     notifies: { name: 1 }
//   }
// }
```

## Console Output

Debug logs use colored output:
- **GET** (green): Property reads
- **SET** (orange): Property writes  
- **NOTIFY** (pink): Subscriber notifications
- **SUBSCRIBE** (purple): New subscriptions

---

**← Previous: [hydrateState()](hydrateState.md)** | **Next: [withPlugins()](withPlugins.md) →**


========================================================================
FILE: docs/api/addons/withPlugins.md
========================================================================

# withPlugins API

> **Version:** 2.0.0+ **Status:** Stable

The plugin system lets you extend Lume state with custom behaviors — logging, validation, persistence, transformation, and more. Plugins intercept state operations through a small set of hooks.

Plugins are applied via `withPlugins()`, an addon wrapper. The core `state()` function has no plugin support — this keeps the core minimal and fast.

## Table of Contents

- [Quick Start](#quick-start)
- [Plugin Interface](#plugin-interface)
- [Hook Execution Order](#hook-execution-order)
- [Chain Pattern](#chain-pattern)
- [Best Practices](#best-practices)
- [Common Patterns](#common-patterns)
- [Performance](#performance)

## Quick Start

```javascript
import { state } from 'lume-js';
import { withPlugins } from 'lume-js/addons';

const debugPlugin = {
  name: 'debug',
  onGet: (key, value) => {
    console.log(`GET ${key}:`, value);
    return value;
  },
  onSet: (key, newValue, oldValue) => {
    console.log(`SET ${key}:`, oldValue, '→', newValue);
    return newValue;
  }
};

const store = withPlugins(state({ count: 0 }), [debugPlugin]);
```

## Plugin Interface

A plugin is a plain object with a `name` property and optional hook functions:

```typescript
interface Plugin {
  name: string;                                                    // Required: unique identifier
  onInit?: () => void;                                             // Called when state is created
  onGet?: (key: string, value: any) => any;                       // Intercept reads
  onSet?: (key: string, newValue: any, oldValue: any) => any;     // Intercept writes
  onSubscribe?: (key: string) => void;                             // Called when a subscriber is added
  onNotify?: (key: string, value: any) => void;                   // Before subscribers are notified
}
```

> **Plugin objects are frozen after registration.** Once `withPlugins()` returns, `Object.freeze()` has been applied to each plugin — hooks cannot be swapped afterwards, and writes to plugin properties fail silently. Mutable plugin state (a history stack, a cache) must live in a closure variable next to the plugin, not on the plugin object itself. `onInit` runs before the freeze, so one-time setup on the object is still possible there.

### Hook: `onInit()`

Called synchronously when the state object is created.

**Use cases:** initialize plugin state, set up external connections, register global handlers.

```javascript
const plugin = {
  name: 'logger',
  onInit: () => {
    console.log('State initialized at', new Date());
  }
};
```

### Hook: `onGet(key, value)`

Called when a property is accessed, before the value is returned.

**Parameters:**
- `key` — Property key being accessed.
- `value` — Current value (possibly transformed by earlier plugins in the chain).

**Returns:** Transformed value, or the original `value` to pass it through unchanged.

**Use cases:** transform values on read, log access, implement computed properties, lazy loading.

```javascript
const transformPlugin = {
  name: 'transform',
  onGet: (key, value) => {
    if (key === 'name' && typeof value === 'string') {
      return value.toUpperCase();
    }
    return value;
  }
};
```

### Hook: `onSet(key, newValue, oldValue)`

Called when a property is updated, before subscribers are notified.

**Parameters:**
- `key` — Property key being updated.
- `newValue` — New value (possibly transformed by earlier plugins).
- `oldValue` — Previous value.

**Returns:** The value to store. Return `oldValue` to reject the change.

**Use cases:** validate input, transform values on write, prevent updates, track history.

```javascript
const validationPlugin = {
  name: 'validation',
  onSet: (key, newValue, oldValue) => {
    if (key === 'age' && (newValue < 0 || newValue > 150)) {
      console.warn('Invalid age, keeping old value');
      return oldValue; // Reject change
    }
    return newValue; // Accept change
  }
};
```

### Hook: `onSubscribe(key)`

Called when a new subscriber is added to a property.

**Parameters:**
- `key` — Property key being subscribed to.

**Use cases:** track active subscriptions, lazy load data, initialize watchers.

```javascript
const trackPlugin = {
  name: 'tracker',
  onSubscribe: (key) => {
    console.log(`New subscriber for "${key}"`);
  }
};
```

### Hook: `onNotify(key, value)`

Called during microtask flush, before subscribers are notified. This is the right place for side effects.

**Parameters:**
- `key` — Property key that changed.
- `value` — New value being notified.

**Use cases:** log notifications, sync with external systems, trigger side effects.

```javascript
const syncPlugin = {
  name: 'sync',
  onNotify: (key, value) => {
    localStorage.setItem(key, JSON.stringify(value));
  }
};
```

## Hook Execution Order

### Property access (get)

```
1. Property accessed: store.count
2. onGet hooks run (all plugins, in registration order)
3. Transformed value returned to caller
```

### Property update (set)

```
1. Property set: store.count = 5
2. onSet hooks run (all plugins, in registration order)
3. Final value stored
4. Change queued for microtask
--- microtask boundary ---
5. onNotify hooks run (all plugins, in registration order)
6. Subscribers notified
7. Effects re-run
```

### Diagram

```
store.count = 5
    ↓
  onSet (plugin1)
    ↓
  onSet (plugin2)
    ↓
  value stored
    ↓
  microtask scheduled
    ↓
  --- wait for microtask ---
    ↓
  onNotify (plugin1)
    ↓
  onNotify (plugin2)
    ↓
  subscribers called
    ↓
  effects run
```

## Chain Pattern

When multiple plugins are registered, each plugin receives the output of the previous one.

### Get chain

```javascript
const plugin1 = {
  name: 'double',
  onGet: (key, value) => typeof value === 'number' ? value * 2 : value
};

const plugin2 = {
  name: 'add10',
  onGet: (key, value) => typeof value === 'number' ? value + 10 : value
};

const store = withPlugins(state({ count: 5 }), [plugin1, plugin2]);

console.log(store.count); // (5 * 2) + 10 = 20
```

### Set chain

```javascript
const plugin1 = {
  name: 'clamp',
  onSet: (key, value) => {
    if (key === 'age') return Math.max(0, Math.min(150, value));
    return value;
  }
};

const plugin2 = {
  name: 'round',
  onSet: (key, value) => {
    if (key === 'age') return Math.round(value);
    return value;
  }
};

const store = withPlugins(state({ age: 0 }), [plugin1, plugin2]);

store.age = 175.7;
console.log(store.age); // Math.round(Math.min(150, 175.7)) = 150
```

## Best Practices

### Keep plugins focused

Each plugin should do one thing well.

```javascript
// Good: Single responsibility
const validationPlugin = { name: 'validation', onSet: validateData };
const loggingPlugin    = { name: 'logging',    onGet: logAccess };

// Avoid: Mixed responsibilities in one plugin
const godPlugin = {
  name: 'everything',
  onGet: (key, value) => { /* validate + log + transform + … */ }
};
```

### Return early for non-applicable keys

```javascript
const ageValidator = {
  name: 'age-validator',
  onSet: (key, newValue, oldValue) => {
    if (key !== 'age') return newValue;
    if (newValue < 0 || newValue > 150) return oldValue;
    return newValue;
  }
};
```

### Handle errors gracefully

Lume catches errors in plugin hooks and logs them, but your plugin should handle expected errors:

```javascript
const safePlugin = {
  name: 'safe',
  onGet: (key, value) => {
    try {
      return JSON.parse(value);
    } catch (e) {
      console.warn(`Failed to parse ${key}:`, e);
      return value;
    }
  }
};
```

### Keep `onGet` pure

`onGet` runs on every property read. Side effects here (fetch calls, writes to other keys) will fire far more often than you expect. Use `onNotify` for side effects instead.

```javascript
// Good: pure transformation
const plugin = {
  name: 'format',
  onGet: (key, value) => typeof value === 'string' ? value.toUpperCase() : value
};

// Avoid: side effects in onGet
const plugin = {
  name: 'bad',
  onGet: (key, value) => {
    fetch('/api/log', { method: 'POST', body: key }); // fires on every read!
    return value;
  }
};
```

### Use `onNotify` for side effects

```javascript
const persistPlugin = {
  name: 'persist',
  onNotify: (key, value) => {
    localStorage.setItem(key, JSON.stringify(value));
  }
};
```

## Common Patterns

### Validation

```javascript
const validationPlugin = {
  name: 'validation',
  onSet: (key, newValue, oldValue) => {
    const rules = {
      email: (v) => typeof v === 'string' && v.includes('@'),
      age:   (v) => typeof v === 'number' && v >= 0 && v <= 150
    };

    if (rules[key] && !rules[key](newValue)) {
      console.error(`Validation failed for ${key}`);
      return oldValue;
    }

    return newValue;
  }
};
```

### History / Undo-Redo

```javascript
// Plugin objects are frozen after registration, so mutable plugin state
// lives in a closure variable — not on the plugin object.
const historyStack = [];

const historyPlugin = {
  name: 'history',
  onSet: (key, newValue, oldValue) => {
    historyStack.push({ key, value: oldValue });
    return newValue;
  }
};

function undo(store) {
  if (historyStack.length > 0) {
    const { key, value } = historyStack.pop();
    store[key] = value;
  }
}
```

### Persistence

```javascript
const persistPlugin = {
  name: 'persist',

  onInit: () => {
    persistPlugin.loaded = true;
  },

  onGet: (key, value) => {
    if (persistPlugin.loaded && value === undefined) {
      const stored = localStorage.getItem(key);
      return stored ? JSON.parse(stored) : value;
    }
    return value;
  },

  onNotify: (key, value) => {
    localStorage.setItem(key, JSON.stringify(value));
  }
};
```

### Transform / Normalize

```javascript
const normalizePlugin = {
  name: 'normalize',
  onSet: (key, newValue) => {
    if (key === 'email' && typeof newValue === 'string') {
      return newValue.toLowerCase().trim();
    }
    if (key === 'phone' && typeof newValue === 'string') {
      return newValue.replace(/\D/g, ''); // digits only
    }
    return newValue;
  }
};
```

## Performance

Plugin hooks add minimal overhead — typically 10–30% per operation depending on complexity. Each hook call is synchronous, and multiple plugins execute sequentially.

**Tips:**
- Filter early: return immediately for non-applicable keys.
- Keep hook logic lightweight.
- Cache computed results when needed.
- For typical apps, 1–3 plugins is plenty.

Typical overhead on a modern system (M1 Mac):

| Operation | No Plugins | 1 Plugin | 3 Plugins | 10 Plugins |
|-----------|------------|----------|-----------|------------|
| Get | 0.001 ms | 0.002 ms | 0.004 ms | 0.010 ms |
| Set | 0.002 ms | 0.003 ms | 0.006 ms | 0.015 ms |

For the vast majority of applications, plugin overhead is negligible.

## Error Handling

Plugin errors are caught and logged but do not crash the application:

```javascript
const buggyPlugin = {
  name: 'buggy',
  onGet: (key, value) => {
    throw new Error('Oops!');
  }
};

const store = withPlugins(state({ count: 0 }), [buggyPlugin]);

store.count; // Logs error, returns original value
// Console: [Lume.js] Plugin "buggy" error in onGet: Error: Oops!
```

## TypeScript Support

Full TypeScript definitions are provided:

```typescript
import { state } from 'lume-js';
import { withPlugins, Plugin } from 'lume-js/addons';

const myPlugin: Plugin = {
  name: 'example',
  onGet: (key: string, value: unknown): unknown => {
    return value;
  }
};

const store = withPlugins(state({ count: 0 }), [myPlugin]);
```

## See also

- [Design Decisions](../../design/design-decisions.md) — Why plugins work this way
- [State API](../core/state.md) — Core state documentation
- [addons/debug](./debug.md) — Built-in debug plugin using withPlugins

---

**← Previous: [createDebugPlugin() / debug](debug.md)** | **Next: [isReactive()](isReactive.md) →**


========================================================================
FILE: docs/api/addons/isReactive.md
========================================================================

# isReactive(value)

Returns `true` if the value is a Lume reactive proxy created by `state()`.

> **Import path changed in v2.0.0:** `isReactive` moved from `lume-js` to `lume-js/addons`.

## Signature

```ts
function isReactive(value: any): boolean;
```

## Parameters

- `value` — The value to check.

## Returns

`true` if the value carries the Lume reactive brand (a registry symbol stamped by `state()`), or — as a compatibility fallback — has a `$subscribe` method. `false` otherwise.

## Example

```js
import { state } from 'lume-js';
import { isReactive } from 'lume-js/addons';

const store = state({ count: 0 });

isReactive(store); // true
isReactive({});    // false
```

This is useful when writing utilities or addons that need to accept either a raw object or an already-reactive store without double-wrapping it.

## Note

Detection checks the shared brand symbol first (`Symbol.for('lume.reactive')`, checked with the `in` operator so it never registers an effect dependency), then falls back to duck-typing (`typeof obj.$subscribe === 'function'`) for stores created by older lume-js versions. The brand is a type tag, not a security boundary — any code can stamp it.

---

**← Previous: [withPlugins()](withPlugins.md)** | **Next: [Handlers API](../core/handlers.md) →**


========================================================================
FILE: docs/api/core/handlers.md
========================================================================

# Handlers API

`bindDom()` accepts a `handlers` option — plain objects that teach it how to interpret additional `data-*` attributes. This page documents that extension contract. For the ready-to-use handlers themselves (`show`, `boolAttr`, `ariaAttr`, `classToggle`, `stringAttr`, `on`, `htmlAttrs`, presets), see the [API — Handlers](../handlers/show.md) reference pages.

## Table of Contents

- [Quick Start](#quick-start)
- [Handler Contract](#handler-contract)
- [Handler Override](#handler-override)
- [Custom Handlers](#custom-handlers)
- [Usage Patterns](#usage-patterns)

## Quick Start

```javascript
import { state, bindDom } from 'lume-js';
import { show, classToggle, stringAttr } from 'lume-js/handlers';

const store = state({ isVisible: true, isActive: false, url: '/profile' });

bindDom(document.body, store, {
  handlers: [show, classToggle('active'), stringAttr('href')]
});
```

```html
<span data-show="isVisible">Visible when truthy</span>
<div data-class-active="isActive">Toggles CSS class</div>
<a data-href="url">Profile</a>
```

## Handler Contract

A handler is any object with two properties:

```typescript
interface Handler {
  readonly attr: string;                        // e.g., 'data-show', 'data-class-active'
  apply(el: HTMLElement, val: any): void;       // Called with the reactive value
}
```

- `attr` — The `data-*` attribute name that triggers this handler.
- `apply` — Called immediately with the current value, then again whenever the state changes.

Handlers passed to `bindDom(root, store, { handlers: [...] })` can also be **arrays** of handler objects — `bindDom` auto-flattens one level, which is how factory functions like `classToggle(...names)` return multiple handlers from a single call.

## Handler Override

User-supplied handlers override built-in handlers with the same `attr`. This lets you customize default behavior:

```javascript
// Override data-hidden to use display:none instead of the hidden property
const customHidden = {
  attr: 'data-hidden',
  apply(el, val) {
    el.style.display = val ? 'none' : '';
  }
};

bindDom(root, store, { handlers: [customHidden] });
```

Built-in handlers that can be overridden: `data-hidden`, `data-disabled`, `data-checked`, `data-required`, `data-aria-expanded`, `data-aria-hidden`.

## Custom Handlers

Any plain object matching `{ attr, apply }` works as a handler — no registration system, no framework API:

```javascript
// Tooltip handler
const tooltip = {
  attr: 'data-tooltip',
  apply(el, val) { el.title = val ?? ''; }
};

// Background color handler
const bgColor = {
  attr: 'data-bg',
  apply(el, val) { el.style.backgroundColor = val ?? ''; }
};

bindDom(root, store, { handlers: [tooltip, bgColor] });
```

```html
<span data-tooltip="helpText">Hover me</span>
<div data-bg="themeColor">Styled</div>
```

## Usage Patterns

### Minimal (built-ins only)

```javascript
// No handlers import needed — defaults are always active
bindDom(document.body, store);
```

### Cherry-pick what you need

```javascript
import { show, classToggle } from 'lume-js/handlers';
bindDom(root, store, { handlers: [show, classToggle('active')] });
```

### Everything at once

```javascript
import { htmlAttrs } from 'lume-js/handlers';

bindDom(root, store, { handlers: [htmlAttrs()] });
```

See [htmlAttrs](../handlers/htmlAttrs.md) for what's included, and when to prefer cherry-picking instead.

### Multiple `bindDom` calls with different handlers

```javascript
// Form section needs form handlers
bindDom(document.getElementById('form'), formStore, {
  handlers: formHandlers
});

// Nav section needs different handlers
bindDom(document.getElementById('nav'), navStore, {
  handlers: [show, classToggle('active')]
});
```

## See also

- [Ready-to-use handlers](../handlers/show.md) — `show`, `className`, `boolAttr`, `ariaAttr`, `classToggle`, `stringAttr`, `on`, `htmlAttrs`
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](bindDom.md)

---

**← Previous: [isReactive()](../addons/isReactive.md)** | **Next: [show](../handlers/show.md) →**


========================================================================
FILE: docs/api/handlers/show.md
========================================================================

# show

Hides or shows an element based on a store value. When the value is truthy, the element is visible. When falsy, it gets `hidden = true`. This is the inverse of the built-in `data-hidden` attribute.

## Attribute

`data-show="key"`

## Import

```js
import { show } from 'lume-js/handlers';
```

## Usage

```js
import { state, bindDom } from 'lume-js';
import { show } from 'lume-js/handlers';

const store = state({ loggedIn: false, loading: true });

bindDom(document.body, store, { handlers: [show] });
```

```html
<nav data-show="loggedIn">
  <a href="/dashboard">Dashboard</a>
  <a href="/settings">Settings</a>
</nav>

<div class="spinner" data-show="loading">Loading…</div>
```

When `store.loggedIn` is `false`, the nav gets `hidden` set to `true`. When it becomes truthy, `hidden` is set to `false` and the element is shown.

## Behavior

| Value | Effect |
|-------|--------|
| Truthy | `el.hidden = false` (element shown) |
| Falsy (`false`, `null`, `0`, `''`) | `el.hidden = true` (element hidden) |

This uses the native `hidden` attribute mechanism, not inline `style.display`.

## Compared to `data-hidden`

`bindDom` has a built-in `data-hidden` attribute that sets `el.hidden = Boolean(val)`. The difference:

| | `data-show` | `data-hidden` |
|--|-------------|---------------|
| Value meaning | truthy = visible | truthy = hidden |
| Mechanism | `hidden` attribute | `hidden` attribute |
| Import required | Yes | No |

Use `data-show` when the condition is already in "visible" form (`isLoggedIn`, `hasResults`). Use `data-hidden` when it's in "hidden" form (`isLoading`, `isEmpty`).

## See also

- [classToggle](classToggle.md)
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [Handlers API](../core/handlers.md)** | **Next: [className](className.md) →**


========================================================================
FILE: docs/api/handlers/className.md
========================================================================

# className

Replaces an element's full class string with a store value.

## Attribute

`data-classname="key"`

## Import

```js
import { className } from 'lume-js/handlers';
```

## Usage

```js
import { state, bindDom } from 'lume-js';
import { className } from 'lume-js/handlers';

const store = state({ cardStyle: 'card card--featured' });

bindDom(document.body, store, { handlers: [className] });
```

```html
<div data-classname="cardStyle">Featured</div>
```

When `store.cardStyle` changes, `el.className` is replaced with the new value. If the value is falsy (`null`, `undefined`, `false`, `''`), the class string is set to `''`.

## Behavior

| Value | Effect |
|-------|--------|
| `'card card--featured'` | `el.className = 'card card--featured'` |
| `''` / falsy | `el.className = ''` (all classes removed) |

`className` replaces the entire class string on every update. Any classes added outside reactive state will be lost.

## Compared to `classToggle`

| | `className` | `classToggle` |
|--|-------------|---------------|
| Controls | Full class string | Individual CSS classes |
| Use when | Class string comes from state | Toggling one class on/off |
| Static classes safe | ❌ (overwritten) | ✅ (other classes preserved) |

Use `className` when the entire class string is computed. Use `classToggle` to flip individual classes based on boolean state while preserving others.

## See also

- [classToggle](classToggle.md)
- [show](show.md)
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [show](show.md)** | **Next: [boolAttr](boolAttr.md) →**


========================================================================
FILE: docs/api/handlers/boolAttr.md
========================================================================

# boolAttr(name)

Creates a handler that toggles any HTML boolean attribute reactively.

## Signature

```ts
function boolAttr(name: string): { attr: string; apply(el: HTMLElement, val: any): void }
```

## Import

```js
import { boolAttr } from 'lume-js/handlers';
```

## Parameters

- `name` — The HTML attribute name (e.g. `'readonly'`, `'open'`, `'contenteditable'`).

## Returns

A handler object `{ attr: 'data-<name>', apply }` for use in `bindDom`'s `handlers` option.

## Usage

```js
import { state, bindDom } from 'lume-js';
import { boolAttr } from 'lume-js/handlers';

const store = state({ editable: false, panelOpen: true });

bindDom(document.body, store, {
  handlers: [boolAttr('contenteditable'), boolAttr('open')]
});
```

```html
<div data-contenteditable="editable">Click to edit</div>
<details data-open="panelOpen">
  <summary>Details</summary>
  <p>Content</p>
</details>
```

## Behavior

Uses `el.toggleAttribute(name, Boolean(val))`. A truthy value sets the attribute; a falsy value removes it.

| Value | Effect |
|-------|--------|
| Truthy | `el.setAttribute(name, '')` — attribute present |
| Falsy (`false`, `null`, `0`, `''`) | `el.removeAttribute(name)` — attribute absent |

## Built-in Boolean Attributes

`bindDom` has built-in handlers for the most common boolean attributes — you don't need `boolAttr` for these:

| Attribute | Built-in |
|-----------|----------|
| `hidden` | `data-hidden` |
| `disabled` | `data-disabled` |
| `checked` | `data-checked` |
| `required` | `data-required` |

Use `boolAttr` for any boolean attribute not covered by the built-ins (e.g. `readonly`, `open`, `contenteditable`, `multiple`, `novalidate`).

## Presets

The `formHandlers` preset includes `boolAttr('readonly')`:

```js
import { formHandlers } from 'lume-js/handlers';
// equivalent to: [boolAttr('readonly')]
```

## See also

- [ariaAttr](ariaAttr.md)
- [stringAttr](stringAttr.md)
- [htmlAttrs()](htmlAttrs.md)
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [className](className.md)** | **Next: [ariaAttr](ariaAttr.md) →**


========================================================================
FILE: docs/api/handlers/ariaAttr.md
========================================================================

# ariaAttr(name)

Creates a handler that sets an ARIA attribute to `"true"` or `"false"` based on a store value.

## Signature

```ts
function ariaAttr(name: string): { attr: string; apply(el: HTMLElement, val: any): void }
```

## Import

```js
import { ariaAttr } from 'lume-js/handlers';
```

## Parameters

- `name` — The ARIA attribute name, with or without the `aria-` prefix (e.g. `'pressed'` or `'aria-pressed'`).

## Returns

A handler object `{ attr: 'data-aria-<name>', apply }` for use in `bindDom`'s `handlers` option.

## Usage

```js
import { state, bindDom } from 'lume-js';
import { ariaAttr } from 'lume-js/handlers';

const store = state({ menuOpen: false, selected: true });

bindDom(document.body, store, {
  handlers: [ariaAttr('expanded'), ariaAttr('selected')]
});
```

```html
<button data-aria-expanded="menuOpen">Menu</button>
<li data-aria-selected="selected" role="option">Option A</li>
```

When `store.menuOpen` is `false`, `aria-expanded="false"` is set on the button. When truthy, `aria-expanded="true"`.

## Behavior

| Value | Effect |
|-------|--------|
| Truthy | `el.setAttribute('aria-<name>', 'true')` |
| Falsy | `el.setAttribute('aria-<name>', 'false')` |

The attribute is always present on the element — it's set to either `"true"` or `"false"`, never removed. This is correct behavior for boolean ARIA states.

## Built-in ARIA Attributes

`bindDom` has built-in handlers for the most common ARIA attributes:

| Attribute | Built-in |
|-----------|----------|
| `aria-expanded` | `data-aria-expanded` |
| `aria-hidden` | `data-aria-hidden` |

Use `ariaAttr` for ARIA state attributes not covered by the built-ins (`pressed`, `selected`, `disabled`, `checked`, `invalid`, etc.).

## ariaAttr vs stringAttr for ARIA

`ariaAttr` coerces values to `"true"`/`"false"` — use it for ARIA *boolean state* attributes.

For ARIA *string/token* attributes (e.g. `aria-live`, `aria-label`, `aria-sort`), use `stringAttr('aria-live')` instead, which passes the value through as a string.

```js
import { ariaAttr, stringAttr } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [
    ariaAttr('pressed'),          // aria-pressed="true"/"false"
    stringAttr('aria-live'),      // aria-live="polite" (string value)
    stringAttr('aria-label'),     // aria-label="Close dialog"
  ]
});
```

## Presets

The `a11yHandlers` preset includes common ARIA boolean state attributes:

```js
import { a11yHandlers } from 'lume-js/handlers';
// equivalent to: [ariaAttr('pressed'), ariaAttr('selected'), ariaAttr('disabled')]
```

## See also

- [boolAttr](boolAttr.md)
- [stringAttr](stringAttr.md)
- [htmlAttrs()](htmlAttrs.md)
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [boolAttr](boolAttr.md)** | **Next: [classToggle](classToggle.md) →**


========================================================================
FILE: docs/api/handlers/classToggle.md
========================================================================

# classToggle

Adds or removes a CSS class on an element based on a store value. When the value is truthy, the class is added. When falsy, it's removed. The visual behavior stays entirely in your CSS.

## Attribute

`data-class-{name}="key"`

## Import

```js
import { classToggle } from 'lume-js/handlers';
```

## Usage

`classToggle` is a factory. Call it with the class name you want to control, then pass the result to `bindDom`:

```js
import { state, bindDom } from 'lume-js';
import { classToggle } from 'lume-js/handlers';

const store = state({ active: false, hasError: false, isSelected: false });

bindDom(document.body, store, {
  handlers: [
    classToggle('active'),
    classToggle('error'),
    classToggle('selected')
  ]
});
```

```html
<li data-class-active="active">Menu item</li>
<input data-class-error="hasError" data-bind="email">
<div data-class-selected="isSelected">Card</div>
```

When `store.active` is truthy, the `active` class is added. When falsy, it's removed.

## Multiple classes at once

Pass multiple class names to one call:

```js
bindDom(root, store, {
  handlers: [classToggle('loading', 'disabled')]
});
```

This registers two handlers: `data-class-loading` and `data-class-disabled`.

## Class naming

The handler strips `data-class-` from the attribute name to get the CSS class. The attribute `data-class-is-open` toggles the class `is-open`:

```html
<div data-class-is-open="menuOpen">Menu</div>
```

```js
bindDom(root, store, { handlers: [classToggle('is-open')] });
```

## Compared to `data-hidden` / `data-show`

`classToggle` is more flexible — you define the visual behavior entirely in CSS. Use it when the show/hide logic is better expressed as a class:

```css
.sidebar { width: 0; overflow: hidden; transition: width 0.2s; }
.sidebar.open { width: 260px; }
```

```html
<aside class="sidebar" data-class-open="sidebarOpen">…</aside>
```

## See also

- [show](show.md)
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [ariaAttr](ariaAttr.md)** | **Next: [stringAttr](stringAttr.md) →**


========================================================================
FILE: docs/api/handlers/stringAttr.md
========================================================================

# stringAttr

Sets an HTML attribute to a reactive store value. Whenever the value changes, `el.setAttribute(name, value)` is called automatically. Use this when you need to drive `href`, `src`, `alt`, or any other attribute from state.

## Attribute

`data-{name}="key"` → sets `el.setAttribute(name, value)`

## Import

```js
import { stringAttr } from 'lume-js/handlers';
```

## Usage

`stringAttr` is a factory. Call it with the attribute name you want to drive, then pass the result to `bindDom`:

```js
import { state, bindDom } from 'lume-js';
import { stringAttr } from 'lume-js/handlers';

const store = state({
  profileUrl: '/user/ada',
  avatarSrc: '/avatars/ada.png',
  altText: 'Ada Lovelace'
});

bindDom(document.body, store, {
  handlers: [
    stringAttr('href'),
    stringAttr('src'),
    stringAttr('alt')
  ]
});
```

```html
<a data-href="profileUrl">Profile</a>
<img data-src="avatarSrc" data-alt="altText">
```

As `store.profileUrl` changes, `el.setAttribute('href', newValue)` is called automatically.

## Null / undefined handling

When the value is `null` or `undefined`, the attribute is **removed** (`el.removeAttribute(name)`):

```js
store.profileUrl = null; // <a> loses its href attribute entirely
```

## Common use cases

```js
bindDom(root, store, {
  handlers: [
    stringAttr('href'),    // <a data-href="url">
    stringAttr('src'),     // <img data-src="src">, <script data-src="...">
    stringAttr('alt'),     // <img data-alt="desc">
    stringAttr('title'),   // tooltip text
    stringAttr('type'),    // <button data-type="submit|button|reset">
    stringAttr('target'),  // <a data-target="_blank">
    stringAttr('value'),   // <option data-value="...">
  ]
});
```

## Compared to `data-bind`

`data-bind` sets DOM **properties** (like `el.href`, `el.textContent`). `stringAttr` sets HTML **attributes** (like `el.setAttribute('href', ...)`). For most `href` and `src` use cases they behave the same, but attributes are sometimes needed for custom elements or ARIA.

## See also

- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)
- [show](show.md), [classToggle](classToggle.md)

---

**← Previous: [classToggle](classToggle.md)** | **Next: [on](on.md) →**


========================================================================
FILE: docs/api/handlers/on.md
========================================================================

# on(...types)

Creates handlers for declarative event wiring: `data-on{type}="key"` attaches the function stored at that state key as a DOM event listener.

## Signature

```ts
function on(...types: string[]): Handler[]
```

Imported from `lume-js/handlers`. Returns an array — pass it directly to `handlers` (bindDom flattens one level).

## Example

```html
<input type="text" data-bind="newTitle" data-onkeydown="maybeSubmit">
<button data-onclick="addTodo">Add</button>
```

```js
import { state, bindDom } from 'lume-js';
import { on } from 'lume-js/handlers';

const store = state({
  newTitle: '',
  todos: [],
  addTodo() {
    if (!store.newTitle.trim()) return;
    store.todos = [...store.todos, { id: Date.now(), title: store.newTitle }];
    store.newTitle = '';
  },
  maybeSubmit(e) {
    if (e.key === 'Enter') store.addTodo();
  },
});

bindDom(document.body, store, { handlers: [on('click', 'keydown')] });
```

The behavior now lives in state and the wiring lives in HTML — no `getElementById` + `addEventListener` boilerplate, and the markup documents itself.

## Behavior

| Situation | Result |
|-----------|--------|
| Key holds a function | attached via `addEventListener(type, fn)`; receives the native event |
| Key assigned a *new* function | old listener removed, new one attached (no stacking) |
| Key assigned `null`/`undefined` | listener detached |
| Key assigned a truthy non-function | listener detached + console warning |

Nested paths work like any binding: `data-onclick="actions.save"` resolves `store.actions.save` (the nested object must be its own `state()` for reactive re-wiring, as usual).

## Security

Same trust model as `data-bind`: an injected `data-on*` attribute can only reference **functions that already exist in reachable state** — there is no expression language and no `eval`. Sanitize untrusted HTML before calling `bindDom`, as always.

## Cleanup

`bindDom`'s cleanup function stops future re-wiring but does not detach listeners already attached to elements still in the DOM. Discarding the bound subtree (normal SPA teardown) drops them with the elements.

## See also

- [Handlers API](../core/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [stringAttr](stringAttr.md)** | **Next: [htmlAttrs](htmlAttrs.md) →**


========================================================================
FILE: docs/api/handlers/htmlAttrs.md
========================================================================

# htmlAttrs()

One-import preset that enables reactive handlers for all standard HTML and ARIA attributes.

## Signature

```ts
function htmlAttrs(): Array<{ attr: string; apply(el: HTMLElement, val: any): void }>
```

## Import

```js
import { htmlAttrs } from 'lume-js/handlers';
```

## Returns

A flat array of handler objects — pass directly to `bindDom`'s `handlers` option.

## Usage

```js
import { state, bindDom } from 'lume-js';
import { htmlAttrs } from 'lume-js/handlers';

const store = state({
  profileUrl: '/user/alice',
  avatarSrc: '/img/alice.jpg',
  panelOpen: false,
  isPressed: false,
  liveRegion: 'polite',
});

bindDom(document.body, store, { handlers: htmlAttrs() });
```

```html
<a data-href="profileUrl">Profile</a>
<img data-src="avatarSrc" data-alt="username">
<details data-open="panelOpen">
  <summary>Details</summary>
</details>
<button data-aria-pressed="isPressed">Toggle</button>
<div role="status" data-aria-live="liveRegion">Updates here</div>
```

## What's Included

`htmlAttrs()` includes handlers for three categories:

**Boolean HTML attributes** — toggled present/absent via `toggleAttribute`: `readonly`, `open`, `novalidate`, `formnovalidate`, `multiple`, `autofocus`, `autoplay`, `controls`, `loop`, `muted`, `defer`, `async`, `reversed`, `selected`, `inert`, `allowfullscreen`

**String HTML attributes** — set as strings, removed when `null`/`undefined`: `href`, `src`, `alt`, `title`, `placeholder`, `action`, `method`, `target`, `rel`, `type`, `name`, `role`, `lang`, `tabindex`, `pattern`, `min`, `max`, `step`, `minlength`, `maxlength`, `width`, `height`, `for`, `form`, `accept`, `autocomplete`, `loading`, `decoding`, `inputmode`, `enterkeyhint`, `draggable`, `contenteditable`, `spellcheck`, `translate`, `dir`, `id`, `poster`, `preload`, `download`, `media`, `sizes`, `srcset`, `colspan`, `rowspan`, `scope`, `headers`, `wrap`, `sandbox`, and more.

**ARIA attributes** — both boolean states (`aria-pressed`, `aria-selected`, `aria-disabled`, …) and string/token attributes (`aria-live`, `aria-label`, `aria-sort`, …).

Also includes the `show` handler (`data-show`).

## When to use

`htmlAttrs()` is the simplest choice when you want broad coverage without importing individual handlers. It covers nearly every standard HTML and ARIA attribute reactively.

For precise control over bundle size, import only the handlers you actually use:

```js
import { boolAttr, stringAttr, ariaAttr } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [boolAttr('open'), stringAttr('href'), ariaAttr('expanded')]
});
```

## See also

- [boolAttr](boolAttr.md)
- [ariaAttr](ariaAttr.md)
- [stringAttr](stringAttr.md)
- [show](show.md)
- [Handlers guide](../../guides/handlers.md)
- [bindDom()](../core/bindDom.md)

---

**← Previous: [on](on.md)** | **Next: [Build a Todo app](../../tutorials/build-todo-app.md) →**


========================================================================
FILE: docs/tutorials/build-todo-app.md
========================================================================

# Tutorial: Build a Todo App

Build a fully functional todo app — add, toggle, delete, filter, and persist — using nothing but a single HTML file and a CDN import. No build step required.

**What you will learn:**
- Handling form inputs
- Rendering lists with `repeat` (for performance)
- Filtering data with `computed`
- Persisting data to `localStorage`

## Step 1: The Setup

Create an `index.html` file.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Lume Todo</title>
  <style>
    body { font-family: sans-serif; max-width: 500px; margin: 2rem auto; }
    .todo-list { list-style: none; padding: 0; }
    .todo-item { display: flex; gap: 10px; padding: 5px 0; border-bottom: 1px solid #eee; }
    .done { text-decoration: line-through; color: #888; }
  </style>
</head>
<body>
  <h1>Todo App</h1>
  
  <!-- Input Form -->
  <form id="todo-form">
    <input id="new-todo" placeholder="What needs to be done?" autocomplete="off">
    <button>Add</button>
  </form>

  <!-- List Container -->
  <ul id="todo-list" class="todo-list"></ul>

  <script type="module">
    import { state, bindDom } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
    import { repeat, computed } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/addons.min.mjs';

    // Code goes here...
  </script>
</body>
</html>
```

## Step 2: Define the State

We need a list of todos. Each todo will be an object with an `id`, `text`, and `done` status.

```javascript
const store = state({
  todos: [
    { id: 1, text: 'Learn Lume.js', done: false },
    { id: 2, text: 'Build something cool', done: false }
  ]
});
```

## Step 3: Render the List

We *could* use `innerHTML` like in the Tic-Tac-Toe tutorial. But for lists that change often, Lume provides a helper called `repeat`. It's much faster because it reuses DOM elements.

```javascript
const listContainer = document.getElementById('todo-list');

repeat(listContainer, store, 'todos', {
  // 1. Unique Key (Critical for performance!)
  key: todo => todo.id,

  // 2. Create Function (DOM structure - called once per element)
  create: (todo, el) => {
    el.className = 'todo-item';
    el.innerHTML = `
      <input type="checkbox" class="toggle">
      <span class="text"></span>
      <button class="delete">×</button>
    `;
  },

  // 3. Update Function (Data binding - called on every update)
  update: (todo, el) => {
    const checkbox = el.querySelector('.toggle');
    const span = el.querySelector('.text');
    
    checkbox.checked = todo.done;
    span.textContent = todo.text;
    span.classList.toggle('done', todo.done);
  }
});
```

Open `index.html`. You should see the two initial todos.

## Step 4: Adding Todos

Let's handle the form submission.

```javascript
const form = document.getElementById('todo-form');
const input = document.getElementById('new-todo');

form.addEventListener('submit', (e) => {
  e.preventDefault(); // Prevent page reload
  
  const text = input.value.trim();
  if (!text) return;

  // Create new todo object
  const newTodo = {
    id: Date.now(), // Simple ID generator
    text: text,
    done: false
  };

  // IMPORTANT: Immutable Update!
  // We create a NEW array with the new item at the end.
  store.todos = [...store.todos, newTodo];

  // Clear input
  input.value = '';
});
```

Try adding a few items. They should appear instantly!

## Step 5: Toggling and Deleting

Event listeners belong in `create` — it runs once per DOM element, so you won't accidentally attach duplicate listeners on every update.

Replace your `create` function with this complete version:

```javascript
create: (todo, el) => {
  el.className = 'todo-item';
  el.innerHTML = `
    <input type="checkbox" class="toggle">
    <span class="text"></span>
    <button class="delete">×</button>
  `;

  el.querySelector('.toggle').addEventListener('change', () => {
    store.todos = store.todos.map(t =>
      t.id === todo.id ? { ...t, done: !t.done } : t
    );
  });

  el.querySelector('.delete').addEventListener('click', () => {
    store.todos = store.todos.filter(t => t.id !== todo.id);
  });
}
```

Notice the pattern: `create` sets up structure and listeners, `update` (from the previous step) handles data. They don't overlap.

## Step 6: Computed Filtering

Let's add a feature to show only "Active" or "Completed" items.

First, add a `filter` key to the store. Update your `state()` call to include it:

```javascript
const store = state({
  todos: [
    { id: 1, text: 'Learn Lume.js', done: false },
    { id: 2, text: 'Build something cool', done: false }
  ],
  filter: 'all' // 'all', 'active', 'completed'
});
```

Then, create a `computed` value for the visible todos:

```javascript
const visibleTodos = computed(() => {
  if (store.filter === 'active') {
    return store.todos.filter(t => !t.done);
  }
  if (store.filter === 'completed') {
    return store.todos.filter(t => t.done);
  }
  return store.todos;
});
```

Finally, update `repeat` to read from `visibleTodos` instead of `store` directly. Computed objects work as stores — just use `'value'` as the key:

```javascript
repeat(listContainer, visibleTodos, 'value', {
  key: todo => todo.id,
  create: (todo, el) => { /* same as before */ },
  update: (todo, el) => { /* same as before */ }
});
```

And add some buttons to change the filter:

```html
<div>
  <button onclick="setFilter('all')">All</button>
  <button onclick="setFilter('active')">Active</button>
  <button onclick="setFilter('completed')">Completed</button>
</div>

<script>
  // ...
  window.setFilter = (f) => store.filter = f;
</script>
```

## Step 7: LocalStorage Persistence

We want our todos to survive a page refresh. We can use `effect()` to automatically save whenever `store.todos` changes.

```javascript
// 1. Load initial state
const saved = localStorage.getItem('lume-todos');
const initialTodos = saved ? JSON.parse(saved) : [];

const store = state({
  todos: initialTodos,
  filter: 'all'
});

// 2. Auto-save
effect(() => {
  localStorage.setItem('lume-todos', JSON.stringify(store.todos));
});
```

Now refresh the page. Your todos are still there!

## Final Code

<details>
<summary>Click to see the full working code</summary>

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Lume Todo</title>
  <style>
    body { font-family: sans-serif; max-width: 500px; margin: 2rem auto; }
    .todo-list { list-style: none; padding: 0; }
    .todo-item { display: flex; gap: 10px; padding: 5px 0; border-bottom: 1px solid #eee; }
    .done { text-decoration: line-through; color: #888; }
    .filters { margin-top: 1rem; }
  </style>
</head>
<body>
  <h1>Todo App</h1>
  
  <form id="todo-form">
    <input id="new-todo" placeholder="What needs to be done?" autocomplete="off">
    <button>Add</button>
  </form>

  <ul id="todo-list" class="todo-list"></ul>

  <div class="filters">
    <button onclick="setFilter('all')">All</button>
    <button onclick="setFilter('active')">Active</button>
    <button onclick="setFilter('completed')">Completed</button>
  </div>

  <script type="module">
    import { state, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
    import { repeat, computed } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/addons.min.mjs';

    // --- State ---
    const saved = localStorage.getItem('lume-todos');
    const store = state({
      todos: saved ? JSON.parse(saved) : [],
      filter: 'all'
    });

    // --- Persistence ---
    effect(() => {
      localStorage.setItem('lume-todos', JSON.stringify(store.todos));
    });

    // --- Computed ---
    const visibleTodos = computed(() => {
      if (store.filter === 'active') return store.todos.filter(t => !t.done);
      if (store.filter === 'completed') return store.todos.filter(t => t.done);
      return store.todos;
    });

    // --- Actions ---
    window.setFilter = (f) => store.filter = f;

    const form = document.getElementById('todo-form');
    const input = document.getElementById('new-todo');

    form.addEventListener('submit', (e) => {
      e.preventDefault();
      const text = input.value.trim();
      if (!text) return;

      store.todos = [...store.todos, { id: Date.now(), text, done: false }];
      input.value = '';
    });

    // --- Render ---
    const listContainer = document.getElementById('todo-list');

    repeat(listContainer, visibleTodos, 'value', {
      key: todo => todo.id,
      create: (todo, el) => {
        el.className = 'todo-item';
        el.innerHTML = `
          <input type="checkbox" class="toggle">
          <span class="text"></span>
          <button class="delete">×</button>
        `;
        
        // Bind Events (once)
        el.querySelector('.toggle').addEventListener('change', () => {
          store.todos = store.todos.map(t => t.id === todo.id ? { ...t, done: !t.done } : t);
        });
        
        el.querySelector('.delete').addEventListener('click', () => {
          store.todos = store.todos.filter(t => t.id !== todo.id);
        });
      },
      update: (todo, el) => {
        el.querySelector('.toggle').checked = todo.done;
        el.querySelector('.text').textContent = todo.text;
        el.querySelector('.text').classList.toggle('done', todo.done);
      }
    });
  </script>
</body>
</html>
```
</details>

---

**← Previous: [htmlAttrs](../api/handlers/htmlAttrs.md)** | **Next: [Build Tic-Tac-Toe](build-tic-tac-toe.md) →**


========================================================================
FILE: docs/tutorials/build-tic-tac-toe.md
========================================================================

# Tutorial: Tic-Tac-Toe

Build a complete Tic-Tac-Toe game with move history and time travel — entirely in a single HTML file, with no build step. This tutorial is a good introduction to `computed` values and keeping state as an immutable history.

**What you will learn:**
- Creating reactive state
- Rendering lists
- Handling clicks
- Computed values
- Implementing "Undo" (Time Travel)

## Step 1: The Setup

Create an `index.html` file. We'll put everything in here.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Lume Tic-Tac-Toe</title>
  <style>
    /* Basic CSS to make it look decent */
    body { font-family: sans-serif; margin: 20px; }
    .board-row { display: flex; }
    .square { 
      width: 60px; height: 60px; 
      background: #fff; border: 1px solid #999;
      font-size: 24px; font-weight: bold;
      margin: -1px -1px 0 0; padding: 0;
      cursor: pointer;
    }
    .square:focus { background: #ddd; }
    .game { display: flex; gap: 20px; }
  </style>
</head>
<body>
  <div id="root"></div>

  <script type="module">
    import { state, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
    import { computed } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/addons.min.mjs';

    const root = document.getElementById('root');

    // We will write our code here...
  </script>
</body>
</html>
```

## Step 2: Define the State

We need a place to store the game state. For a simple board, we need an array of 9 squares.

```javascript
// 1. Create the state
const store = state({
  squares: Array(9).fill(null), // [null, null, null, ...]
  xIsNext: true                 // 'X' starts first
});
```

## Step 3: Render the Board

Now let's display the board. We'll use `effect()` to render the HTML whenever the state changes.

```javascript
// 2. Render the board
effect(() => {
  const status = `Next player: ${store.xIsNext ? 'X' : 'O'}`;

  root.innerHTML = `
    <div class="status">${status}</div>
    <div class="board">
      ${[0, 1, 2].map(row => `
        <div class="board-row">
          ${[0, 1, 2].map(col => {
            const i = row * 3 + col;
            return `<button class="square" data-index="${i}">${store.squares[i] || ''}</button>`;
          }).join('')}
        </div>
      `).join('')}
    </div>
  `;
});
```

Open `index.html` in your browser. You should see the empty grid.

## Step 4: Handle Clicks

We need to update the state when a user clicks a square. We'll use **Event Delegation** (attaching one listener to the root) for better performance.

```javascript
// 3. Handle clicks
root.addEventListener('click', (e) => {
  // Only care if a .square was clicked
  if (!e.target.matches('.square')) return;
  
  const i = parseInt(e.target.dataset.index);
  
  // If square is already filled, ignore
  if (store.squares[i]) return;

  // IMPORTANT: Create a COPY of the array (Immutability)
  const nextSquares = [...store.squares];
  
  // Update the copy
  nextSquares[i] = store.xIsNext ? 'X' : 'O';
  
  // Save back to state
  store.squares = nextSquares;
  store.xIsNext = !store.xIsNext;
});
```

Try clicking the squares now. They should fill with X and O!

## Step 5: Determine a Winner

We need a helper function to check for a winner.

```javascript
function calculateWinner(squares) {
  const lines = [
    [0, 1, 2], [3, 4, 5], [6, 7, 8], // Rows
    [0, 3, 6], [1, 4, 7], [2, 5, 8], // Cols
    [0, 4, 8], [2, 4, 6]             // Diagonals
  ];
  for (let line of lines) {
    const [a, b, c] = line;
    if (squares[a] && squares[a] === squares[b] && squares[a] === squares[c]) {
      return squares[a];
    }
  }
  return null;
}
```

Now, let's use `computed()` to automatically track the winner.

```javascript
// 4. Computed values
const winner = computed(() => calculateWinner(store.squares));

// Update our effect to show the winner
effect(() => {
  let statusText;
  if (winner.value) {
    statusText = `Winner: ${winner.value}`;
  } else {
    statusText = `Next player: ${store.xIsNext ? 'X' : 'O'}`;
  }

  // ... rest of render code ...
});
```

And update the click handler to stop the game if someone won:

```javascript
root.addEventListener('click', (e) => {
  // ...
  // Check if winner exists
  if (store.squares[i] || winner.value) return;
  // ...
});
```

## Step 6: Adding Time Travel (History)

To support "Undo", we need to store the entire history of the game, not just the current squares.

Let's change our state structure:

```javascript
const store = state({
  history: [
    { squares: Array(9).fill(null) }
  ],
  stepNumber: 0,
  xIsNext: true
});
```

## Step 7: Updating Computed Values

Now that the board state lives inside `history`, we derive the current squares from the active step number:

```javascript
const currentSquares = computed(() => store.history[store.stepNumber].squares);
const winner = computed(() => calculateWinner(currentSquares.value));
```

## Step 8: Updating the Click Handler for History

When clicking, we now add to history instead of just replacing `squares`.

```javascript
root.addEventListener('click', (e) => {
  if (!e.target.matches('.square')) return;
  const i = parseInt(e.target.dataset.index);

  // If we went back in time, discard "future" history
  const history = store.history.slice(0, store.stepNumber + 1);
  const current = history[history.length - 1];
  const squares = current.squares;

  if (calculateWinner(squares) || squares[i]) return;

  const nextSquares = [...squares];
  nextSquares[i] = store.xIsNext ? 'X' : 'O';

  store.history = [...history, { squares: nextSquares }];
  store.stepNumber = history.length;
  store.xIsNext = !store.xIsNext;
});
```

## Step 9: Rendering the History List

Finally, let's render the list of past moves.

```javascript
// Jump to any past move
window.jumpTo = (step) => {
  store.stepNumber = step;
  store.xIsNext = (step % 2) === 0;
};

effect(() => {
  const squares = currentSquares.value;

  // Build the history button list
  const moves = store.history.map((step, move) => {
    const desc = move ? `Go to move #${move}` : 'Go to game start';
    const isCurrent = move === store.stepNumber;
    return `
      <li>
        <button onclick="jumpTo(${move})" style="${isCurrent ? 'font-weight: bold' : ''}">
          ${desc}
        </button>
      </li>
    `;
  }).join('');

  // Render board + history together
  root.innerHTML = `
    <div class="game">
      <div class="game-board">
        <div class="status">${winner.value ? 'Winner: ' + winner.value : 'Next player: ' + (store.xIsNext ? 'X' : 'O')}</div>
        <div class="board">
          ${[0, 1, 2].map(row => `
            <div class="board-row">
              ${[0, 1, 2].map(col => {
                const i = row * 3 + col;
                return \`<button class="square" data-index="\${i}">\${squares[i] || ''}</button>\`;
              }).join('')}
            </div>
          `).join('')}
        </div>
      </div>
      <div class="game-info">
        <ol>${moves}</ol>
      </div>
    </div>
  `;
});
```

## Final Code

<details>
<summary>Click to see the full working code</summary>

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Lume Tic-Tac-Toe</title>
  <style>
    body { font-family: sans-serif; margin: 20px; }
    .game { display: flex; gap: 20px; }
    .board-row { display: flex; }
    .square { 
      width: 60px; height: 60px; 
      background: #fff; border: 1px solid #999;
      font-size: 24px; font-weight: bold;
      margin: -1px -1px 0 0; padding: 0;
      cursor: pointer;
    }
    .square:focus { background: #ddd; }
  </style>
</head>
<body>
  <div id="root"></div>

  <script type="module">
    import { state, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
    import { computed } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/addons.min.mjs';

    // --- Logic ---
    function calculateWinner(squares) {
      const lines = [
        [0, 1, 2], [3, 4, 5], [6, 7, 8],
        [0, 3, 6], [1, 4, 7], [2, 5, 8],
        [0, 4, 8], [2, 4, 6]
      ];
      for (let line of lines) {
        const [a, b, c] = line;
        if (squares[a] && squares[a] === squares[b] && squares[a] === squares[c]) {
          return squares[a];
        }
      }
      return null;
    }

    // --- State ---
    const store = state({
      history: [{ squares: Array(9).fill(null) }],
      stepNumber: 0,
      xIsNext: true
    });

    // --- Computed ---
    const currentSquares = computed(() => store.history[store.stepNumber].squares);
    const winner = computed(() => calculateWinner(currentSquares.value));
    const status = computed(() => {
      if (winner.value) return `Winner: ${winner.value}`;
      return `Next player: ${store.xIsNext ? 'X' : 'O'}`;
    });

    // --- Actions ---
    window.jumpTo = (step) => {
      store.stepNumber = step;
      store.xIsNext = (step % 2) === 0;
    };

    const root = document.getElementById('root');

    root.addEventListener('click', (e) => {
      if (!e.target.matches('.square')) return;
      
      const i = parseInt(e.target.dataset.index);
      const history = store.history.slice(0, store.stepNumber + 1);
      const current = history[history.length - 1];
      const squares = current.squares;

      if (calculateWinner(squares) || squares[i]) return;

      const nextSquares = [...squares];
      nextSquares[i] = store.xIsNext ? 'X' : 'O';

      store.history = [...history, { squares: nextSquares }];
      store.stepNumber = history.length;
      store.xIsNext = !store.xIsNext;
    });

    // --- Render ---
    effect(() => {
      const squares = currentSquares.value;
      
      const moves = store.history.map((step, move) => {
        const desc = move ? `Go to move #${move}` : 'Go to game start';
        const isCurrent = move === store.stepNumber;
        return `
          <li>
            <button onclick="jumpTo(${move})" style="${isCurrent ? 'font-weight: bold' : ''}">
              ${desc}
            </button>
          </li>
        `;
      }).join('');

      root.innerHTML = `
        <div class="game">
          <div class="game-board">
            <div class="status">${status.value}</div>
            <div class="board">
              ${[0, 1, 2].map(row => `
                <div class="board-row">
                  ${[0, 1, 2].map(col => {
                    const i = row * 3 + col;
                    return \`<button class="square" data-index="\${i}">\${squares[i] || ''}</button>\`;
                  }).join('')}
                </div>
              `).join('')}
            </div>
          </div>
          <div class="game-info">
            <ol>\${moves}</ol>
          </div>
        </div>
      `;
    });
  </script>
</body>
</html>
```
</details>

---

**← Previous: [Build a Todo app](build-todo-app.md)** | **Next: [Working with Arrays](working-with-arrays.md) →**


========================================================================
FILE: docs/tutorials/working-with-arrays.md
========================================================================

# Working with Arrays in Lume.js

If you are coming from Vue 2 or older frameworks, you might be used to modifying arrays directly:
```javascript
// ❌ THIS WILL NOT WORK IN LUME
store.items.push(newItem);
```

In Lume.js, **you must update arrays immutably**. This guide explains why and how.

## The Golden Rule

> **Always create a new array when you want to trigger an update.**

```javascript
// ✅ CORRECT
store.items = [...store.items, newItem];
```

## Why?

Lume.js uses **Reference Equality** (`===`) to detect changes.

1.  **Performance**: Checking `oldArray === newArray` is instant. Checking every item inside an array is slow.
2.  **Predictability**: You explicitly tell Lume "I have changed this data" by assigning a new value.
3.  **Simplicity**: Lume doesn't need to monkey-patch `Array.prototype.push` or wrap arrays in heavy Proxies.

## Common Patterns

Here is a cheat sheet for common array operations.

### Adding Items

**Don't use:** `push()`, `unshift()`

**Use:** Spread syntax `[...]`

```javascript
// Add to end (push)
store.items = [...store.items, newItem];

// Add to start (unshift)
store.items = [newItem, ...store.items];
```

### Removing Items

**Don't use:** `splice()`, `pop()`, `shift()`

**Use:** `filter()`

```javascript
// Remove by ID
store.items = store.items.filter(item => item.id !== targetId);

// Remove by Index
store.items = store.items.filter((_, index) => index !== targetIndex);

// Remove last item
store.items = store.items.slice(0, -1);
```

### Updating Items

**Don't use:** `store.items[i] = newValue`

**Use:** `map()`

```javascript
// Update item with specific ID
store.items = store.items.map(item => 
  item.id === targetId 
    ? { ...item, status: 'done' } // Create new object for the updated item
    : item                        // Keep other items as-is
);
```

### Sorting and Reordering

**Don't use:** `sort()`, `reverse()` (these mutate in place!)

**Use:** Copy then sort

```javascript
// Sort by name
store.items = [...store.items].sort((a, b) => a.name.localeCompare(b.name));

// Reverse
store.items = [...store.items].reverse();
```

## Integration with `repeat`

When using the `repeat` addon, immutable updates are essential. `repeat` compares the new array to the old one to decide what DOM elements to add, remove, or update.

```javascript
// Pattern 1: Simple (render only)
repeat(list, store, 'items', {
  key: item => item.id,
  render: (item, el) => {
    el.textContent = item.name;  // Called on every update
  }
});

// Pattern 2: Clean separation (recommended)
repeat(list, store, 'items', {
  key: item => item.id,
  create: (item, el) => { /* DOM structure once */ },
  update: (item, el) => { /* Data binding on updates */ }
});
```

If you mutate the array in place (`push`), `repeat` won't know anything happened because the array reference hasn't changed.

## Common Mistakes

### Mistake 1: Mutating inside `map`
```javascript
// ❌ WRONG: Mutating the object inside map
store.items = store.items.map(item => {
  if (item.id === 1) {
    item.done = true; // Mutates existing object!
    return item;
  }
  return item;
});

// ✅ CORRECT: Return a new object
store.items = store.items.map(item => {
  if (item.id === 1) {
    return { ...item, done: true }; // New object
  }
  return item;
});
```

### Mistake 2: Using `sort()` directly
```javascript
// ❌ WRONG: sort() mutates in place
store.items.sort(); // Returns the SAME array, no update triggered

// ✅ CORRECT: Copy then sort
store.items = [...store.items].sort(); // New array
```

## Summary

- **Read** arrays however you want.
- **Write** arrays by creating new ones.
- Use `map`, `filter`, and `[...spread]` instead of `push`, `splice`, and loops.

## Using Helper Libraries (e.g., Immer)

If you prefer writing mutable-style code, you can use libraries like [Immer](https://immerjs.github.io/immer/).

Immer takes your current state, lets you "mutate" a draft, and then produces a **new immutable state**. This works perfectly with Lume because Lume sees the new reference and triggers the update.

```javascript
import { produce } from 'immer';

// ✅ WORKS: Immer returns a new array reference
store.items = produce(store.items, draft => {
  draft.push(newItem);
  draft[0].done = true;
});
```

Any library that follows the **Immutable Update Pattern** (Redux toolkit, etc.) is compatible with Lume.js.

---

> **Deep Dive:** Why does Lume require immutable updates? Read the [Design Decision](../design/design-decisions.md#why-no-loop-rendering-in-core-v-for-x-for).

---

**← Previous: [Build Tic-Tac-Toe](build-tic-tac-toe.md)** | **Next: [Migrating from 1.x](../guides/migration.md) →**


========================================================================
FILE: docs/design/design-decisions.md
========================================================================

# Design Decisions

This document explains **why** Lume.js is designed the way it is. If you have suggestions for improvements, please open an issue with your reasoning!

---

## Core Philosophy

### Why "Standards-Only"?

**Decision:** Use only `data-*` attributes and standard JavaScript APIs.

**Reasoning:**
- HTML validators accept `data-*` attributes (HTML5 standard)
- Screen readers and accessibility tools work without special configuration
- No learning curve for HTML structure
- Works in environments where custom directives would break (WordPress, Shopify, email templates)
- Future-proof - won't break when framework trends change

**Alternatives considered:**
- ❌ Custom directives like `x-bind`, `v-model` → Breaks validation, harder accessibility
- ❌ JSX/Template literals → Requires build step, breaks progressive enhancement

---

## API Design

### Why Only Objects in State (Not Primitives)?

**Decision:** `state()` only accepts objects, not primitives.

```javascript
// ✅ Correct
const store = state({ count: 0 });

// ❌ Won't work
const count = state(0);  // Error: Must pass an object
```

**Reasoning:**
1. **Proxy limitation:** JavaScript Proxies can only wrap objects, not primitives
2. **Consistency:** All state uses the same API (dot notation)
3. **Namespace benefits:** `store.count` is clearer than generic `value`
4. **Multiple properties:** Objects naturally group related state
5. **Extensibility:** Easy to add more properties later

**Why this doesn't limit applications:**

```javascript
// ✅ Single value? Just use one property
const timer = state({ seconds: 0 });

// ✅ Boolean flag? Same pattern
const ui = state({ isOpen: false });

// ✅ Multiple related values? Natural grouping
const auth = state({ 
  user: null, 
  token: '', 
  isLoggedIn: false 
});

// ✅ Need multiple stores? Create multiple objects
const counter = state({ count: 0 });
const todos = state({ items: [], filter: 'all' });
```

**Alternatives considered:**
- ❌ Support both primitives and objects → Inconsistent API, confusing edge cases
- ❌ Use getter/setter functions → Verbose, doesn't match natural property access

**Tradeoff:** Slight verbosity (wrapping in object) for consistency and clarity.

---

### Why Nested State Must Be Explicitly Wrapped?

**Decision:** Require explicit `state()` wrapping for nested objects.

```javascript
// ✅ Required
const store = state({
  user: state({ name: 'Alice' })  // Must wrap
});

// ❌ Won't work reactively
const store = state({
  user: { name: 'Alice' }  // Plain object, not reactive
});
```

**Reasoning:**
- **Explicit opt-in:** Clear which objects are reactive vs plain data
- **Performance:** Don't auto-wrap everything (could be expensive for large objects)
- **Predictability:** No magic - you control what's reactive
- **Clear ownership:** Each `state()` manages its own listeners and batching
- **Easier debugging:** Stack traces show exactly where reactivity was added

**Alternatives considered:**
- ❌ Auto-wrap nested objects → Hidden performance cost, unclear ownership
- ❌ Deep reactivity by default → Vue 3 moved away from this for performance reasons

**Tradeoff:** Slight verbosity for better explicitness and performance.

---

### Why Microtask Batching Instead of Synchronous Updates?

**Decision:** Batch updates in microtasks (per-state).

```javascript
store.count = 1;
store.count = 2;
store.count = 3;
// DOM updates ONCE with value 3 (after microtask)
```

**Reasoning:**
- **Performance:** Prevents excessive DOM updates (3 writes → 1 render)
- **Consistency:** All effects see the final state, not intermediate values
- **Standard behavior:** Matches Promise timing, feels natural to JS developers
- **Deduplication:** Multiple property changes trigger effects once

**Alternatives considered:**
- ❌ Synchronous updates → Too many DOM writes, poor performance
- ❌ RequestAnimationFrame → Delays updates unnecessarily, feels sluggish
- ❌ Global scheduler → Complex, harder to reason about cross-state timing

**Tradeoff:** Slight delay (1 microtask) for much better performance.

---

### Why Per-State Batching Instead of Global Scheduler?

**Decision:** Each `state()` object maintains its own microtask flush.

**Reasoning:**
- **Simplicity:** No global state to manage or debug
- **Isolation:** One state's batching doesn't affect another
- **Easier testing:** Can test each state independently
- **Predictable:** Clear execution order within each state
- **Minimal:** Aligns with "no framework tax" philosophy

**Alternatives considered:**
- ❌ Global scheduler (like Vue/React) → More complex, harder to test, tighter coupling

**Tradeoff:** Effects depending on multiple states may run multiple times (acceptable as the *default*; see `batch()` below for the explicit, opt-in way to group writes across stores).

---

### Why `batch()` Is Part of the Kernel (v2.3)

**Decision:** Ship a synchronous, opt-in `batch(fn)` in core (`lume-js` and `lume-js/state`), implemented in `core/batch.js` behind a single seam in `state.js`.

```javascript
import { state, effect, batch } from 'lume-js';

batch(() => {
  cart.items = [...cart.items, item];
  totals.sum += item.price;
});
// effects reading both stores ran exactly ONCE, synchronously
```

**Reasoning:**
- **The per-state tradeoff stayed, but gained an escape hatch.** Per-state microtask batching remains the default and is unchanged. `batch()` is lexical and opt-in — nothing changes unless you call it.
- **Scheduling is core semantics, not an extension.** Plugins extend what happens *around* reads/writes; handlers extend what attributes *mean*; `withReadObserver` extends how reads are *observed*. Batching changes *when the engine runs* — it lives inside the write path, which is why it cannot be a plugin (a plugin cannot un-queue a scheduled microtask, flush synchronously, or dedupe private effect queues). Every peer library (Solid, Svelte, Vue, MobX, Preact Signals) reached the same conclusion: `batch` is core, never a plugin.
- **The universal audience wants it most.** Tests, servers, and CLI code benefit from the synchronous flush (`batch(() => {...}); assert(...)`) even more than browsers do.
- **Measured cost:** +0.37 KB gz on the kernel (1.08 → 1.45 KB).

**Alternatives considered:**
- ❌ Global pluggable scheduler (`setScheduler`) → last-writer-wins global, import-order coupling, conflicts with `sideEffects: false`; explored and rejected on `feature/pluggable-scheduler`
- ❌ Batch as a `withPlugins` plugin → plugins sit outside the write scheduler; cannot deliver synchronous flush or cross-store dedupe
- ❌ Per-store opt-in (`state(obj, { scheduler })`) → viral: every `state()` call site must participate or batching silently has holes
- ❌ `globalThis` symbol channel → implicit global coupling; violates "explicit over magic"

**Keeping batch optional later (decided, not built):** `state.js` touches batching through exactly one seam — `enqueueIfBatching(handle)` — and `batch.js` never imports `state.js`. If a batch-free kernel is ever wanted, either a `state-lite` artifact (hook compiled out at build time) or a per-store scheduler option can be added **without breaking changes**. We deliberately did not build this now.

**Tradeoff:** Every `lume-js/state` consumer carries ~0.37 KB of batch even if unused, in exchange for zero configuration and one consistent mental model.

---

---

### Why `$subscribe()` Calls Immediately?

**Decision:** `$subscribe(key, fn)` calls `fn` with the current value immediately.

```javascript
store.count = 5;
store.$subscribe('count', val => {
  console.log(val); // Logs 5 immediately (synchronous)
});
```

**Reasoning:**
- **Consistency:** Ensures subscriber always has the current value
- **Initialization:** Sets up DOM/UI state on first call
- **Standard pattern:** Matches RxJS `.subscribe()`, Svelte stores
- **Prevents bugs:** No "forgot to initialize" issues

**Alternatives considered:**
- ❌ Only notify on changes → Forces manual initialization, easy to forget
- ❌ Batched initial call → Delay feels broken for setup code

**Tradeoff:** Subscribers must handle being called immediately (usually what you want anyway).

---

### Why Auto-Ready `bindDom()` by Default?

**Decision:** `bindDom()` automatically waits for DOMContentLoaded if needed.

```javascript
// Works anywhere - no timing issues!
bindDom(document.body, store);
```

**Reasoning:**
- **Zero friction:** "Just works" without thinking about timing
- **Fewer bugs:** Eliminates entire class of "DOM not ready" errors
- **Better DX:** New users don't hit timing issues immediately
- **Standards-based:** Uses native `DOMContentLoaded` event
- **Opt-out available:** `{ immediate: true }` for edge cases

**Alternatives considered:**
- ❌ Require manual `DOMContentLoaded` → Worse DX, common pitfall
- ❌ Add `onMount()` helper → Extra API surface, feels like framework lifecycle hooks

**Tradeoff:** Tiny overhead checking `document.readyState` (negligible).

---

### Why No Built-in Event Handling (`@click` style)?

**Decision:** Use standard `addEventListener()`, not custom event attributes.

```javascript
// ✅ Lume.js approach
document.getElementById('btn').addEventListener('click', () => {
  store.count++;
});
```

```html
<!-- ❌ NOT supported (Alpine/Vue style) -->
<button @click="count++">Increment</button>
```

**Reasoning:**
- **Standards-only:** `addEventListener()` is the standard way
- **No custom syntax:** Keeps HTML validator-friendly
- **Flexibility:** Use event delegation, capture phase, passive listeners, etc.
- **Familiarity:** Everyone knows `addEventListener()`
- **Separation of concerns:** HTML stays declarative, JS handles logic

**Alternatives considered:**
- ❌ Custom `@click` or `on:click` → Breaks standards-only philosophy
- ❌ Inline handlers `onclick="..."` → Poor separation, XSS risks

**Tradeoff:** Slightly more verbose, but keeps everything standards-compliant.

#### Amendment (v2.3): the opt-in `on()` handler

**Decision:** The rejection above targets *custom syntax* (`@click`, `on:click`) and *inline code* (`onclick="count++"`). The opt-in `on()` handler is neither, and is now allowed:

```html
<button data-onclick="addTodo">Add</button>
```

```javascript
import { on } from 'lume-js/handlers';
const store = state({ addTodo() { ... } });
bindDom(root, store, { handlers: [on('click')] });
```

**Why this passes the original reasoning:**
- **Standards-only:** `data-on*` is a valid `data-*` attribute — no custom syntax.
- **No code in HTML:** the attribute references a *state key holding a function*, exactly as `data-bind` references a state key holding data. No expressions, no eval — an injected attribute can only point at functions already in reachable state (same trust model as `data-bind`).
- **Separation of concerns preserved:** logic lives in JS (the function in state); HTML only declares the wiring — the same relationship `data-bind` established for data.
- **Opt-in handler:** zero bytes and zero behavior unless imported and passed to `bindDom` — consistent with the handler-system decision.

`addEventListener()` remains the documented default; `on()` is the declarative option for state-driven apps (and makes handlers runtime-swappable by assignment).

---

### Why No Conditional Rendering (`v-if`, `x-if`)?

**Decision:** Use standard JavaScript for conditionals, not template directives.

```javascript
// ✅ Lume.js approach
store.$subscribe('isLoggedIn', (value) => {
  document.querySelector('.user-menu').style.display = 
    value ? 'block' : 'none';
});
```

```html
<!-- ❌ NOT supported (Vue/Alpine style) -->
<div v-if="isLoggedIn">Welcome back!</div>
```

**Reasoning:**
- **Standards-only:** No custom template syntax needed
- **Full control:** Use any DOM manipulation method you prefer
- **Simple mental model:** "Just JavaScript" - no special rules
- **Integration:** Works with any DOM library (jQuery, GSAP, etc.)

**Alternatives (user can choose):**
```javascript
// Option 1: Display toggle
el.style.display = condition ? 'block' : 'none';

// Option 2: Add/remove from DOM
if (condition) {
  parent.appendChild(el);
} else {
  el.remove();
}

// Option 3: Use classes
el.classList.toggle('hidden', !condition);
```

**Tradeoff:** More manual, but gives complete flexibility and stays standards-compliant.

---

### Why No Loop Rendering in Core (`v-for`, `x-for`)?

**Decision:** Core uses standard JavaScript for loops; `repeat()` helper planned as optional addon.

```javascript
// ✅ Core approach - pure JavaScript
store.$subscribe('items', (items) => {
  const container = document.querySelector('.list');
  container.innerHTML = items.map(item => `
    <li>${item.name}</li>
  `).join('');
});
```

```javascript
// ✅ Future addon approach
import { repeat } from 'lume-js/addons';

repeat(container, store, 'items', {
  key: item => item.id,
  create: (item, el) => { el.textContent = item.name; },
  update: (item, el) => { el.textContent = item.name; }
});
```

```html
<!-- ❌ NOT supported - custom template syntax -->
<li v-for="item in items">{{ item.name }}</li>
```

**Reasoning:**
- **Core minimalism:** Most users can write their own loops easily
- **Standards-only in core:** No custom syntax required
- **Flexibility:** Users choose their strategy (innerHTML vs createElement)
- **Addon for convenience:** `repeat()` helper for common use case
- **No lock-in:** If repeat() doesn't fit, just use JavaScript

**Alternatives (user can choose):**
```javascript
// Option 1: Template literals (simple)
container.innerHTML = items.map(i => `<li>${i.name}</li>`).join('');

// Option 2: createElement (more control)
items.forEach(item => {
  const li = document.createElement('li');
  li.textContent = item.name;
  container.appendChild(li);
});

// Option 3: Template element (reusable)
const template = document.querySelector('#item-template');
items.forEach(item => {
  const clone = template.content.cloneNode(true);
  clone.querySelector('.name').textContent = item.name;
  container.appendChild(clone);
});
```

**Current Status (v2.3):** The `repeat` addon is stable, with keyed reconciliation, `create`/`update` separation, focus/scroll preservation — and a declarative **template mode** (below).

```javascript
import { repeat } from 'lume-js/addons';

// ⚠️ IMPORTANT: Arrays must be updated immutably!
// store.items.push(newItem);       // ❌ Won't trigger update
// store.items = [...store.items, newItem]; // ✅ Triggers update

repeat(container, store, 'items', {
  key: item => item.id,
  create: (item, el) => {
    el.innerHTML = '<span class="name"></span>';
  },
  update: (item, el) => {
    el.querySelector('.name').textContent = item.name;
  }
});
```

**Why Immutable Updates?**
- **Performance:** Checking reference equality (`oldArray === newArray`) is instant.
- **Simplicity:** No need to monkey-patch `Array.prototype.push` or use expensive Proxies on arrays.
- **Predictability:** Explicit updates mean explicit renders.

**Tradeoff:** Users must learn to use spread syntax (`[...items, new]`) instead of `push()`.

### Why `repeat()` Gained a Template Mode (v2.3)

**Decision:** `repeat()` accepts `template: true | selector | HTMLTemplateElement`; the template's single root is cloned per item and its `data-bind` paths bind against **each item** (`"name"`, `"user.city"`, `"$item"`, `"$index"`).

```html
<ul id="list">
  <template>
    <li><strong data-bind="name"></strong></li>
  </template>
</ul>
```

```javascript
repeat('#list', store, 'people', { key: p => p.id, template: true });
```

**Reasoning:**
- **It automates this document's own recommendation.** "Option 3: Template element" above was already the documented user-land pattern — template mode is that exact pattern with the cloning, caching, and re-binding handled.
- **Standards-only:** `<template>` is the platform's templating primitive; `data-bind` is the attribute users already know. No expressions, no custom syntax — paths only.
- **Attacks the verbosity problem** (VISION.md's hardest open problem): list rows no longer require imperative `createElement`/`innerHTML` code.
- **Value semantics shared with core:** template bindings call `bindDom`'s own `applyBindValue`, so item bindings and store bindings can never drift.

**Boundaries (deliberate):**
- One-way snapshot bindings — items are plain objects, not stores. Two-way per-row binding would require per-item stores, conflicting with "explicit nested states".
- `render` is ignored (with a warning) in template mode; `create`/`update` compose on top.
- Exactly one root element per template, enforced with a clear error.

**Tradeoff:** `data-bind` inside a repeat template resolves against the item rather than the store — context-dependent meaning for one attribute, consistent with `data-bind`'s existing context-awareness (input vs span).


### Why `create` + `update` Instead of Just `render`?

**Problem:** A single `render` function forces users to guard one-time setup:

```javascript
render: (item, el) => {
  if (!el.dataset.bound) {
    el.innerHTML = '...';  // DOM setup
    el.addEventListener('click', ...);  // Event listeners
    el.dataset.bound = 'true';
  }
  el.textContent = item.name;  // Data binding
}
```

**Decision:** Explicit separation with `create` and `update` callbacks.

```javascript
create: (item, el) => {
  el.innerHTML = '...';  // Once
  el.addEventListener('click', ...);  // Once
},
update: (item, el) => {
  el.textContent = item.name;  // Every render
}
```

**Benefits:**
- Cleaner code without guards
- Event listeners attached exactly once
- Clear intent: structure vs data

### Why Check Both Reference AND Index for Update Skip?

**Problem:** If only checking item reference, reordered items don't update:

```javascript
// Items: [Alice, Bob] → [Bob, Alice]
// Same references, different indices
// Index-dependent rendering (e.g., "Item #1") would be wrong
```

**Decision:** Skip `update` only when both reference AND index unchanged.

```javascript
if (prevItem !== item || prevIndex !== i) {
  update(item, el, i, { isFirstRender });
}
```

**Tradeoff:** Slightly more overhead, but correct behavior for index-dependent renders.

## Binding Patterns

### Why Nested State for Multiple Checkboxes Instead of Arrays?

**Decision:** Recommend nested state objects over array bindings for multiple checkboxes.

```javascript
// ✅ Recommended
const store = state({
  tags: state({
    javascript: true,
    python: false
  })
});
```

```html
<input type="checkbox" data-bind="tags.javascript">
<input type="checkbox" data-bind="tags.python">
```

**Why not array bindings?**

Array bindings like `store.tags = ['javascript', 'python']` would require:

1. **DOM scanning complexity:**
   - Scan all checkboxes to find which share the same binding path
   - Group them by `data-bind` attribute
   - Track which are checked/unchecked

2. **Ambiguous two-way sync:**
   - When unchecked: remove from array or set to empty?
   - When checked: append to array or set index?
   - What if user reorders checkboxes?

3. **Dynamic checkbox problems:**
   - Adding/removing checkboxes requires re-scanning DOM
   - Which checkbox "owns" which array index?
   - How to handle cleanup when checkbox is removed?

4. **Performance:**
   - Every checkbox update would trigger array mutation
   - Array mutations are harder to optimize than object property sets

**Nested state benefits:**
- ✅ Each checkbox has a clear, independent state path
- ✅ Easy to validate individual checkboxes
- ✅ Works naturally with Lume's property-based reactivity
- ✅ Simpler cleanup (each binding is independent)
- ✅ Better TypeScript support

**Alternatives considered:**
- ❌ Array bindings → Too complex for minimal library, edge cases proliferate
- ❌ Custom `data-array` attribute → Custom syntax breaks standards-only philosophy

**Tradeoff:** Slightly more verbose state structure for much simpler implementation and better explicitness.

**Future consideration:** Could add array binding support in v2.0+ if there's strong demand and a clean solution emerges.

---

### Why No Two-Way Binding for `contenteditable`?

**Decision:** Only support `data-bind` on standard form inputs, not `contenteditable`.

**Reasoning:**
- **Complexity:** `contenteditable` has inconsistent browser behavior
- **Cursor position:** Updating innerHTML loses cursor position
- **Security:** XSS risks if binding user input directly to innerHTML
- **Standards focus:** `contenteditable` isn't a standard form input
- **Workaround exists:** Use manual subscriptions for control

**Alternatives considered:**
- ❌ Add `contenteditable` support → Security risks, cursor issues, scope creep

**Workaround:**
```javascript
store.$subscribe('text', (value) => {
  const el = document.querySelector('[contenteditable]');
  if (el.textContent !== value) {
    el.textContent = value; // Note: Loses cursor position
  }
});
```

**Future consideration:** Could add with proper cursor position handling if there's demand.

---

### Why `data-bind` Only (Not `data-model` or `data-text`)?

**Decision:** Single attribute `data-bind` for both one-way and two-way binding.

```html
<!-- One attribute for everything -->
<span data-bind="count"></span>
<input data-bind="name">
```

**Reasoning:**
- **Simplicity:** One concept to learn
- **Context-aware:** Behavior changes based on element type (span vs input)
- **Less typing:** Shorter HTML
- **Consistent:** Same pattern everywhere

**Alternatives considered:**
- ❌ Separate `data-model`, `data-text`, `data-value` → More API surface
- ❌ Directionality flags `data-bind.one-way` → Custom syntax

**Tradeoff:** Slightly less explicit, but much simpler API.

---

## Performance Decisions

### Why No Virtual DOM?

**Decision:** Direct DOM updates using `element.value = x` and `element.textContent = x`.

**Reasoning:**
- **Simplicity:** No diff algorithm, no extra abstraction
- **Performance:** Direct updates are faster for small-to-medium UIs
- **Minimal:** Keeps library tiny (~2KB)
- **Predictable:** You see exactly what updates when
- **Standards:** Uses native DOM APIs

**Alternatives considered:**
- ❌ Virtual DOM → Adds complexity, size, and abstractions
- ❌ Template compilation → Requires build step

**Tradeoff:** Reorder-heavy updates on very large lists (1000+ rows) may move more DOM nodes than minimal-move virtual DOM diffing — `repeat()` reconciles in a single forward pass, not with an LIS-style algorithm. For ordinary updates this is not a penalty: keyed element reuse plus the same-reference/same-index skip make the work proportional to what actually changed, with no vnode allocation at all. For very large lists, prefer pagination or virtualization — as you would with any framework.

#### Amendment (v2.3, 2026-07): minimal-move reordering, still no virtual DOM

**Decision:** The tradeoff above no longer holds — `repeat()` now reorders with a minimal-move plan: departed rows are removed first, then the longest increasing subsequence over the surviving rows' previous positions marks the nodes already in the right relative order, and only the nodes off that chain are re-inserted (end to start, before the nearest settled node). A k-item change costs O(k) DOM moves instead of cascading into every node after the first mismatch. This is not a virtual DOM: the diff runs on real elements and their previous indices, with no vnode allocation, no render functions, and no change to the addon's API or observable order/lifecycle semantics.

**Reasoning:**
- Moving a DOM node is the expensive part of a list update: it invalidates layout, and reinserted `iframe`/`video` elements reset. The old forward pass turned one far move into O(distance) moves — a 167-swap storm across 2,000 rows cost ~2,000 `insertBefore` calls per tick, indistinguishable from a full shuffle.
- Measured in the animated-grid example (2,000 tiles, DevTools 20x CPU throttle): storm DOM moves per tick ~2,000 → ~310, worst frame gap 674ms → 465ms, main-thread blocking over a 12s storm 9.0s → 3.5s, sampled fps 4.7 → 9.1. jsdom-verified bounds: a far 2-item swap in 100 rows is ≤2 moves (was ~90), removals move zero survivors, k scattered inserts are exactly k moves.
- Full permutations are unchanged by design (nearly every node must move regardless); the O(n log n) bookkeeping added no measurable cost there (shuffle critical path within noise).

**Alternatives considered:**
- ❌ Keep the forward pass → simplest, but sparse reorders (the common real case: swaps, drag-drop, sort-by-column) pay O(n) moves for O(k) changes.
- ❌ Key-index map without LIS (Vue 2 style patching) → fewer moves than the forward pass but still moves nodes that were already in relative order.
- ❌ Full virtual DOM diff → rejected above; nothing about minimal moves requires vnodes.

**Tradeoff:** +0.21 KB gz on the addons bundle (4.68 → 4.89, budget 6) and O(n log n) index bookkeeping per update (Set + Map + one binary-search pass), paid on every list update to make sparse reorders O(k) — negligible against the DOM operations it removes, and shuffle-scale updates showed no measurable regression.

---

### Why Effects Reuse Their Subscriptions Across Runs (v2.3, 2026-07)

**Decision:** Auto-tracked effects keep their dependencies in a persistent per-effect registry (store → key → subscription record). A re-run stamps each dependency it reads with the run's generation; a dependency that already has a record makes no new subscription, and records not stamped by a completed run are swept (unsubscribed) afterwards. Runs that read nothing and runs that throw keep every subscription, so the effect stays reactive. Tracking semantics are unchanged: conditional dependencies attach on first read and drop when a completed run stops reading them.

**Reasoning:**
- The previous implementation tore down and rebuilt every subscription on every run: N unsubscribes (indexOf + splice on listener arrays), N re-subscribes, and ~2N closure allocations per run, even when the read set was identical — and the read set is identical for almost every re-run in practice.
- The cost scales with dependency width, exactly where effects are most useful: an aggregate effect reading 3,000 stores re-ran 7.5x faster after the change (23.8ms → 3.2ms per run in Chrome under a matched CPU throttle; both measurements on the same rig, verified with a busy-loop probe).
- `computed()` is built on `effect()`, so derived values inherit the gain with no changes.
- The old error path also leaked: it discarded the unsubscribe functions of subscriptions made before the throw, leaving listeners that could never be removed. Keeping the records makes the throwing path leak-free with less code, not more.

**Alternatives considered:**
- ❌ Keep teardown/rebuild → simplest, but pays O(deps) churn for the common no-change case and O(1) savings only in the rare shrink case.
- ❌ Version-tagged global epochs (Vue/Preact-signals style doubly-linked dependency lists) → the churn win without the sweep walk, but substantially more code and pointer bookkeeping than this library's size budget justifies.
- ❌ Never drop stale dependencies → cheapest, but a conditional dependency would keep re-running the effect forever (correctness regression, and a memory leak for dynamic reads).

**Tradeoff:** The sweep is O(total dependencies) when a run drops something (unchanged from before, minus the rebuild), and each effect holds strong references to the store proxies it reads via the registry Map — the same lifetime the old unsubscribe closures already implied. Dependency records cost one small object each, allocated once instead of once per run.

---

### Why Writes to an Unobserved Store Skip the Flush Pipeline (v2.3, 2026-07)

**Decision:** The `set` trap short-circuits after storing the value when the store has zero listeners (across all keys — one live integer maintained by `addListener`/unsubscribe) and no `$beforeFlush` hooks: no pending-notification entry, no batch enqueue, no microtask flush. The flush's notify step also drops pending notifications outright when nothing listens (reachable when only hooks scheduled the flush).

**Reasoning:**
- A store nothing observes still paid the full write pipeline per changed key — Map insert, batch enqueue or microtask schedule, then a flush that notified nobody. That cost is O(writes) exactly where writes are heaviest: high-churn data layers that are *polled* (a rAF render loop reading `store.value`) rather than subscribed.
- Measured in a 3,000-cell stress grid under a 20x CPU throttle: worst write-pass frame 156ms → 16ms (~10x), kernel share of active CPU ~9% → ~1.5%, landing reactive writes within ~1–2x of raw plain-array writes — so churny layers keep `state()` instead of abandoning reactivity for plain data.
- No update can be missed: `$subscribe` delivers the current value immediately on registration, and effects subscribe to a key before they can depend on it, so anything that starts observing sees exactly the state it would have seen.

**Alternatives considered:**
- ❌ Per-key listener counts → finer-grained skipping, but more bookkeeping per subscribe/unsubscribe for a store-level question one integer answers; per-key wins only for stores that are partially observed *and* write-heavy on the unobserved keys — not the measured hot case.
- ❌ An explicit opt-in ("silent store" API) → new API surface for something that is safe to do automatically; explicit-over-magic applies to *behavior*, and no observable behavior is removed.
- ❌ Telling users to use plain objects for churny layers → loses reactivity at the edge where it may later be wanted; measurement showed the fast path captures ~85% of what plain data buys.
- ❌ A kernel change-signal (dirty-list) primitive so pollers get O(changed) scans → measured: no responsiveness gain (rendering is paint-bound, not scan-bound) and the signal itself taxes the write path this decision is removing cost from.

**Tradeoff:** One integer of listener accounting on the subscribe/unsubscribe paths (the double-unsubscribe no-op is guarded by the existing index check). One semantic sharpening: a subscriber registered between a write and its microtask no longer receives a duplicate flush delivery of that write — the immediate `$subscribe` call already delivered the current value (previously it got both). +0.03 KB gz on the kernel (1.46 → 1.49, budget 1.75).

---

### Why No Computed Properties in Core?

**Decision:** Move `computed()` to addons, not core.

**Reasoning:**
- **Core minimalism:** Most apps don't need computed values
- **Easy to add:** Users who need it import from `/addons`
- **Smaller core:** Keeps main bundle tiny
- **Separation of concerns:** Core = state + DOM, Addons = advanced patterns

**Alternatives considered:**
- ❌ Include in core → Increases bundle size for everyone

**Tradeoff:** Extra import line for users who need computed values (acceptable).

---

## TypeScript Decisions

### Why Include Type Definitions But No TypeScript Source?

**Decision:** Ship `index.d.ts` but write source in plain JavaScript.

**Reasoning:**
- **No build step:** Keep source code directly runnable
- **Simpler debugging:** Stack traces point to actual source
- **Easier contribution:** Lower barrier to entry
- **Smaller package:** No need for TypeScript tooling in dependencies
- **Type safety preserved:** `.d.ts` provides full IntelliSense

**Alternatives considered:**
- ❌ TypeScript source → Requires build step, complicates debugging
- ❌ No types → Poor DX for TypeScript users

**Tradeoff:** Type definitions must be manually kept in sync (acceptable with tests).

---

## Testing Decisions

### Why Vitest Instead of Jest?

**Decision:** Use Vitest for testing.

**Reasoning:**
- **Faster:** Native ESM support, no transform overhead
- **Better DX:** Hot module reload for tests
- **Modern:** Built for Vite ecosystem
- **Compatible:** Jest-like API, easy migration

**Alternatives considered:**
- ❌ Jest → Slower, requires babel/transform setup

---

## Extension Patterns

### Why Plugin System (v2.0+)?

**Decision:** Add optional plugin system with hook-based architecture.

```javascript
const debugPlugin = {
  name: 'debug',
  onGet: (key, value) => {
    console.log(`GET ${key}:`, value);
    return value;
  }
};

import { withPlugins } from 'lume-js/addons';
const store = withPlugins(
  state({ count: 0 }),
  [debugPlugin]
);
```

**Reasoning:**
- **Zero-cost abstraction:** Unused plugins add 0 bytes to bundle
- **Universal compatibility:** Core state.js works in Node.js, Deno, browsers
- **Extensibility:** Third-party plugins possible without core changes
- **Separation of concerns:** Advanced features in addons, not core
- **Backward compatible:** Optional, doesn't break existing code

**Why not built-in features:**
- ❌ Adding validation/logging/history to core bloats everyone's bundle
- ❌ Different apps need different features
- ❌ Can't predict all use cases

**Plugin architecture benefits:**
- ✅ Debug tools only in development builds
- ✅ Validation only where needed
- ✅ Tree-shakeable by design
- ✅ Community can create plugins

**Tradeoff:** Slight API verbosity (pass plugins array) for much better modularity.

**Performance:** Typical overhead 10-30% with 1-3 plugins. Acceptable for most use cases.

---

### Why Debug Addon in Addons (Not Core)?

**Decision:** The debug addon (`createDebugPlugin`, `debug.stats()`, `debug.filter()`) lives in `/addons`, not core.

**Reasoning:**
- **Zero production cost:** Debug tools are development-only; bundling them in core wastes bytes in production.
- **Tree-shakeable:** Users who don't need debugging pay nothing.
- **Plugin architecture showcase:** Demonstrates how plugins extend Lume.js without core changes.
- **Critical for adoption:** Hard to debug = hard to adopt. But it's still opt-in.

**Why include stats tracking?**
- **Visibility:** Developers need to see what's reactive (GETs, SETs, NOTIFYs).
- **Performance debugging:** Identify over-reactive properties causing unnecessary re-renders.
- **Educational:** Helps users understand fine-grained reactivity.

**Alternatives considered:**
- ❌ Built into core → Bloats production bundles
- ❌ External-only tools (devtools extension) → Higher barrier, less portable

**Tradeoff:** Requires explicit import for dev tooling, but keeps production lean.

---

### Why Support Explicit Dependencies in `effect()`?

**Decision:** Support two modes for `effect()`:
1. **Auto-tracking (Default):** Dependencies collected by property access
2. **Explicit Deps:** Dependencies passed as `[[store, 'key']]` array

```javascript
// Mode 1: Auto-tracking (Magic) - Good for Views
effect(() => {
  el.textContent = store.count; 
});

// Mode 2: Explicit (No Magic) - Good for Logic/Side-Effects
effect(() => {
  analytics.log(store.count);
}, [[store, 'count']]);
```

**Reasoning:**
- **Honest Admission:** Auto-tracking uses `withReadObserver` — a scope-based read observer that is only active during the synchronous execution of an effect's body. This is less magical than a `globalThis` property or a permanently-installed hook, but still implicit within the scope.
- **Why Keep Auto-tracking?**
  1. **Backward Compatibility:** Converting existing code would be painful.
  2. **Simplicity:** It's still the easiest way to write simple View logic (`el.textContent = store.count`).
- **Why Explicit Deps?**
  - **Philosophy Alignment:** Fits "explicit over magic". You know exactly what triggers the effect.
  - **Safety:** Prevents infinite loops and accidental tracking (e.g., reading a value for logging shouldn't trigger a re-run).
- **Architecture Note:** `state.js` does not permanently know about `effect.js`. Read tracking is only active when a function is executed inside `withReadObserver(onRead, fn)`. Multiple observers (nested effects, devtools, computed) are supported simultaneously via a `Set` of active readers.

**Why `[store, key]` tuple syntax?**
- Lume.js uses proxies, not "refs" or "signals" as values.
- `store.count` is just a number/string value, not a reference.
- To subscribe explicitly, we need both the *object* (`store`) and the *property key* (`'count'`).
- Tuples are concise and typed: `Array<[ReactiveState, ...keys]>`.

**Alternatives considered:**
- ❌ React-style `[store.count]` → Passes value (5), not ref. Can't track changes.
- ❌ Strings `'store.count'` → Requires parsing, no type safety.
- ❌ Object `{ store, key: 'count' }` → Too verbose.

**Tradeoff:** Two ways to do one thing, but serves two distinct mental models (View vs Logic).

### Why Explicit-Deps Effects Coalesce to One Run per Tick (v2.3)

**Decision:** In explicit-deps mode, any number of tracked keys changing in the same tick — across any number of stores — produces exactly one re-run, scheduled on the next microtask.

**Reasoning:**
- **Bug half:** within one store, running once per changed key contradicted the documented batching promise ("multiple property changes trigger effects once"). Auto-tracking already behaved correctly via the per-state effect queue.
- **Semantics half:** explicit mode's contract is "run when any listed dependency changed", which naturally coalesces across stores too. This makes explicit mode *stricter* than auto mode (which runs once per store, per the per-state decision) — acceptable because explicit deps are the "Logic" mode where redundant runs are pure waste, and the dependency list is spelled out by the developer.
- A `disposed` guard ensures a run pending at cleanup time never fires.

**Tradeoff:** Re-runs happen one microtask later than before (after the store's flush rather than during subscriber notification). No observable difference for code awaiting a tick.


---

### Why `data-{attr}` for Reactive HTML Attributes?

**Decision:** Make HTML attributes reactive by prefixing with `data-`. Use explicit selector list (not dynamic scanning) for performance. Extend via composable handler objects passed to `bindDom()`.

```html
<!-- Built-in: always available, no imports needed -->
<div data-hidden="isLoading">Content</div>
<button data-disabled="isSubmitting">Submit</button>
<input data-checked="isAgreed" type="checkbox">
<input data-required="fieldRequired">
<button data-aria-expanded="menuOpen">Menu</button>
<div data-aria-hidden="isCollapsed">Panel</div>
```

```html
<!-- Extended: import handlers, pass to bindDom -->
<span data-show="isVisible">Shown when truthy</span>
<div data-class-active="isActive">CSS class toggle</div>
<a data-href="profileUrl">Profile</a>
<input data-readonly="isReadonly">
```

```js
// Implementation: Handler objects with compiled selectors
import { show, classToggle, stringAttr } from 'lume-js/handlers';

bindDom(root, store, {
  handlers: [show, classToggle('active'), stringAttr('href')]
});

// Handler contract: { attr: string, apply(el, val): void }
// Built-in defaults use same pattern internally:
//   boolHandler('hidden')  → { attr: 'data-hidden', apply(el, val) { el.hidden = Boolean(val); } }
//   ariaHandler('aria-expanded') → { attr: 'data-aria-expanded', apply(el, val) { el.setAttribute(...); } }
```

**Reasoning:**
1. **Extends `data-bind` naturally:** Same pattern users already know (`data-{thing}="stateKey"`)
2. **Standards-based:** `data-*` is valid HTML5, works with validators
3. **Explicit mapping:** `data-hidden` → `hidden`, no interpretation needed
4. **Performance:** Compiled selectors built from handler list, `O(n)` DOM pass
5. **Composable:** Handlers are plain objects — combine, override, create custom ones
6. **Tree-shakeable:** Only import the handlers you use (`lume-js/handlers`)
7. **No core modification:** New attributes never require changing `bindDom` source

**Handler system design (v2.0.0-beta.2):**
- Built-in handlers (always active): `hidden`, `disabled`, `checked`, `required`, `aria-expanded`, `aria-hidden`
- User handlers override built-ins with same `attr` (Map deduplication)
- Arrays auto-flattened (supports `classToggle()` returning multiple handlers)
- Custom handler = any object with `{ attr, apply }` — no framework API needed

**Alternatives considered:**
- ❌ Custom directives (`x-hidden`, `v-if`, `x-bind:hidden`) → Breaks standards-only philosophy
- ❌ Generic syntax `data-attr="hidden:isLoading"` → More complex, harder to scan
- ❌ Dynamic scanning (scan all `data-*` attrs) → Ambiguity with non-Lume attrs (`data-testid`), O(n × m)
- ❌ Side-effect imports (auto-register on import) → Violates "explicit over magic" philosophy
- ❌ Marker attribute hybrid (`data-lm` + store-key matching) → Still has collision risks

**What we deferred:**
- `data-style` — Security implications need careful design
- Expressions (`data-hidden="count > 5"`) — Violates explicit philosophy

**What we resolved (previously deferred):**
- ✅ `data-show` — Implemented as `show` handler (inverse of `data-hidden`)
- ✅ `data-class-{name}` toggle — Implemented as `classToggle()` factory
- ✅ `data-href`, `data-src` — Implemented as `stringAttr()` factory
- ✅ Negation pattern — `data-show` is the positive counterpart to `data-hidden`

**Tradeoff:** Explicit handler registration means users opt in to each attr. But this gives performance (compiled selectors), safety (no ambiguity), and composability (mix and match handlers).

---

### Why a `persist()` Addon (v2.3)

**Decision:** Ship localStorage/sessionStorage sync as an addon: hydrate watched keys on call, save on change.

**Reasoning:**
- On the VISION roadmap (~500B estimate; measured 0.75 KB standalone), and every example app was hand-rolling the same `JSON.parse(localStorage.getItem(...))` + scattered `setItem` pattern.
- **Allowlist hydration:** only watched keys are ever assigned from storage — stale or tampered storage cannot inject state (the core `set` trap independently blocks prototype-polluting keys).
- **Contained failures:** corrupted JSON starts fresh, circular state skips the save, quota errors warn, missing storage (SSR) disables itself. Persistence is a convenience; it must never take the app down.
- Saves coalesce to one write per microtask and skip unchanged snapshots.

**Alternatives considered:**
- ❌ In core → bloats everyone; storage is not a reactivity concern
- ❌ Cross-tab sync via the `storage` event → deferred; clean additive option later

**Tradeoff:** One JSON blob per `persist()` call; plain-data values only (functions/symbols are skipped by JSON).

---

## Packaging Decisions

### Why a `lume-js/state` Entry Instead of Demoting bindDom/effect (v2.3)

**Decision:** Publish the DOM-free kernel (`state`, `batch`, `withReadObserver`) as an additional entry — `lume-js/state` (1.45 KB gz, own CI budget) — while `lume-js` keeps exporting the full core.

**Reasoning:**
- The original goal (state-only core for Node/CLI) is a *packaging* question, not a source question: the source was already layered (state imports nothing upward; effect/bindDom sit on its public seams).
- **No-build users can't tree-shake** — for the library's primary audience the universal core must exist as a downloadable file (`dist/state.min.mjs`), not a theoretical import subset.
- Demoting `bindDom`/`effect` out of `lume-js` would break every existing user for zero byte savings (bundlers already drop them for state-only importers via `sideEffects: false`).
- Per-entry CI budgets keep both numbers honest: kernel ≤ 1.75 KB, full core ≤ 3 KB.

**Tradeoff:** Two documented entry points instead of one. Worth it: "1.45 KB universal / 2.66 KB with DOM" is the honest size story.

---

## Tooling Decisions

### Why Docs Facts and Navigation Are Generated (docs:sync)

**Decision:** Facts that change with every build (version, gzipped sizes, test count, browser floor) live in exactly one generated file, `docs/metrics.json` (`scripts/build-metrics.js`, never hand-edited). Structure that changes when pages are added or reordered (nav order, the `docs/README.md` index, the `llms.txt`/`llms-full.txt` bundle order) lives in exactly one authored file, `docs/manifest.json`. `scripts/sync-docs.js` rewrites `<!-- lume:* -->` marker regions embedded directly in the real files — README badges, guide prose, nav footers — from those two sources; `npm run docs:check` fails CI when running the sync would produce a diff.

**Reasoning:**
- Every one of these had shipped as a real bug at some point: the FAQ claiming "2.x is in beta" a year after stable, README and the installation guide quoting three different sizes for the same bundle, `build-llms.js`'s hardcoded section list pointing at two API pages that didn't exist while omitting all eight handler pages, a tutorial with two contradictory prev/next footers, and a version bump in `package.json` that left `llms.txt`'s `Version:` line stale. All of these are the same failure mode — a fact or a link typed as a literal in more than one place — and a CI gate that only checks *some* of the copies will always miss the others.
- Markers live inside the real files rather than a separate template tree so there is no second copy to keep in sync with the first: each file is simultaneously the template and the rendered output.
- An unrecognized `lume:` marker key is a hard build error, not a silently-ignored no-op — a typo in a marker name is exactly the kind of drift this exists to catch.
- `docs/design/design-decisions.md` (this file), `CHANGELOG.md`, and `CLAUDE.md`/`AGENTS.md` are deliberately excluded from marker management — they are historical or hand-authored-by-contract documents (see the "amend, never rewrite" convention already in force here), not facts that should be silently overwritten by a build script.

**Alternatives considered:**
- *A single hand-maintained checklist* ("update these N places when X changes") — this is what existed before, and it is exactly what kept failing; checklists rely on someone remembering to run them.
- *A separate template directory rendered into the docs tree* — rejected because it doubles the files a contributor has to look at to understand what a page says, and markdown-in-markdown templating adds a build step of its own for very little benefit over inline markers.

**Tradeoff:** Every fact-bearing sentence in a managed file now carries a pair of HTML comments, which is visible noise in the raw markdown (and, in a few code-fence examples, in the rendered output too — see `docs/guides/installation.md`'s version-pin example). Traded for: it is no longer possible for these specific facts to silently disagree with each other across the repo.

---

## Future Considerations

**Features We Might Add Later:**

- Array-based checkbox bindings (if clean solution found)
- `contenteditable` support with cursor position handling
- Debounced input binding option
- Form validation addon
- Router addon (standards-based, using History API)

**Will NOT add:**
- Custom directive syntax (breaks standards-only principle)
- Build step requirement (breaks no-build-step principle)
- Virtual DOM (too complex for minimal philosophy)
- Lifecycle hooks (too framework-y)
- Custom event syntax (`@click`, `on:click`) or inline handlers — the opt-in `data-on*` handler (state-key references only) is the allowed form; see the v2.3 amendment above
- Template directives (`v-if`, `v-for`, `x-if`)

---

## How to Suggest Changes

If you think a decision should be reconsidered:

1. **Open an issue** with:
   - Why the current approach is problematic
   - Your proposed alternative
   - How it aligns with Lume's philosophy
   - Performance/complexity tradeoffs

2. **Show a use case** where current design fails

3. **Propose implementation** (code or pseudocode)

We're open to change, but will prioritize **simplicity and standards** over features!

---

**← Previous: [Working with Arrays](../tutorials/working-with-arrays.md)**


========================================================================
FILE: docs/guides/migration.md
========================================================================

# Migrating from 1.x to 2.x

Lume 2.0 is a near-complete rewrite. The internals are faster and the architecture is cleaner — but the core API is fully backward compatible, so migrating is straightforward.

## Breaking changes

**Bump the version in `package.json`:**

```diff
   "dependencies": {
-    "lume-js": "^1.0.0"
+    "lume-js": "^2.0.0"
   }
```

**`isReactive` moved to `lume-js/addons`:**

```diff
- import { state, isReactive } from 'lume-js';
+ import { state } from 'lume-js';
+ import { isReactive } from 'lume-js/addons';
```

Everything else continues to work without modification.

## New in 2.x

- `watch(store, key, fn)` — explicit single-key watcher; fires immediately on subscribe with the current value
- `computed()` — derived value with auto-tracking and `.dispose()`
- `effect()` — reactive side-effect with optional explicit deps
- `isReactive()` — detect a reactive proxy (import from `lume-js/addons`)
- `data-show` attribute (via `show` handler) — conditional visibility, positive counterpart to `data-hidden`
- `data-class-*` attributes (via `classToggle()` factory) — per-class CSS toggle (e.g. `data-class-active`)
- `show`, `classToggle()`, `stringAttr`, `boolAttr`, `ariaAttr` handlers — import from `lume-js/handlers`
- `withPlugins(store, plugins)` — apply plugins (logging, validation, transforms) to a store, import from `lume-js/addons`
- `createDebugPlugin` / `debug` — developer logging addon (import from `lume-js/addons`)

## Unchanged

- `state(obj)` — same API, same contract
- `bindDom(root, store, { handlers })` — same API
- `data-bind`, `data-hidden`, `data-disabled`, `data-checked` attribute names
- Zero dependencies, no build step required

---

**← Previous: [Working with Arrays](../tutorials/working-with-arrays.md)** | **Next: [FAQ](faq.md) →**


========================================================================
FILE: docs/guides/faq.md
========================================================================

# FAQ

## Is Lume.js production-ready?

Yes. Lume 2.x is stable — the current release on npm is v2.4.0 (`npm install lume-js`), backed by 475 tests at 100% coverage and CI-enforced size budgets. The core API (`state`, `bindDom`, `effect`, `batch`) and all addons (`watch`, `computed`, `repeat`, `persist`, `withPlugins`, …) are stable. The 1.x series is legacy — see [Migrating from 1.x](migration.md).

## Does Lume work without a build step?

Yes — that's one of its main advantages. Import from a CDN and write plain JavaScript:

```html
<script type="module">
  import { state, bindDom, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/dist/index.min.mjs';
</script>
```

No bundler, no npm, no config.

## Does Lume support TypeScript?

Yes. Types are included in the package. No `@types/` install needed.

## Can I use Lume with an existing server-rendered page?

Yes — that's a primary use case. Attach `bindDom` to any element on the page and the rest of the page is untouched:

```js
const store = state({ open: false });
bindDom(document.getElementById('nav'), store);
```

## How does Lume compare to Alpine.js?

Both work inline with server-rendered HTML. Lume uses standard `data-*` attributes; Alpine uses `x-*` directives with a custom expression syntax. Lume is smaller (2.77 KB vs ~15 KB gzipped — 1.49 KB for the DOM-free kernel) and has no custom expression evaluator — logic lives in plain JS, not attribute strings.

## How does Lume compare to Vue 3's reactivity?

Lume's core reactivity (`state`, `effect`, `watch`, `computed`) is conceptually similar to Vue's `reactive`/`watchEffect`/`watch`/`computed`. The main difference is that Lume has no component model or template compiler — it binds directly to the DOM via `data-*` attributes.

## Can I use `Map` or `Set` in state?

No. The Proxy only intercepts plain object and array operations. Use plain arrays instead of `Set`, and objects with string keys instead of `Map`.

```js
// Not reactive
const store = state({ tags: new Set(['js', 'css']) });

// Use an array
const store = state({ tags: ['js', 'css'] });
```

## Why does my effect run more than I expect?

Effects re-run for every key they read. If you read `store.a` and `store.b` inside one effect, it re-runs when either changes. Use `watch(store, 'key', fn)` when you need to react to exactly one key, or use `computed` to derive a single value that the effect reads.

## How do I do conditional rendering?

The simplest way is `data-show` or `data-hidden`. Note that `data-show` requires opting in to the `show` handler — it is not built into `bindDom` by default:

```js
import { state, bindDom } from 'lume-js';
import { show } from 'lume-js/handlers';

const store = state({ isLoggedIn: false });
bindDom(document.body, store, { handlers: [show] });
```

```html
<div data-show="isLoggedIn">Welcome back!</div>
<div data-hidden="isLoggedIn">Please log in.</div>
```

For replacing entire sections, assign `innerHTML` inside an `effect` — but only with markup you wrote yourself, never with user-supplied data (Lume's own bindings use `textContent` exactly to avoid HTML injection):

```js
effect(() => {
  outlet.innerHTML = store.page === 'home' ? homeHTML : aboutHTML;
});
```

## Does Lume support async effects?

`effect` itself is synchronous — it runs its function immediately and tracks dependencies. For async work, trigger it from a `watch` callback:

```js
watch(store, 'userId', async (id) => {
  const user = await fetch(`/api/users/${id}`).then(r => r.json());
  store.userName = user.name;
});
```

## How do I share state between multiple `bindDom` calls?

Pass the same store object to each call:

```js
const store = state({ count: 0, theme: 'light' });

bindDom(document.getElementById('header'), store);
bindDom(document.getElementById('main'), store);
bindDom(document.getElementById('footer'), store);
```

All three subtrees share the same reactive store. A write in one subtree updates all of them.

## Can I have multiple independent stores?

Yes — create as many `state()` objects as you need:

```js
const userStore = state({ name: 'Ada', role: 'admin' });
const cartStore = state({ items: [], total: 0 });

bindDom(document.getElementById('user-panel'), userStore);
bindDom(document.getElementById('cart'), cartStore);
```

## How do I clean up when removing a component?

Call the cleanup function returned by `bindDom` and dispose any effects:

```js
const cleanup = bindDom(el, store);
const stopEffect = effect(() => { /* … */ });

// When tearing down:
cleanup();
stopEffect();
```

---

**← Previous: [Migrating from 1.x](migration.md)**