defuss-morph 0.1.1 → 0.3.0

package/dist/stats.json

@@ -1,22 +1,22 @@
 {
   "package": "defuss-morph",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "files": {
     "dist/index.mjs": {
-      "bytes": 41197,
-      "gzip": 9762
+      "bytes": 48836,
+      "gzip": 12403
     },
     "dist/index.cjs": {
-      "bytes": 42228,
-      "gzip": 9912
+      "bytes": 50151,
+      "gzip": 12591
     },
     "dist/all.js": {
-      "bytes": 42634,
-      "gzip": 10082
+      "bytes": 50501,
+      "gzip": 12573
     },
     "dist/all.min.js": {
-      "bytes": 19416,
-      "gzip": 6951
+      "bytes": 23740,
+      "gzip": 8699
     }
   }
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "defuss-morph",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
+  "packageManager": "bun@1.4.3",
   "publishConfig": {
     "access": "public"
   },
   "license": "MIT",
-  "description": "The defuss DOM morphing algorithm is a standalone package: morph an HTML string or JSX object into an existing DOM tree using native APIs and smart DOM diffing. Key/id-aware node matching, move-not-replace, in-place attribute patching, form-state preservation and delegated event cleanup. Allows for isomorphic rendering and patching of server-rendered HTML in the browser. Does not need any framework or virtual DOM. Can be used with any framework or library, or without any. No compile/transpile step required. Extremely lightweight. Just 6 KiB minified and gzipped. Written in TypeScript.",
+  "description": "Morph an HTML string or JSX/VNodes into an existing DOM tree with native APIs: key/id-aware matching, move-not-replace, in-place attribute patching, form-state preservation and delegated event cleanup. Store-driven reactive rendering (reactive(), <Reactive>), refs and a JSX runtime on top. Works with any framework or none, in the browser and on the server, without a virtual DOM or build step. Zero dependencies; written in TypeScript.",
   "keywords": [
     "dom",
     "morph",
@@ -21,9 +22,13 @@
     "ai-prototyping",
     "for-ai-agents"
   ],
+  "homepage": "https://morph.defuss.org/",
   "repository": {
-    "url": "git+https://github.com/kyr0/defuss.git",
-    "type": "git"
+    "type": "git",
+    "url": "git+https://github.com/kyr0/defuss-morph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kyr0/defuss-morph/issues"
   },
   "scripts": {
     "clean": "rm -rf ./coverage ./dist ./node_modules/.vite",
@@ -32,16 +37,17 @@
     "bundle": "bun scripts/bundle.ts",
     "minify": "bun scripts/minify.ts",
     "stats": "bun scripts/stats.ts",
-    "verify": "bun scripts/verify.ts",
-    "lint": "oxlint src scripts",
-    "typecheck": "tsc --noEmit --emitDeclarationOnly false -p tsconfig.json",
+    "docs": "bun scripts/docs.ts",
+    "check:dist": "bun scripts/check-dist.ts",
+    "lint": "oxlint --deny-warnings --ignore-pattern 'docs/assets/defuss-morph.*' --ignore-pattern docs/assets/shiki.js --ignore-pattern docs/assets/demos.js --ignore-pattern docs/assets/router-demo.js --ignore-pattern docs/assets/bench.js --ignore-pattern 'docs/assets/vendor/**' src scripts docs/assets docs/demos",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false -p tsconfig.json && tsc -p docs/demos/tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage --project node --project 'browser (chromium)' --reporter=default --reporter=json --outputFile.json=coverage/tests.json",
+    "e2e": "make e2e",
+    "verify": "make verify",
     "purge-cdn": "bun scripts/purge-cdn.ts",
-    "test": "vitest run --coverage",
-    "test:watch": "vitest --coverage",
-    "pretest:browser": "bunx playwright install chromium",
-    "test:browser": "vitest run --project browser",
-    "e2e": "bun run test:browser",
-    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run clean && bun run build && bun run bundle && bun run minify && bun run stats && bun run verify"
+    "prepublishOnly": "make verify"
   },
   "author": "Aron Homberg <info@aron-homberg.de>",
   "sideEffects": [
@@ -60,6 +66,26 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.mjs"
       }
+    },
+    "./jsx-runtime": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./jsx-dev-runtime": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
     }
   },
   "main": "./dist/index.cjs",
@@ -67,7 +93,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "skills",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -78,11 +106,16 @@
     "@vitest/browser": "^5.0.0",
     "@vitest/browser-playwright": "^5.0.0",
     "@vitest/coverage-v8": "^5.0.0",
+    "defuss-dom-router": "0.1.1",
+    "defuss-i18n": "0.2.0",
+    "defuss-query": "0.2.0",
+    "defuss-store": "0.1.0",
     "happy-dom": "^20.5.0",
     "oxc-minify": "^0.149.0",
     "oxlint": "^1.81.0",
     "pkgroll": "^2.27.0",
     "playwright": "^1.58.2",
+    "shiki": "4.5.0",
     "typescript": "^5.9.3",
     "vitest": "^5.0.0"
   }

package/skills/defuss-morph/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: defuss-morph
+description: Write DOM updates with defuss-morph - morph an HTML string or JSX into the live DOM instead of assigning innerHTML, so focus, typed input and event listeners survive; re-render a region from a store with reactive(), <Reactive> or df$(selector).reactive(); refs and the forwardRef pattern; defuss-query, defuss-store, defuss-i18n and defuss-dom-router together. Use when code renders or updates HTML in the browser or on a server with happy-dom, in a bundled app or a standalone HTML page, without a virtual DOM.
+---
+
+# defuss-morph 0.3.0 - Agent Skill
+
+defuss-morph compares new content (an HTML string, JSX or VNodes) with the children of a live element and patches only the difference with native DOM calls. A node that exists before and after stays the same node, so its focus, caret, typed value, scroll position and listeners survive. There is no component tree, no scheduler and no virtual DOM: each call reads the live DOM as the previous state.
+
+`reactive()`, `<Reactive>`, `installReactive()`, `createRef()` and the JSX runtime exist since 0.3.0. Check the installed version (`node_modules/defuss-morph/package.json`) before using them.
+
+## 1. Install: pick one path
+
+**A package manager** (the project has a `package.json`): `bun add defuss-morph` (or the project's own manager). Add `defuss-store` for stores, `defuss-query` for `df$`, `defuss-i18n` and `defuss-dom-router` as the task needs them. For JSX, set the compiler's import source; TypeScript:
+
+```json
+{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "defuss-morph" } }
+```
+
+Bun, esbuild and Vite read the same two options. `defuss-morph/jsx-runtime` resolves to the package entry, so a bundle holds one copy.
+
+**A standalone HTML page** (no build step): one module script registers the whole API as `window.df$`. Load defuss-query after it when the page uses `df$(selector)`:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/defuss-morph@latest/dist/all.min.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/defuss-query@0.2.0/dist/all.min.js"></script>
+<script type="module">
+  import { createStore } from "https://cdn.jsdelivr.net/npm/defuss-store@0.1.0/dist/browser.min.js";
+  df$.installReactive(df$); // morph loaded before query: give selections .reactive()
+  df$.morph(document.getElementById("app"), "<p>Hello</p>");
+</script>
+```
+
+Module scripts run in document order, so the inline module sees both. Without a compiler, write JSX as `h()` calls: `h("button", { onClick }, "Save")` is `<button onClick={onClick}>Save</button>`.
+
+## 2. Rules
+
+1. **Re-render by morphing the complete next state** into a container: `morph(container, next)`. Never assign `innerHTML` to update a region; it rebuilds every node and loses focus, typed input and listeners.
+2. **Key every list item** with a stable ID: `key="..."` in HTML, `key={item.id}` in JSX, never the index. Keyed nodes move; unkeyed siblings match by tag in order and can swap content.
+3. **A component's `key` lands on the element it returns**, so `items.map((item) => <Row key={item.id} item={item} />)` is keyed.
+4. **Markup that omits something means "leave it alone".** An HTML string cannot uncheck a box, clear a typed `value` or remove a handler. To set such state, send a VNode: `morph(form, [{ attributes: { id: "terms", checked: false } }], { diff: true })`.
+5. **Escape text you put into an HTML string**, or pass it as a VNode child (`h("li", null, userText)`, defuss-query's `.text()`). morph renders its input and does not sanitize it; a `<script>` in an HTML string runs.
+6. **Diff mode (`{ diff: true }`) patches and appends only**: every item needs a `key` or `id`; it never removes or reorders. Use a full `morph()` for that.
+7. **`morph()` is synchronous**, unless it has a `transition` option: then it returns a Promise. `await` it before the next animated morph.
+8. **A component function runs again on every render.** There are no hooks. State that must outlive a render lives in a store created outside the component, or on the component's ref (`ref.state`).
+9. **Lifecycle timing.** morph sets refs while it renders, so `ref.current` is set when `morph()` returns. `onMount` runs in a microtask after insertion, and again after each morph that patches the element with an `onMount`. `onUnmount` runs once the element leaves the document and receives the element.
+10. **One copy of defuss-morph per page.** Your code, defuss-query and defuss-i18n must share it (one bundle, or one import map for ES modules); each copy keeps its own handler registry, and a second copy does not tear down the first one's handlers.
+
+## 3. The four patterns
+
+Full examples with JSX and HTML variants: [references/patterns.md](references/patterns.md).
+
+**Reactive rendering.** `reactive({ store, render }, target)` renders `render()` into `target` now and morphs it in again after every store change. `target` is an element, a ref or a list of elements. It returns `dispose()`.
+
+```ts
+import { reactive } from "defuss-morph";
+import { createStore } from "defuss-store";
+
+const cart = createStore({ count: 0 });
+const dispose = reactive({ store: cart, render: () => `<p>${cart.value.count} items</p>` }, cartEl);
+cart.set("count", 2); // the same <p>, new text
+```
+
+In JSX, `<Reactive store={cart} render={() => <p>{cart.value.count}</p>} />` renders a wrapper (`tag`, default `div`) and stays subscribed while the wrapper is in the document. For markup already in the page, `df$("#cart").reactive({ store, render, signal })` after `installReactive(df$)`; end it with an `AbortController`.
+
+**Ref.** `const field = createRef<HTMLInputElement>()`, then `<input ref={field} />`; morph puts the element into `field.current` and keeps it there while the element survives.
+
+**forwardRef.** There is no `forwardRef()` function. A component takes an optional `ref` prop with a default and puts its API on `ref.state`:
+
+```tsx
+const Stepper = ({ ref = createRef<HTMLElement, StepperApi>() }: { ref?: Ref<HTMLElement, StepperApi> }) => {
+  // createStepper() returns { count: createStore({ n: 0 }), increment, reset }: references/patterns.md
+  const api = (ref.state ??= createStepper()); // state on the ref outlives a parent re-render
+  return <Reactive ref={ref} store={api.count} render={() => <output>{api.count.value.n}</output>} />;
+};
+```
+
+**Query references (HTML-first pages).** Name the parts with `data-ref` and select each once: `const list = df$("[data-ref=list]")`. `list.html(markup)` morphs; `.on()` listens natively; one listener on a container serves buttons rendered from HTML strings (`data-action` attributes), because an HTML string cannot carry handlers.
+
+## 4. Integrations
+
+Details and the CDN variants: [references/integrations.md](references/integrations.md).
+
+- **defuss-store**: `createStore(initial)`, `.value`, `.set(path, value)`, `.update(fn)`, `.subscribe()`; `computed(store, fn)` notifies only when its result changes. Any object with `subscribe(listener)` returning an unsubscribe function works as a store.
+- **defuss-query**: `import df$ from "defuss-query"`; `.html()`, `.text()`, `.morph()` morph; `.form()` returns `FormData`; `installReactive(df$)` adds `.reactive()`.
+- **defuss-i18n**: translations are `<template data-i18n-for data-i18n-locale>` beside the markup; `bindI18n(root, createI18n({ locale: "en", fallback: ["en"] }))`, then `setLocale("de")` morphs the marked parts and keeps typed input.
+- **defuss-dom-router**: `createRouter({ routes, prepare: ({ to }) => ({ commit: () => morph(outlet, view(to)) }) })`, `router.attachLinks(document)`, `await router.start()`. Give each view's root a key per record (`key="project-7"`), so another record does not inherit typed input.
+
+## 5. Check your work
+
+- Unit tests run in happy-dom: `morph(el, html)` works on any element of a happy-dom `Window`; `reactive()` re-renders as soon as the store notifies (defuss-store notifies synchronously); `<Reactive>` subscribes in a microtask, so `await new Promise((r) => setTimeout(r, 0))` before changing a store in a test.
+- Assert identity, not only text: keep a reference to a node, morph, and check the node is still the one in the DOM.
+- In a browser test, type into an input, trigger the re-render, and check the value and `document.activeElement`.
+
+## 6. References
+
+- [references/api.md](references/api.md): every export with its signature and options.
+- [references/patterns.md](references/patterns.md): reactive rendering, ref, forwardRef and query references, in JSX and HTML.
+- [references/integrations.md](references/integrations.md): defuss-query, defuss-store, defuss-i18n, defuss-dom-router; bundler and CDN setups.
+- [references/pitfalls.md](references/pitfalls.md): mistakes that compile and run but break state, and their fixes.
+- Website with live demos of every pattern: https://morph.defuss.org/

package/skills/defuss-morph/references/api.md

@@ -0,0 +1,86 @@
+# defuss-morph API
+
+Everything below is exported from `defuss-morph` (ES module and CommonJS) and, in the CDN bundle, assigned to `window.df$`. Declarations: `node_modules/defuss-morph/dist/index.d.ts`.
+
+## morph
+
+```ts
+morph(el: Element, content: RenderInput, options?: MorphOptions): void | Promise<void>
+```
+
+Makes the children of `el` match `content`: an HTML string, a VNode, an array of VNodes, or text. Without `transition` it finishes synchronously and returns `undefined`; with one it returns a Promise that resolves when the animation has ended.
+
+- Strings are parsed with the `DOMParser` of `el.ownerDocument`, as `<template>` content, so `<tr>`, `<td>` and `<option>` survive at the top level. A full document (starting with a doctype, `<html>`, `<head>` or `<body>`) is parsed as a document.
+- Children match by `key`, then `id`, then tag. Only matches out of order move (the longest run already in order stays). A match is moved with `moveBefore()` where the browser has it (focus and selection stay), else `insertBefore()` with focus and selection put back, and patched in place. Unmatched new children are created; unclaimed old ones are removed after their handlers are torn down.
+- `key` is stored on the element and not written to the DOM.
+- An element with an open shadow root is morphed inside it; a custom element (hyphen in the tag) keeps its light DOM as the target. A `<template>` is morphed in its `.content`.
+- A morph started during another morph on the same element or a descendant is queued; the latest request runs when the active one returns.
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `diff` | `boolean` | `false` | The input is a change-set for the direct children: items addressed by `key` or `id` are patched (attributes merged), unmatched ones appended. Never removes or moves. An item without `key`/`id` throws. |
+| `transition.type` | `"fade" \| "slide-left" \| "slide-right" \| "shake" \| "none"` | `"fade"` | `none` keeps the call synchronous. |
+| `transition.duration` | `number` (ms) | `300` | Per phase. |
+| `transition.easing` | `string` | `"ease-in-out"` | Any CSS timing function. |
+| `transition.delay` | `number` (ms) | `0` | Before the transition starts. |
+| `transition.target` | `"parent" \| "self"` | `"parent"` | The animated element. |
+| `transition.styles` | `{ enter, enterActive, exit, exitActive }` | by type | Own style maps (not used by `fade`). |
+
+## VNodes and JSX
+
+A VNode is `{ type, attributes, children }`; a comment is `{ type: "#comment", value }`. Attributes a VNode can carry that HTML cannot: explicit booleans (`checked: false`), live values (`value: ""`), event props (`onClick`, `onClickCapture`), `ref`, `key`, `onMount`, `onUnmount`, `className`, `class` as an array, `style` as an object, `dangerouslySetInnerHTML`.
+
+| Export | Use |
+| --- | --- |
+| `jsx(type, props, key?)`, `jsxs`, `jsxDEV`, `Fragment` | The automatic runtime for `jsxImportSource: "defuss-morph"`. `defuss-morph/jsx-runtime` and `defuss-morph/jsx-dev-runtime` resolve to the package entry. |
+| `h(type, props, ...children)` | The classic factory: `jsxFactory: "h"`, or pages without a build step. |
+| `type Component<P>` | `(props: P) => RenderInput`. Called at once by `jsx()`; a `key` given to it lands on the element it returns. |
+| `namespace JSX` | Loose JSX types: any tag, any attribute; a JSX expression is a `RenderInput`. |
+
+Event props listen on the element itself (one listener per element, event and phase), so propagation is native: order, `stopPropagation()`, `currentTarget`, non-bubbling events such as `toggle`. A morph that drops an event prop removes the handler; an HTML string never removes registered handlers, because it cannot declare them.
+
+## Reactive rendering
+
+```ts
+reactive(config: ReactiveConfig, target: Element | RefLike | ArrayLike<Element>): () => void
+```
+
+Renders `config.render()` into each target element now, then again after every store change. Returns `dispose()`: it unsubscribes from every store and runs `cleanup` once. A ref target is read on every render and must hold an element when `reactive()` is called (otherwise a `TypeError`); a list is a snapshot; an empty list renders and subscribes nothing.
+
+| Config | Type | Meaning |
+| --- | --- | --- |
+| `store` | `Subscribable \| Subscribable[]` | A change in any of them renders again. `Subscribable` is `{ subscribe(listener): unsubscribe }`; a returned object with `unsubscribe()` works too. |
+| `render` | `() => RenderInput` | JSX, VNodes or an HTML string. Pure: it may run more often than the stores change. |
+| `cleanup?` | `() => void` | Runs once when the region is disposed. |
+| `signal?` | `AbortSignal` | Disposes on abort. An already aborted signal renders nothing. |
+
+```tsx
+<Reactive store={store} render={() => …} tag="section" className="x" ref={ref} cleanup={…} {...attributes} />
+```
+
+`Reactive(props)` returns a VNode: the wrapper element with the first `render()` result as its children. Once morph has mounted the wrapper (`onMount`, a microtask later) it subscribes and renders once more; a parent re-render moves the subscription to the latest `render` and `store`; leaving the document unsubscribes and runs `cleanup`. A plain-text render needs no `DOMParser`; an HTML string inside `<Reactive>` needs a global one (any browser).
+
+`installReactive(df$)` adds `.reactive(config)` to defuss-query's selections (`df$.fn`) and returns `df$`. The method calls `reactive(config, selection)` and returns the selection. The CDN bundle calls it itself when it loads after defuss-query.
+
+## Refs
+
+```ts
+createRef<T extends Element = HTMLElement, S = unknown>(state?: S): Ref<T, S> // { current: T | null, state?: S }
+isRef(value): value is RefLike
+```
+
+morph sets `current` when it creates or patches the element that carries `ref={…}`.
+
+## Low-level primitives
+
+For framework integration (defuss-query is built on them); `globals` is optional everywhere and derived from the element's document.
+
+| Export | What it does |
+| --- | --- |
+| `updateDomWithVdom(el, vnodes, globals?, mode?)` | The guarded VNode morph; `mode` is `"replace"` or `"diff"`. |
+| `replaceDomWithVdom(el, vnodes, globals?)` | Removes every child (with handler teardown) and renders from scratch. |
+| `htmlStringToVNodes(html, DOMParser)`, `domNodeToVNode(node)` | Markup or a DOM node as VNodes. |
+| `getRenderer(document)` | Creates DOM from VNodes. |
+| `registerDelegatedEvent(el, type, handler, options?)`, `removeDelegatedEvent`, `clearDelegatedEventsDeep` | The handler registry JSX event props use. |
+| `onClearDelegatedEvents(hook)` | Runs `hook(element)` whenever morph removes or replaces an element; returns an unregister function. |
+| `performTransition(el, update, config)` | The transition runner. |

package/skills/defuss-morph/references/integrations.md

@@ -0,0 +1,116 @@
+# Integrations
+
+Each package does one job and leaves rendering to defuss-morph. defuss-morph 0.3.0 is tested with defuss-query 0.2.0, defuss-store 0.1.0, defuss-i18n 0.2.0 and defuss-dom-router 0.1.1 (`devDependencies` in its `package.json`); the website runs all four.
+
+## Setup
+
+**With a bundler**: install what the task needs and import by name. The bundle then holds one copy of defuss-morph, which defuss-query and defuss-i18n import too.
+
+```sh
+bun add defuss-morph defuss-store defuss-query defuss-i18n defuss-dom-router
+```
+
+defuss-i18n 0.2.0 declares peer ranges older than these releases (`defuss-morph ^0.1.1`, `defuss-query ^0.1.0`); the package manager warns, and it works with defuss-morph 0.3.0 and defuss-query 0.2.0 in the tests.
+
+**ES modules without a bundler**: an import map gives every package one URL, so all of them share one copy of defuss-morph. The website does this with copies of the published files:
+
+```html
+<script type="importmap">
+{ "imports": {
+  "defuss-morph": "./assets/defuss-morph.mjs",
+  "defuss-morph/jsx-runtime": "./assets/defuss-morph.mjs",
+  "defuss-query": "./assets/vendor/defuss-query/index.js",
+  "defuss-store": "./assets/vendor/defuss-store/browser.js",
+  "defuss-i18n": "./assets/vendor/defuss-i18n/index.js",
+  "defuss-dom-router": "./assets/vendor/defuss-dom-router/index.js"
+} }
+</script>
+```
+
+**Classic CDN globals**: defuss-morph's `all.min.js` first, then defuss-query's `all.min.js` (it turns `window.df$` into the query function and keeps morph's API on it), then `df$.installReactive(df$)`. Loaded the other way round, defuss-morph installs `.reactive()` itself.
+
+## defuss-store
+
+```ts
+import { computed, createStore } from "defuss-store";
+
+const profile = createStore({ name: "Ada", visits: 0 });
+profile.value.name;                  // read
+profile.set("visits", 1);            // path write, notifies synchronously
+profile.update((p) => ({ ...p, name: "Grace" }));
+const greeting = computed(profile, (p) => `Hello, ${p.name}`); // notifies only when the string changes
+
+reactive({ store: greeting, render: () => `<p>${esc(greeting.value)}</p>` }, el);
+```
+
+- Snapshots are immutable: write with `set` or `update`, never mutate `store.value`.
+- `reactive()` accepts any `{ subscribe(listener) }` that returns an unsubscribe function, so another store library works as well.
+- ESM only; Node 22.12 or newer on the server.
+
+## defuss-query
+
+```js
+import df$ from "defuss-query";
+
+df$("#list").html(markup);                         // morph; returns the selection
+await df$("#card").html(next, { transition: { type: "fade", duration: 200, target: "self" } });
+df$("#list").html(tags.map((tag) => ({ type: "li", attributes: { key: tag }, children: [tag] }))); // user text as text
+df$("#form").on("submit", function (event) { event.preventDefault(); const data = df$(this).form(); });
+df$("#name").text(userInput);                      // literal text, never parsed
+```
+
+- `df$(selector)` returns a snapshot Array of elements; `.find()`, `.closest()`, `.attr()`, `.prop()`, `.val()`, `.addClass()` work as in jQuery.
+- `.on()` listens on each element natively; inside the handler use `this` for the element.
+- `installReactive(df$)` from defuss-morph adds `.reactive(config)`.
+
+## defuss-i18n
+
+```html
+<section data-i18n-component>
+  <h2 data-i18n-target="title">Your order</h2>
+  <template data-i18n-for="title" data-i18n-locale="en">Your order</template>
+  <template data-i18n-for="title" data-i18n-locale="de">Ihre Bestellung</template>
+  <input placeholder="Delivery note" data-i18n-placeholder-en="Delivery note" data-i18n-placeholder-de="Lieferhinweis">
+</section>
+```
+
+```ts
+import { bindI18n, createI18n } from "defuss-i18n";
+
+const locale = createI18n({ locale: "en", fallback: ["en"] });
+const binding = bindI18n(document.querySelector("[data-i18n-component]")!, locale);
+locale.setLocale("de"); // synchronous: the <h2> and the placeholder are German, the typed note is kept
+binding.dispose();       // when the component leaves the page
+```
+
+- Templates sit beside their target, never inside it.
+- Attributes translate through `data-i18n-{attribute}-{locale}`.
+- Markup that holds i18n templates may itself be rendered by morph: morph keeps a `<template>`'s content in `.content` (since 0.3.0).
+
+## defuss-dom-router
+
+```ts
+import { morph } from "defuss-morph";
+import { createRouter } from "defuss-dom-router";
+
+const outlet = document.querySelector<HTMLElement>("main")!;
+const esc = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const router = createRouter({
+  routes: [{ id: "home", path: "/" }, { id: "project", path: "/projects/:id" }, { id: "missing", path: "*" }],
+  prepare: ({ to }) => {
+    const id = esc(to.params.id ?? ""); // params come from the URL: escape them like any user input
+    const markup = to.routeId === "project"
+      ? `<section key="project-${id}"><h1>Project ${id}</h1><input aria-label="Note"></section>`
+      : `<section key="${to.routeId}"><h1>${to.routeId}</h1></section>`;
+    return { commit: () => morph(outlet, markup) };
+  },
+});
+router.attachLinks(document); // <a data-router-link href="/projects/7">
+await router.start();
+```
+
+- `prepare()` builds the next view without touching the page; `commit()` renders it.
+- The router catches what `prepare()` and `commit()` throw and reports it only to `onError`: pass one, or a view that throws fails without a trace.
+- The view's root key names the record: query-only changes (`?tab=files`) keep typed input, another record gets fresh fields.
+- Without a server that answers deep links with the app's HTML, use `mode: "hash"` and `href="#/projects/7"`.
+- Keep UI that outlives routes (header, search) outside the outlet.

package/skills/defuss-morph/references/patterns.md

@@ -0,0 +1,190 @@
+# Patterns
+
+Start from these four patterns. Each runs live on https://morph.defuss.org/#patterns, from the sources in the repository's `docs/demos/` folder.
+
+## Reactive rendering
+
+One store, three ways to bind it. The store (defuss-store):
+
+```ts
+import { createStore } from "defuss-store";
+
+export const cart = createStore({ items: [{ id: "tea", name: "Tea", qty: 1 }] });
+export const add = (id: string) =>
+  cart.update(({ items }) => ({ items: items.map((item) => (item.id === id ? { ...item, qty: item.qty + 1 } : item)) }));
+```
+
+### JSX: `<Reactive>`
+
+```tsx
+import { Reactive, morph } from "defuss-morph";
+
+const CartList = () => (
+  <Reactive tag="ul" store={cart} render={() =>
+    cart.value.items.map((item) => (
+      <li key={item.id}>
+        {item.name} × {item.qty}
+        <input placeholder="note" />
+        <button type="button" onClick={() => add(item.id)}>+1</button>
+      </li>
+    ))
+  } />
+);
+
+morph(app, <CartList />);
+```
+
+The wrapper is `<ul>`; each store change morphs the new rows in. A note typed into a row stays, and moves with the row when the order changes, because the rows are keyed and the input has no `value` in the markup.
+
+### HTML: `reactive()`
+
+```ts
+import { reactive } from "defuss-morph";
+
+const esc = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+// one listener on the container: HTML strings carry no handlers
+app.addEventListener("click", (event) => {
+  const id = (event.target as Element).closest<HTMLElement>("[data-add]")?.dataset.add;
+  if (id) add(id);
+});
+
+const dispose = reactive({
+  store: cart,
+  render: () => `<ol>${cart.value.items.map((item) =>
+    `<li key="${item.id}">${esc(item.name)} × ${item.qty} <button type="button" data-add="${item.id}">+1</button></li>`).join("")}</ol>`,
+}, app);
+```
+
+Call `dispose()` when the region goes away. `reactive()` renders synchronously: when `cart.set()` returns, the DOM shows the change.
+
+### defuss-query: `df$(selector).reactive()`
+
+```js
+import df$ from "defuss-query";
+import { installReactive } from "defuss-morph";
+
+installReactive(df$);
+
+const stop = new AbortController();
+df$("[data-ref=cart-total]").reactive({
+  store: cart,
+  render: () => `<strong>${cart.value.items.reduce((sum, item) => sum + item.qty, 0)}</strong> items`,
+  signal: stop.signal, // stop.abort() ends the binding; the method returns the selection
+});
+```
+
+In TypeScript, `reactive(config, df$(selector))` is the typed form of the same call.
+
+### Several stores, derived values
+
+`store: [a, b]` re-renders on a change in either. `computed(store, (value) => value.name)` from defuss-store notifies only when its result changes: pass it as the store when a region depends on one field of a large store.
+
+## Ref
+
+```tsx
+import { createRef, morph } from "defuss-morph";
+
+const field = createRef<HTMLInputElement>();
+
+const Search = () => (
+  <form>
+    <input ref={field} name="q" />
+    <button type="button" onClick={() => field.current?.focus()}>Focus</button>
+  </form>
+);
+
+morph(app, <Search />);
+field.current?.select(); // set: morph assigns refs while it renders
+```
+
+A morph that keeps the `<input>` keeps `field.current` on the same node. In the component body, `field.current` still holds the previous render's element (or `null` on the first render): use it in handlers, in `onMount`, or after `morph()` returns.
+
+A ref is also a `reactive()` target: `reactive({ store, render }, field)` reads `field.current` on each render.
+
+## forwardRef
+
+```tsx
+import { Reactive, type Ref, createRef, morph } from "defuss-morph";
+import { createStore } from "defuss-store";
+
+const createStepper = () => {
+  const count = createStore({ n: 0 });
+  return { count, increment: () => count.set("n", count.value.n + 1), reset: () => count.set("n", 0) };
+};
+export type StepperApi = ReturnType<typeof createStepper>;
+
+const Stepper = ({ label, ref = createRef<HTMLElement, StepperApi>() }: { label: string; ref?: Ref<HTMLElement, StepperApi> }) => {
+  const api = (ref.state ??= createStepper());
+  return (
+    <Reactive ref={ref} store={api.count} render={() => (
+      <>
+        {label}: <output>{api.count.value.n}</output>
+        <button type="button" onClick={api.increment}>+1</button>
+      </>
+    )} />
+  );
+};
+
+const steps = createRef<HTMLElement, StepperApi>();
+morph(app, (
+  <div>
+    <Stepper label="Steps" ref={steps} />
+    <button type="button" onClick={() => steps.state?.reset()}>Reset</button>
+  </div>
+));
+```
+
+- The default `createRef()` makes the component work without a parent ref.
+- The API and the state live on `ref.state`, created on the first render (`??=`), so a parent re-render, which calls `Stepper` again, keeps the count. A component without a parent ref gets a fresh ref, and so fresh state, on each parent render.
+- `ref.current` is the wrapper element; `ref.state` is the API.
+
+## Query references (HTML-first pages)
+
+When the markup comes from a server, a CMS or a template, do not re-create it in JavaScript. Name its parts and select each once:
+
+```html
+<input type="search" data-ref="filter" aria-label="Filter">
+<ul data-ref="list">
+  <li key="ts">TypeScript</li>
+  <li key="py">Python</li>
+</ul>
+<p data-ref="count">2 of 2</p>
+```
+
+```js
+import df$ from "defuss-query";
+
+const ui = { filter: df$("[data-ref=filter]"), list: df$("[data-ref=list]"), count: df$("[data-ref=count]") };
+const items = ui.list.find("li").map((li) => ({ key: li.getAttribute("key"), name: li.textContent }));
+const esc = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+ui.filter.on("input", function () {
+  const shown = items.filter((item) => item.name.toLowerCase().includes(this.value.toLowerCase()));
+  ui.list.html(shown.map((item) => `<li key="${item.key}">${esc(item.name)}</li>`).join(""));
+  ui.count.text(`${shown.length} of ${items.length}`);
+});
+```
+
+- `key` attributes in server markup are read by morph, so the server-rendered items match the re-rendered ones.
+- A selection is a snapshot Array: select once at start for parts that are never replaced, select again for parts a morph creates.
+- Buttons rendered from HTML strings get one listener on a stable container, dispatching on `data-action` or `data-*` attributes.
+
+## Without a build step
+
+All of the above works in a plain page with the CDN bundle. JSX becomes `h()`:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/defuss-morph@latest/dist/all.min.js"></script>
+<script type="module">
+  import { createStore } from "https://cdn.jsdelivr.net/npm/defuss-store@0.1.0/dist/browser.min.js";
+  const { h, Reactive, morph } = df$;
+  const counter = createStore({ n: 0 });
+  morph(document.getElementById("app"), h(Reactive, {
+    store: counter,
+    render: () => h("button", { type: "button", onClick: () => counter.set("n", counter.value.n + 1) }, `clicked ${counter.value.n}`),
+  }));
+</script>
+```
+
+The repository's `examples/reactive-html.html` and `examples/reactive-jsx.html` are complete pages.