@nativele/ts-dom 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,882 @@
-# Temporary Holding Version
+# Nativele
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript-driven, HTML-first UI library.
+
+Nativele publishes this library as `@nativele/ts-dom` (import it from `@nativele/ts-dom`); its command line tool is `ts-dom`.
+
+A small library (prototype) for managing HTML with TypeScript. HTML describes the structure and "where data goes", TypeScript owns behavior and state, and the DOM is the single source of truth for what is rendered.
+
+English | [繁體中文](README.zh-TW.md)
+
+```html
+<!-- user-card.html: HTML only describes structure, where data goes, and which method handles an event -->
+<h2>Hello, {{ name }}!</h2>
+<button type="button" data-on-click="rename">Rename</button>
+<p data-if="admin">Admin</p>
+```
+
+```ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./user-card.html.js"; // generated by ts-dom gen, fully typed
+
+class UserCard extends Component(tpl, {
+  state: { name: "Ada", admin: true }, // data lives only here; {{ name }} and data-if="admin" bind to the same-named fields automatically
+}) {
+  rename() {
+    this.set({ name: "Grace" }); // the only entry point for changing data; the view updates automatically
+  }
+}
+define("user-card", UserCard);
+```
+
+If the HTML uses a name that `state` does not have, or `data-on-click` points to a method that does not exist, `tsc` reports an error.
+
+## Quick Start
+
+```sh
+npm i -D typescript && npm i @nativele/ts-dom
+npx ts-dom gen      # generate x.html.ts (fully typed) for every x.html
+npx tsc             # type-check and compile; no Vite or other bundler needed
+```
+
+The three examples below are real, runnable files in `examples/readme/` (type-checked, linted, and tested).
+
+### Example 1: Counter (state, derived values, events, data-if)
+
+The HTML only describes the structure, where data goes, and which method handles an event:
+
+```html
+<p>Count: {{ count }} (double: {{ double }})</p>
+<button type="button" data-on-click="inc">+1</button>
+<button type="button" data-on-click="reset">Reset</button>
+<p data-if="big">That is a lot of clicks!</p>
+```
+
+TypeScript owns the data and behavior. `{{ count }}`, `{{ double }}`, and `data-if="big"` bind automatically to the same-named state or derived value, and data is changed only through `this.set()`:
+
+```ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./counter.html.js";
+
+export class MyCounter extends Component(tpl, {
+  state: { count: 0 },
+  derive: { double: (s) => s.count * 2, big: (s) => s.count >= 10 },
+}) {
+  inc(): void {
+    this.set((s) => ({ count: s.count + 1 }));
+  }
+  reset(): void {
+    this.set({ count: 0 });
+  }
+}
+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: 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.
+
+## 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`.
+
+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
+});
+```
+
+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"
+  },
+},
+```
+
+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
+```
+
+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 gen && tsc && ts-dom lint`.
+
+## 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 (starting with `<!doctype>` or `<html>`, such as `index.html`) are page entry points, not templates, and are not processed.
+
+## 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.
+
+## 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
+
+Measurement environment: real Chrome (WSL), one text hole per item, counting only script execution time (excluding layout and paint), a single measurement, so treat it as an order-of-magnitude reference.
+
+| List size | Initial creation | Identical data | Change 1 item | Reverse order |
+|---|---|---|---|---|
+| 1,000 | about 11 ms | about 0.6 ms | about 0.4 ms | about 1.3 ms |
+| 5,000 | about 23–34 ms | about 2 ms | about 0.9 ms | about 6–8 ms |
+| 10,000 | about 65 ms | about 9 ms | about 2 ms | about 19 ms |
+
+"Identical data" is the cost of `render` re-running the whole list every time: text nodes are not written when their value has not changed, so it is cheap. The budget for one frame is about 16 ms, so re-running tens of thousands of items on every keystroke gets tight; use `changed` to skip, use `skipUnchanged`, or split the list into smaller ones. Event delegation does not add listeners as the number of items 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)).
+
+## 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): HTMLElement {
+  const view = itemTpl.instantiate();
+  view.text.label = label;
+  view.refs.button.addEventListener("click", () => select(label));
+  return view.root.firstElementChild as HTMLElement;
+}
+```
+
+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
+
+```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.
+
+## 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
+
+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.
+
+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`, `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), 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-ts-domy-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.
+
+## Limitations
+
+- 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.