@nativele/ts-dom 0.4.6 → 0.5.0

package/README.md

@@ -1,12 +1,14 @@
 # Nativele
 
-A TypeScript-driven, HTML-first UI library.
+<p align="center"><img src="https://raw.githubusercontent.com/Pixmi/nativele/main/docs/assets/banner.png" alt="Nativele: designed for AI agents, driven by TypeScript, defined in vanilla HTML" width="100%"></p>
+
+**Designed for AI agents. Driven by TypeScript. Defined in vanilla HTML.**
 
 Nativele publishes this library as `@nativele/ts-dom` (import it from `@nativele/ts-dom`); its command line tool is `ts-dom`.
 
-A lightweight UI library: HTML describes the structure and where data goes, TypeScript owns behavior and state, and the native DOM renders it, with no virtual DOM and no template expressions. It is built for type safety and for working with AI agents: `tsc` checks every name the HTML uses, and every diagnostic says how to fix it. Complex UI is built by composing native custom elements.
+A lightweight library for building web components: HTML describes the structure and where data goes, TypeScript owns behavior and state, and the native DOM renders it, with no virtual DOM and no template expressions. It is built for type safety and for working with AI agents: `tsc` checks every name the HTML uses, and every diagnostic says how to fix it. Complex UI is built by composing native custom elements.
 
-**Nativele is made for AI coding agents.** An agent writes a template and a class, runs `ts-dom check`, and corrects its own mistakes from the type errors: a name the HTML uses that the class does not have, an event handler that does not exist, list items of the wrong shape. There is no template language to learn and no hidden reactivity to reason about, so what the agent reads in the HTML and the class is all that happens. Every diagnostic from `ts-dom gen` and `ts-dom lint` names its rule and ends with a `Fix:` hint the agent can apply, [`llms.txt`](llms.txt) describes the whole API on one page, and [Rules for AI Agents](#rules-for-ai-agents) is a list you can paste into a project's agent instructions.
+**Nativele is made for AI coding agents.** An agent writes a template and a class, runs `ts-dom check`, and corrects its own mistakes from the type errors: a name the HTML uses that the class does not have, an event handler that does not exist, list items of the wrong shape. There is no template language to learn and no hidden reactivity to reason about, so what the agent reads in the HTML and the class is all that happens. Every diagnostic from `ts-dom gen` and `ts-dom lint` names its rule and ends with a `Fix:` hint the agent can apply, [`llms.txt`](llms.txt) describes the whole API on one page, and [Nativele Skills](#nativele-skills) give agents verified procedures for building components and for using them with other tools.
 
 English | [繁體中文](README.zh-TW.md)
 
@@ -44,17 +46,28 @@ Six things cover most components:
 5. **Props go down, events go up**: the parent sets props; the child calls `this.emit("name", detail)` and the parent handles it with `data-on-name` on the child's tag.
 6. **A handler is a public method** `(event, hit)`; inside a list item `hit.key` is the item's key.
 
-## Rules for AI Agents
+## Nativele Skills
+
+Nativele ships Skills with the package: task procedures for coding agents, each with set-up steps, a complete example, known limitations, the commands that verify the result, and the exact versions it was verified with. The guides hold the facts about the API; a Skill tells an agent how to do a job with them.
+
+```sh
+npx ts-dom skills                      # list the Skills in the installed version
+npx ts-dom skills nativele-core        # print one
+npx ts-dom skills add nativele-core    # copy it into .claude/skills/ (when the project has .claude) or .agents/skills/
+```
 
-Paste these into your project's agent instructions (`AGENTS.md`, `CLAUDE.md` or similar):
+`npx ts-dom doctor` reads your `package.json` and suggests the Skills that match it, for example `nativele-react` when React is a dependency.
 
-- Write the `.html` and the `.ts` of a component together; never edit `x.html.ts` or `ts-dom-tags.ts`, which `ts-dom gen` writes.
-- After changing any `.html` or component, run `npx ts-dom check` (add `--json` to read the result as data). It regenerates the generated files, runs `tsc`, maps the template contract errors back to the template line and column, and runs the lint rules. Fix every issue it reports, following its `Fix:` hint, instead of casting a type error away.
-- Import templates as `./x.html.js`.
-- No expressions in HTML: put computed values in `derive`, and change state only with `this.set()`.
-- Every diagnostic from `ts-dom gen` and `ts-dom lint` ends with a `Fix:` hint; follow it. `npx ts-dom rules` lists all rule ids, and `npx ts-dom lint --a11y` also checks accessibility.
-- A `data-each` list cannot be nested: put the inner list in its own `.html` as a child component.
-- For a list of components, write `data-key` and `data-prop` on the `<template data-each>`, give the item component `role="listitem"` inside `<ul>` or `<ol>`, assign `this.lists.x.items = ...` with new objects for changed items (never mutate an assigned item), and let `tsc` check the items.
+| Skill | Covers |
+|---|---|
+| `nativele-core` | building components: the `ts-dom check` loop, templates, state, lists, data flow |
+| `nativele-react` | Nativele components in React 19: props, events, children and slots, lifecycle, TSX types |
+
+Tiers: Official Skills are verified by the maintainers against an example project in CI; Community Skills are contributed and show their author and last verified versions; Experimental Skills are not fully verified yet. `ts-dom skills` marks a Skill as stale when its verification is more than six months old or does not cover the installed version.
+
+Nativele stays a light UI layer and grows its integrations through Skills: a new Skill changes no runtime code and adds no dependency. The planned Skills and how to contribute one are in [the Skills guide](https://github.com/Pixmi/nativele/blob/main/skills/README.md).
+
+If your agent does not load Skills, add this line to its instructions (`AGENTS.md`, `CLAUDE.md` or similar): "Before working on Nativele components, run `npx ts-dom skills nativele-core` and follow it."
 
 ## Quick Start
 
@@ -64,7 +77,7 @@ npx ts-dom gen      # generate x.html.ts (fully typed) for every x.html; run it
 npx tsc             # type-check and compile; no Vite or other bundler needed
 ```
 
-The four examples below are real, runnable files in `examples/readme/` (type-checked, linted, and tested).
+The two examples below are real, runnable files in `examples/readme/` (type-checked, linted, and tested).
 
 ### Example 1: Counter (state, derived values, events, data-if)
 
@@ -99,139 +112,7 @@ define("my-counter", MyCounter);
 
 If the HTML uses a name that neither `state` nor `derive` has, or `data-on-click` points to a method that does not exist, `tsc` reports an error.
 
-### Example 2: Todo list (lists, event delegation, `hit.key`)
-
-```html
-<form data-on-submit="add">
-  <input data-ref="input" aria-label="New todo" />
-  <button type="submit">Add</button>
-</form>
-<ul>
-  <template data-each="items">
-    <li>
-      <input type="checkbox" data-ref="check" data-on-change="toggle" />
-      <span>{{ title }}</span>
-      <button type="button" data-on-click="removeItem">Delete</button>
-    </li>
-  </template>
-</ul>
-<p>{{ remaining }} left</p>
-```
-
-```ts
-import { Component, define } from "@nativele/ts-dom";
-import type { EventHit } from "@nativele/ts-dom";
-import tpl from "./todo-list.html.js";
-
-interface Item {
-  id: number;
-  title: string;
-  done: boolean;
-}
-
-export class TodoList extends Component(tpl, {
-  state: { items: [] as Item[] },
-  derive: { remaining: (s) => s.items.filter((i) => !i.done).length },
-}) {
-  #nextId = 1;
-
-  add(e: Event): void {
-    e.preventDefault();
-    const title = this.refs.input.value.trim();
-    this.refs.input.value = "";
-    if (title) this.set((s) => ({ items: [...s.items, { id: this.#nextId++, title, done: false }] }));
-  }
-  toggle(_e: Event, hit: EventHit): void {
-    this.set((s) => ({ items: s.items.map((i) => (i.id === hit.key ? { ...i, done: !i.done } : i)) }));
-  }
-  removeItem(_e: Event, hit: EventHit): void {
-    this.set((s) => ({ items: s.items.filter((i) => i.id !== hit.key) }));
-  }
-
-  // Automatic binding handles {{ remaining }}; the list is filled here.
-  override render(view: { items: readonly Item[] }, changed: ReadonlySet<string>): void {
-    if (!changed.has("items")) return;
-    this.lists.items.replace(
-      view.items,
-      (i) => i.id,
-      (i, { text, refs }) => {
-        text.title = i.title;
-        refs.check.checked = i.done;
-        refs.check.setAttribute("aria-label", `Done: ${i.title}`);
-      },
-      { skipUnchanged: true },
-    );
-  }
-}
-define("todo-list", TodoList);
-```
-
-- The `<template>` with `data-each` is the list item; automatic binding does not handle lists, so the list is filled in `render` with `replace`.
-- Events use delegation: for `data-on-change` and `data-on-click` inside a list item, the `hit.key` they receive is that item's key.
-- `{{ remaining }}` is a derived value and updates automatically.
-
-### Example 3: Parent and child components (props down, events up)
-
-The child component owns only `props` (given by the parent, read-only). To change a value, it uses `emit` to ask the parent to handle it:
-
-```html
-<button type="button" data-on-click="dec">-</button>
-<output>{{ value }}</output>
-<button type="button" data-on-click="inc">+</button>
-```
-
-```ts
-import { Component, define, event } from "@nativele/ts-dom";
-import tpl from "./quantity-input.html.js";
-
-/** A child component: the parent owns the value (a prop); the child only asks for a change through an event. */
-export class QuantityInput extends Component(tpl, {
-  props: { value: 0, min: 0, max: 10 },
-  emits: { "quantity-change": event<{ value: number }>() },
-}) {
-  dec(): void {
-    if (this.props.value > this.props.min) this.emit("quantity-change", { value: this.props.value - 1 });
-  }
-  inc(): void {
-    if (this.props.value < this.props.max) this.emit("quantity-change", { value: this.props.value + 1 });
-  }
-}
-define("quantity-input", QuantityInput);
-```
-
-The parent uses the child's tag directly in its own HTML. `ts-dom gen` automatically `import`s the child component and gives `this.refs.qty` the child's full type:
-
-```html
-<quantity-input data-ref="qty" min="1" max="5" data-on-quantity-change="onQuantity"></quantity-input>
-<p>Total: {{ total }}</p>
-```
-
-```ts
-import { Component, define } from "@nativele/ts-dom";
-import type { EmitEvent } from "@nativele/ts-dom";
-import type { QuantityInput } from "./quantity-input.js";
-import tpl from "./order-line.html.js";
-
-export class OrderLine extends Component(tpl, {
-  state: { quantity: 1, price: 20 },
-  derive: { total: (s) => s.quantity * s.price },
-}) {
-  // Event up: the child asked for a new quantity; the parent decides.
-  onQuantity(e: Event): void {
-    this.set({ quantity: (e as EmitEvent<QuantityInput, "quantity-change">).detail.value });
-  }
-
-  // Data down: the child's props are typed (a wrong name or type is a tsc error).
-  override render(view: { quantity: number }): void {
-    this.refs.qty.value = view.quantity;
-  }
-}
-define("order-line", OrderLine);
-```
-
-The data flow goes in only one direction: the parent's state → the child's props (`this.refs.qty.value = ...`); the child's request → event → the parent's handler method.
-
-### Example 4: A list of components (`items =`, props down, events up)
+### Example 2: A list of components (`items =`, props down, events up)
 
 When an item has anything of its own (state, events, a nested list), make it a component and fill the list with one assignment. The item component receives its task as a prop and sends changes up as events:
 
@@ -304,16 +185,16 @@ export class TaskBoard extends Component(tpl, { state: { tasks: [] as Task[], ne
     this.refs.title.value = "";
   }
   // A changed task is a new object: the list sets the prop only on items that are not the same object as before.
-  toggleTask(_e: Event, hit: EventHit): void {
+  toggleTask(_e: Event, hit: EventHit<Task, "id">): void {
     this.set((s) => ({ tasks: s.tasks.map((t) => (t.id === hit.key ? { ...t, done: !t.done } : t)) }));
   }
-  removeTask(_e: Event, hit: EventHit): void {
+  removeTask(_e: Event, hit: EventHit<Task, "id">): void {
     this.set((s) => ({ tasks: s.tasks.filter((t) => t.id !== hit.key) }));
   }
   sortByTitle(): void {
     this.set((s) => ({ tasks: [...s.tasks].sort((a, b) => a.title.localeCompare(b.title)) }));
   }
-  override render(view: { tasks: readonly Task[] }, changed: ReadonlySet<string>): void {
+  override render(view: { tasks: readonly Task[] }, changed: ReadonlySet<"tasks">): void {
     if (changed.has("tasks")) this.lists.tasks.items = view.tasks;
   }
 }
@@ -322,753 +203,22 @@ define("task-board", TaskBoard);
 
 Adding, removing, sorting and toggling all go through `this.set()`; the list keeps the element of each task that stays (so a checkbox keeps its focus), creates one for a new task, removes the ones that are gone, and sets `task` only on items that are a new object. `tsc` checks that the assigned items match the `task` prop of `<task-row>` and have an `id`.
 
-## Design Principles
-
-- HTML is the single source of structure.
-- TypeScript is the single source of behavior and state.
-- The DOM is the single source of truth for the UI; there is no virtual tree.
-- Updates are explicit, local DOM operations; there is no whole-tree diff.
-- Component lifecycle reuses Custom Elements.
-- State subscriptions exist only where you call `bind`.
-- There is no template language: HTML contains only **names**, never expressions.
-- Type safety: names are derived by codegen, and tsc and lint can check that the HTML and TS match.
-
-Comparison with Vue templates:
-
-| Vue | ts-dom | Difference |
-|---|---|---|
-| `{{ expr }}` | `{{ name }}` | Must be a single identifier, not a path or an operation |
-| `v-if` | `data-if="name"` | The condition is decided by TS calling `show(name, bool)` |
-| `v-for` | `<template data-each="name">` | The list is updated by TS calling methods such as `replace` |
-| `<slot>` | `<slot name>` | In Light mode the library moves the content; with `shadow: true` it uses native slots |
-| `<style scoped>` | `<style scoped>` | Implemented with native `@scope`; without `scoped` it is global |
-| `<template>` | The HTML file itself | One `.html` file is one component template |
-
-## Installation and Setup
-
-You only need TypeScript; **no Vite or any other bundler is required**:
-
-```sh
-npm i -D typescript
-npm i @nativele/ts-dom
-```
-
-`tsconfig.json` (the same as in an ordinary TS project, with no special options):
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022", "DOM"],
-    "strict": true,
-    "rootDir": "src",
-    "outDir": "out"
-  }
-}
-```
-
-Workflow: first generate the template modules, then compile and type-check with `tsc`.
-
-```sh
-npx ts-dom gen        # generate x.html.ts for every x.html under src/
-npx tsc               # type-check and compile to out/
-```
-
-Whitespace in text is kept as written. To collapse each run of whitespace into one space and drop line-break-only text between tags (so indented HTML does not add stray spaces), use `npx ts-dom gen --whitespace=collapse` or the Vite plugin option `whitespace: "collapse"`; `<pre>` and `<textarea>` are left alone.
-
-During development, use `npx ts-dom gen --watch` to keep watching `.html` files, together with `tsc --watch`.
-
-`npx ts-dom gen --check` writes nothing: it lists generated files that are missing, outdated (their template or a `define()` changed) or orphaned (their template was deleted), and exits with code 1 if there are any (`--json` for machine-readable output). Use it in CI if your project commits the generated files, or to confirm they are fresh before reading type errors.
-
-In your code, import templates with a `.js` suffix (standard NodeNext style; TS maps it to the generated `x.html.ts`):
-
-```ts
-import tpl from "./user-card.html.js";
-```
-
-### Running in the browser (no bundler)
-
-The compiled JS is standard ES modules. Only one bare module specifier, `ts-dom`, needs to be mapped, and an import map does it:
-
-```html
-<script type="importmap">
-  { "imports": { "@nativele/ts-dom": "/node_modules/@nativele/ts-dom/dist/index.mjs" } }
-</script>
-<user-card></user-card>
-<script type="module" src="/out/main.js"></script>
-```
-
-This workflow (installing only `typescript`, no Vite, from `gen` to running in a real browser) is verified automatically by `npm run smoke:no-bundler`.
-
-### With Vite (optional)
-
-When you use a bundler you do not need an import map. The `@nativele/ts-dom/vite` plugin is just a convenience: it generates `.html.ts` automatically at build time, watches `.html` and regenerates during dev, and offers optional ARIA warnings.
-
-```ts
-import { defineConfig } from "vite-plus"; // or "vite"
-import { tsDom } from "@nativele/ts-dom/vite";
-
-export default defineConfig({
-  plugins: [tsDom()], // options: dirs (default ["src"]), runtime, whitespace, include, exclude, a11y
-});
-```
-
-While the dev server runs, the plugin keeps the generated files in step: adding or editing a template regenerates its `x.html.ts` and reloads the page once if a page uses it (a save that changes nothing does not reload), deleting a template removes its `x.html.ts`, and adding or removing a `define()` updates `ts-dom-tags.ts` and the child imports of the templates. `dirs` are relative to Vite's `root`. The page reloads rather than hot-swapping the component because a custom element tag can be defined only once, so a new class cannot replace the running one.
-
-When installing, we recommend installing `vite-plus` first and then `ts-dom` (when both are installed in the same npm run, `vite` may not be hoisted to the top level).
-
-### Lint (optional)
-
-```ts
-// lint settings in vite.config.ts (vp lint / oxlint)
-lint: {
-  ignorePatterns: ["node_modules", "dist", "**/*.html.ts"],
-  jsPlugins: [{ name: "ts-dom", specifier: "@nativele/ts-dom/oxlint" }],
-  rules: {
-    "ts-dom/unused-markup": "error",
-    "ts-dom/a11y": ["warn", { ignore: [] }], // optional: ARIA checks, see "ARIA / Accessibility Checks"
-    "ts-dom/data-flow": ["warn", { ignore: [] }], // optional: avoid passing props and events layer by layer, see "Data Flow"
-  },
-},
-```
-
-Each rule id is also a rule of its own, so a project can enable rules one by one and give each its own severity, for example `"ts-dom/unused-ref": "warn"` or `"ts-dom/missing-handler": "error"` instead of the whole `ts-dom/unused-markup` group. `ts-dom rules` lists the ids.
-
-**In the editor.** Install the Oxc extension for VS Code (it runs `oxlint --lsp`) and keep the plugin in your oxlint config: the findings show on the template's import line as you type, and `missing-handler` offers a quick fix that adds the method to the component class. From the command line, `oxlint --fix-suggestions` applies the same fix. A fix can only change the file being linted, so problems that live in the HTML (an unused `data-ref`, broken markup) are reported but not fixed there; for markup structure and layout use a formatter such as oxfmt.
-
-Without oxlint, the same checks are available through the CLI:
-
-```sh
-npx ts-dom lint [dirs...]   # unused markup (errors) and data flow suggestions (warnings)
-npx ts-dom lint --a11y      # additionally check ARIA / accessibility (warnings)
-npx ts-dom lint --strict    # warnings also make the exit code 1 (errors always do)
-npx ts-dom lint --json      # output JSON: { "issues": [{ file, line, col, severity, rule, message }] }
-npx ts-dom rules            # list all rule ids and descriptions
-npx ts-dom rules --explain=unused-ref   # why the rule exists, a wrong example and the fix
-npx ts-dom rules --json     # every rule as data: { id, group, description, why, bad, good }
-```
-
-Every message has the same format. It explains **what is wrong, why, and how to fix it**, and includes the line and column in the HTML:
-
-```
-a.html:2:1 error [unused-ref] data-ref="dead" is never used by the component class. Fix: use this.refs.dead, or remove the attribute if the element needs no TypeScript access.
-a.html:3:1 warning [unknown-prop] <x-kid lable> is not a declared prop of <x-kid>. Declared props: label, count. Did you mean "label"? Fix: declare "lable" in the child's props option, or remove the attribute.
-```
-
-Exit codes: 0 = no problems, 1 = there are errors (or warnings when `--strict` is used). Messages from the oxlint plugin start with `./x.html.js:line:column [rule id] message` and are reported on the `import` line.
-
-Recommended check workflow: `ts-dom check` (it runs `gen`, `tsc` and `lint` in one pass; see "Checks").
-
-## How Types Are Generated
-
-Next to each `x.html`, an `x.html.ts` is generated (already added to `.gitignore`; a `ts-dom-tags.ts` is generated as well, see "Composition"). It is a real TS module that contains both the parsed markup of this template (as data that the runtime turns into DOM nodes with DOM calls, so no HTML string is parsed in the browser) and its schema, so `tsc` can compile and check it directly.
-
-```ts
-// user-card.html.ts (auto-generated)
-import { template } from "@nativele/ts-dom";
-import type { El } from "@nativele/ts-dom";
-export default template<{
-  refs: { "toggle": El<"button"> };
-  lists: { "tags": { refs: {}; text: "label"; ifs: "hot" } };
-  ifs: "admin";
-  slots: "extra";
-  text: "name";
-}>([["h2", {}, ["Hello, {{ name }}!"]], /* ... */]);
-```
-
-Whole-page documents are page entry points, not templates, and are not processed. A file is a page when its content starts with `<!doctype html>` or `<html>` (comments before it are fine); the file name does not matter, so `index.html`, `main.html` and `login.html` all work. A template is a fragment of a component, so `<html>`, `<head>` and `<body>` are rejected in it (rule `document-tag`): the browser would drop them from the fragment and whatever you put on them would have no effect. To keep a file out of generation in another way, use `--exclude`.
-
-## HTML Syntax
-
-There are only a few kinds of markup, plus one kind of hole.
-
-| Markup | Meaning | TS side |
-|---|---|---|
-| `data-ref="name"` | Get the element; the type is derived from the tag | `this.refs.name` |
-| `data-if="name"` | Conditional block, **hidden by default** (removed from the DOM); shown only when TS says so | `this.show("name", bool)` |
-| `<template data-each="name">` | List; the content must be exactly one root element | `this.lists.name` |
-| `<slot name="x">` | Slot | The user provides child nodes with `slot="x"` |
-| `{{ name }}` | Text hole; the same name may appear in multiple places | `this.text.name = value`, or bound automatically from `state` |
-| `data-on-click="method"` | Event: calls the component method of that name (event names must be lowercase) | `method(e, hit)`, see "Events" |
-
-Rules for holes:
-
-- A hole must be a single identifier. `{{ data.name }}` and `{{ a + 1 }}` cause an error at codegen time.
-- Holes are only for text nodes; they are not supported inside attributes (`title="{{ x }}"` is an error). When needed, get the element with `data-ref` and set it in TS.
-- Content inside `<style>` and `<script>` is not treated as holes.
-- A value of `null`, `undefined`, or `false` is displayed as an empty string.
-
-## Components
-
-```ts
-class MyEl extends Component(tpl) {}                    // default: Light DOM
-class Iso extends Component(tpl, { shadow: true }) {}   // optional: Shadow DOM
-```
-
-Provided members:
-
-| Member | Description |
-|---|---|
-| `refs` | The elements corresponding to `data-ref` |
-| `text` | Holes; assigning a value updates every place where the hole appears |
-| `lists` | List objects |
-| `show(name, on)` | Toggle a `data-if` (hidden by default) |
-| `props` / `emit(name, detail)` | When using the `props` and `emits` options: data given by the parent (read-only) and events emitted upward, see "Data Flow" |
-| `slotchange(name)` | Override to react to later changes of slot content in Light mode |
-| `assignedNodes(name)` | The nodes currently assigned to that slot (excluding fallback content); behaves the same in Light and Shadow |
-| `bind(store, fn)` | Subscribe to a store, call once immediately, and unsubscribe automatically when the element is removed |
-| `on(target, type, fn)` | Attach a native event listener, removed automatically when the element is removed; returns a function for manual removal. Event types and parameters are inferred from `HTMLElementEventMap` |
-| `onCleanup(fn)` | Register a cleanup function to run when the element is removed |
-| `root` | The element itself (default), or the `ShadowRoot` (`shadow: true`) |
-| `connected()` / `disconnected()` | Override to attach your own behavior |
-
-The lifecycle is the Custom Elements `connectedCallback` / `disconnectedCallback`; you can also override them directly (remember to call `super`).
-
-### Light (default) and Shadow
-
-ts-dom does no style management, so by default it renders into the element itself (Light DOM): what you see in the DOM is the structure you wrote, CSS is global, and id references for forms and ARIA work as usual. `shadow: true` uses Shadow DOM instead.
-
-| | Light (default) | `shadow: true` |
-|---|---|---|
-| Render location | The element itself | The element's open shadow root |
-| Styles | Global; `<style scoped>` can scope locally | Native isolation: document styles do not get in, and the component's `<style>` does not leak out; `:host` works |
-| `<style>` | Extracted and injected into `document.head` only once | Stays inside the shadow root, not injected into `<head>`; the `scoped` attribute has no effect |
-| `<slot>` | Moved once at creation, then maintained by a `MutationObserver` | Native to the browser |
-| Slot change notification | Override `slotchange(name)` | **Native `slotchange` event** (`slot.addEventListener("slotchange", …)`); the `slotchange(name)` method is only called in Light mode |
-| `assignedNodes(name)` | Yes | Yes (equivalent to native `slot.assignedNodes()`) |
-| `state`, `props`, `derive`, `emit`, `data-on-*`, lists, `data-if`, attributes | All supported | All supported, with the same behavior |
-| Forms | Naturally compatible with outer forms | You must handle `ElementInternals` yourself |
-
-Shadow DOM is verified in real Chrome ([browser/shadow.test.ts](browser/shadow.test.ts), 18 tests), covering: rendering and style isolation, `:host`, native slots and `slotchange`, attributes and props (including assignment before upgrade), `state` / `derive` / `data-if`, event delegation (including non-bubbling `focus`), `emit` not bubbling to `window`, child components inside list items (`hit.key`), **a Shadow parent containing a Light child and a Light parent containing a Shadow child**, and the fact that content a user puts into a slot is not treated as the component's own `data-on-*`.
-
-Light-mode slot rules:
-
-- Matching is by `slot="name"`. Nodes without a slot attribute go into the default slot, and when there is no content, the fallback content inside `<slot>` is used.
-- `{{ }}`, `data-ref`, and `data-if` in user content are not parsed; they belong to the user's own DOM.
-- As with native Shadow DOM, only the **direct child nodes of the host element** are assigned (nodes nested deeper are not). Child nodes added to the element after creation are assigned to the matching slot; when the `slot` attribute of an assigned node is changed, it is reassigned immediately; when an assigned node is removed, the fallback content is restored if that slot becomes empty; nodes with no matching slot are not rendered, consistent with native behavior. These changes call `slotchange(name)` (the initial assignment at creation does not).
-- Dynamic changes rely on a `MutationObserver`, which observes only while the element is connected and is disconnected on removal.
-
-```ts
-class Card extends Component(tpl) {
-  override slotchange(name: "head" | "") { console.log("slot changed", name); }
-}
-```
-
-### Styles
-
-A top-level `<style>` in a template can be written in two ways in Light mode:
-
-```html
-<style>
-  user-card .tag { color: gray }   /* global: shared by the whole document */
-</style>
-<style scoped>
-  :scope { display: block }        /* scoped: only applies inside <user-card> */
-  .tag { color: gray }
-</style>
-```
-
-- `<style>` **must be at the first level of the HTML** and must not be wrapped by other elements (including `<template data-each>` and `data-if` elements); otherwise codegen reports an error.
-- Both are injected into `document.head` only once and are not duplicated per instance.
-- In supporting browsers, `scoped` uses native CSS `@scope (<tag name>)`; where it is unsupported it falls back to CSS nesting automatically (`<tag name> { ... }`, with `:scope` converted to `&`). Neither needs a CSS parser. The precedence of `@scope` is decided by "proximity to the root", not by specificity alone.
-- In Light mode `:host` has no effect, and a warning is logged to the console at runtime; use a tag selector or `:scope` instead.
-- With `shadow: true`, `<style>` stays inside the shadow root and the `scoped` attribute has no effect.
-
-## Data and View: state (optional)
-
-The simplest usage: give `Component` a `state`, and change data only with `this.set()`.
-
-```ts
-class Counter extends Component(tpl, {
-  state: { title: "Todo", items: [] as Item[], filter: "all" },
-  derive: { remaining: (s) => s.items.filter((i) => !i.done).length }, // derived value
-}) {
-  add(e: Event) {
-    this.set((s) => ({ items: [...s.items, { id: nextId++, title: "x", done: false }] }));
-  }
-  override render(view, changed) {
-    // whatever automatic binding cannot handle (lists, attributes, focus…) goes here
-    if (changed.has("items")) this.lists.items.replace(view.items, (i) => i.id, (i, { text }) => (text.title = i.title));
-  }
-}
-```
-
-| Member | Description |
-|---|---|
-| `state` | The current data, read-only. Use `set` to change data |
-| `set(patch)` / `set(s => patch)` | **The only entry point for changing data**: shallow-merges the patch; **if no field actually changes (`Object.is`), it does nothing** and `render` is not called. When something changes, it updates the automatic bindings synchronously and then calls `render` |
-| `render(view, changed)` | Override it to handle updates other than automatic binding. `view` is `state` plus the derived values, and `changed` is the set of state fields that changed this time (all of them on the first render). Use `changed.has("x")` to skip the parts that did not change |
-| `batch(fn)` | Combine multiple `set` calls: after `fn` finishes, the update runs once and `render` is called once |
-| `derive` option | Derived values, usable directly by `{{ }}`, `data-if`, and `render`. They are recomputed after every state change, with **no dependency tracking** |
-
-**Automatic binding**: `{{ name }}` and `data-if="admin"` map to the same-named state field (or derived value) and are written automatically when the field's value changes; `data-if` shows the block based on truthiness. **Names are checked by tsc**: when the HTML uses a name that neither `state` nor `derive` has, `class X extends Component(...)` reports an error that lists the missing names (the error message is `missingStateKeys: "name"`). Lists (`data-each`) are not bound automatically, because the key and how each item is filled are for you to decide; use `replace` in `render`.
-
-Design trade-offs:
-
-- **Synchronous**: when `set` returns, the view has already been updated. There is no implicit asynchronous batching, so reading the DOM right after `set` always gives the new state. To combine updates, use `batch` explicitly.
-- **No fine-grained updates**: on every change, `render` re-runs as a whole, and its cost depends on what you write in it. For large lists, use `changed` to skip unnecessary redraws and enable `skipUnchanged` on `replace` (see "Lists").
-- `set` may be called inside `render`; it is processed in another round after the current one ends. If it has not stabilized after 50 consecutive rounds, a "suspected infinite loop" error is thrown.
-- When `state` is not used, the original `refs`, `text`, `show`, `bind`, and `createStore` work as before, fully backward compatible.
-
-**Read-only all the way down**: `state`, `props`, the `view` passed to `render` and the argument of each `derive` function are typed `DeepReadonly`: arrays and objects inside them cannot be changed in place. `this.state.items[0].done = true` or `this.state.items.push(x)` is a `tsc` error, because an object changed in place keeps its identity and the list and child props, which compare by reference, would not update. Pass new objects instead: `this.set((s) => ({ items: s.items.map((i) => (i.id === id ? { ...i, done: true } : i)) }))`. When you annotate `render`'s `view` or a helper that takes the state, use read-only types (`readonly Item[]`, or `DeepReadonly<State>` from `@nativele/ts-dom`).
-
-## Events: data-on-*
-
-HTML writes only the event name and the method name; the logic is in TS:
-
-```html
-<form data-on-submit="add">…</form>
-<template data-each="items"><li><button data-on-click="removeItem">✕</button></li></template>
-```
-
-```ts
-add(e: Event) { e.preventDefault(); … }
-removeItem(e: Event, hit: EventHit) { this.set((s) => ({ items: s.items.filter((i) => i.id !== hit.key) })); }
-```
-
-- The method receives `(event, hit)`. `hit.el` is the element carrying the `data-on-*`; when the event happens inside a list item, `hit.key` is that item's key and `hit.item` is the data most recently passed to `update`; this also holds for events emitted by a child component placed inside the item. `hit.item` is `unknown` unless the handler annotates it, e.g. `hit: EventHit<Todo>`. If you need extra parameters, put them in `data-*` attributes and read `hit.el.dataset` in the method.
-- **Event delegation**: only one listener per event type is attached at the component root, so a longer list does not add listeners, and adding or removing items needs no rebinding. Non-bubbling events (`focus`, `blur`, `mouseenter`, etc.) use the capture phase and handle only the target itself; for bubbling events, the handler methods are called in order from the inside out, and `stopPropagation()` stops the chain.
-- **Only elements in the component's own template count**: content a user puts into a slot does not trigger anything even if it has `data-on-click`.
-- Only a method name may be written; `add(1)` and `a.b` cause an error at codegen time. A method name must not collide with DOM built-in methods or ts-dom members (for example `remove`, `click`, `focus`, `set`, `render`); otherwise they would be overridden, and codegen reports an error and suggests renaming.
-- **tsc checks that the method exists**: `define(name, Class)` checks that every method referenced by the HTML is a public member of the class, and reports an error listing the names when one is missing (`missingHandlers: "name"`). The check runs again when the element is connected to the page and throws a clear runtime error.
-- Event names must be lowercase (HTML attributes are case-insensitive); for mixed-case events such as `DOMContentLoaded`, use `this.on()` instead.
-
-## Composition: Using Multiple Components Together
-
-Each `.html` plus its TS is one component (a custom element), and writing its tag in another template is composition:
-
-```html
-<!-- signup-form.html -->
-<form-field data-ref="name" label="Name" data-on-field-input="onName"></form-field>
-<template data-each="entries">
-  <li><entry-row data-ref="row" data-on-remove-entry="removeEntry"></entry-row></li>
-</template>
-```
-
-```ts
-render(v) {
-  this.refs.name.value = v.name;          // data down: the child's props, fully typed
-  this.lists.entries.replace(v.entries, (x) => x.id, (x, { refs }) => { refs.row.name = x.name; });
-}
-onName(e: Event) {                         // event up: sent only to the direct parent of this tag
-  this.set({ name: (e as EmitEvent<FormField, "field-input">).detail.value });
-}
-```
-
-Composition needs three things, and ts-dom handles all of them:
-
-- **Child components are loaded automatically**: for a tag used in a template (its name contains a hyphen), if there is a `define("tag", Class)` in the scanned directories, `ts-dom gen` automatically adds `import "./child.js"` to the generated `x.html.ts`. HTML is the single source of dependencies, and you do not need to `import` child components yourself (referencing a type with only `import type` does not register the element, which is an easy trap to fall into). Components outside the directories, or third-party ones, still need to be imported by you.
-- **Child component types**: `ts-dom gen` scans `define("tag", Class)` (the class must be `export`ed) and generates `ts-dom-tags.ts`, which registers the components in `HTMLElementTagNameMap`. As a result, for `<form-field data-ref="name">` in a template, `refs.name` is `FormField`: prop names and types, and methods, are all checked by tsc. This file is already in `.gitignore` and, like `.html.ts`, is generated by `gen`.
-- **Slots can cross layers**: for content the parent puts into a child component's slot, its `{{ }}` belongs to the parent and is updated by the parent; `data-on-*` is also handled by the parent, and the child does not catch it by mistake.
-
-"Template fragment include" is not provided: it would become a template-language feature. To share a piece of structure, make it a component.
-
-## Data Flow: props Down, Events Up
-
-`props` and `emits` are two options besides `state` that give the data flow between parent and child components clear rules:
-
-```ts
-class FormField extends Component(tpl, {
-  props: { label: "", value: "", error: "" },      // given by the parent (read-only)
-  state: { touched: false },                       // owned by itself
-  derive: { showError: (s) => s.touched && s.error !== "" },
-  emits: { "field-input": event<{ value: string }>() },   // events emitted upward
-}) {
-  onInput() {
-    this.set({ touched: true });
-    this.emit("field-input", { value: this.refs.input.value });
-  }
-}
-```
-
-| | Owner | Who can change it | How |
-|---|---|---|---|
-| `state` | The component itself | The component itself | `this.set()` |
-| `props` | The parent | The parent | HTML attribute (`user-name="Ada"`) or JS property (`el.userName = "Ada"`) |
-| Events | Emitted by the component itself | Anyone can subscribe | `this.emit(name, detail)` |
-
-- The default value of a prop determines its type and how the attribute is converted: `string`, `number` (an invalid number warns and uses the default), `boolean` (the attribute being present means `true`; `"false"` and removal mean `false`). Arrays and objects can only be passed through JS properties. camelCase names map to kebab-case attributes: `maxLength` ↔ `max-length`.
-- Like `state` and `derive`, `props` can be bound automatically by `{{ }}` and `data-if`, and also appear in the `view` and `changed` of `render`; a prop assigned before the element is upgraded is not lost either.
-- Events in `emits` **do not bubble** by default, and only the child's own tag can receive them: the handler is always written on `<child data-on-xxx="method">` in the parent's HTML, so you can see from the HTML where data goes. Declare `event({ bubbles: true })` explicitly only when you need bubbling.
-- The event's data type is obtained from `EmitEvent<FormField, "field-input">` (`CustomEvent<{ value: string }>`).
-
-### Safeguards in Types and at Runtime
-
-| Problem | Safeguard |
-|---|---|
-| Modifying a prop with `set()` inside the component | The type of `set` does not include props; a clear error is thrown at runtime |
-| `emit` of an undeclared event, wrong data type, or missing data that should be provided | tsc reports an error; an undeclared event throws an error at runtime |
-| `state` / `props` / `derive` with the same name | tsc reports an error (`conflictingKeys`); an error is thrown when `Component()` is called |
-| A prop name that is the same as a member of `HTMLElement` or ts-dom (`title`, `hidden`, `render`…) | tsc reports an error (`reservedPropNames`); an error is thrown at runtime |
-| `emits` with the same name as a native event (`click`, `input`…) | tsc reports an error (`nativeEventNames`); an error is thrown at runtime |
-| The parent gives the child a prop with a wrong name or type | tsc reports an error (types come from `HTMLElementTagNameMap`) |
-
-### Avoiding Layer-by-Layer Passing (lint: `ts-dom/data-flow`)
-
-A common problem in Vue is re-emitting layer by layer and passing props down layer by layer (prop drilling and emit chains), which is held back only by habit. Besides "events do not bubble by default", there are lint hints here (suggestions only, not errors):
-
-| Id | Detection |
-|---|---|
-| `prop-forwarding` | Assigning your own prop as-is to a child component (`this.refs.kid.name = v.name`, where `name` is your own prop) |
-| `emit-forwarding` | A method that handles a child event merely `emit`s the event again (with the same name, or the whole method is just one `this.emit(...)`) |
-| `props-mutation` | Assigning to props inside the component (`this.count = …`) |
-| `custom-event-on-native` | Writing a custom event on the `data-on-*` of a native element (a child component's events do not bubble, so it would never be received) |
-| `unknown-prop` | An attribute written on a child component's tag is not a prop it declares (hints "Did you mean …") |
-| `invalid-prop-value` | The attribute cannot set that prop: the prop is not string / number / boolean (it can only be passed through JS properties) |
-| `unknown-event` | `data-on-xxx` is written on a child component's tag, but the child does not declare (`emits`) this event and it is not a native event either |
-
-The last three are **HTML-level props / emit checks**: `tsc` checks `refs.child.prop` and `emit()` in TypeScript, while these three rules check the child component attributes and events written in the **parent's HTML**. They read the child components from `define("tag", Class)` in the directories and extract the declarations from `Component(tpl, { props, emits })`; when no child component definition is found (for example a third-party component), nothing is checked.
-
-
-Recommended practices:
-
-- **Data and events cross only one layer**: the parent owns the data and passes props down, and the child notifies with events.
-- **Data shared across many layers uses a shared store**: put `createStore` in a separate module, and have the components that need it import it directly and subscribe with `this.bind(store, fn)`, so the intermediate layers do not need to know about it or forward it.
-- When an event has to cross two layers, handle it explicitly in the middle layer (it has its own logic) instead of forwarding it as-is.
-
-```ts
-// session.ts — components at any depth can use it directly, no layer-by-layer passing
-export const session = createStore({ user: "Ada" });
-// deep component
-connected() { this.bind(session, (s) => (this.text.user = s.user)); }
-```
-
-Enable it the same way as other lint rules: `"ts-dom/data-flow": ["warn", { ignore: [] }]`, or the CLI `npx ts-dom lint` (which also shows data flow warnings; adding `--strict` makes the exit code 1).
-
-### A Small Reminder About Form Inputs
-
-When writing data back to an `<input>` in `render`, first compare whether the value is the same: when data returns to the child component through "input → emit → parent → props", writing the same value again makes the cursor jump to the end.
-
-```ts
-if (changed.has("value") && this.refs.input.value !== v.value) this.refs.input.value = v.value;
-```
-
-The example [examples/signup](examples/signup/signup-form.ts) does exactly this, and a real Chrome test verifies that the cursor position does not jump.
-
-## Performance
-
-`npm run bench` runs a large list benchmark in real Chrome and prints this table. Each item shows one text; the times are the median of 5 runs and count script execution only (no layout or paint). They were measured on one machine (Chrome on WSL), so read them as proportions, not absolute numbers. "Direct DOM" is a hand-written keyed list with plain DOM calls, the floor any library adds to.
-
-| Approach | Items | Create | Update 10% | Reverse | Remove half | Append 1,000 |
-|---|---|---|---|---|---|---|
-| Components (`items =`) | 1,000 | 15.4 ms | 0.5 ms | 1.8 ms | 1.1 ms | 14.6 ms |
-| Components (`items =`) | 5,000 | 80.5 ms | 1.6 ms | 10 ms | 5.4 ms | 17.6 ms |
-| Components (`items =`) | 10,000 | 160.6 ms | 3.2 ms | 21 ms | 11.3 ms | 16 ms |
-| Plain elements (`replace()`) | 1,000 | 2.8 ms | 0.1 ms | 0.7 ms | 0.2 ms | 2.9 ms |
-| Plain elements (`replace()`) | 5,000 | 15.8 ms | 0.7 ms | 4.3 ms | 1.7 ms | 3.7 ms |
-| Plain elements (`replace()`) | 10,000 | 42 ms | 1.4 ms | 8.6 ms | 3.3 ms | 4.4 ms |
-| Direct DOM (baseline) | 1,000 | 0.8 ms | 0.2 ms | 1 ms | 0.3 ms | 0.8 ms |
-| Direct DOM (baseline) | 5,000 | 4 ms | 0.8 ms | 4.3 ms | 1.6 ms | 1.1 ms |
-| Direct DOM (baseline) | 10,000 | 8.7 ms | 1.7 ms | 10.9 ms | 3.9 ms | 1.6 ms |
-
-- Creating component items costs about 15 µs per item, because each item is a custom element with its own template, refs and lifecycle; plain elements cost about 3–4 µs and direct DOM about 1 µs.
-- Once the items exist, updating, reordering and removing them stay within about two times of direct DOM: only items that are a new object are touched, and kept elements are moved, not rebuilt.
-- A frame has about 16 ms. A list of a few thousand component items is comfortable; for tens of thousands, use plain elements with `replace()`, show a page or a window of the list at a time, or keep component items for the rows that need state and events.
-- Event delegation adds no listeners as the list grows.
-
 ## Examples
 
 - [examples/signup](examples/signup/signup-form.ts): a signup form. Three components composed (`signup-form` → `form-field`, `entry-row`), covering `props` down, `emits` up, child components inside lists (`hit.key`), `derive` validation, and form input without cursor jumps; the corresponding real Chrome test is in [browser/signup.test.ts](browser/signup.test.ts).
 - [examples/user-card](examples/user-card.ts): the minimal example, covering `state` automatic binding, `data-on-click`, lists, and slots.
 - [examples/todo](examples/todo/todo-app.ts): a complete todo list, covering `state` and `derive`, `data-on-*` event delegation (including `hit.key` for list items), filtering, an empty state, `aria-pressed`, and `skipUnchanged`; it has a corresponding real Chrome end-to-end test ([browser/todo.test.ts](browser/todo.test.ts)).
+- [examples/recipes](examples/recipes/contact-app.ts): a contacts screen for the [Recipes](https://github.com/Pixmi/nativele/blob/main/docs/recipes.md) guide, covering loading and error states from a shared store, a filtered list, a modal dialog with form validation, and typed `hit.key`; its real Chrome test is [browser/recipes.test.ts](browser/recipes.test.ts).
 
-## State: store (when not using state)
-
-```ts
-const store = createStore({ count: 0 });
-store.get();
-store.set({ count: 1 });
-store.set((s) => ({ count: s.count + 1 }));
-const off = store.subscribe((s) => console.log(s)); // returns an unsubscribe function
-```
-
-`this.bind` also accepts a read-only source that has only `get` and `subscribe`. There is no dependency tracking: after `set`, all subscribers are called; if the value is the same under `Object.is`, no notification is sent. It is a small utility for when the `state` option is not used, and you may also skip it entirely, manage state yourself, and write directly to `refs` / `text`. When you need automatic binding and `render`, use `state` above instead.
-
-## Templates Without a Component
-
-`tpl.instantiate()` builds a template without a custom element and returns the same typed handles a component has: `root` (a `DocumentFragment`), `refs`, `lists`, `text` and `show`. Use it for small pieces created in code, such as a menu item added to a list:
-
-```ts
-import itemTpl from "./menu-item.html.js";
-
-function menuItem(label: string): HTMLLIElement {
-  const view = itemTpl.instantiate();
-  view.text.label = label;
-  view.refs.button.addEventListener("click", () => select(label));
-  return view.rootElement; // typed by the template's top-level tag
-}
-```
-
-`rootElement` is the template's only top-level element (a top-level `<style>` does not count); it exists in the type only when the template has exactly one, so a template that later gains a second root element makes `tsc` report the use.
-
-There is no host element, so `data-on-*` attributes do nothing here (listen on `refs`) and `<slot>` is not projected; use a component when you need those.
-
-## Lists
-
-There are two ways to fill a list, and one rule decides between them: **an item that has anything of its own (state, events, a nested list) is a component, filled with `items =`; an item that is a few texts and `data-if` is plain elements, filled with `replace()`.** Example 4 shows the first, Example 2 the second.
-
-### Items as components: `items = ...`
-
-Name the field that identifies an item and the property that receives it, on the `<template data-each>`; the item is one custom element:
-
-```html
-<ul>
-  <template data-each="todos" data-key="id" data-prop="todo">
-    <todo-row role="listitem" data-on-toggled="toggle"></todo-row>
-  </template>
-</ul>
-```
-
-```ts
-render(view, changed) {
-  if (changed.has("todos")) this.lists.todos.items = view.todos;
-}
-toggle(_e: Event, hit: EventHit) { /* hit.key is the item's id */ }
-```
-
-Assigning `items` keeps the element of each key that stays (moved with `moveBefore` where the browser has it, so focus and state survive), creates one for a new key, removes the ones that are gone, and sets `todo` on each element whose item is not the same object as last time. Use immutable updates: changing a field of an object you already assigned and assigning the same object again does not update the item component, because props are compared by reference; assign a new object instead, for example `{ ...todo, done: true }`. The item component declares `todo` in its `props`, shows it however it likes, and tells the parent with `emit`; the parent reads `hit.key` in the handler. Reading `items` returns what was last assigned. `tsc` checks the assignment: each item must have the type of the `todo` property that `<todo-row>` declares and a `data-key` field (`id`), and the item component must declare the `data-prop` property; a list without `data-key` and `data-prop` takes no items. This relies on the component being registered in `ts-dom-tags.ts` (an exported `define("todo-row", TodoRow)` in a scanned directory). When the component is defined in a scanned directory but its class is not exported, or `ts-dom-tags.ts` does not list it yet, the assignment is a type error that says so (`itemComponentClassNotExported`, `itemComponentMissingFromTagMap`); only a component from outside the scanned directories accepts any item with the `id` field. At runtime, assigning throws when the value is not an array of objects, when an item has no string or number `id`, when two items share one, or when the template has no `data-key` and `data-prop`.
-
-Inside a `<ul>` or `<ol>` the item component needs `role="listitem"`, because a custom element is not an `<li>`; the accessibility check (`list-structure`) asks for it. `data-each` cannot be nested, on purpose: an item is one component, so a list inside an item is that component's own `data-each`. Every template then holds one level, with its own `refs`, `text` and event handling.
-
-### Items as plain elements: `replace()`
-
-```html
-<ul>
-  <template data-each="tags">
-    <li><span>{{ label }}</span> <b data-if="hot">🔥</b></li>
-  </template>
-</ul>
-```
-
-```ts
-this.lists.tags.replace(
-  tags,
-  (t) => t.id, // key
-  (t, { text, refs, show, el }) => {
-    text.label = t.label;
-    show("hot", t.hot === true);
-  },
-);
-```
-
-| Method | Description |
-|---|---|
-| `replace(items, key, update, opts?)` | Keyed reconciliation: remove the extra items, create the missing ones, reorder in sequence, and call `update` for each item. With `opts.skipUnchanged: true`, `update` is skipped when the item reference is the same as last time (off by default: it is safe only when you use immutable updates; if you mutate objects directly, the view stays on the old value) |
-| `upsert(key, item, update)` | Add (at the end) or update a single item |
-| `remove(key)` | Remove a single item |
-| `clear()` | Clear everything |
-| `has(key)` / `get(key)` / `size` | Queries |
-
-`replace` only does one-dimensional key matching; the DOM nodes of existing items are kept and moved, and subtrees are not compared. The content of an item is entirely decided by your `update`.
-
-Notes:
-
-- `data-ref`, holes, and `data-if` inside an item belong to that item and do not appear in the component-level `refs` / `text`.
-- `data-if` cannot be placed on an item's root element; wrap it in one more layer.
-- `data-each` cannot be nested. Split it into two templates: put the inner list in its own `.html` (a child component with its own `data-each`) and use that component's tag inside the outer item.
-- `<slot>` cannot be placed inside an item.
-
-### Moving items, connecting and subscriptions
-
-- In a browser with `moveBefore`, a moved item stays connected: neither `disconnected()` nor `connected()` runs, and its focus, scroll position and subscriptions are untouched.
-- In a browser without it, a moved item is taken out and put back: `disconnected()` runs and releases everything registered with `bind`, `on` and `onCleanup`, then `connected()` runs again. Its element, props and state stay the same.
-- So subscribe in `connected()` (`this.bind(store, ...)`, `this.on(...)`), not in the constructor or a field initializer: then the subscription is made again after a move in every browser. A subscription made in the constructor is released by the first move and never comes back.
-- Data that every item needs (a theme, the current user, a registry) belongs in a `createStore` that the item component binds in `connected()`, not copied into every item object.
-
-### Order of list updates
-
-Assigning `items` sets the `data-prop` property of a new item before its element goes into the document, so the item component is connected with its item already set and its first render shows it. `replace()` and `upsert()` put a new item's element into the document first and then call `update`, so a child component placed in such an item is connected before the parent has set its properties; there, build per-item state when the child first receives data (for example in a property setter), and guard a render in `connected()` with the data it needs.
-
-## Trusted Types, Translations and Icons
-
-- Trusted Types: pages that enforce `require-trusted-types-for 'script'` work with no policy, because `ts-dom gen` writes the markup as data and the runtime builds it with DOM calls. Your own code must avoid `innerHTML` too.
-- Translations: ts-dom has no i18n. Write the translated string into a hole, `this.text.title = t("title")`, or into `render()` for attributes; the HTML stays free of words if you want it that way.
-- Icons: ts-dom does not manage icons. Make an icon a custom element of your own that builds its SVG with `createElementNS` from whatever source you use, and place it in a template as a child component:
-
-```html
-<app-icon name="send" class="size-4"></app-icon>
-```
-
-- Reordering: a keyed list (`data-each`) moves its items with `moveBefore` where the browser has it, and every component accepts the move without being disconnected, so a moved item keeps its focus, scroll position and subscriptions.
-
-## Checks
-
-Each tool checks what it can see, and none repeats another:
-
-| Tool | What it checks |
-|---|---|
-| A formatter such as oxfmt (`oxfmt --check`, or `vp fmt --check`) | Whether the template markup is well formed (a misnested closing tag such as `<p><div></p></div>` is a syntax error there, while the HTML parser the library uses would silently repair it into a different tree) and laid out consistently. It knows nothing of `{{ }}` or `data-*` names. Generate with whitespace `collapse` when you use one, or reformatting can change the spacing on the page. |
-| `ts-dom gen` | The template rules: holes, `data-each`, `data-if`, `data-on-*`, forbidden markup. |
-| `tsc` | That every name in the HTML exists in the component with the right type, and that lists, props and events fit. |
-| `ts-dom lint` / the oxlint plugin | What the HTML declares but the class never uses, data flow between components, accessibility. |
-| `ts-dom doctor` | The project set-up that the other tools depend on. |
-| `ts-dom check` | Runs `gen`, `tsc` and `lint` in one pass and points the template contract errors at the template. |
-
-Four complementary checks. **Every message has a stable rule id and explains what is wrong, why, and how to fix it**; `npx ts-dom rules` lists all rules.
-
-**When the set-up itself may be wrong: `npx ts-dom doctor [dirs...]`.** It checks what a project needs before any of the checks can work: a tsconfig with `strict`, the DOM lib, a module resolution that maps `./x.html.js` to the generated file and an `include` that covers the template folders; the runtime package being installed; templates imported as `./x.html.js` (not `./x.html`); generated files that are stale; the Vite plugin and the oxlint plugin being configured; and, when a formatter such as oxfmt or Prettier is set up, templates generated with whitespace `collapse`. Every issue has a stable rule id and a `Fix:` hint, and `--json` prints them as data.
-
-**One command for all of them: `npx ts-dom check [dirs...]`.** It reports template diagnostics, regenerates the generated files (with `--no-write` it reports stale ones instead), runs the project's own `tsc` (TypeScript 5, 6 or 7; `--project=` picks the tsconfig), and runs the lint rules (`--a11y` adds the accessibility checks). TypeScript errors that come from the template contract point at the template, not at the `Component(...)` call: a `{{ title }}` with nothing named `title` is reported at its line and column in the `.html` as `missing-binding`, and a missing handler as `missing-handler`; item component problems get their own rule ids, and the errors that only follow from a broken class are left out. `--json` prints the issues as data, and the exit code is 1 when there is an error (with `--strict`, a warning too).
-
-1. **codegen diagnostics** (`ts-dom gen` and the Vite plugin, with line and column numbers; on errors they abort and write no files): duplicate `data-ref`, `data-each` without a single root element, `data-each` not on a `<template>`, nested `data-each`, an incomplete or invalid `data-key` / `data-prop`, a `data-key` list whose item is not one custom element, `data-if` on an item root element, `<slot>` inside an item, `<style>` not at the first level, invalid holes, holes inside attributes, invalid `data-on-*` (including names that collide with DOM or ts-dom members), `<html>`, `<head>` and `<body>` inside a template, and markup that runs code or Trusted Types blocks: `<script>`, `on*` attributes, `srcdoc`, and `javascript:` URLs.
-2. **tsc**: an error when TypeScript uses a name the HTML does not declare (`this.refs.nope`, `this.show("nope", true)`); all constraints between `state`, `props`, `derive`, `emits` and the HTML (see "Data Flow"); child component prop names and types; `define()` checks that the methods for `data-on-*` exist.
-3. **Runtime**: `Component()` and components, at definition, connection, and use, throw errors that carry a `[rule id]` and a fix for the same problems.
-4. **lint** (`ts-dom/unused-markup`, `ts-dom/data-flow`, `ts-dom/a11y`): markup declared in the HTML but never used (errors, with the HTML location), data flow suggestions and child component contracts (warnings), ARIA (warnings).
-
-Rules of `unused-markup`:
-
-| Id | Detection |
-|---|---|
-| `unused-ref` | A `data-ref` is not used by the component |
-| `unused-if` | A `data-if` is never toggled (`data-if` is hidden by default, so the content never appears) |
-| `unused-text` | A `{{ hole }}` is never filled and displays blank |
-| `unused-list` | A `data-each` is never rendered, so the list is always empty |
-| `unused-item-name` | A name inside a list item is never referenced |
-| `missing-handler` | A method referenced by `data-on-*` is not defined by the class |
-| `no-importer` | No TypeScript file imports this template |
-
-lint compares per **class body** of `class X extends Component(tpl)`. When the `state` / `props` / `derive` options are used, `{{ }}` and `data-if` are handled by automatic binding and are not required to appear in the code, but the methods referenced by `data-on-*` must exist (if the code uses dynamic access such as `refs[k]`, `text[k]`, or `lists[k]`, it cannot tell which names are used, so it conservatively treats all of them as used). Hence importing multiple templates in the same file does not make them overwrite each other:
-
-```ts
-import listTpl from "./list.html.js";   // data-ref="title"
-import cardTpl from "./card.html.js";   // data-ref="title" (Card never uses it)
-class List extends Component(listTpl) { connected() { this.refs.title.hidden = true } }
-class Card extends Component(cardTpl) {}   // → reports that title in card.html is unused
-```
-
-Note: refs, text, and so on should be used by the component's own class. Access through an instance outside the class (for example in tests) is not counted, so turn this rule off for test directories. When no corresponding class can be found (for example when `Component` is wrapped by a helper), it falls back to comparing the whole file.
-
-## ARIA / Accessibility Checks
-
-**Off** by default. When enabled, it produces **warnings** (not errors) for places in the template where ARIA or a label is recommended. There are three ways to enable it, all sharing the same checks:
-
-```ts
-// 1. lint: shown by both the editor and vp lint, warnings are reported on the import line (the message contains the html line and column)
-lint: { rules: { "ts-dom/a11y": ["warn", { ignore: ["img-alt"] }] } }
-
-// 2. build: shown in the terminal during dev / build
-plugins: [tsDom({ a11y: true })]            // or { a11y: { ignore: ["img-alt"] } }
-```
-
-```sh
-# 3. CLI
-npx ts-dom lint --a11y [--strict]
-```
-
-`ignore` takes rule ids and can turn off individual checks:
-
-| Id | Check |
-|---|---|
-| `img-alt` | `<img>` needs `alt` (use `alt=""` for decorative images) |
-| `control-name` | `<button>`, `<a href>`, and `<summary>` need a readable name (text, `{{ }}`, `<slot>`, `aria-label`, or `aria-labelledby`) |
-| `form-label` | `<input>`, `<select>`, and `<textarea>` need a `<label for>`, to be wrapped by a `<label>`, or `aria-label` |
-| `iframe-title` | `<iframe>` needs `title` |
-| `dialog-name` | `<dialog>` needs `aria-label` or `aria-labelledby` |
-| `heading-empty` | `h1`–`h6` must not be empty |
-| `aria-role` | `role` must be a valid ARIA role |
-| `aria-attr` | `aria-*` must be a valid ARIA attribute |
-| `role-tabindex` | A non-natively-focusable element with an interactive role (button, tab, checkbox…) needs `tabindex` |
-| `tabindex-positive` | Do not use a `tabindex` greater than 0 |
-| `hidden-focusable` | A focusable element must not have `aria-hidden="true"` |
-| `label-for` | `<label for>` must point to an `id` that exists in the template |
-| `id-in-list` | An `id` inside a `data-each` item is duplicated with each item; use `data-ref` or a class instead |
-| `duplicate-id` | An `id` must not be duplicated within a template |
-| `aria-idref` | The ids referenced by `aria-labelledby`, `describedby`, `controls`, `owns`, etc. must exist in the template (use `ignore` to turn it off when pointing to elements outside the template) |
-| `heading-order` | Heading levels must not skip (`h3` directly after `h1`), judged by document order within the template |
-| `table-header` | `<table>` needs `<th>`; for layout tables set `role="presentation"` |
-| `list-structure` | The children of `<ul>`/`<ol>` (including the root element of a `data-each` item) must be `<li>`; `<li>` must be inside `<ul>`, `<ol>`, or `<menu>` |
-| `landmark-label` | When a template has multiple `<nav>` or `<aside>`, they need to be distinguished with `aria-label` |
-| `redundant-role` | `role` is the same as the element's native semantics, for example `<button role="button">` |
-| `click-semantics` | `data-on-click` should be on an operable element (`button`, `a[href]`, `label`, or an element with an interactive role plus `tabindex`); otherwise keyboards and assistive technologies cannot use it |
-
-To avoid many false positives, elements with `data-ref` are treated as "managed by TS", and the checks whose "name or reference may be set in TS" are skipped for them: `img-alt`, `control-name`, `form-label`, `iframe-title`, `dialog-name`, `heading-empty`, `role-tabindex`, `table-header`, `landmark-label`, `aria-idref`.
-
-This is a static check that looks only at the HTML template: it does not analyze attributes that TS adds at runtime, and it does not cover items that can only be judged with actual rendering, such as color contrast, focus management, and keyboard interaction, so it cannot replace tools like axe and manual testing.
-
-## Project Structure
-
-```
-src/lib/
-  component.ts      Component base class, define
-  list.ts           keyed lists
-  cond.ts           data-if
-  text.ts           {{ }} holes
-  slots.ts          slots for Light DOM
-  style.ts          style injection for Light mode, scoped
-  store.ts          createStore
-  template.ts       Template / Schema types
-  codegen.ts        parse5 parsing, diagnostics, generating .html.ts
-  vite-plugin.ts    optional Vite plugin (@nativele/ts-dom/vite)
-  lint.ts           unused markup and data flow checks
-  reserved.ts       reserved names (collisions with DOM and ts-dom members)
-  a11y.ts           ARIA / accessibility checks
-  oxlint-plugin.ts  oxlint JS plugin (@nativele/ts-dom/oxlint)
-src/cli.ts          ts-dom gen / lint
-examples/           user-card and todo list (todo) examples, demo entry
-test/               unit tests (happy-dom)
-browser/            real Chrome tests and fixtures
-```
-
-## Developing This Project
-
-| Command | Description |
-|---|---|
-| `npm run dev` | Start the demo (`vp dev`) |
-| `npm run build` | Build the demo into `demo-dist/` |
-| `npm run build:lib` | Build the library into `dist/` |
-| `npm run smoke` | After packing, verify `gen → tsc → lint → build` in a fresh project with Vite installed |
-| `npm run smoke:no-bundler` | After packing, verify `gen → tsc → running in a browser` in a fresh project with **only typescript installed** |
-| `npm run verify:pack` | Build and check the publishing configuration with `publint` and `attw` (runs automatically before `npm pack`) |
-| `npm run gen` | Generate the `.html.ts` files for examples and tests |
-| `npm run check` | Run `tsc` after `gen` |
-| `npm test` | Unit tests (happy-dom) |
-| `npm run test:browser` | Tests that run in real Chrome (see below) |
-| `npm run lint` | `vp lint`, including `ts-dom/unused-markup` |
-| `npm run lint:html` | The CLI version of the same checks |
-
-Examples in the repo point directly to `src/lib` through an alias in `vite.config.ts`, so no packing is needed first.
-
-### Browser tests
-
-`npm run test:browser` starts `vp dev` and drives the system-installed Chrome with `playwright-core` (no browser is downloaded), verifying behavior that happy-dom cannot cover: native `@scope`, slot assignment for parser-created elements, dynamic slots through `MutationObserver`, and native slots and style isolation in Shadow DOM.
-
-| Environment variable | Description |
-|---|---|
-| `CHROME_BIN` | Path to Chrome, default `/usr/bin/google-chrome` |
-| `TSDOM_CHROME_HOME` | HOME used by Chrome, default `/tmp/chome` (avoids crashpad write failures under WSL or a read-only home directory) |
-
-The tests always use `--no-sandbox --no-zygote`, which suits WSL and container environments; they can also run on an ordinary desktop.
-
-By default only Chromium is run, and CI also runs only Chromium: this library is a TS tool that relies on standard DOM APIs, not on CSS rendering, where browsers differ a lot. To try it on Firefox, use `BROWSER=firefox PLAYWRIGHT_BROWSERS_PATH=<path> npm run test:browser` (run `npx playwright-core install firefox` first; Firefox 157 has been verified to pass everything). WebKit is not verified.
-
-## Design Decisions
-
-These are deliberate trade-offs, not missing features:
-
-- **`{{ }}` is only a single identifier**: paths and expressions would give the HTML a second data shape and slide toward a template language. If you need computation, do it in TS and fill a named hole.
-- **No attribute binding**: get the element with `data-ref`, then set the attribute in TS.
-- **`<slot>` cannot be placed inside a `data-each` item**: items repeat, but user-provided content exists only once, and the semantics of native Shadow DOM are also that only the first slot of a given name gets the content. To give each item its own content, you would need a mechanism like a Vue scoped slot that "passes the item data to the slot", which would require expressions. Fill it in with TS in the `update` callback instead, or make the item content another component.
-- **The data flow goes in only one direction**: state is changed by itself, props are changed by the parent, events go up; `emit` does not bubble by default, and to cross layers you handle it explicitly or use a shared store; there is no implicit cross-layer passing.
-- **One entry point for data, one place for the view** (`set` and `render`): "how data becomes the view" is concentrated in `render`, and to trace data changes you only need to look at the calls to `set`.
-- **Synchronous rendering, no implicit asynchronous batching**: reading the DOM right after `set` always gives the new state, and tests need no waiting; to combine updates, use `batch` explicitly.
-- **No fine-grained reactive system**: `derive` is recomputed every time and `render` re-runs as a whole every time, in exchange for predictable behavior and no dependency-tracking magic.
-- **`data-if` is hidden by default**: state lives only in TS, and nothing is shown unless it says so.
-- **`data-if` cannot be on an item root element and `data-each` cannot be nested**: removing the root element would make the list lose its ordering anchor, and one template then holds exactly one level of list. A nested list is a second template (a child component), which keeps each template's `refs`, `text` and event handling in a single scope.
+## Documentation
 
-## Limitations
+The full guide is in English:
 
-- When running directly in the browser (no bundler), you must provide an import map for `ts-dom` yourself, and relative imports must use the `.js` extension (the NodeNext convention).
-- Event names for `data-on-*` must be lowercase; non-bubbling events handle only the target itself.
-- Automatic import and tag types of child components scan only the directories given to `gen`; third-party components or those outside the directories must be imported by you, and you must declare `HTMLElementTagNameMap` yourself. A class passed to `define` without `export` gets no tag type.
-- The `CustomEvent` received by an event handler method must be cast with `EmitEvent<child component, "event name">`, because HTML attributes cannot carry types.
-- `props` can be passed through HTML attributes only when the default value is a string / number / boolean.
-- Automatic binding covers only text holes and `data-if`; lists and attributes must be written in `render`.
-- Version 0.x, and the API may still change (for example, the `Update` callback signature has changed twice); see [CHANGELOG.md](CHANGELOG.md) for the versioning policy.
-- No SSR or hydration.
-- No attribute binding (deliberately; use `refs`).
-- The unused-markup lint compares against the class body text, and is looser for names inside list items (it only looks at identifiers).
-- `<style scoped>` falls back to CSS nesting in browsers that do not support `@scope`, which requires browser support for nesting (mainstream since 2023).
-- ARIA checks cover only common items in static HTML (see the list above) and are not a complete accessibility audit.
-- Browser tests are based on Chromium; Firefox 157 passed manual verification, and WebKit (Safari) is not verified.
+- [Templates: HTML syntax, generated types, templates without a component, Trusted Types, translations and icons](https://github.com/Pixmi/nativele/blob/main/docs/templates.md)
+- [Components and data flow: state, props, derive, events, composition, stores](https://github.com/Pixmi/nativele/blob/main/docs/components.md)
+- [Recipes: loading and error states, store data, filtered lists, dialogs, form validation](https://github.com/Pixmi/nativele/blob/main/docs/recipes.md)
+- [Lists: lists of components with `items =`, plain lists with `replace()`, moving items](https://github.com/Pixmi/nativele/blob/main/docs/lists.md)
+- [Setup, checks and lint: installation, Vite, oxlint, `ts-dom check`, `ts-dom doctor`, accessibility](https://github.com/Pixmi/nativele/blob/main/docs/tooling.md)
+- [Performance: the large list benchmark](https://github.com/Pixmi/nativele/blob/main/docs/performance.md)
+- [Design: principles, deliberate decisions, limitations](https://github.com/Pixmi/nativele/blob/main/docs/design.md)
+- [Developing Nativele: project structure, tests](https://github.com/Pixmi/nativele/blob/main/docs/contributing.md)