# Lumen — full documentation

> A transparent, no-magic, no-build vanilla-JS OOP UI framework. What you write is what runs.



---

<!-- README.md -->

# Lumen

> A transparent, no-magic, no-build vanilla-JS OOP UI framework. **What you write is what runs.**
>
> Un framework de UI en JS vanilla, OOP, transparente, sin magia y sin build. **Lo que escribes es lo que corre.**

**📖 Live docs & examples · Documentación y ejemplos en vivo:** https://dragones-tech.github.io/lumen/site/

## Install · Instalar

No build, native ES modules, zero runtime deps. Full guide: [en](docs/en/install.md) · [es](docs/es/install.md).

```html
<!-- 1) CDN, no install — import map + jsDelivr (pin a tag/commit for production) -->
<script type="importmap">
{ "imports": {
  "lumenjs": "https://cdn.jsdelivr.net/gh/dragones-tech/lumen@main/src/index.js",
  "lumenjs/": "https://cdn.jsdelivr.net/gh/dragones-tech/lumen@main/src/"
}}
</script>
<script type="module">
  import { View } from 'lumenjs';
</script>
```

```bash
# 2) or copy src/ into your project (most transparent)
# 3) or npm:
npm i @jehosogo/lumenjs                    # published on npm
# or from GitHub: npm i github:dragones-tech/lumen
```

## Principles · Principios

- **No build.** Native ES modules. The only thing you need is a static file server (ES module imports are blocked on `file://`). Your `.js` reaches the browser untouched.
- **No magic.** No global side effects on import, no hidden proxies, no compiler rewriting your code. Explicit OOP with a lifecycle you can read.
- **No Web Components.** Plain classes (not `extends HTMLElement`), so you keep full control of `animate`/`unmount`. A Custom Element adapter is an opt-in escape hatch.
- **Separate HTML.** Markup lives in native `<template>` elements — real HTML, full editor autocomplete.
- **Style-agnostic.** Ships zero CSS. Bring plain CSS, native `@scope`, Tailwind — whatever you like.
- **Typed without a build.** Plain `.js` + JSDoc types, checked with `tsc --noEmit`.

## Run the examples · Correr los ejemplos

```bash
# from the repo root — zero-dep Node static server with live reload
npm run serve   # save a file → the browser reloads (set LIVERELOAD=0 to disable)
# then open http://localhost:8000/examples/event-emitter/
```

## Docs site · Sitio de docs

A bilingual (EN/ES) documentation site **built with Lumen itself** — sidebar + router +
each page's live example embedded. Un sitio de documentación bilingüe **hecho con Lumen**.

```bash
npm run serve
# open http://localhost:8000/site/
```

## Type-check · Verificar tipos

```bash
npm install   # dev-only: TypeScript, for checking JSDoc types (never runs in the browser)
npm run check
```

## Modules · Módulos

| Module | Status | Docs |
|---|---|---|
| `event-emitter` | ✅ done | [en](docs/en/event-emitter.md) · [es](docs/es/event-emitter.md) |
| `dom` | ✅ done | [en](docs/en/dom.md) · [es](docs/es/dom.md) |
| `animate` | ✅ done | [en](docs/en/animate.md) · [es](docs/es/animate.md) |
| `view` | ✅ done | [en](docs/en/view.md) · [es](docs/es/view.md) — abstract base class you extend |
| `model` | ✅ done | [en](docs/en/model.md) · [es](docs/es/model.md) |
| `collection` | ✅ done | [en](docs/en/collection.md) · [es](docs/es/collection.md) |
| `collection-view` | ✅ done | [en](docs/en/collection-view.md) · [es](docs/es/collection-view.md) |
| `region` | ✅ done | [en](docs/en/region.md) · [es](docs/es/region.md) |
| `router` | ✅ done | [en](docs/en/router.md) · [es](docs/es/router.md) |
| `http` | ✅ done | [en](docs/en/http.md) · [es](docs/es/http.md) — `fetch` wrapper |
| `i18n` | ✅ done | [en](docs/en/i18n.md) · [es](docs/es/i18n.md) — translations |
| `validate` | ✅ done | [en](docs/en/validate.md) · [es](docs/es/validate.md) — model + UI validation |
| `element` | ✅ done | [en](docs/en/element.md) · [es](docs/es/element.md) — use a View as a Custom Element (`defineElement`) |
| `canvas` | 🧪 experimental | [en](docs/en/canvas.md) · [es](docs/es/canvas.md) — render the same Model/Collection to canvas (`Stage`/`Node2D`/`CanvasLayer`); import from `lumenjs/canvas` |

## Guides · Guías

- **Styling** (Lumen is style-agnostic; plain CSS, `@scope`, Tailwind): [en](docs/en/styling.md) · [es](docs/es/styling.md) — runnable [Tailwind example](examples/tailwind/).
- **Deployment & loading** (HTTP/2, import maps, `modulepreload` — no bundler needed): [en](docs/en/deployment.md) · [es](docs/es/deployment.md).
- **For AI agents** (llms.txt, AGENTS.md): [en](docs/en/llms.md) · [es](docs/es/llms.md).
- **Credits & lineage** (homage to Backbone & Marionette): [en](docs/en/credits.md) · [es](docs/es/credits.md).

## For AI agents · Para agentes de IA

Machine-readable docs so an assistant (Claude, Codex, Cursor…) writes idiomatic Lumen:

- [`llms.txt`](https://dragones-tech.github.io/lumen/llms.txt) — index of all docs ([llmstxt.org](https://llmstxt.org) convention).
- [`llms-full.txt`](https://dragones-tech.github.io/lumen/llms-full.txt) — every page in one file; paste it into your assistant.
- [`AGENTS.md`](AGENTS.md) — project conventions for coding agents (and `CLAUDE.md` for Claude Code).

Regenerate the `llms.*` files after editing docs with `npm run llms`.

## Credits · Créditos

Lumen is a respectful, modernized homage to **[Backbone.js](https://backbonejs.org/)**
(Model, Collection, events-first) and **[Marionette.js](https://marionette.js.org/)**
(View, Region, CollectionView, layouts). The patterns are theirs; the implementation is
rebuilt on the modern platform — no jQuery, no Underscore, no build. No Backbone/Marionette
code is used; these are conceptual inspirations. See [credits](docs/en/credits.md).


---

<!-- docs/en/install.md -->

# Installation

Lumen is no-build, native ES modules, with zero runtime dependencies — so "installing" can
be as light as pointing at a CDN or copying a folder. Pick what fits your setup.

## Option 1 — CDN, no install (quickest)

Add an import map and load from a CDN (jsDelivr serves the GitHub repo directly):

```html
<script type="importmap">
{
  "imports": {
    "lumenjs": "https://cdn.jsdelivr.net/gh/dragones-tech/lumen@main/src/index.js",
    "lumenjs/": "https://cdn.jsdelivr.net/gh/dragones-tech/lumen@main/src/"
  }
}
</script>

<script type="module">
  import { View } from 'lumenjs';
  // …your app
</script>
```

Pin a tag or commit for production instead of `@main` (e.g. `@v0.1.0`) so it can't change under you.

## Option 2 — copy `src/` (most transparent)

Lumen is just plain `.js` files. Copy the repo's `src/` into your project (e.g.
`vendor/lumen/`) and import it — relatively or via an import map:

```html
<script type="importmap">
{ "imports": { "lumenjs": "/vendor/lumen/index.js", "lumenjs/": "/vendor/lumen/" } }
</script>
```

You own the code, no package manager, nothing to update behind your back. Very on-brand.

## Option 3 — npm / GitHub

```bash
npm i @jehosogo/lumenjs     # published on npm
# or straight from GitHub:
npm i github:dragones-tech/lumen
```

Bundlers and Node resolve `@jehosogo/lumenjs` via the package's `exports`. In the
browser **without** a bundler, still add an import map pointing the specifier at the
installed files (e.g. `node_modules/@jehosogo/lumenjs/src/index.js`), since browsers
don't resolve bare specifiers on their own.

## Serve it

Any static server works (ES module imports are blocked on `file://`). The repo ships a
zero-dep one with live reload:

```bash
npm run serve   # → http://localhost:8000
```

## Type-checking (optional)

Types are JSDoc; check them with TypeScript (dev-only, never runs in the browser):

```bash
npm i -D typescript
npm run check   # tsc --noEmit
```

> Status: published on npm as `@jehosogo/lumenjs`, source on GitHub (`dragones-tech/lumen`);
> the CDN and `github:` install also work.


---

<!-- docs/en/event-emitter.md -->

# EventEmitter

A tiny, typed, leak-free event emitter. It is the foundation of messaging in Lumen.

## Philosophy

- **No global singleton.** You create emitters with `new` and pass them around explicitly. Importing the module has *no side effects* — nothing is registered, nothing touches `window`.
- **Symmetric cleanup.** Every `on()` returns an unsubscribe function. You can also pass an `AbortSignal`, so aborting one controller removes every listener bound to it at once. (This is how `View` will tear listeners down on unmount, without leaks.)
- **Safe by default.** `off()` on an event that was never registered is a no-op, not a crash.

## API

| Method | Returns | Description |
|---|---|---|
| `on(event, handler, { signal? })` | `() => void` | Subscribe. Returns an unsubscribe function. |
| `once(event, handler, { signal? })` | `() => void` | Subscribe for a single emission, then auto-remove. |
| `off(event, handler)` | `void` | Remove a specific handler. No-op if absent. |
| `emit(event, payload)` | `void` | Call every handler synchronously with `payload`. |
| `clear(event?)` | `void` | Remove all handlers for `event`, or all events if omitted. |
| `listenerCount(event)` | `number` | How many handlers are registered for `event`. |

## Typing your events

Pass an events map as the generic to get autocomplete and payload checking:

```js
/** @typedef {{ 'todo:add': { text: string }, 'todo:clear': void }} TodoEvents */

/** @type {EventEmitter<TodoEvents>} */
const bus = new EventEmitter();

bus.on('todo:add', (p) => console.log(p.text)); // p is { text: string }
bus.emit('todo:add', { text: 'milk' });          // payload checked
```

For events with no data, type the payload as `void` and pass `undefined`.

## Example

```js
import { EventEmitter } from 'lumenjs/event-emitter';

const bus = new EventEmitter();

// Subscribe; keep the unsubscribe handle.
const off = bus.on('ping', (n) => console.log('ping', n));
bus.emit('ping', 1); // logs: ping 1
off();
bus.emit('ping', 2); // nothing — already unsubscribed

// Group cleanup with an AbortController.
const ac = new AbortController();
bus.on('tick', () => console.log('tick'), { signal: ac.signal });
bus.on('tock', () => console.log('tock'), { signal: ac.signal });
ac.abort(); // removes BOTH listeners at once
```

## App-wide messaging (a shared bus)

This is how independent views, models and collections talk to each other — the role
Backbone's Radio played, minus the global singleton. Create an `EventEmitter`, share it by
importing it, and let unrelated views subscribe (each with `this.signal`, so it auto-cleans on
unmount). Models and Collections already emit events you can subscribe to the same way. A
running example — a catalog, a cart badge, and toasts coordinating through a shared bus and a
shared collection — is at [examples/messaging](../../examples/messaging/).

## Design notes

- Handlers are stored in a `Map<string, Set<Function>>`. The `Set` dedupes the same handler reference and makes `off()` O(1).
- `emit()` iterates over a **copy** of the handler set, so a handler may call `on()`/`off()` during emission without disturbing the current pass.
- This replaces the old framework's `eventing` package, fixing two bugs: the global frozen singleton (now instantiable) and `off()` throwing when the event was never registered (now guarded).


---

<!-- docs/en/dom.md -->

# dom

DOM helpers — the bridge between your separate HTML (`<template>` elements) and your component classes.

## Philosophy

- **No magic.** `clone` is a convenient deep-clone of a `<template>`, `refs` is one `querySelectorAll` collected into an object, `$`/`$$` are typed wrappers. Importing the module has **no side effects** — nothing touches `window`, nothing observes the document. (The old framework installed a global `window.createElement` and a document-wide `MutationObserver` on import; Lumen does neither.)
- **The pattern:** write markup once in a `<template>` → `clone()` a fresh node → `refs()` the elements you'll update. A component then touches only what changed, instead of re-rendering its whole subtree.

## API

| Function | Returns | Description |
|---|---|---|
| `$(selector, root?)` | `Element \| null` | `querySelector`, typed and scoped (default root `document`). |
| `$$(selector, root?)` | `Element[]` | `querySelectorAll` as a real array, not a live NodeList. |
| `clone(template, root?)` | `HTMLElement` | Deep-clone a `<template>`'s single root element. Accepts a `<template>` or a selector. |
| `refs(root)` | `Record<string, HTMLElement>` | Collect every `[data-ref]` descendant into a keyed object. |

## Conventions

- **One root per template.** `clone()` returns the template's first element child. Wrap each component's markup in a single root element.
- **`data-ref` for references.** `<button data-ref="save">` → `refs.save`. The root element is included if it has a `data-ref`. `data-ref` is for a component's *own* markup — child components manage their own.

## Example

```html
<template id="card">
  <article class="card">
    <h2 data-ref="title"></h2>
    <button data-ref="save">Save</button>
  </article>
</template>
```

```js
import { clone, refs } from 'lumenjs/dom';

const el = clone('#card');          // fresh detached <article>
const ui = refs(el);                // { title, save }

ui.title.textContent = 'Hello';
ui.save.onclick = () => console.log('saved');

document.body.appendChild(el);
```

Typing the refs map (optional) gives you autocomplete:

```js
/** @type {{ title: HTMLElement, save: HTMLButtonElement }} */
const ui = refs(el);
```

## Design notes

- `$$` spreads the NodeList into an array so you can `map`/`filter` directly and so it is not live.
- `clone` throws a clear error if the template is missing or empty — failures are loud, not silent.
- `clone` deliberately returns a single element (not a fragment): a component's root is one node, which makes `mount`/`unmount` and animations straightforward.
- No `el()`/hyperscript helper is included by default — markup lives in `<template>`. One can be added later if a use case needs purely programmatic nodes.


---

<!-- docs/en/animate.md -->

# animate

Promise-based animation helpers built on the native Web Animations API. These are the primitives a `View` uses to coordinate enter/leave transitions.

## Philosophy

- **Promises, not callbacks.** Every helper returns `Promise<void>` that resolves when the animation finishes. This is what makes `animateOut` possible: a `View` can `await view.animateOut()` *before* removing the node, so the leave animation always plays fully.
- **No side effects on import.** `prefers-reduced-motion` is checked lazily, per call.
- **Accessible by default.** When the user prefers reduced motion (or `duration` is `0`), helpers resolve immediately without animating.
- **Never rejects.** A cancelled animation resolves rather than throwing, so an interrupted transition can't crash an unmount.

## API

| Function | Description |
|---|---|
| `play(el, keyframes, options?)` | Run any keyframes; resolve when done. The primitive below the rest. |
| `fadeIn(el, options?)` | Opacity 0 → 1. |
| `fadeOut(el, options?)` | Opacity 1 → 0. |
| `slideIn(el, options?)` | Rise into place while fading in. |
| `slideOut(el, options?)` | Sink slightly while fading out. |

### `AnimateOptions`

| Option | Default | Description |
|---|---|---|
| `duration` | `200` | Milliseconds. `0` skips the animation. |
| `easing` | `'ease'` | A CSS easing keyword or `cubic-bezier(...)`. |
| `delay` | `0` | Milliseconds before starting. |

## Example

```js
import { fadeIn, slideOut } from 'lumenjs/animate';

// Enter: append, then play the in animation.
document.body.appendChild(el);
await fadeIn(el, { duration: 250 });

// Leave: play the out animation, THEN remove.
await slideOut(el, { duration: 200 });
el.remove();
```

Inside a `View` (module 4) this becomes:

```js
class Toast extends View {
  animateIn()  { return slideIn(this.el); }
  animateOut() { return slideOut(this.el); } // awaited before the node leaves the DOM
}
```

## Custom keyframes

`play` accepts any Web Animations keyframes, so you are never boxed in:

```js
import { play } from 'lumenjs/animate';

await play(el, [
  { transform: 'scale(0.8)', opacity: 0 },
  { transform: 'scale(1)',   opacity: 1 },
], { duration: 180, easing: 'cubic-bezier(.2,.8,.2,1)' });
```

## Design notes

- Helpers don't use `fill`/`commitStyles`: each animation's end state equals the element's natural resting style (opacity 1, no transform), so nothing needs to be pinned and no inline styles are left behind.
- `play` resolves on both fulfillment and rejection of `Animation.finished`, collapsing "finished" and "cancelled" into one safe outcome.


---

<!-- docs/en/view.md -->

# View

The abstract base class for everything you see. **A view is a class — you extend `View`.**
It wraps the `dom` primitives (`clone` + `refs`), an explicit lifecycle, and leak-free
cleanup, so you never wire that plumbing by hand.

## Philosophy

- **OOP, not functions.** A view is a class with behavior and a lifecycle. The stateless helpers (`clone`, `refs`, `fadeIn`…) are the primitives it uses internally.
- **A plain class, not a Custom Element.** You keep full control of the lifecycle, so `animateOut()` finishes *before* the node leaves the DOM. (A Custom Element's `disconnectedCallback` only fires *after* removal — too late to animate out.)
- **Surgical updates, no re-render.** You change nodes in `this.ui` directly. Focus, scroll and input state are never lost. (The old framework re-ran `innerHTML = ''` on every change; Lumen never does.)
- **Symmetric, automatic cleanup.** Listeners bound with `this.signal` (or `this.listen(...)`) are removed on `unmount()` — no leaks, and none of the old framework's "listener re-subscribed on every update" bug.

## Lifecycle, in order

1. `new View(props)` — cheap; nothing is built or touched yet.
2. `build()` (called by `mount`) — `render()` makes `el`, `refs()` fills `ui`, then `onCreate()`. Runs once.
3. `mount(parent)` — inserts `el`, sets `mounted`, calls `onMount()`, awaits `animateIn()`.
4. `unmount()` — awaits `animateOut()`, unmounts children, calls `onUnmount()`, aborts `signal`, removes `el`.

Wire listeners in `onMount()` (it re-runs on remount); do one-time setup in `onCreate()`.

## API

| Member | Description |
|---|---|
| `static template` | A `<template>` selector (e.g. `'#card'`) or element used by the default `render()`. |
| `props` | The data/handlers passed to the constructor. |
| `el` | The root element (`null` until `build()`/`mount()`). |
| `ui` | The `[data-ref]` elements, keyed by name. |
| `events` | A per-view `EventEmitter` for talking to a parent. |
| `signal` | An `AbortSignal` tied to the mounted lifetime — bind listeners with it for auto-cleanup. |
| `mounted` | Whether the view is in the DOM. |
| `render()` | Build the root node. Default clones `static template`; override to build differently. |
| `build()` | Create `el` + `ui` (idempotent). |
| `mount(parent)` | Insert and run the mount lifecycle. Returns `Promise<this>`. |
| `unmount()` | Animate out, tear down children, clean up, remove. Returns `Promise<void>`. |
| `addChild(child, parent?)` | Mount a child (default parent: `this.el`) and track it for cascade unmount. |
| `removeChild(child)` | Untrack and unmount a child. |
| `listen(target, type, handler, options?)` | `addEventListener` bound to `signal` (auto-removed on unmount). |
| `observe(target, callback, options?)` | `IntersectionObserver` bound to `signal` (auto-disconnected on unmount). |
| `onResize(target, callback, options?)` | `ResizeObserver` bound to `signal` (auto-disconnected on unmount). |
| `onMedia(query, callback)` | `matchMedia` listener bound to `signal`; returns the `MediaQueryList` (read `.matches`). |
| `interval(callback, ms)` | `setInterval` cleared on unmount (bound to `signal`); returns the timer id. |
| `mount(parent, { animate? })` | `animate: false` skips `animateIn()` (used by `Region`'s View-Transition path). |
| `unmount({ animate? })` | `animate: false` skips `animateOut()`; propagates through the cascade. |
| `onCreate / onMount / onUnmount` | Lifecycle hooks (override). |
| `animateIn / animateOut` | Transition hooks; return a Promise (override). |

## Example

```html
<template id="note">
  <div class="note">
    <span data-ref="text"></span>
    <button data-ref="remove">×</button>
  </div>
</template>
```

```js
import { View } from 'lumenjs/view';
import { slideIn, slideOut } from 'lumenjs/animate';

class Note extends View {
  static template = '#note';

  onMount() {
    this.ui.text.textContent = this.props.text;
    // Bound to signal → removed automatically on unmount.
    this.listen(this.ui.remove, 'click', () => this.props.onRemove(this));
  }
  onUnmount() { /* timers/subscriptions are cleaned automatically via signal */ }

  animateIn()  { return slideIn(this.el); }
  animateOut() { return slideOut(this.el); } // plays fully BEFORE removal
}

await new Note({ text: 'Hello', onRemove: (n) => n.unmount() }).mount(document.body);
```

## Typing your refs

Extend with a generic so `this.ui` is typed:

```js
/** @extends {View<{ text: HTMLElement, remove: HTMLButtonElement }>} */
class Note extends View {
  static template = '#note';
  onMount() {
    this.ui.text;   // HTMLElement
    this.ui.remove; // HTMLButtonElement
  }
}
```

## Event handler styles

Lumen does not force a handler style — any standard approach works. The framework's only
job is to keep `this` correct and clean up on unmount (that's `listen` + `signal`). Pick
whichever your team prefers. Three common ones, with trade-offs:

**1. Auto-bound arrow field** — the handler is a class field; reference it directly.
```js
onMount() { this.listen(this.ui.name, 'input', this.onNameInput); }
onNameInput = () => this.props.model.set('name', this.ui.name.value);
```
No inline arrow, no `bind`, `this` always correct. Lives per-instance (not on the prototype), so it isn't overridable via `super`.

**2. Method bound once** — the `@boundMethod` idea without a decorator; bind in `onCreate`.
```js
onCreate() { this.onNameInput = this.onNameInput.bind(this); }
onMount()  { this.listen(this.ui.name, 'input', this.onNameInput); }
onNameInput() { this.props.model.set('name', this.ui.name.value); }
```
The method stays on the prototype (shared, overridable), at the cost of one bind line.

**3. Method + wiring arrow** — reference the method through a thin arrow.
```js
onMount() { this.listen(this.ui.name, 'input', () => this.onNameInput()); }
onNameInput() { this.props.model.set('name', this.ui.name.value); }
```
Method on the prototype; the arrow keeps `this`, at the cost of an inline function at the wiring site.

> Never pass a raw, unbound method reference (`this.listen(el, 'input', this.onNameInput)`) — `this` is lost inside it.

The examples use styles 1 and 3; neither is "the" way.

## Observing visibility (`observe`)

`observe()` is to `IntersectionObserver` what `listen()` is to `addEventListener`: it wires
the native observer and disconnects it automatically on `unmount()` (via `signal`). The
observer has no `signal` option of its own, so the view bridges it for you — no manual
`disconnect()` in `onUnmount`, no leak.

Use it for *viewport-driven* behavior: reveal-on-scroll, lazy-loading, infinite scroll
sentinels. It is a third trigger source alongside the model (data) and the lifecycle
(mount/unmount) — and it composes with both.

```js
class Card extends View {
  static template = '#card';
  onMount() {
    // Reveal once, the first time the card scrolls into view.
    this.observe(this.el, ([entry], io) => {
      if (!entry.isIntersecting) return;
      this.animateIn();          // or fadeIn(this.el), or this.props.model.set('seen', true)
      io.unobserve(this.el);     // one-shot: don't fire again
    }, { threshold: 0.2 });
  }
  animateIn() { return slideIn(this.el); }
}
```

The callback receives the standard `(entries, observer)` arguments, so `threshold`,
`rootMargin` and `observer.unobserve()` all work exactly as on the platform. No magic, no
global document scanner — each view observes only what it asks to. See the
[live example](../../examples/observe/).

## More lifecycle-bound helpers

`observe` is one of a family: native subscriptions that have no `signal` of their own, bridged
to the view's mounted lifetime so they clean up on `unmount()` with no bookkeeping. Call them
in `onMount()`.

- **`onResize(target, callback, options?)`** — a `ResizeObserver`, disconnected on unmount.
  Returns the observer.
- **`onMedia(query, callback)`** — a `matchMedia` listener for breakpoints or
  `prefers-color-scheme`. Returns the `MediaQueryList`, so you can read `.matches` for the
  initial state. The listener detaches on unmount.
- **`interval(callback, ms)`** — a `setInterval` that clears itself on unmount, so a polling
  timer never outlives the view. Returns the timer id.

```js
onMount() {
  // re-layout when the element resizes
  this.onResize(this.el, ([entry]) => this.relayout(entry.contentRect));

  // react to a breakpoint, seeded with the current state
  const wide = this.onMedia('(min-width: 60rem)', (e) => this.setWide(e.matches));
  this.setWide(wide.matches);

  // poll while mounted; the timer is cleared automatically on unmount
  this.interval(() => this.refresh(), 5000);
}
```

Same guarantee as `listen`/`observe`: no manual `clearInterval`/`disconnect`, no leak.

## Regions (layouts)

Declare `static regions` — a map of region name → the `data-ref` of its slot — and a
`Region` is created for each as `this.regions.<name>`. They are emptied automatically on
`unmount()`, so **nested layouts tear down in cascade**.

```html
<template id="app-layout">
  <div class="app">
    <header data-ref="header"></header>
    <aside  data-ref="sidebar"></aside>
    <main   data-ref="main"></main>
  </div>
</template>
```

```js
class AppLayout extends View {
  static template = '#app-layout';
  static regions = { header: 'header', sidebar: 'sidebar', main: 'main' };
  onMount() {
    this.regions.header.show(new NavBar());
    this.regions.sidebar.show(new Menu());
    this.regions.main.show(new Dashboard());   // Dashboard can declare its OWN regions
  }
}
```

A view shown in a region can itself have regions, all the way down. When `AppLayout`
unmounts, it empties its regions → each shown view unmounts → that view empties *its*
regions → and so on. You write no teardown code.

> `View` (content) vs `Region` (a slot that swaps which view is shown). A layout is a
> View whose slots are Regions filled with other Views. See [region](region.md).

## Talking to a parent

Two patterns, both explicit:

- **Props callbacks** (simplest): pass `onRemove` in, call `this.props.onRemove(this)`.
- **Per-view events**: `this.events.emit('remove', this)`; the parent does
  `child.events.on('remove', handler, { signal: child.signal })`.

## Shared render behaviour

`animateIn()`/`animateOut()` are **empty no-op stubs** on the base `View` — they exist only as
override points, so a subclass that defines them isn't fighting a default, just filling it in.

When several views share the *same* behaviour — the same close-button wiring, a loading
skeleton, a common exit animation — don't copy it into each one. Because a view is a class,
factor the shared behaviour into a base subclass and extend it:

```js
class Dismissable extends View {
  onMount() {
    this.listen(this.ui.close, 'click', () => this.props.onDismiss?.(this)); // shared wiring
  }
  animateOut() { return fadeOut(this.el); }   // a shared default; a subclass may still override
}

class Toast  extends Dismissable { static template = '#toast'; }
class Banner extends Dismissable { static template = '#banner'; }
```

A base class earns its keep when the *body* repeats identically. Overriding `animateIn`/`animateOut`
alone isn't "sharing" — that's just the per-view hook every view already has; the real win is the
shared `onMount` wiring (and a sensible animation default) living in one place. (A subclass that
needs its own `onMount` should call `super.onMount()` to keep the inherited wiring.)

If the behaviour depends on *state*, the model exposes the intent and the view translates it:

```js
animateOut() { return this.props.model.isOverdue ? shake(this.el) : fadeOut(this.el); }
```

Keep the split clean: **derived presentational *data*** (a colour for a status, an "is overdue"
flag) lives on the model as getters — see [Model › derived data](model.md#derived-data--the-model-as-its-own-presenter);
**render *behaviour*** (animations, DOM wiring) lives on the view, shared via a base class.

## Design notes

- `build()` runs `render()`/`refs()` *after* the subclass is fully constructed (it is called by `mount`, not the constructor), so overridden `render()` and `onCreate()` can safely use subclass fields — no constructor field-ordering footgun.
- `unmount()` recreates a fresh `AbortController` at the end, so a view can be unmounted and mounted again; listeners rebind in `onMount()`.
- Composition is explicit: `addChild` mounts and tracks; `unmount` cascades to children. There is no hidden parent/child registry.


---

<!-- docs/en/model.md -->

# Model

Observable data for a single entity (a user, a todo, a setting). It pairs with
`Collection` (a list of models, module 6).

## Philosophy

- **Explicit state.** Read with `get`, write with `set`. `set` emits events; direct mutation of `model.data.x` does **not** notify — on purpose, so every notification has a visible cause. No proxies, no hidden interception.
- **Granular, not total.** A change emits `change:<key>`, so a view updates only the node that changed. There is no forced full re-render (the old framework re-rendered the whole view on any change).
- **No crashes on new keys.** Setting a key that wasn't in the initial data is fine. (The old `AbstractModel` threw a `TypeError` in this case.)
- **No-op on equal values.** `set` compares with strict `!==` and stays silent when nothing actually changed.

## Events

| Event | Payload | When |
|---|---|---|
| `change:<key>` | `{ value, previous, model }` | A specific attribute changed. |
| `change` | `{ keys, model }` | Once per `set`, listing the changed keys. |

## API

| Method | Description |
|---|---|
| `new Model(data)` | Create with initial attributes (copied, not referenced). |
| `get(key)` / `get('a.b.c')` | Read an attribute, or a nested value by dot-path (missing branch → `undefined`). |
| `has(key)` / `has('a.b.c')` | Whether the attribute **exists** (even if its value is `undefined`). Dot-path aware. |
| `set(key, value)` / `set('a.b.c', value)` / `set(patch)` | Write one attribute, a nested dot-path (immutable, creates missing branches), or merge a partial object. Returns `this`. |
| `unset(key)` / `unset('a.b.c')` | Remove an attribute (not the same as setting `undefined`). Emits `change`. No-op if absent. Returns `this`. |
| `on(event, handler, { signal? })` | Subscribe. Returns an unsubscribe function. |
| `once(event, handler, { signal? })` | Subscribe for a single emission. |
| `off(event, handler)` | Unsubscribe. |
| `isDirty(key?)` | Whether attributes differ from the last committed baseline (unsaved edits). With a `key`, checks just that attribute. |
| `changedKeys()` | The attribute names that differ from the baseline. |
| `changes()` | A `{ key: { value, baseline } }` map of every changed attribute (`{}` = clean). |
| `commit()` | Adopt the current attributes as the new clean baseline (call after a save). Returns `this`. |
| `revert(key?)` | Discard unsaved edits back to the baseline — fires `change` events. With a `key`, reverts just that attribute. Returns `this`. |
| `await validate()` | Validate the attributes against `static rules`. **Async** — resolves to errors keyed by field (`{}` = valid). |
| `await isValid()` | Whether the attributes pass validation. **Async**. |
| `clearStored()` | Remove this model's persisted entry (see [Persistence](#persistence)). In-memory data is untouched. Returns `this`. |
| `toJSON()` | A shallow copy of the attributes. |

## Example: one model, observed surgically

```js
import { Model } from 'lumenjs/model';

const profile = new Model({ name: 'Ada', color: '#2563eb' });

// A view subscribes with its signal, so this cleans up on unmount,
// and updates ONLY the node that changed.
profile.on('change:name',  ({ value }) => badge.textContent = value, { signal: view.signal });
profile.on('change:color', ({ value }) => badge.style.color = value, { signal: view.signal });

profile.set('name', 'Grace');   // fires change:name + change
profile.set('name', 'Grace');   // no-op — value unchanged, silent
profile.set({ color: '#dc2626', role: 'admin' }); // new key 'role' is fine
```

## Using a model inside a View

Subscribe in `onMount` with `this.signal`:

```js
class Badge extends View {
  static template = '#badge';
  onMount() {
    const { model } = this.props;
    const paint = () => {
      this.ui.name.textContent = model.get('name');
      this.ui.name.style.color = model.get('color');
    };
    paint();
    model.on('change', paint, { signal: this.signal }); // auto-removed on unmount
  }
}
```

## Type your data

```js
/** @type {Model<{ name: string, color: string }>} */
const profile = new Model({ name: 'Ada', color: '#2563eb' });
profile.get('name'); // string
```

## Validation

A model is the single source of truth for whether its data is valid. Declare `static rules`
and `await validate()`; the UI renders the returned errors. See the [validation guide](validate.md).

`validate()` and `isValid()` are **async** (they return Promises): a rule may be synchronous
*or* hit the server (e.g. "is this email already taken?"), and both go through the **same**
path — there is no separate async validator.

```js
import { Model, required, email } from 'lumenjs';

class User extends Model {
  static rules = { email: [required(), email()] };
}
await new User({ email: 'bad' }).validate(); // { email: ['must be a valid email'] }
```

## Nested attributes — dot-paths

API responses are rarely flat. When your JSON nests (`{ user: { address: { city } } }`),
read and write deep with a **dot-path** instead of pulling the branch out by hand:

```js
const m = new Model({ user: { name: 'Ada', address: { city: 'London' } } });

m.get('user.name');             // 'Ada'
m.get('user.address.city');     // 'London'
m.get('user.phone.work');       // undefined — a missing branch never throws
m.get('tags.0');                // array indices work too

m.set('user.address.city', 'Oslo');   // writes deep
m.set('user.contact.email', 'a@x.io'); // creates the missing `contact` branch
```

**Writes are immutable.** `set` clones every branch along the path (and creates any missing
one), so the top-level reference changes and the usual `!==` change-detection still fires —
untouched siblings keep their identity. The event is keyed to the **root** of the path:

```js
m.on('change:user', ({ value }) => render(value));  // fires for ANY edit under `user`
m.set('user.address.city', 'Oslo');                 // → change:user + change
```

So a view observes the whole branch it cares about (`change:user`) without subscribing to a
combinatorial set of deep paths. Because writes are immutable, [dirty tracking](#dirty-tracking--unsaved-edits)
works through nesting unchanged — `revert()` restores the deep value, `commit()` re-baselines it.

> Dot-paths apply to the `get(path)` / `set(path, value)` forms. Keys of a **patch object**
> (`set({ 'a.b': 1 })`) are taken **literally** — that creates a key named `'a.b'`, by design.

## Presence — `has` and `unset`

`has` answers "does this attribute exist?" — a different question from "what is its value?".
A field set to `undefined` still *exists*; a field that was never set does not:

```js
const m = new Model({ name: 'Ada', nickname: undefined });
m.has('name');      // true
m.has('nickname');  // true  — present, even though its value is undefined
m.has('age');       // false — never set
m.get('age');       // undefined  ← same value as nickname, but has() tells them apart
```

`unset` truly removes a key — unlike `set(key, undefined)`, which keeps it present. It emits
`change:<key>`/`change` like any edit, is a silent no-op if the key wasn't there, and both
are dot-path aware:

```js
m.unset('nickname');        // fires change:nickname + change
m.has('nickname');          // false
m.toJSON();                 // { name: 'Ada' } — gone
m.unset('user.address.zip'); // removes the leaf immutably, fires change:user
```

## Dirty tracking — unsaved edits

A model remembers a **baseline**: its last committed clean state. Editing makes it *dirty*;
`commit()` adopts the current values as the new baseline; `revert()` throws the edits away.
Nothing is bookkept inside `set` — dirtiness is derived by comparison, so it stays honest.

```js
const draft = new Model({ title: 'Untitled', body: '' });

draft.isDirty();            // false — matches baseline
draft.set('title', 'Lumen 1.0');
draft.isDirty();            // true
draft.isDirty('body');     // false — only `title` changed
draft.changes();           // { title: { value: 'Lumen 1.0', baseline: 'Untitled' } }

draft.revert();            // restore baseline — fires change:title, so views update surgically
draft.isDirty();           // false

// After a successful save, make the current values the new clean baseline:
await api.save(draft.toJSON());
draft.commit();            // isDirty() === false again, no events emitted
```

This is exactly what a form needs: enable the **Save** button only `while (model.isDirty())`,
wire **Discard** to `revert()`, and `commit()` once the server confirms. Because `revert()`
goes through `set`, every observing view reacts through the same `change` path as any edit.

## Persistence

Persistence is a **first-class `Model` capability**, declared like `static rules` — not a
wrapper you bolt on. Declare `static storage` and the model **loads its state on
construction** and **saves on every change**, with no extra wiring: the same `set`/`unset`
that notify views also persist.

```js
class Todos extends Model {
  static storage = 'todos';   // a key in localStorage
}

const list = new Todos({ items: [] });
list.set('items', [...list.get('items'), 'Buy milk']);  // saved automatically
// next page load: new Todos({ items: [] }) comes back with the saved items
```

A **string** is a `localStorage` key. For full control, use the object form:

```js
class Session extends Model {
  static storage = {
    key: (data) => `user:${data.id}`,  // derive a per-entity key from the data
    area: sessionStorage,              // default is localStorage; this is tab-scoped
    serialize: JSON.stringify,         // customise if you need to
    deserialize: JSON.parse,
  };
}
```

- **Loaded state is the clean baseline.** A freshly-hydrated model reports `isDirty() === false`;
  persisted values win over the initial defaults you pass in (defaults fill only missing keys).
- **Safe when storage is absent.** Under SSR/headless (no Web Storage) the model works normally
  and simply doesn't persist — it never throws. Write errors (full quota, private mode) are
  swallowed too, so persistence can never break the app.
- **`clearStored()`** removes the persisted entry; the in-memory attributes are untouched.

## Derived data — the model as its own presenter

API JSON arrives flat (`{ status: 'done', due: 1699… }`), but views need *presentational*
values that aren't in it: a colour for a status, an "is overdue" flag, a human label. Don't
store those and don't recompute them in every view — **a `Model` is a real class, so express
them once as getters**. Every view that renders the model reuses them:

```js
class Task extends Model {
  get color()     { return { todo: '#9ca3af', doing: '#2563eb', done: '#16a34a' }[this.get('status')]; }
  get isOverdue() { return !this.get('done') && this.get('due') < Date.now(); }
  get label()     { return this.get('title').trim() || '(untitled)'; }
}
```

```js
// the view reads the derived value — it never re-implements the colour map:
const paint = () => {
  this.el.style.setProperty('--accent', model.color);
  this.el.classList.toggle('is-overdue', model.isOverdue);
};
paint();
model.on('change', paint, { signal: this.signal });
```

This is the **presenter / view-model** pattern: the layer that turns raw data into
render-ready values. In Lumen that layer *is* the `Model` subclass — no separate decorator
object, because "what colour a `done` task is" belongs to the data's meaning.

- **Reactivity stays explicit.** A getter emits no `change:color` of its own; it doesn't need
  to. `color` derives from `status`, so the view listens to the *source* key (`change:status`,
  or `change`) and recomputes. The dependency is written in the handler, not hidden in a tracker.
- **Getters aren't serialized.** `toJSON()` spreads `data` only, so derived values never leak
  into a save payload. If you want a snapshot *with* them, add your own `toView()`.
- **Position is not derived data — it belongs to the `Collection`.** A model's index depends on
  the list, not on itself, so don't put it on the model (it would go stale on insert/remove).
  Read it from the collection (`collection.models.indexOf(model)`, or the `index` on `add`/`remove`
  events) or pass it down via `CollectionView`'s `childProps(model)`.
- **Shared *render* behaviour (e.g. the same enter/exit animation)** is the View's job, not the
  model's — factor it into a base `View` subclass. See [View › shared render behaviour](view.md#shared-render-behaviour).

## Design notes

- Notification carries `previous` and `value`, so observers can diff without keeping their own copy.
- `change` fires once per `set`, even for a multi-key patch, so a "something changed, recompute" listener runs a single time.
- Built directly on `EventEmitter`; subscriptions accept an `AbortSignal`, which is what makes the View integration leak-free.


---

<!-- docs/en/collection.md -->

# Collection

An ordered list of `Model`s with structural events. It pairs with `CollectionView`
(module 7), which renders one view per model.

## Philosophy

- **Mutations are announced.** `add`, `remove` and `reset` change the list and emit an event.
- **Queries never mutate.** `find`, `where`, `filter`, `map` and `sort` return results and leave the collection's contents and order untouched. (The old framework's `find`/`where`/`sort` *overwrote* the visible list as a side effect of querying — this fixes that trap.)
- **Changes bubble.** A model's `change` re-emits as a collection-level `change` — react to "anything in the list changed" without a sub-view per row. Subscriptions are managed for you (added on `add`/`reset`, dropped on `remove`/`reset`), so removed models leak nothing. For per-row UI, prefer a `CollectionView` — each model gets its own view subscribed to its own model, keeping reactions granular.

## Events

| Event | Payload | When |
|---|---|---|
| `add` | `{ model, index, collection }` | A model was appended. |
| `remove` | `{ model, index, collection }` | A model was removed. |
| `reset` | `{ models, collection }` | The whole list was replaced. |
| `change` | `{ model, keys, collection }` | A model in the list changed (bubbled). `keys` are the changed attributes. |

## API

| Member | Description |
|---|---|
| `new Collection(items?, Model?)` | Wrap plain data with `Model` (a subclass), or pass `Model` instances. |
| `length` / `at(i)` / `get(id)` | Size, index access, **O(1)** lookup by `id` attribute (indexed). |
| `add(item)` | Append (wrapping data). Emits `add`. Returns the model. |
| `remove(model)` | Remove. Emits `remove`. No-op if absent. |
| `reset(items?)` | Replace all. Emits `reset`. |
| `find(fn)` | First match, or `undefined`. |
| `where(attrs)` | New array of models matching all attributes. |
| `filter(fn)` / `map(fn)` / `forEach(fn)` | Standard, non-mutating. |
| `sort(compare)` | A **sorted copy** — does not reorder the collection. |
| `isDirty()` / `changed()` | Whether any model has unsaved edits / the array of models that do. |
| `commitAll()` / `revertAll()` | `commit()` / `revert()` every model (batch save / discard). Returns `this`. |
| `on/once/off(event, handler, { signal? })` | Subscribe / unsubscribe. |
| `toJSON()` | Array of each model's data. |
| `for…of` | Iterates the models. |

## Example

```js
import { Collection } from 'lumenjs/collection';
import { Model } from 'lumenjs/model';

class Todo extends Model {}

const todos = new Collection([
  { id: 1, text: 'a', done: true },
  { id: 2, text: 'b', done: false },
], Todo);

todos.on('add',    ({ model }) => console.log('added', model.get('text')));
todos.on('remove', ({ model }) => console.log('removed', model.get('text')));

// `change` bubbles from any model — handy for a "Save all" button or a live total:
todos.on('change', ({ model, keys }) => console.log(model.get('id'), 'changed', keys));
todos.at(0).set('done', false);                     // → change { model: a, keys: ['done'] }

todos.add({ id: 3, text: 'c', done: false });

// Queries return results WITHOUT changing the collection's order:
todos.where({ done: false });                       // [model b, model c]
todos.sort((a, b) => a.get('text') < b.get('text') ? -1 : 1); // a sorted COPY
todos.map((m) => m.get('text'));                    // still ['a','b','c'] — unchanged
```

## Editable list — aggregate dirty tracking

Building on each model's [dirty tracking](model.md#dirty-tracking--unsaved-edits) and the bubbled
`change`, the collection answers "does the whole list have unsaved edits?" and saves/discards in
batch — exactly what an editable table needs:

```js
todos.isDirty();        // true if ANY model has unsaved edits
todos.changed();        // the models that changed — for per-row markers

// One handler keeps the Save-all button honest as the user edits or discards:
todos.on('change', () => saveAllBtn.disabled = !todos.isDirty());

todos.revertAll();      // discard — each revert bubbles change, so the button updates
await api.saveAll(todos.toJSON());
todos.commitAll();      // re-baseline the whole list — isDirty() is false again
```

`revertAll()` reverts through each model's `set`, so it bubbles `change` and views react;
`commitAll()` emits nothing (no observable value changed) — recompute right after the call.

## Type it

```js
/** @typedef {{ id: number, text: string, done: boolean }} TodoData */
/** @type {Collection<TodoData, Todo>} */
const todos = new Collection([], Todo);
```

## Design notes

- `sort` returns a copy rather than sorting in place, so a query can never reorder what observers see. To present a different order, render from the returned array (or, later, feed it to a `CollectionView`).
- Built on `EventEmitter`; subscriptions accept an `AbortSignal`, so a view can subscribe with `this.signal` and clean up on unmount.
- `add`/`remove` carry the `index`, which `CollectionView` will use to insert or remove a single child view without rebuilding the list.
- `change` bubbling uses one shared handler reference subscribed to each model, so the collection drops a removed model's subscription with a single `off` — no per-model bookkeeping, no leaks.
- `get(id)` is **O(1)**: the collection keeps an `id → model` index in sync with `add`/`remove`/`reset` (first-wins, matching `find` order) and rebuilds it if a model changes its own `id`. Models without an `id` simply aren't indexed.


---

<!-- docs/en/collection-view.md -->

# CollectionView

Renders one child `View` per model in a `Collection`, and keeps them in sync through
**keyed reconciliation**.

> **A `Collection` is best used with a `CollectionView`.** The collection is the data
> layer — it holds models and announces structural changes. The `CollectionView` is what
> turns that into UI: it maps each model to a view and reacts to `add`/`remove`/`reset`
> by mounting or unmounting only the affected child. Using a collection without a
> `CollectionView` means re-rendering lists by hand; pairing them is the intended path.

## Philosophy

- **Incremental, not rebuilt.** On `add`, one child mounts (with its `animateIn`); on `remove`, one child unmounts (its `animateOut` plays first); siblings are never touched. (The old framework recreated every child on each render — and broke on the second pass.)
- **Keyed.** A `Map` from model → child view is the index, so the right child is found in O(1) for removal.
- **Composed from the parts you know.** It is a `View` subclass; children are tracked via `addChild`, so unmounting the list cascades to every child and cleans up.

## Configure with statics

| Static | Required | Description |
|---|---|---|
| `childView` | yes | The `View` subclass to instantiate per model. |
| `template` | no | A `<template>`; children mount into the `container` ref (or the root). |
| `container` | no | The `data-ref` name of the element children mount into. Default: the root element. |
| `tag` | no | When there is no `template`, the tag of the auto-created root. Default `'div'`. |

Pass the collection as a prop: `new TodoList({ collection })`. Each child view receives
`{ model }` plus anything you return from `childProps(model)`.

## Example

```html
<template id="todo-list">
  <div>
    <form data-ref="form"><input data-ref="input" placeholder="New todo…" /></form>
    <ul data-ref="items"></ul>
  </div>
</template>
<template id="todo-item">
  <li><label><input type="checkbox" data-ref="check"> <span data-ref="text"></span></label>
      <button data-ref="remove">×</button></li>
</template>
```

```js
import { Collection, Model, View, CollectionView, slideIn, slideOut } from 'lumenjs';

class Todo extends Model {}

class TodoItem extends View {
  static template = '#todo-item';
  onMount() {
    const { model } = this.props;
    this.ui.text.textContent = model.get('text');
    this.ui.check.checked = model.get('done');
    this.listen(this.ui.check, 'change', this.toggle);
    this.listen(this.ui.remove, 'click', this.remove);
  }
  toggle = () => this.props.model.set('done', this.ui.check.checked);
  remove = () => this.props.onRemove();           // provided by the list's childProps
  animateIn()  { return slideIn(this.el); }
  animateOut() { return slideOut(this.el); }
}

class TodoList extends CollectionView {
  static template  = '#todo-list';
  static childView = TodoItem;
  static container = 'items';                      // children mount into ui.items
  onMount() {
    super.onMount();                               // sets up reconciliation
    this.listen(this.ui.form, 'submit', this.onSubmit);
  }
  onSubmit = (e) => {
    e.preventDefault();
    const text = this.ui.input.value.trim();
    if (text) this.collection.add({ text, done: false });
    this.ui.input.value = '';
  };
  childProps(model) {
    return { onRemove: () => this.collection.remove(model) };
  }
}

const todos = new Collection([], Todo);
new TodoList({ collection: todos }).mount(document.body);
```

Adding a todo appends a model → the list mounts one new `TodoItem` (sliding in). Removing
calls `collection.remove` → the list unmounts that one child (sliding out first). Nothing
else re-renders.

## Design notes

- `CollectionView` overrides `View.render()` to clone `template` or create a `tag` element; everything else (lifecycle, cascade unmount, signal cleanup) is inherited.
- Subscriptions to the collection use `this.signal`, so they are removed when the list unmounts.
- `childProps(model)` is the seam for passing per-child callbacks or shared dependencies without coupling the child to the collection.
- The collection currently appends on `add`, so children append in order. Reordering is a query (`sort` returns a copy) and does not emit, so the rendered order follows insertion; render from a sorted array if you need a different order.


---

<!-- docs/en/region.md -->

# Region

Manages a single DOM slot that holds at most one `View` at a time, with an animated swap.

## Philosophy

- **Ordered transitions.** `show(view)` plays the current view's `animateOut()` to completion, unmounts it, then mounts the new view and plays its `animateIn()`. Out, then in — predictable.
- **What Custom Elements can't do.** Because a `View` is a plain class, the region controls removal timing, so the leave animation always finishes before the node goes. A Custom Element's `disconnectedCallback` fires only *after* removal.
- **The base for navigation.** Point a region at an "outlet" element and call `show()` as routes change. The router (module 9) is built on this.

## API

| Member | Description |
|---|---|
| `new Region(target, { transition? })` | `target` is an element or a CSS selector for the slot. `transition: true` opts into native View Transitions. |
| `el` | The slot element. |
| `current` | The view currently shown, or `null`. |
| `show(view, { transition? })` | Animated swap. Returns `Promise<view>` (resolves after the entrance). No-op if already current. |
| `empty()` | Unmount whatever is shown (animating out first). Returns `Promise<void>`. |

## Example

```js
import { Region, View, fadeIn, fadeOut } from 'lumenjs';

class Screen extends View {
  static template = '#screen';
  onMount()   { this.ui.title.textContent = this.props.title; }
  onUnmount() { console.log('left', this.props.title); }
  animateIn()  { return fadeIn(this.el); }
  animateOut() { return fadeOut(this.el); }
}

const main = new Region('#outlet');
await main.show(new Screen({ title: 'Home' }));
await main.show(new Screen({ title: 'About' })); // Home fades out, then About fades in
```

## Native View Transitions (opt-in)

By default a swap is two JS animations: the old view's `animateOut()`, then the new view's
`animateIn()`. Opt into the native [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)
and the browser does the work instead — a crossfade out of the box, and *shared-element*
morphs for anything you tag with `view-transition-name`.

```js
const main = new Region('#outlet', { transition: true });   // default for this region
await main.show(new Home());
await main.show(new About());     // browser crossfades; views' animateIn/animateOut are skipped

// or per-swap:
await main.show(new About(), { transition: true });
```

This is **pure progressive enhancement**:

- Off by default — existing regions behave exactly as before.
- On browsers without `document.startViewTransition`, it **falls back** to the normal
  JS-animated swap. Nothing breaks; you just don't get the native crossfade.
- Inside a transition the views' `animateIn`/`animateOut` are skipped (the browser plays the
  visual), so you never double-animate. The lifecycle (`onMount`/`onUnmount`, cascade cleanup,
  `signal`) runs exactly as always.

Shared-element morph: give the same `view-transition-name` to an element in the outgoing and
incoming views (in your CSS) and the browser animates it from one position to the other.

> Same-document View Transitions are Baseline (widely supported). Cross-document transitions
> are not yet — Lumen only uses the same-document API, which is all an SPA needs.

## Named regions in a layout

A layout usually has several regions (header, sidebar, main, modal). You don't create them
by hand — declare them on a `View` with `static regions` and each is created and emptied
for you, cascading through nested layouts. See [View → Regions (layouts)](view.md). The
example below is a nested layout built that way.

## Design notes

- `show` awaits `unmount()` (which awaits `animateOut`) before mounting the next view, so transitions never overlap. For a crossfade, either enable `{ transition: true }` (native) or mount into two stacked regions.
- A region holds exactly one view; for lists use `CollectionView`.
- `show` returning the view (after `animateIn`) lets callers `await` a completed transition — handy for sequencing navigation.


---

<!-- docs/en/router.md -->

# Router

A small client-side router built on native `hashchange`/`popstate` events. It pairs with
`Region` to swap screens as the URL changes.

## Philosophy

- **Events, not polling.** It listens to the browser's own navigation events. (The old framework polled the URL every 50 ms with `setInterval` — wasteful and laggy.)
- **No singleton.** Create a router, register routes, `start()`.
- **Plain handlers.** A route handler is just a function called with the matched params; `navigate` resolves immediately (even in `history` mode, where `pushState` doesn't fire `popstate`) — fixing the old bug where navigation didn't trigger the route.

## API

| Member | Description |
|---|---|
| `new Router({ mode?, root? })` | `mode` is `'hash'` (default) or `'history'`; `root` is the base path for history mode. |
| `add(pattern, handler)` | Register a route. `:name` segments become params. First match wins. |
| `notFound(handler)` | Handler when nothing matches (receives the path). |
| `start()` / `stop()` | Begin / end listening. `start()` also resolves the current URL. |
| `navigate(path)` | Change the URL and resolve the matching route. |
| `current()` | The current normalized path. |

## Patterns

| Pattern | Matches | Params |
|---|---|---|
| `/` | `/` | `{}` |
| `/about` | `/about` | `{}` |
| `/users/:id` | `/users/42` | `{ id: '42' }` |
| `/posts/:cat/:slug` | `/posts/js/raw` | `{ cat: 'js', slug: 'raw' }` |

## Example (with a Region)

```js
import { Router, Region, View } from 'lumenjs';

const main = new Region('#outlet');

const router = new Router(); // hash mode
router
  .add('/',          () => main.show(new HomeView()))
  .add('/about',     () => main.show(new AboutView()))
  .add('/users/:id', ({ id }) => main.show(new UserView({ id })))
  .notFound(() => main.show(new NotFoundView()))
  .start();

// later, in code:
router.navigate('/users/42');
// or in markup (hash mode): <a href="#/users/42">User 42</a>
```

Each route resolves to a single `region.show(...)`, so the previous screen animates out
and the next animates in — navigation gets transitions for free.

## Design notes

- `hash` mode needs no server configuration and is the default. `history` mode gives clean URLs but needs the server to serve your app for unknown paths.
- `navigate` in `history` mode calls `_resolve()` itself because `pushState` does not emit `popstate`.
- Handlers receive only params; keep `this` via an arrow or a bound method if a handler is a class method (see [View → event handler styles](view.md)).


---

<!-- docs/en/http.md -->

# Http

A small, transparent `fetch` wrapper (phase 2). It replaces the old framework's
`requester`.

## Philosophy

- **Thin over `fetch`.** Sensible defaults — JSON encode/decode and "throw on non-2xx" — and nothing else by default. Interceptors and retry are **opt-in and explicit**, never magic: nothing happens unless you ask for it.
- **Cancellable, lifecycle-friendly.** Pass an `AbortSignal` (e.g. a view's `this.signal`) and the request is cancelled automatically when the view unmounts.
- **Errors carry data.** A non-2xx response throws `HttpError` with the status, the `Response`, and the already-parsed body.

## API

| Member | Description |
|---|---|
| `new Http({ baseURL?, headers?, signal?, timeout?, retry?, onRequest?, onResponse? })` | Configure a client. `timeout` (ms) and `retry` are defaults for every request. `onRequest`/`onResponse` are interceptors. |
| `get(path, options?)` | GET. Returns the parsed body. |
| `post(path, body?, options?)` | POST (plain objects are JSON-encoded). |
| `put` / `patch(path, body?, options?)` | PUT / PATCH. |
| `delete(path, options?)` | DELETE. |
| `request(method, path, options?)` | The primitive the rest build on. |

### `RequestOptions`

| Option | Description |
|---|---|
| `body` | Plain object → JSON; `string`/`FormData` sent as-is. |
| `headers` | Extra headers for this request. |
| `signal` | `AbortSignal` to cancel (pass `view.signal`). |
| `query` | Object of query params appended to the URL. |
| `timeout` | Abort after N ms. Composed with `signal` via `AbortSignal.any`; overrides the client default. |
| `retry` | Retry transient failures. A number is shorthand for `{ retries: n }`; overrides the client default. |

### `HttpError`

`status`, `response`, and `body` (parsed). Thrown on any non-2xx.

## Example

```js
import { Http, HttpError } from 'lumenjs/http';

const api = new Http({ baseURL: 'https://api.example.com', headers: { Authorization: 'Bearer …' } });

const users = await api.get('/users', { query: { active: true }, signal: this.signal });
await api.post('/users', { name: 'Ada' });

try {
  await api.get('/missing');
} catch (e) {
  if (e instanceof HttpError) console.log(e.status, e.body);
}
```

## With Collection + CollectionView

The natural pattern: fetch JSON, drop it into a `Collection`, let a `CollectionView`
render it.

```js
class UserList extends CollectionView {
  static childView = UserItem;
  async onMount() {
    super.onMount();
    try {
      const data = await api.get('/users', { signal: this.signal });
      this.collection.reset(data);            // CollectionView reconciles
    } catch (e) {
      if (e.name !== 'AbortError') this.showError(e);
    }
  }
}
```

Because the request uses `this.signal`, navigating away (which unmounts the view) cancels
an in-flight fetch — no "setState on unmounted view" class of bug.

## Timeouts

Pass `timeout` (ms) to abort a slow request — built on the platform's `AbortSignal.timeout()`,
combined with your `signal` via `AbortSignal.any()`, so **either** cancelling the view **or**
the timeout firing aborts the request. Set a default on the client, override per request:

```js
const api = new Http({ baseURL: 'https://api.example.com', timeout: 8000 });

await api.get('/slow', { timeout: 2000, signal: this.signal }); // per-request override
```

A timeout rejects with a `TimeoutError` (not an `AbortError`), so you can tell "took too long"
apart from "user navigated away":

```js
try {
  await api.get('/slow', { timeout: 2000, signal: this.signal });
} catch (e) {
  if (e.name === 'TimeoutError') this.showRetry();      // it timed out
  else if (e.name !== 'AbortError') this.showError(e);  // real error (ignore unmount aborts)
}
```

## Interceptors

Two optional hooks let you touch every request without wrapping each call site. They live
on the client, run on the primitive `request`, and stay explicit — you pass the functions, so
there is nothing hidden.

- **`onRequest(ctx)`** runs before each attempt (and again on every retry). The context is
  `{ method, url, headers, init }`, all mutable — the canonical use is injecting auth.
- **`onResponse(res, ctx)`** runs after each response, before status handling. Observe it, or
  return a **replacement `Response`** to continue with that one (e.g. after refreshing a token).

```js
const api = new Http({
  baseURL: 'https://api.example.com',
  onRequest: (ctx) => { ctx.headers.Authorization = `Bearer ${getToken()}`; },
  onResponse: (res) => { if (res.status === 401) signOut(); },
});
```

Both may be `async`, so a token refresh can `await` before the request proceeds.

## Retry

Pass `retry` to retry transient failures with exponential backoff. A number is shorthand
for `{ retries: n }`; the full form is `{ retries, delay = 300, factor = 2, when }`. Set a
default on the client and override per request:

```js
const api = new Http({ baseURL: 'https://api.example.com', retry: 2 });

await api.get('/flaky', { retry: { retries: 3, delay: 500 } }); // per-request override
```

- Backoff between attempts is `delay * factor ** attempt` — `300, 600, 1200…` by default.
- The default `when` retries **network errors** and **`5xx`/`429`** responses, and never other
  `4xx` (a `404` won't fix itself). Pass your own `when({ error?, response?, attempt })` to change that.
- The wait is **cancellable**: if the request's `signal` aborts mid-backoff, it stops at once.
- **Aborts and timeouts are never retried** — an `AbortSignal` is single-use, so the retry would
  fail instantly anyway.

## Design notes

- Bodies are parsed by content type: JSON when the response is JSON, text otherwise, `null` for `204`/empty.
- A cancelled request rejects with an `AbortError` (the platform's behavior) — check `e.name === 'AbortError'` to ignore it. A timeout rejects with a `TimeoutError`.
- No global instance: create one `Http` per API/base URL and pass it where needed.


---

<!-- docs/en/resource.md -->

# Resource

Observable **server state** — the stale-while-revalidate (SWR) pattern, kept small and
transparent. It's the piece every data-loading view otherwise re-implements by hand:
a cache, request dedupe, background revalidation, and mutations.

## Philosophy

- **A peer, not a wrapper.** `Resource` sits beside `Model`/`Collection` as an observable state primitive. It does **not** patch `Http`; it *consumes* a plain `fetcher` (often `(key) => http.get(key)`), so the transport stays a transport and the cache stays a cache.
- **Stale-while-revalidate.** A `read` returns whatever is cached **instantly**, then revalidates in the background — the UI never blocks on a network round-trip it already has an answer for.
- **Explicit sharing, no singleton.** One `Resource` instance is a cache you create and pass around — exactly like an `EventEmitter` bus or an `Http` client. Two views that share the instance share the cache and dedupe each other's requests. Nothing is global.
- **Errors are state, not exceptions.** A failed fetch lands in the key's `error`; background revalidation never throws. For imperative "fetch and throw on error", call `Http` directly.

## State

Every key exposes a `ResourceState`:

| Field | Meaning |
|---|---|
| `data` | The last successfully fetched value (`undefined` until the first success). |
| `error` | The last fetch error (`undefined` when the latest fetch succeeded). |
| `isLoading` | **First** load: no data yet *and* a fetch is in flight → render a skeleton. |
| `isValidating` | **Any** fetch in flight, including a background revalidation over existing data → render a subtle spinner. |

## API

| Member | Description |
|---|---|
| `new Resource({ fetcher, dedupe? })` | `fetcher(key)` loads the data and receives the original (un-serialized) key. `dedupe` (ms, default `2000`) is the window in which a `read` of a fresh key skips refetching. |
| `get(key)` | The current cached `ResourceState` **without** triggering a fetch. |
| `read(key, handler?, { signal? })` | Return the cached snapshot now, trigger a background fetch if missing/stale, and (with `handler`) subscribe to later changes. The main entry in `onMount()`. |
| `subscribe(key, handler, { signal? })` | Subscribe to a key's changes **without** triggering a fetch. Returns an unsubscribe function. |
| `revalidate(key)` | Force a refetch (deduped). Never rejects — errors land in state. Resolves when the fetch settles. |
| `mutate(key, data?, options?)` | Update the cache, then (by default) revalidate. See [Mutations](#mutations). Resolves to the freshest data. |
| `clear(key?)` | Drop one key, or the whole cache with no argument. Subscribers stay subscribed and get a reset (empty) state. |

Keys are strings, or anything JSON-serializable (e.g. `['users', id]`) — keep array parts in
a stable order. In-flight requests are **always** deduped, regardless of the `dedupe` window.

## Example

Create one resource for the app and pass it to views. A view reads in `onMount`, binds the
subscription to its `signal`, and renders each state it receives:

```js
import { Http } from 'lumenjs/http';
import { Resource } from 'lumenjs/resource';

const http = new Http({ baseURL: 'https://api.example.com' });
const resource = new Resource({ fetcher: (key) => http.get(key) });

class UserCard extends View {
  static template = '#user-card';
  onMount() {
    const state = this.props.resource.read('/users/1', (s) => this.render(s), { signal: this.signal });
    this.render(state); // the cached snapshot now; the handler fires on every later change
  }
  render({ data, error, isLoading }) {
    if (isLoading) return this.showSkeleton();
    if (error) return this.showError(error);
    this.ui.name.textContent = data.name;
  }
}

new UserCard({ resource }).mount(document.querySelector('#app'));
```

Because the subscription is bound to `this.signal`, unmounting the view detaches it
automatically — no leak, no "update on unmounted view".

## Mutations

`mutate` is one method with four shapes, from simplest to richest:

```js
resource.mutate('/users/1');                       // invalidate → refetch
resource.mutate('/users/1', { name: 'Ada' });      // write a value into the cache
resource.mutate('/users/1', (prev) => ({ ...prev, seen: true })); // derive from current
```

The fourth shape is an **optimistic update with rollback**: pass the server write itself as a
`Promise`, show `optimisticData` immediately, and let `Resource` reconcile — on success it
writes the resolved result (then revalidates); on failure it restores the previous data.

```js
const patch = { name: 'Ada Lovelace' };
await resource.mutate('/users/1', http.patch('/users/1', patch), {
  optimisticData: { ...currentUser, ...patch },
});
// UI shows the new name instantly; if the PATCH rejects, it rolls back to currentUser.
```

| Option | Default | Meaning |
|---|---|---|
| `revalidate` | `true` | Refetch from the server after the local write. |
| `optimisticData` | — | Value to show immediately while a passed `Promise` resolves. |
| `rollbackOnError` | `true` | Restore the previous data if the `Promise` rejects. |

A rejected optimistic `mutate` re-throws after rolling back, so you can still `catch` it to
show a toast.

## Design notes

- **Dedupe vs. revalidate window.** Two views mounting at once share a single in-flight request (in-flight dedupe). A `read` within `dedupe` ms of the last successful fetch skips the network entirely; past that window it serves cached data **and** revalidates.
- **`isLoading` vs. `isValidating`.** Use `isLoading` to decide *skeleton vs. content* (first paint) and `isValidating` for a *background refresh* indicator. They overlap only on the very first fetch.
- **`clear` keeps subscriptions.** On logout, `resource.clear()` wipes every entry and pushes an empty state to live views without unsubscribing them — the views simply re-render as "loading/empty".
- **Pair with `Http`.** The natural `fetcher` is `(key) => http.get(key)`; retries, timeouts, and auth interceptors all live in `Http`, so `Resource` inherits them for free.
- **No global instance.** Create one `Resource` per cache scope and pass it where needed (props, a shared module). Sharing is always explicit.


---

<!-- docs/en/i18n.md -->

# I18n

Minimal internationalization (phase 2). Replaces the old framework's `translate`.

## Philosophy

- **Plain dictionaries.** You hold message trees per locale; `t(key)` reads them. No extraction step, no compilation.
- **Reactive, lifecycle-friendly.** `setLocale` emits `change`; views subscribe with `this.signal` and re-render their text, cleaning up on unmount.
- **Graceful fallback.** Missing key → fallback locale → the key itself. Never throws.

## API

| Member | Description |
|---|---|
| `new I18n({ locale?, fallback?, messages? })` | `messages` is `{ en: {...}, es: {...} }`. |
| `t(key, params?)` | Translate. Dotted keys (`'home.title'`) and `{placeholders}`. |
| `setLocale(locale)` | Switch locale; emits `change` if it changed. |
| `onChange(handler, { signal? })` | Subscribe to locale changes. Returns unsubscribe. |
| `locale` / `fallback` / `messages` | The current state. |

## Example

```js
import { I18n } from 'lumenjs/i18n';

const i18n = new I18n({
  locale: 'en',
  messages: {
    en: { greeting: 'Hello, {name}', home: { title: 'Home' } },
    es: { greeting: 'Hola, {name}',  home: { title: 'Inicio' } },
  },
});

i18n.t('greeting', { name: 'Ada' }); // "Hello, Ada"
i18n.setLocale('es');
i18n.t('home.title');                // "Inicio"
i18n.t('missing.key');               // "missing.key" (fallback to the key)
```

## Inside a View

Render text in `onMount`, and re-render on locale change via `this.signal`:

```js
class Header extends View {
  static template = '#header';
  onMount() {
    this.paint();
    this.props.i18n.onChange(this.paint, { signal: this.signal }); // auto-removed on unmount
  }
  paint = () => {
    this.ui.title.textContent = this.props.i18n.t('home.title');
  };
}
```

## Design notes

- Built on `EventEmitter`; the `change` subscription accepts an `AbortSignal`, so it integrates with `View` cleanup.
- No global instance — create one `I18n` and pass it (props) or import a shared one from your app.
- Interpolation only replaces `{name}` tokens; unknown placeholders are left intact (easy to spot missing params).


---

<!-- docs/en/validate.md -->

# Validation

One source of truth: define the rules on the `Model`, call `model.validate()`, and the UI
renders the returned errors. (Validation is a domain concern — the model knows what valid
data is — unlike persistence, which lives elsewhere.)

## Philosophy

- **Rules live with the model.** `static rules` on the model; the UI doesn't redefine them.
- **`validate()` returns; nothing is magic.** It does not block `set` or auto-render — you `await` it when it makes sense (on submit, on blur, on input) and render the result.
- **Composable rules, sync or async.** Each rule is `(value, data) => string | null | Promise<string | null>`. A server-side check (e.g. "email already taken?") is just a rule that returns a Promise — same path, no separate async validator. Bring your own.

## Defining rules on a model

```js
import { Model, required, email, minLength, match } from 'lumenjs';

class Signup extends Model {
  static rules = {
    email:    [required(), email()],
    password: [required(), minLength(8)],
    confirm:  [match('password', 'passwords must match')],
  };
}

const user = new Signup({ email: 'bad', password: '123', confirm: '' });
await user.validate();  // { email: ['must be a valid email'], password: ['must be at least 8 characters'], confirm: ['passwords must match'] }
await user.isValid();   // false
```

`validate()` resolves to errors keyed by field — an empty object means valid. It is **async**
so a rule can hit the server; sync-only rules just resolve on the next microtask. Override
`validate()` for custom cross-field logic.

## Built-in rules

| Rule | Fails when |
|---|---|
| `required(msg?)` | value is empty/null/undefined |
| `minLength(n, msg?)` / `maxLength(n, msg?)` | string length out of range |
| `pattern(re, msg?)` | doesn't match the regex |
| `email(msg?)` | not an email |
| `min(n, msg?)` / `max(n, msg?)` | number out of range |
| `match(field, msg?)` | not equal to another field |
| custom: `(value, data) => msg \| null` | your logic returns a message |
| async: `(value, data) => Promise<msg \| null>` | an awaited check (e.g. a server lookup) returns a message |

### An async rule

A rule that returns a Promise is awaited like any other — no special registration:

```js
const emailAvailable = (msg = 'is already taken') => async (value) => {
  if (!value) return null;                       // let `required()` own emptiness
  const { taken } = await api.get('/check-email', { query: { value } });
  return taken ? msg : null;
};

class Signup extends Model {
  static rules = { email: [required(), email(), emailAvailable()] };
}

await new Signup({ email: 'ada@x.io' }).validate(); // awaits the server check
```

## Rendering errors in a View

Set the form fields into the model, validate, and paint the errors into per-field slots:

```js
class SignupForm extends View {
  static template = '#signup';
  onMount() { this.listen(this.ui.form, 'submit', this.submit); }
  submit = async (e) => {
    e.preventDefault();
    this.props.model.set({
      email: this.ui.email.value,
      password: this.ui.password.value,
      confirm: this.ui.confirm.value,
    });
    const errors = await this.props.model.validate();
    this.showErrors(errors);
    if (Object.keys(errors).length === 0) this.props.onValid();
  };
  showErrors(errors) {
    for (const field of ['email', 'password', 'confirm']) {
      this.ui[field + 'Err'].textContent = errors[field]?.[0] ?? '';
    }
  }
}
```

The model is the single source of truth; the view only renders what `validate()` returns.

## Using native constraints too (optional)

For instant browser feedback you can still add `required`/`type="email"`/`pattern` to inputs
and use the platform's Constraint Validation API (`form.checkValidity()`,
`input.setCustomValidity(msg)`). The model rules remain the authority; native constraints
are a UX nicety on top.

## Design notes

- `validate.js` imports nothing (pure leaf). `Model` imports `runRules` from it — a clean one-directional dependency (no cycle).
- `runRules` is **async** (returns a Promise): it `await`s each rule, runs them in declaration order, and a field collects every failure (it does not short-circuit on the first).
- Standalone use: `await runRules(anyData, rules)` works without a model (e.g. validate raw form values directly).


---

<!-- docs/en/element.md -->

# defineElement (Custom Element adapter)

Register a `View` as a Custom Element, so it can be used as `<tag-name>` in plain HTML
— or consumed inside React/Vue/Angular. This is the **escape hatch** for distributing a
widget; your class stays a normal `View`.

## Why an adapter (and not Custom Elements everywhere)

Lumen views are plain classes by default precisely so you keep control of the lifecycle —
e.g. `animateOut()` can finish before a node is removed. Custom Elements can't do that
(`disconnectedCallback` fires *after* removal). So Lumen inverts the usual choice: classes by
default, Custom Element only when you need interop — via this thin adapter.

## API

```js
defineElement(tagName, ViewClass, { attributes? })
```

| Param | Description |
|---|---|
| `tagName` | A custom element name (must contain a hyphen), e.g. `'hello-widget'`. |
| `ViewClass` | The `View` subclass to wrap. |
| `options.attributes` | Attribute names to keep synced into `props` after mount (`observedAttributes`). |

## Example

```js
import { View, defineElement } from 'lumenjs';

class Hello extends View {
  static template = '#hello';
  onMount() { this.ui.name.textContent = this.props.name; }
}

defineElement('hello-widget', Hello);
```

```html
<hello-widget name="Ada"></hello-widget>
<hello-widget name="Grace"></hello-widget>   <!-- independent instances -->
```

- **Attributes → props.** On connect, every attribute is read into `props` (string values).
- **Complex data → `.props`.** For objects or callbacks, set the element's `.props` property before inserting it: `el.props = { onSave }`.
- **Lifecycle.** Connect mounts the view into the host; disconnect unmounts it (cleanup runs).

## Caveat: no leave animation

The browser removes the node *before* `disconnectedCallback`, so `animateOut()` cannot play
when the host element is removed — cleanup (signal abort, `onUnmount`) still runs. This is
the exact limitation that keeps plain classes the default; the adapter is for interop, where
leave-animations aren't expected.

## Design notes

- `element.js` imports nothing — it wraps any object with `mount`/`unmount`/`props` (duck-typed), so it adds no coupling to the framework graph.
- `defineElement` is idempotent (a second call for the same tag is a no-op).


---

<!-- docs/en/canvas.md -->

# Canvas (experimental)

A minimal HTML-canvas rendering layer. The data layer — `Model`, `Collection`, `EventEmitter`,
`signal` — is **renderer-agnostic**, so the *same* state can drive a DOM `View` **and** a canvas
node at once: **one source of truth, two projections**. This module is the canvas projection.

> **Young & deliberately tiny.** 2D context only, a flat scene (one level of nesting), no asset
> pipeline. It's for the cases where reaching for a full engine is overkill — a bar chart, a
> sparkline, particles, a draggable diagram. When you need thousands of sprites, WebGL, or filters,
> attach **Pixi** instead (and drive its objects from Lumen `Model`s — same idea, bigger engine).

## Philosophy

- **One state, two projections.** Nothing to "sync": a single `Model`/`Collection` feeds a DOM
  `CollectionView` and a canvas `CanvasLayer`, each subscribed to the same events. Standalone canvas
  libraries are state-islands; here the canvas is just another reader of your data.
- **Immediate mode, honestly.** The DOM is retained (mutate a node, the browser repaints). Canvas
  is immediate — you clear and redraw each frame. So the "no full re-render" mantra *inverts*: events
  drive **when** to redraw (a dirty flag), not what to mutate.
- **One unified loop.** On-demand by default — a change schedules a single frame, then the stage
  idles (zero frames). A continuous ticker kicks in only while animators (tweens, emitters) are
  active and auto-stops when they finish. A static chart costs nothing; particles still animate.
- **Reuse, don't reinvent.** It imports no Lumen runtime — it only *consumes* a `Collection`'s
  events. Your state and validation code is unchanged whether it renders to DOM or canvas.

## The class map — DOM ↔ canvas

| Role | DOM | Canvas |
|---|---|---|
| One object | `View` | `Node2D` (base for shapes; **not** a View — no DOM) |
| Concrete primitives | *(your views)* | `Rect`, `Circle`, `Line`, `Text` |
| List: one per model | `CollectionView` | `CanvasLayer` |
| Slot / container | `Region` | `Stage` |
| State | `Model` / `Collection` | the **same** `Model` / `Collection` |

The state column is **shared** — the other two are interchangeable, coexisting projections.

## API

### `Stage`

| Member | Description |
|---|---|
| `new Stage(canvas)` | Wrap an `HTMLCanvasElement`; start the loop. |
| `add(node)` / `remove(node)` | Add/remove a root node (fires `onAdd`/`onRemove`). Returns the node. |
| `invalidate()` | Mark the scene dirty → one frame, then idle. |
| `animate(update)` | Register a per-frame `(dt) => void` (a tween/emitter). Returns a deregister fn; the ticker runs while any are active. |
| `hitTest(px, py)` | Topmost node at a canvas-space point, or `null` (translate + scale; rotation is phase 2). |
| `destroy()` | Stop the loop and abort `signal`. |
| `signal` | An `AbortSignal` for the stage's lifetime. |

### `Node2D` — the base (every shape extends it)

Fields: `x`, `y`, `scale`, `rotation`, `alpha`, `visible`, `model`.

| Member | Description |
|---|---|
| `onAdd()` / `onRemove()` | Lifecycle hooks (≈ `onMount`/`onUnmount`). |
| `update(dt)` | Advance time-based motion (particles/physics). `dt` in seconds. |
| `paint(ctx)` | **Override this** — draw, in a context already transformed by this node. |
| `draw(ctx)` | Applies transform + alpha, calls `paint`, restores. Rarely overridden. |
| `animate(to, { duration?, easing? })` | Tween fields to `to` over the loop. Returns a `Promise`; supersedes any tween in flight. |
| `stop()` | Cancel the tween in flight. |
| `contains(x, y)` | Local-space hit test (override per shape). Used by `Stage.hitTest`. |
| `stage` / `signal` | The attached stage and its signal. |

### Shapes

| Shape | Fields | Hit test |
|---|---|---|
| `Rect` | `w`, `h`, `fill`, `stroke`, `lineWidth` | ✅ box |
| `Circle` | `r`, `fill`, `stroke`, `lineWidth` | ✅ radius |
| `Line` | `points` (`[x,y][]`), `stroke`, `lineWidth`, `closed` | — |
| `Text` | `text`, `font`, `fill`, `align`, `baseline` | — |

### `CanvasLayer` — one node per model

| Member | Description |
|---|---|
| `new CanvasLayer(collection, factory, props?)` | `factory(model, index)` builds a node per model. |
| `children` | The child nodes, in collection order. |

Reconciles on the collection's `add`/`remove`/`reset`, and a bubbled `change` from any model
invalidates the stage. The same `Collection` can feed a DOM `CollectionView` simultaneously.

### Easings

`linear`, `easeOutCubic`, `easeInOutCubic` — pure `t → t` functions for `animate`.

## Example: one state, two projections

```js
import { Model, Collection, View, CollectionView } from 'lumenjs';
import { Stage, Node2D, CanvasLayer, easeOutCubic } from 'lumenjs/canvas';

// ── one state — with a derived getter reused by BOTH projections ──
class Bar extends Model {
  get color() { const v = this.get('value'); return v >= 80 ? '#dc2626' : v >= 50 ? '#f59e0b' : '#2563eb'; }
}
const data = new Collection([{ label: 'Q1', value: 40 }, { label: 'Q2', value: 92 }], Bar);

// ── projection A — canvas ──
class BarNode extends Node2D {
  paint(ctx) { ctx.fillStyle = this.model.color; ctx.fillRect(0, -this.h, 56, this.h); }
  contains(x, y) { return x >= 0 && x <= 56 && y <= 0 && y >= -this.h; }
  onAdd() {
    this.animate({ h: this.model.get('value') * 2 }, { duration: 600, easing: easeOutCubic });
    this.model.on('change:value', ({ value }) => this.animate({ h: value * 2 }), { signal: this.signal });
  }
}
const stage = new Stage(document.querySelector('#chart'));
stage.add(new CanvasLayer(data, () => new BarNode({ h: 0 }), { x: 50, y: 250 }));

// ── projection B — DOM (a normal CollectionView over the SAME collection) ──
class BarLabel extends View { /* … renders model.get('label'), model.get('value'), model.color … */ }
class Legend extends CollectionView { static childView = BarLabel; static container = 'list'; }
new Legend({ collection: data }).mount(aside);

// edit once → both projections react:
data.get('q2')?.set('value', 30);
```

See the [`canvas` example](../examples/canvas/) for the full bar chart, and the
[`particles` example](../examples/particles/) for the continuous-ticker side.

## Movement — the model says *where*, the node says *how*

Movement is presentation, exactly like the [derived data](model.md#derived-data--the-model-as-its-own-presenter)
split: the model holds the target value, `animate` decides how the node gets there.

```js
bar.model.on('change:value', ({ value }) =>
  bar.animate({ h: value * 2 }, { duration: 400 }), { signal: bar.signal });
// snap instead of tween: bar.h = value * 2; stage.invalidate();
```

## Particles — the continuous ticker

The bar chart only used the loop's **on-demand** half (redraw when data changes, then idle).
Particles exercise the other half. They're *output-only* — no `Model` per particle (there could be
thousands) — so an `Emitter` owns a flat array and advances it by **time** in `update(dt)`. To keep
the loop running it registers a **continuous animator**; pausing deregisters it and the stage returns
to a true idle (zero frames). This is the second `canvas` example on this page.

```js
class Emitter extends Node2D {
  play()  { this._stop = this.stage.animate((dt) => this.update(dt)); }  // keep the ticker alive
  pause() { this._stop?.(); this._stop = null; }                          // → stage goes idle
  update(dt) {                                                            // advance by elapsed time
    for (const p of this.particles) { p.x += p.vx * dt; p.y += p.vy * dt; p.vy += 480 * dt; }
    this.particles = this.particles.filter((p) => p.age < p.life);
  }
  paint(ctx) { /* draw each particle */ }
}
```

So the same `Stage` covers both modes without you choosing one: discrete data edits redraw on
demand, while anything that moves by time registers an animator and rides the ticker until it stops.

## Interaction — hit-testing

`Stage.hitTest(px, py)` walks nodes front-to-back (recursing into layers) and returns the topmost
whose `contains(x, y)` is true. Wire it from a pointer listener; a click on the canvas can edit the
shared model, so both projections follow:

```js
canvas.addEventListener('pointerdown', (e) => {
  const r = canvas.getBoundingClientRect();
  const node = stage.hitTest(e.clientX - r.left, e.clientY - r.top);
  if (node?.model) node.model.set('value', node.model.get('value') + 10);
});
```

## Limits & when to reach for Pixi

- **2D context only**, no WebGL/batching — fine for hundreds of shapes, not thousands of sprites.
- **No accessibility/selection on canvas** — keep text and forms in the DOM projection; canvas is
  for graphics. (`Text` exists for labels/annotations, not UI copy.)
- **Hit-testing honors translate + scale, not rotation**; the scene is flat (one layer level).
- No asset loader / `Sprite`, no exit animation on remove. These are deferred on purpose.

When any of those bite, attach Pixi and drive its display objects from Lumen `Model`s — your state
layer doesn't change.

## Design notes

- The loop is a **single scheduler** with two "needs a frame" sources: the dirty flag (discrete
  changes) and active animators (continuous). Neither → no frame scheduled. Multiple `set()`s in a
  tick coalesce into one redraw.
- `animate` tweens a node's plain fields (not the model), so a 60fps tween never floods the data
  model with `change` events; the data holds the target, the visual interpolates toward it.
- Everything ties to `Stage#signal`, so `destroy()` stops the loop and removes every subscription —
  the same leak-free story as `View`.


---

<!-- docs/en/tradeoffs.md -->

# Trade-offs: strengths & limits

Lumen makes a handful of deliberate bets: **no build, no magic, surgical updates,
client-side, zero dependencies.** Every strength *and* every limitation on this page flows
from those bets — they are coherent consequences, not accidental gaps. So the question is
never "does Lumen lack feature X?" but **"do my constraints match its bets?"**

**Lumen is a UI library, not a server.** It builds and manages views in the browser; it does
not serve HTTP or render pages server-side. When you need SEO or a server-rendered first
paint, pair it with a server (Express, Rails, FastAPI…) that renders the content — Lumen adds
the interactivity on top. See [Project structure](structure.md).

One framing to keep in mind: the axis that limits Lumen is **not app size**. It is
**UI dynamism + SEO needs + ecosystem dependence**. A large server-rendered app with
interactive islands fits beautifully; a medium but highly dynamic editor-style SPA will
fight you.

## Strengths

| Strength | Why it matters |
|---|---|
| **No build, no dependency rot** | Native ES modules — what you write is what runs, today and in five years. Nothing to transpile, nothing to update behind your back. |
| **Load only what you use** | Zero runtime dependencies; the browser fetches just the modules you import. No half-megabyte framework for a dropdown. |
| **Transparent, no magic** | Explicit state (`model.set`), explicit lifecycle, no proxies, no globals. Easy to read, debug, and reason about. |
| **Surgical updates** | You touch only the nodes that changed — focus, scroll, selection and input state are never lost. No re-render, no diffing. |
| **Plays with the platform** | Cleanup via `AbortSignal`, transitions via the View Transitions API, visibility via `IntersectionObserver`, requests via `fetch`. The platform does the heavy lifting. |
| **Built for islands** | `defineElement` exposes any view as a custom element — drop behavior into server-rendered pages or other frameworks. |
| **Ideal host for imperative libraries** | `onMount`/`onUnmount`/`signal` are the exact integration seam for three.js, pixi, CodeMirror, maps, charts — often cleaner than the `useRef` + `useEffect` dance, with no re-render to fight. See [Libraries vs. components](#libraries-vs-components). |
| **OOP & longevity** | Plain classes, JSDoc types. A small, stable surface that ages well. |

## Limitations

| Limitation | What it means |
|---|---|
| **No SSR / SSG / hydration** | Views render in the browser, so content isn't in the initial HTML. For SEO-critical pages and fast first paint, let the **server** render the content and use Lumen for interactivity (islands) — Lumen alone is not a page renderer for content sites. This is the biggest gap vs. Next/Nuxt/SvelteKit. |
| **Manual updates don't scale with dynamism** | You are the reconciler. For webs of derived state, complex conditional rendering, or editor/spreadsheet-like UIs, you write a lot of DOM-sync code by hand — and risk state/DOM drift. There is no reactivity/computed-state engine (no signals, no bindings). |
| **No framework-coupled component kits** | You don't inherit React/Vue's thousands of ready components (a React date picker, a Vue data table, MUI) — those are bound to their framework's render model. So standard product-UI velocity is lower. Note this is only *half* a limitation: framework-agnostic libraries integrate cleanly — see [Libraries vs. components](#libraries-vs-components). |
| **DX & team scale** | No state-preserving HMR (the dev server does a full reload), no static type-checking of template/DOM wiring, no dedicated devtools. And it's bespoke — most developers already know React/Vue, so onboarding has a cost. |
| **Data layer & large lists** | No global store, normalized cache, or data-fetching/caching layer (think React Query/Apollo) — you build those on `EventEmitter`/`Model`/`Http`. `CollectionView` mounts real DOM per model, with **no virtualization**, so huge lists need windowing you write yourself. |
| **Evergreen browsers only** | Lumen leans on modern platform APIs. Supporting legacy browsers would require polyfills and a build step — which contradicts the whole premise. |

## Libraries vs. components

"No ecosystem" needs a sharper line, because it's only half a limitation.

**Framework-agnostic libraries** — three.js, pixi.js, CodeMirror, Chart.js, MapLibre,
ProseMirror, D3 — own a DOM node and render themselves. Lumen is an *ideal* host: instantiate
the library in `onMount`, dispose it in `onUnmount`. The imperative library and the imperative
lifecycle match naturally — often cleaner than React's `useRef` + `useEffect` + cleanup dance,
with no re-render to fight and no `StrictMode` double-invoke.

```js
import * as THREE from 'three'; // ESM — importable via a CDN/import map (still no build)

class Scene extends View {
  static template = '#scene';                 // e.g. <canvas data-ref="canvas"></canvas>
  onMount() {
    this.renderer = new THREE.WebGLRenderer({ canvas: this.ui.canvas });
    // …build the scene, then start the render loop
    this.tick();
  }
  tick = () => {
    this.renderer.render(this.scene, this.camera);
    this._raf = requestAnimationFrame(this.tick);
  };
  onUnmount() {
    cancelAnimationFrame(this._raf);
    this.renderer.dispose();                  // free GPU resources — clean teardown
  }
}
```

The library owns its subtree; Lumen just hosts the root node and the lifecycle. For
creative-coding, dataviz, maps and editors this is a genuine **strength**, not a gap.

**Framework-coupled component kits** — a React date picker, a Vue data table, MUI — are bound
to their framework's render model and can't be dropped into Lumen. *This* is the real gap.
Many needs are still covered by agnostic vanilla libraries; what you don't get is the
framework-bound kits.

## The deciding axis

Don't ask "how big is the app?" Ask three things:

1. **Do I need SEO / server-rendered first paint?** If yes, the server renders content; Lumen is the interactivity layer, not the page.
2. **How dynamic is the UI?** Mostly content + discrete interactions → great. A dense web of derived, interdependent state → you'll miss declarative reactivity.
3. **Do I depend on a component ecosystem to move fast?** If yes, a mainstream framework wins on velocity.

## When to use Lumen — and when not to

> **Use Lumen** when the server (or a static build) already provides the HTML/SEO; the
> interactivity is "islands," an internal tool, or a long-lived dashboard; you control the
> browser; and you value transparency and longevity over ecosystem velocity. Internal apps
> and dashboards can be **large** — size is not the limit.
>
> **Reach for React / Vue / Svelte + a meta-framework** when you need SSR/SEO out of the
> box, the UI is large and highly dynamic with derived state everywhere, you rely on the
> component ecosystem for speed, or a big team already lives in that stack.

## These limits are intentional

Adding SSR, a reactivity engine, or a bundled ecosystem would reintroduce exactly the build
step and the bloat Lumen exists to avoid. The limitations are the *price* of the strengths —
choose by fit, not by feature count. See also [Project structure](structure.md) (how to keep
a growing app clean), [defineElement](element.md) (islands), and [Deployment](deployment.md)
(why no bundler is needed).


---

<!-- docs/en/structure.md -->

# Project structure

Lumen separates **behavior** (classes) from **markup** (`<template>`). That separation is
easy in the small; the question this page answers is how to keep it as an app grows — so
each section (header, customers, contact…) owns its own thing, and you never end up with
one giant file holding everything.

## The unit: one View per file

A view is a class, so its natural home is its own module. A section maps to a file:

```text
views/
  app-layout.js     # the shell (regions)
  header.js
  customers.js
  contact.js
```

Each file owns one view's behavior. Its markup lives in a `<template>` — never as an HTML
string inside the JS (you'd lose the editor's HTML support: highlighting, auto-close,
Emmet, format-on-save). Keep HTML as HTML.

## Where the markup lives (the key decision)

`clone('#id')` resolves the selector against the **document**, so every `<template>` a view
uses must be present in the page. That's fine — what you want to avoid is hand-maintaining
one monolithic `index.html` with every section's markup. The clean answer depends on whether
you have a server.

### With a server (Rails, FastAPI, any templating) — recommended

Each section owns its own partial; the server composes them. On disk you get true single
responsibility; the browser still receives one document with all the templates — exactly
what `clone('#id')` needs. The assembled page is **generated output**, not a file you edit.

**Rails**

```erb
<%# app/views/site/_header.html.erb %>
<template id="header"><header data-ref="root">…</header></template>

<%# app/views/site/index.html.erb %>
<%= render "header" %>
<%= render "customers" %>
<%= render "contact" %>
<div id="app"></div>
<%= javascript_import_module_tag "app" %>
```

**FastAPI / Jinja**

```django
{# templates/index.html #}
{% include "_header.html" %}    {# each holds its own <template id> #}
{% include "_customers.html" %}
{% include "_contact.html" %}
<div id="app"></div>
<script type="module" src="/static/app.js"></script>
```

**Hono** (the Node/edge flavor — Lumen is a UI library, so it needs a server like this for SEO; Web-Standards, runs on Node/Bun/Deno/edge, same ADN as Lumen)

```js
// server.js
import { Hono } from 'hono';
import { html } from 'hono/html';
import { serveStatic } from '@hono/node-server/serve-static'; // edge: 'hono/cloudflare-workers'

const app = new Hono();
app.use('/static/*', serveStatic({ root: './' }));  // your JS: copied src/ or a CDN import map

app.get('/', async (c) => {
  const customers = await db.customers();
  return c.html(html`<!doctype html>
    <body>
      <ul>${customers.map((x) => html`<li>${x.name}</li>`)}</ul>  <!-- server-rendered → indexed -->
      <template id="customers">…</template>
      <div id="app"></div>
      <script type="module" src="/static/app.js"></script>
    </body>`);
});

export default app;
```

> On edge runtimes (Cloudflare Workers) there's no filesystem — serve the JS via the
> platform's static assets, or just point an import map at a CDN for `lumenjs`.

> Whatever you need **indexed** must be rendered into this server HTML; Lumen then adds the
> interactivity. Content that only appears after client-side `fetch` is not crawled.

### Static (no server templating)

The platform has no native HTML include (HTML Modules aren't Baseline), so you can't compose
`.html` files at load time without machinery. Two honest choices:

1. **One organized `index.html`** — keep all `<template id>` in the page, grouped and
   commented by section. The JS still lives in per-section files. For most static sites this
   is the pragmatic sweet spot: the markup is in one file, but each *behavior* is separate.
2. **A partial loader** — ship per-section `.html` and `fetch` + inject their `<template>`s
   before mounting. You get per-file markup at the cost of async ordering and extra requests.
   Only worth it for large static apps.

Either way: **don't inline markup as JS strings** to "separate" the files — that trades a
markup-organization problem for a worse editor-ergonomics one.

## Wiring it together: the entry

One small entry imports the section views and mounts the shell. Compose with a layout's
`static regions` (one region per section) or the `Router` — never a god-file:

```js
// app.js — the entry
import { View } from 'lumenjs';
import { Header } from './views/header.js';
import { Customers } from './views/customers.js';
import { Contact } from './views/contact.js';

class AppLayout extends View {
  static template = '#app-shell';
  static regions = { header: 'header', main: 'main', contact: 'contact' };
  onMount() {
    this.regions.header.show(new Header());
    this.regions.main.show(new Customers());
    this.regions.contact.show(new Contact());
  }
}

new AppLayout().mount(document.querySelector('#app'));
```

Each section view, in its own file, stays tiny and focused:

```js
// views/contact.js
import { View } from 'lumenjs';
export class Contact extends View {
  static template = '#contact';
  onMount() { /* wire this section's listeners */ }
}
```

## A suggested layout (server-backed)

```text
app/
  views/site/
    index.html.erb        # <div id="app"></div> + asset tags
    _header.html.erb      # <template id="header">…
    _customers.html.erb   # <template id="customers">…
    _contact.html.erb
  javascript/
    app.js                # entry: mounts AppLayout
    views/                # one View per section
      app-layout.js  header.js  customers.js  contact.js
    models/               # Model / Collection subclasses
    api.js                # a single Http instance, imported where needed
```

## Rules of thumb

- **One View per file**; the filename names the section.
- **Markup in `<template>`**, never as a string in JS.
- **Sections own their markup** — server partials when you have a server; one organized
  `index.html` when you don't.
- **Compose, don't centralize** — a layout's `static regions` (see [View → Regions](view.md))
  or the [Router](router.md) wire sections together; the entry just mounts the shell.
- **One `Http` per API**, imported explicitly — no globals.


---

<!-- docs/en/messaging.md -->

# Messaging between views

How independent views, models and collections talk to each other — the role Backbone's Radio
played, minus the global singleton. Create an `EventEmitter`, share it by importing it, and let
unrelated views subscribe (each with `this.signal`, so subscriptions auto-clean on unmount).
`Model` and `Collection` already emit events you subscribe to the same way.

## Two channels

The live example (a small shop) coordinates three **independent** views — a catalog, a cart
badge, and toasts — through two shared channels, with zero direct coupling:

- A shared **`Collection`** (`cart`) — its structural events (`add`/`remove`/`reset`) drive the badge.
- A shared **`EventEmitter`** (`bus`) — app-wide notifications drive the toasts.

```js
import { View, Model, Collection, EventEmitter } from 'lumenjs';

const bus  = new EventEmitter();        // app-wide notifications
const cart = new Collection([], Model); // shared cart; emits add/remove/reset

class CartBadge extends View {
  static template = '#bar';
  onMount() {
    this.update();
    cart.on('add',    this.update, { signal: this.signal });  // subscribe straight to the Collection
    cart.on('remove', this.update, { signal: this.signal });
    cart.on('reset',  this.update, { signal: this.signal });
  }
  update = () => { this.ui.count.textContent = String(cart.length); };
}

class Toasts extends View {
  static template = '#toasts';
  onMount() { bus.on('notify', this.show, { signal: this.signal }); }  // listen on the app bus
  show = ({ text }) => { /* append a transient toast */ };
}
```

A `Product` view does both at once when you click *add*: `cart.add(model)` (structural event →
the badge updates) and `bus.emit('notify', …)` (app bus → a toast appears). Neither subscriber
knows the product exists.

## No leaks, no global

- Every subscription is bound to `this.signal`, so it's removed on `unmount()` — no manual `off()`, none of Backbone Radio's classic listener leaks.
- The bus is **explicit**: you create it and share it by importing the module — not a `window`-level global, no side effects on import. For separate concerns, create separate buses.

## When to use it

- **Use a bus** for *cross-cutting, decoupled* reactions: notifications, a theme switch, an "unsaved changes" indicator — things many unrelated views care about.
- **Don't** reach for it for local parent↔child talk: pass a callback in `props`, or use the child's own `events` emitter. A global bus for everything recreates the "who's listening?" tangle Lumen exists to avoid.

See [event-emitter](event-emitter.md), [model](model.md) and [collection](collection.md).


---

<!-- docs/en/styling.md -->

# Styling

Lumen ships **zero CSS** and imposes nothing. You bring whatever you like. Because views
render into the **Light DOM** (no Shadow DOM), any global stylesheet or utility classes
apply directly to the nodes cloned from your `<template>` — there is nothing to pierce or
configure.

## Your options

| Approach | When |
|---|---|
| **Plain CSS** + a naming convention | Simplest; total control. |
| Native **`@scope`** | Component-scoped styles without Shadow DOM and without a build. Recommended for isolation. |
| **Tailwind** (or any utility framework) | Utilities in your template markup. |
| Any CSS framework via CDN/build | It's just global CSS; Lumen doesn't get in the way. |

## Scoped styles without a build: `@scope`

`@scope` (Chrome/Edge 118+, Safari 17.4+, Firefox 2024+) gives real isolation in the Light
DOM — no Shadow DOM, no build:

```css
@scope (.card) {
  :scope { padding: 1rem; border-radius: var(--radius); }
  h3 { font-size: 1.1rem; }   /* only h3 inside .card */
}
```

Global design tokens (`:root { --radius: 8px }`) still reach everything, so theming stays simple.

## Tailwind

Write utilities right in the `<template>`; `clone` copies them and they apply because the
view is Light DOM:

```html
<template id="card">
  <div class="rounded-xl border border-slate-200 shadow-sm p-4 bg-white" data-ref="root">
    <h3 class="font-semibold" data-ref="title"></h3>
  </div>
</template>
```

```js
class Card extends View {
  static template = '#card';            // Tailwind handles the look
  onMount() { this.ui.title.textContent = this.props.title; }
}
```

No integration code is needed — Lumen manages behavior and lifecycle, Tailwind manages the look.
See the runnable [Tailwind example](../../examples/tailwind/).

For prototyping you can use the Tailwind **Play CDN** (`<script src="https://cdn.tailwindcss.com"></script>`),
which JITs in the browser with no build. For production, use Tailwind's build or a prebuilt
stylesheet.

## Third-party JS widgets (e.g. Bootstrap components)

For CSS frameworks that also ship JavaScript widgets (modals, dropdowns), instantiate the
widget in `onMount` and dispose it in `onUnmount` — Lumen's lifecycle gives you the exact
hooks:

```js
class Modal extends View {
  static template = '#modal';
  onMount()   { this.widget = new SomeLib.Modal(this.el); this.widget.show(); }
  onUnmount() { this.widget.dispose(); }   // clean teardown
}
```

## Optional: per-component styles

A view can declare a `static styles` string and inject it once if you want self-contained
components — but it is opt-in and off by default. Most apps are better served by a global
stylesheet, `@scope`, or utilities.


---

<!-- docs/en/deployment.md -->

# Deployment & loading

Lumen ships unbundled native ES modules. Thanks to **HTTP/2** (and HTTP/3), that is not a
trade-off — it's an advantage. This page covers how to serve it well.

## Why no bundler is needed

Under HTTP/1.1, many small files were slow (≈6 connections, per-request overhead) — which
is why bundling existed. Under HTTP/2 that penalty is gone:

- **Multiplexing** — many requests share one connection with no head-of-line blocking, so loading Lumen's small modules costs about the same as one file.
- **Header compression (HPACK)** — cheap per-request overhead.
- **Per-file caching** — change `view.js` and only that file's cache is invalidated; a bundle would bust the whole thing.

Almost every modern static host serves HTTP/2 by default (Netlify, Vercel, Cloudflare,
nginx, Caddy). So: **deploy the files as-is.** A bundler is optional, not required.

## Flatten the ESM waterfall: `modulepreload`

The one downside of native modules is the *discovery waterfall*: the browser loads
`index.js`, parses it, sees its imports, fetches those, parses them, and so on — one round
trip per level. Tell the browser to fetch the whole graph up front, in parallel:

```html
<link rel="modulepreload" href="/src/index.js" />
<link rel="modulepreload" href="/src/view.js" />
<link rel="modulepreload" href="/src/dom.js" />
<!-- …one per module your page actually uses -->
```

Combined with HTTP/2 multiplexing, this gives a **bundle's load performance without a
bundle**. (Server-side, `103 Early Hints` can send these preloads even earlier.)

## Clean imports: import maps

An import map lets you write `import { View } from 'lumenjs'` instead of relative paths, and
keeps your URLs in one place:

```html
<script type="importmap">
  { "imports": { "lumenjs": "/src/index.js", "lumenjs/": "/src/" } }
</script>
```

Then: `import { View } from 'lumenjs'` or `import { clone } from 'lumenjs/dom.js'`. Import maps
are supported in all current browsers; this docs site uses one.

## Caching headers

Because files are independent, cache them aggressively and let the URL change on deploy:

```text
Cache-Control: public, max-age=31536000, immutable   # for versioned/hashed asset URLs
Cache-Control: no-cache                               # for index.html
```

If you don't hash filenames, use a shorter max-age or `must-revalidate` so updates are
picked up.

## Don't rely on HTTP/2 Server Push

Server Push was **removed** from Chrome (2022). Its replacement is exactly the
`modulepreload` / `preload` hints above (optionally delivered via `103 Early Hints`).

## The Http module

The `http` module needs nothing special: `fetch` uses HTTP/2 automatically when the server
supports it. One practical consequence — concurrency is cheap, so firing several requests at
once is fine:

```js
const [user, posts] = await Promise.all([
  api.get('/user', { signal }),
  api.get('/posts', { signal }),
]);
```


---

<!-- docs/en/credits.md -->

# Credits & lineage

Lumen stands on the shoulders of **Backbone.js** and **Marionette.js**. Its design is a
deliberate, modernized descendant of theirs — a respectful homage, not a fork (no Backbone
or Marionette code is used; these are conceptual inspirations).

## Backbone.js

*(Jeremy Ashkenas & DocumentCloud)* — the events-first, explicit-state design.

- **`Model`** and **`Collection`** descend directly from Backbone's. `get`/`set`,
  `change` events, validation on the model — the lineage is obvious and intentional.

## Marionette.js

*(Derick Bailey)* — the view layer and composition patterns.

- **`View`** — lifecycle (`onMount`/`onUnmount`), `ui`/refs, declarative event wiring.
- **`Region`** — managing a slot and swapping the view in it.
- **`CollectionView`** — one child view per model, kept in sync.
- **Layouts** (`static regions`) — Marionette's `LayoutView` with named regions.

If you came from Marionette, Lumen should feel like home.

## What Lumen changes

The patterns were right; the implementation is rebuilt for today:

- **No jQuery, no Underscore, no Backbone runtime** — just the platform.
- **No build, native ES modules** — viable now thanks to HTTP/2.
- **No global event bus by default** — events are instances you pass explicitly.
- **`AbortSignal`-based cleanup** — no "zombie views", no leaked listeners.
- **Typed via JSDoc**, separate `<template>` HTML, and an **animation-aware lifecycle**
  (`animateOut` finishes before a node is removed — something Marionette's era couldn't do cleanly).

## And the platform

Thanks also to the web standards that make the "no-magic, no-build" approach practical:
`<template>`, the Web Animations API, the Constraint Validation API, import maps, and
HTTP/2 multiplexing.

> Backbone and Marionette showed that explicit, OOP, no-magic UI was not only possible but
> pleasant. Lumen is a love letter to that idea, rewritten for the modern platform.