commit bd13d0fa0d99142d87877ccc08a0f308c25a0ae2
Author: Thomas Hain <thain39@proton.me>
Date:   Sun May 10 11:33:26 2026 +0200

    feat: slhx requirements, project structure, and core primitives

diff --git a/.githooks/commit-msg b/.githooks/commit-msg
new file mode 100755
index 0000000..56e8944
--- /dev/null
+++ b/.githooks/commit-msg
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+msg_file="$1"
+# Require scope if REQs exist
+if [ -f REQUIREMENTS.md ]; then
+  if ! grep -qE '^[a-z]+(\(.+\))?:' "$msg_file"; then
+    echo "error: commit requires scope — e.g. feat(parser): ..."
+    exit 1
+  fi
+fi
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000..a8342ad
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+changed=$(git diff --cached --name-only)
+# fail if REQs changed but AGENTS.md is older
+if echo "$changed" | grep -q '^REQUIREMENTS.md$' && echo "$changed" | grep -q '^AGENTS.md$'; then
+  # Both changed — OK
+  :
+else
+  req_time=$(git log -1 --format=%ct -- REQUIREMENTS.md 2>/dev/null || echo 0)
+  ag_time=$(git log -1 --format=%ct -- AGENTS.md 2>/dev/null || echo 0)
+  if [ "$req_time" -gt "$ag_time" ]; then
+    echo "error: REQUIREMENTS.md newer than AGENTS.md — run: redgate agents > AGENTS.md"
+    exit 1
+  fi
+fi
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..825cb48
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,12 @@
+# Tool Registry
+
+| Tool | Description |
+|------|-------------|
+| redgate | Requirements-first governance: list, refs, health, agents |
+
+## redgate usage
+
+- `redgate list` — TSV of all requirements
+- `redgate refs` — find req: citations in source
+- `redgate health` — ok/uncited per requirement
+- `redgate agents` — render AGENTS.md from REQUIREMENTS.md
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..dd7fef7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,280 @@
+#  — AGENTS.md
+
+> Auto-generated from REQUIREMENTS.md. Do not edit directly.
+> Edit REQUIREMENTS.md and run: redgate agents > AGENTS.md
+
+## Requirements
+
+### req:_boundary/001
+
+- **001** hemplate does not expose a slhx API. It exposes a stable, generic Template Surface IR. slhx is one consumer; a11y tools, test generators, and documentation generators are others.
+
+### req:_boundary/002
+
+- **002** hemplate never interprets `data-slhx-*`, `slhx-*`, or any other tool-prefixed attribute. It records them as raw `name: value` pairs in the Surface.
+
+### req:_boundary/003
+
+- **003** slhx never parses `.heml` directly. It consumes `hemplate.surface.postcard` emitted by `hemplate_build`. slhx interprets tool-specific conventions (`data-slhx-handle`, `data-slhx-slot`, etc.) from the generic Surface.
+
+### req:_build/001
+
+- **001** Build order: `.heml` → `hemplate_build` → `hemplate.surface.postcard` → `slhx_build` → `slhx.syms` + generated Rust constants.
+
+### req:_build/002
+
+- **002** `slhx-derive` (`#[slhx::handler]`) reads `slhx.syms` at expansion time to validate handle names, slot names, and form signatures.
+
+### req:_build/003
+
+- **003** A `build.rs` failure (missing Surface, version mismatch, stale hash) is a hard error before proc-macro expansion.
+
+### req:_build/004
+
+- **004** Id allocation is deterministic from canonical symbol paths. Stable across builds unless the symbol path changes.
+
+### req:_check/001
+
+- **001** All cross-file references verified at `cargo check`. Unknown handle → hard error. Unknown slot → hard error. Type mismatch between slot and atom → hard error.
+
+### req:_check/002
+
+- **002** Dead handle warning: `#[slhx::handler]` never referenced by any template. Dead slot warning: template node never targeted by any handler.
+
+### req:_check/003
+
+- **003** Renaming a slot or handle breaks `cargo check` immediately with a span pointing to the Rust handler or template source.
+
+### req:_check/004
+
+- **004** Page-scoped slot lookup: JS runtime resolves `data-sid` only within the current Page root element.
+
+### req:_derive_app/001
+
+- **001** `#[slhx::app]` marks the root application struct containing all global atoms. It is the registry entry point for `slhx_build`. Zero- or single-instance per process.
+
+### req:_effect/001
+
+- **001** Effects are a typed command stream describing *what*, *where*, and *how* of a DOM mutation. Declarative: Rust builds the stream; JS applies it.
+
+### req:_effect/002
+
+- **002** The public API is `IntoEffect` (a trait) for Rust ergonomics and zero-allocation encoding. The wire API is a canonical postcard opcode schema (`Op::ReplaceHtml`, `Op::SetText`, `Op::PatchAtom`, `Op::Navigate`, `Op::Focus`, `Op::AddClass`, `Op::RemoveClass`, `Op::RemoveKeyed`, `Op::CustomOp`). IntoEffect writes opcodes directly; advanced users may implement the trait to stream custom opcodes.
+
+### req:_effect/003
+
+- **003** Core effect helpers: `replace(slot, html)`, `patch(slot, atom)`, `text(slot, value)`, `remove_keyed(slot, key)`, `append_keyed(slot, key, html)`, `move_keyed(slot, key, target_slot, target_key, position)`, `class_keyed(slot, key, class, active)`, `navigate(Nav { url, mode, title, scroll })`, `focus(slot)`, `add_class(slot, class)`, `remove_class(slot, class)`, `batch((...))`.
+
+### req:_effect/004
+
+- **004** `batch` composes effects in declared order. No implicit ordering, no priority weights.
+
+### req:_effect/005
+
+- **005** `Effect::navigate` carries `NavMode::Push | Replace | Redirect`, optional `title`, and `ScrollMode`. No separate router framework required for basic cases.
+
+### req:_effect/006
+
+- **006** Core effects may carry an opaque transition token, but core never interprets or implements transitions. Transitions live in `slhx-transition`.
+
+### req:_effect/007
+
+- **007** Zero runtime parsing of selectors. The JS runtime looks up elements by numeric `data-sid` or `data-hid` attributes. Slot ids are allocated deterministically.
+
+### req:_form/001
+
+- **001** Forms are first-class. hemplate exports `FormSurface` with raw `ControlKind` facts. slhx generates/validates Rust form structs from those facts.
+
+### req:_form/002
+
+- **002** `Form<T>` is generated by slhx-build from the Surface. `T` derives from HTML control names and kinds, mapped to Rust types by slhx rules (e.g. `type="number"` + `required` → `u64`; same without `required` → `Option<u64>`).
+
+### req:_form/003
+
+- **003** Handler signature mismatch between generated `Form<T>` and the handler parameter is a `cargo check` error.
+
+### req:_form/004
+
+- **004** Progressive enhancement: if JS fails, `<form data-slhx-handle>` degrades to normal submission via hidden `__h` field. Server reads `__h` and dispatches by numeric handle id.
+
+### req:_invariant/001
+
+- **001** User-authored references are symbolic at author time and numeric at runtime.
+
+### req:_invariant/002
+
+- **002** The JS runtime never parses CSS selectors, expressions, or handler names.
+
+### req:_invariant/003
+
+- **003** Rust handlers return effects; they do not imperatively mutate DOM.
+
+### req:_invariant/004
+
+- **004** Cross-file references fail at `cargo check` with a precise span.
+
+### req:_invariant/005
+
+- **005** slhx core owns effects, typed ids, and registries only. Routing, auth, sessions, transport, transitions, and sync are integration concerns.
+
+### req:_js/001
+
+- **001** The JS runtime is a single file under 3 kB minified+gzipped. It reads `data-hid` and `data-sid`, delegates events on `document`, and applies effects by direct DOM mutation.
+
+### req:_js/002
+
+- **002** No build step, no virtual DOM, no diffing, no scheduler. Receiving an effect = apply ops immediately in declared order.
+
+### req:_js/003
+
+- **003** The runtime consists of an Op interpreter (`ReplaceHtml`, `SetText`, `PatchAtom`, `Navigate`, `Focus`, `AddClass`, `RemoveClass`, `RemoveKeyed`, `CustomOp`) reading from a postcard byte stream.
+
+### req:_list/001
+
+- **001** Any `data-slhx-slot` or `data-slhx-handle` inside `@for` requires an explicit `key` expression. Syntax: `@for item in items key item.id { ... }`. Without `key`, slhx-addressable nodes inside the loop are rejected at build time. Keyed identity is `(SlotId, KeyValue)`.
+
+### req:_list/002
+
+- **002** Slots inside a keyed loop receive a composite identity: `(SlotId, KeyValue)`, not a flat id. hemplate records `key_expr` in the Surface; slhx implements keyed slot lookups.
+
+### req:_list/003
+
+- **003** Effects on keyed slots: `replace_keyed(slot, key, value)`, `remove_keyed(slot, key)`, `append_keyed(slot, key, value)`. Mismatch between key type and slot key type is compile-time error.
+
+### req:_misc/001
+
+- **001** Workspace layout: `slhx-core` (types + postcard schema, no_std), `slhx-derive` (proc-macros), `slhx-build` (surface consumer + code generation), `slhx-axum` (integration), `slhx-js` (runtime single file), `slhx-transition` (optional), `slhx-sync` (optional), `slhx-wasm` (optional). No kitchen-sink crate.
+
+### req:_misc/002
+
+- **002** All crates compile on stable Rust. MSRV 1.80. `slhx-core` has zero proc-macro dependencies.
+
+### req:_misc/003
+
+- **003** No auth, no routing, no session storage inside slhx core. `slhx-axum` provides typed route mounting; actual routing is axum/tower.
+
+### req:_misc/004
+
+- **004** Three execution modes supported: server-first (request/response), client-local WASM (requestAnimationFrame, no round-trip), and hybrid sync (local + remote via `slhx-sync`). Modes are opt-in per handler, not global.
+
+### req:_misc/005
+
+- **005** The only user-facing proc-macro is `#[slhx::handler]`. No `!` call-syntax macros. Attribute macros only.
+
+### req:_ms/001
+
+- **001** **Milestone app: Local-first Multiplayer Kanban.** A board with drag-and-drop cards, 60fps pointer-follow, optimistic updates, offline queue, conflict reconciliation, live presence, and SSR-first rendering — all without React/Vue/VDOM, in a single typed Rust codebase. This acts as the north-star integration test for slhx + hemplate + slhx-sync. [north_star]
+
+### req:_pitch/001
+
+- **001** slhx is checked hypermedia for Rust. Authors write HTML templates and Rust handlers. The compiler lowers every cross-file reference to a stable numeric id. The browser runtime only sees ids and effect bytes. [north_star]
+
+### req:_pitch/002
+
+- **002** No CSS selectors. No hx-* strings. No virtual DOM. No client framework. No hidden global proxy magic. No hydration. [north_star]
+
+### req:_pitch/003
+
+- **003** slhx replaces React/Vue not with a UI framework, but with a compiler contract: hemplate knows the surface, Rust knows the types, slhx knows the effects, the browser only executes commands. [north_star]
+
+### req:_resource/001
+
+- **001** Async remote data lives in `Resource<T>` / `Query<K, T>` / `Mutation<I, O>`. These are optional, not core primitives. They provide loading/error/refresh semantics without client-side data libraries.
+
+### req:_resource/002
+
+- **002** `Effect::resource(res).reload()` triggers a re-fetch and re-render. The server sends a new EffectBatch when data is ready.
+
+### req:_state/001
+
+- **001** `Atom<T>` is a typed, stable-id handle to a piece of state. Atoms are the only state primitive in core.
+
+### req:_state/002
+
+- **002** State shape is flat. Nesting is an anti-pattern; compose via multiple atoms.
+
+### req:_state/003
+
+- **003** No proxy magic. State access is explicit: `store.get(atom)` returns `Option<&T>`. Mutations return `impl IntoEffect`, not side-effects.
+
+### req:_state/004
+
+- **004** Page-local transient state lives in JS as `Map<AtomId, unknown>`. Not reactive-by-default.
+
+### req:_state/005
+
+- **005** Global long-lived state is stored server-side in a session-compatible way. On re-render the server injects a `postcard`-encoded blob in `<script type="application/slhx-state">`; JS hydrates it so client-side handlers (WASM-compiled Rust) can read it without round-trips.
+
+### req:_state/006
+
+- **006** The atom model is isomorphic to ECS. Atoms are components, Pages are worlds, Slots are entities. Scales to game-like WASM applications.
+
+### req:_surface/001
+
+- **001** `hemplate_build` scans `.heml` files and emits `$OUT_DIR/hemplate.surface.postcard` (postcard-encoded, deterministic, versioned).
+
+### req:_surface/002
+
+- **002** The Surface contains: nodes (NodeId, parent, scope, element, attrs, source span), scopes (ScopeKind: Root | If | For { binding, key_expr }), forms (form controls with raw HTML types), and component uses.
+
+### req:_surface/003
+
+- **003** Node identity is `NodeId` in a parent/scope graph. No `css_path` is used as a primary identifier. An optional `debug_path` string may exist for diagnostics only.
+
+### req:_surface/004
+
+- **004** Form controls in the Surface carry raw HTML facts: `ControlKind::Text`, `ControlKind::Number { min, max, step }`, `ControlKind::Checkbox`, `ControlKind::Select { multiple, options }`, etc. No Rust type mapping lives in hemplate.
+
+### req:_surface/005
+
+- **005** Loop scopes expose the binding name and an optional `key_expr` (e.g. `todo.id`). hemplate does not enforce key usage; it only records it for consumers.
+
+### req:_surface/006
+
+- **006** Surface schema is versioned (`schema_version: u32`). Postcard encoding, no JSON. `no_std`-compatible schema definition so any tool can read it without heavy dependencies.
+
+### req:_surface/007
+
+- **007** `hemplate-derive` does not write Surface files. Surface generation is a `build.rs` / `hemplate_build` concern, proc-macro side-effect free.
+
+### req:_sync/001
+
+- **001** `slhx-sync` is an optional crate for collaborative / multiplayer state. Provides presence tracking, patch reconciliation, conflict resolution (server-authoritative), and offline queueing. Not part of core.
+
+### req:_sync/002
+
+- **002** `SyncEffect::send_patch(atom, patch)` queues a state diff for server sync. If offline, the patch is stored in a local queue and sent when connection resumes. If online, it is sent immediately via WebSocket/SSE.
+
+### req:_sync/003
+
+- **003** `Effect::ack(atom)` acknowledges a successful server-side mutation, allowing the client to clear its local optimistic queue for that atom.
+
+### req:_sync/004
+
+- **004** `Effect::broadcast(channel, effect_batch)` sends an `EffectBatch` to all subscribers of a named channel. Used for presence updates and live collaboration. The server framework manages the transport (WS/SSE).
+
+### req:_sync/005
+
+- **005** `#[slhx_sync::presence]` is an attribute macro on functions that return `impl IntoEffect` when a user joins or leaves a shared session. Emits `Effect::broadcast` over a presence channel scoped to the session.
+
+### req:_sync/006
+
+- **006** `slhx-sync` uses a flat patch model per atom, not CRDT by default. Server is authoritative; clients apply server-canonical state on conflict. Optional CRDT backend may be provided by a future `slhx-crdt` crate.
+
+### req:_wire/001
+
+- **001** HTML wire format is standard HTML with `data-hid` and `data-sid` attributes only. No custom markup, no hx-* attributes.
+
+### req:_wire/002
+
+- **002** POST bodies carry `application/x-www-form-urlencoded` with distinguished field `__h` (handle id). Server routes by numeric id, not by URL path.
+
+### req:_wire/003
+
+- **003** Responses are `text/html` fragments (or `application/slhx` for push streams). Fragments may contain `<template data-slhx>` elements whose text content is a base64url-encoded postcard `EffectBatch`. JS decodes and applies.
+
+### req:_wire/004
+
+- **004** Server push is supported orthogonally: `Effect::push(stream, effect)` sends a pre-serialized effect batch over an SSE or WebSocket connection. Connection management is a server-framework concern.
+
+## Coverage: 0/68 (100.0% uncited)
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..2fceb18
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,11 @@
+[workspace]
+resolver = "2"
+members = ["slhx-core", "slhx-derive", "slhx-js", "slhx-axum"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+
+[profile.release]
+opt-level = "z"
+lto = true
diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
new file mode 100644
index 0000000..949b336
--- /dev/null
+++ b/REQUIREMENTS.md
@@ -0,0 +1,365 @@
+# slhx — Semantic, Laterally HX
+
+slhx does not compete with React by becoming a better frontend framework.
+slhx competes with React by making frontend frameworks unnecessary for most apps.
+
+> **hemplate owns syntax. hemplate emits surface. slhx consumes surface. slhx owns semantics. JS executes bytecode.**
+
+---
+
+## pitch
+
+### req: pitch/001
+001	slhx is checked hypermedia for Rust. Authors write HTML templates and Rust handlers. The compiler lowers every cross-file reference to a stable numeric id. The browser runtime only sees ids and effect bytes. [north_star]
+
+### req: pitch/002
+002	No CSS selectors. No hx-* strings. No virtual DOM. No client framework. No hidden global proxy magic. No hydration. [north_star]
+
+### req: pitch/003
+003	slhx replaces React/Vue not with a UI framework, but with a compiler contract: hemplate knows the surface, Rust knows the types, slhx knows the effects, the browser only executes commands. [north_star]
+
+---
+
+## invariant
+
+### req: invariant/001
+001	User-authored references are symbolic at author time and numeric at runtime.
+
+### req: invariant/002
+002	The JS runtime never parses CSS selectors, expressions, or handler names.
+
+### req: invariant/003
+003	Rust handlers return effects; they do not imperatively mutate DOM.
+
+### req: invariant/004
+004	Cross-file references fail at `cargo check` with a precise span.
+
+### req: invariant/005
+005	slhx core owns effects, typed ids, and registries only. Routing, auth, sessions, transport, transitions, and sync are integration concerns.
+
+---
+
+## boundary
+
+### req: boundary/001
+001	hemplate does not expose a slhx API. It exposes a stable, generic Template Surface IR. slhx is one consumer; a11y tools, test generators, and documentation generators are others.
+
+### req: boundary/002
+002	hemplate never interprets `data-slhx-*`, `slhx-*`, or any other tool-prefixed attribute. It records them as raw `name: value` pairs in the Surface.
+
+### req: boundary/003
+003	slhx never parses `.heml` directly. It consumes `hemplate.surface.postcard` emitted by `hemplate_build`. slhx interprets tool-specific conventions (`data-slhx-handle`, `data-slhx-slot`, etc.) from the generic Surface.
+
+---
+
+## surface
+
+### req: surface/001
+001	`hemplate_build` scans `.heml` files and emits `$OUT_DIR/hemplate.surface.postcard` (postcard-encoded, deterministic, versioned).
+
+### req: surface/002
+002	The Surface contains: nodes (NodeId, parent, scope, element, attrs, source span), scopes (ScopeKind: Root | If | For { binding, key_expr }), forms (form controls with raw HTML types), and component uses.
+
+### req: surface/003
+003	Node identity is `NodeId` in a parent/scope graph. No `css_path` is used as a primary identifier. An optional `debug_path` string may exist for diagnostics only.
+
+### req: surface/004
+004	Form controls in the Surface carry raw HTML facts: `ControlKind::Text`, `ControlKind::Number { min, max, step }`, `ControlKind::Checkbox`, `ControlKind::Select { multiple, options }`, etc. No Rust type mapping lives in hemplate.
+
+### req: surface/005
+005	Loop scopes expose the binding name and an optional `key_expr` (e.g. `todo.id`). hemplate does not enforce key usage; it only records it for consumers.
+
+### req: surface/006
+006	Surface schema is versioned (`schema_version: u32`). Postcard encoding, no JSON. `no_std`-compatible schema definition so any tool can read it without heavy dependencies.
+
+### req: surface/007
+007	`hemplate-derive` does not write Surface files. Surface generation is a `build.rs` / `hemplate_build` concern, proc-macro side-effect free.
+
+---
+
+## build
+
+### req: build/001
+001	Build order: `.heml` → `hemplate_build` → `hemplate.surface.postcard` → `slhx_build` → `slhx.syms` + generated Rust constants.
+
+### req: build/002
+002	`slhx-derive` (`#[slhx::handler]`) reads `slhx.syms` at expansion time to validate handle names, slot names, and form signatures.
+
+### req: build/003
+003	A `build.rs` failure (missing Surface, version mismatch, stale hash) is a hard error before proc-macro expansion.
+
+---
+
+## effect
+
+### req: effect/001
+001	Rust handlers return `impl IntoEffect`, not a concrete `Vec<Effect>`. `IntoEffect::encode(self, &mut EffectWriter)` may write directly into a response buffer, a test collector, or an event stream. Zero-allocation encoding is possible; allocation is not required.
+
+### req: effect/002
+002	`EffectWriter` has a fixed canonical op set: `Set`, `Patch`, `Insert`, `Remove`, `Move`, `Focus`, `Navigate`, `Emit`. The DOM is one backend; core does not hardcode DOM operations. Wire format is canonical postcard opcodes; Rust API is flexible.
+
+### req: effect/003
+003	Multiple effects are combined with `Effect::batch((...))` or a method chain on `EffectWriter`. No `!` call-syntax macros.
+
+### req: effect/004
+004	`Effect::render(slot, value)` is sugar for `Effect::set` on a Slot resource. `Effect::text(slot, value)` is sugar for `Effect::set` with a text payload.
+
+### req: effect/005
+005	effects may carry an opaque transition token, but core never interprets or implements transitions. `slhx-transition` provides transition semantics as an orthogonal integration.
+
+### req: effect/006
+006	`Effect::event(name, payload)` dispatches a native `CustomEvent` on the root element. Core interprets the payload as opaque bytes. Web Components, charts, editors, or legacy JS may listen without slhx knowing about them. [north_star]
+
+---
+
+## state
+
+### req: state/001
+001	Typed atoms with `Atom<T>`: read via `atom.get()`, subscribe via `Effect::set`. No hidden global proxy / reactive graph. Atoms are explicit values in `struct App`.
+
+### req: state/002
+002	Subscription is explicit: `Effect::set(atoms::FOO, 42)` pushes the new value to all consumers. No automatic component re-render graph.
+
+### req: state/003
+003	JS runtime maintains a client-side atom store with identical API to the server: `get<T>(atom)`, `set<T>(atom, value)`, `subscribe<T>(atom, callback)`. Type erased at runtime with `TypeId`.
+
+### req: state/004
+004	SSR pages carry a `data-slhx-st` base64url-encoded postcard blob on the document root. Runtime decodes it into the client atom store. Atoms computed from server state are immediately available to client-side handlers without a round-trip.
+
+---
+
+## form
+
+### req: form/001
+001	Forms are source of truth in HTML. hemplate Surface exports form shape (controls, names, required, types). slhx checks compatibility with the Rust handler's `Form<T>` type. No auto-generated structs; domain types (e.g. `Email`) are first-class. The Surface describes; Rust owns; slhx checks.
+
+### req: form/002
+002	The handle id is carried as `__h` in POST `application/x-www-form-urlencoded`. A JSON body is allowed at the integration boundary (`application/json`) only if the handler accepts it; core uses form encoding.
+
+### req: form/003
+003	handler receives `form: Form<CreateTodo>`. Validation errors are returned as `Effect::form_error(field, message)`, which the JS runtime maps back to the originating input via `data-sid`.
+
+---
+
+## list
+
+### req: list/001
+001	Any `data-slhx-slot` or `data-slhx-handle` inside `@for` requires an explicit `key` expression. Syntax: `@for item in items key item.id { ... }`. Without `key`, slhx-addressable nodes inside the loop are rejected at build time. Keyed identity is `(SlotId, KeyValue)`.
+
+### req: list/002
+002	Slots inside a keyed loop receive a composite identity: `(SlotId, KeyValue)`, not a flat id. hemplate records `key_expr` in the Surface; slhx implements keyed slot lookups.
+
+### req: list/003
+003	Effects on keyed slots: `replace_keyed(slot, key, value)`, `remove_keyed(slot, key)`, `append_keyed(slot, key, value)`. Mismatch between key type and slot key type is compile-time error.
+
+---
+
+## typed_id
+
+### req: typed_id/001
+001	All public cross-page identifiers (`Slot`, `Atom`, `Handle`, `Form`) share a single internal primitive `ResourceId { kind: ResourceKind, id: u32, key: Option<ScopeKey> }`. Typed wrappers (`Slot<T>`, `KeyedSlot<K, T>`, `Atom<T>`, `Handle<I>`, `Form<T>`) enforce kind safety at compile time. No special-case opcodes per resource kind; effects address resources uniformly. [north_star]
+
+### req: typed_id/002
+002	`ResourceKind` is an internal closed enum (Slot, Atom, Handle, Form, Route). External crates may not add variants. Extensibility comes via `Effect::event`, `Effect::emit`, or custom `IntoEffect` implementations, never via new `ResourceKind` variants in core.
+
+---
+
+## async_data
+
+### req: async_data/001
+001	Async remote data lives in `Resource<T>` / `Query<K, T>` / `Mutation<I, O>`. These are optional, not core primitives. They provide loading/error/refresh semantics without client-side data libraries.
+
+### req: async_data/002
+002	`Effect::resource(res).reload()` triggers a re-fetch and re-render. The server sends a new EffectBatch when data is ready.
+
+---
+
+## scope
+
+### req: scope/001
+001	`Scope` is a first-class primitive. Keyed loops (`@for`), conditional branches (`@if`), component instances, modals, tabs, nested forms — all are scopes. A slhx-addressable node inside any dynamic scope must carry a stable `ScopeKey`. Composite identity is `(ResourceId, ScopeKey)`. [north_star]
+
+---
+
+## wire
+
+### req: wire/001
+001	HTML wire format is standard HTML with `data-hid` and `data-sid` attributes only. No custom markup, no hx-* attributes.
+
+### req: wire/002
+002	POST bodies carry `application/x-www-form-urlencoded` with distinguished field `__h` (handle id). Server routes by numeric id, not by URL path.
+
+### req: wire/003
+003	Responses are `text/html` fragments (or `application/slhx` for push streams). Fragments may contain `<template data-slhx>` elements whose text content is a base64url-encoded postcard `EffectBatch`. JS decodes and applies.
+
+### req: wire/004
+004	Server push is supported orthogonally: `Effect::push(stream, effect)` sends a pre-serialized effect batch over an SSE or WebSocket connection. Connection management is a server-framework concern.
+
+### req: wire/005
+005	No JSON anywhere in slhx-internal artifacts. Public request/response envelopes use `application/x-www-form-urlencoded`; effects and symbols use postcard. `application/json` is acceptable only at integration boundaries.
+
+---
+
+## runtime
+
+### req: runtime/001
+001	Every slhx tree must declare a root boundary via `data-slhx-root` on an ancestor element. The JS runtime resolves lookups within that root only. Multiple independent slhx apps/widgets/modals may coexist on the same document without ID collision. [north_star]
+
+### req: runtime/002
+002	JS runtime attaches a single delegated listener per event type on the root. No per-node listeners. Dispatch resolves target via `data-hid` / `data-sid` attributes on the event path.
+
+### req: runtime/003
+003	The JS runtime is a tiny op interpreter (~2KB, no selectors, no VDOM, no scheduler, no expressions). It reads postcard `EffectBatch` bytes and applies them as DOM operations.
+
+### req: runtime/004
+004	`RuntimeCaps { binary, wasm, sync, transitions }` is exchanged once at init. Handlers may query capabilities and degrade gracefully (e.g. fall back to server request if WASM unavailable). Core does not know about these features; caps are opaque to the wire protocol and only consulted by integrations.
+
+---
+
+## js
+
+### req: js/001
+001	Runtime reads attributes `data-hid` and `data-sid`, delegates events on `document`, and applies effects by direct DOM mutation.
+
+### req: js/002
+002	No build step, no virtual DOM, no diffing, no scheduler. Receiving an effect = apply ops immediately in declared order.
+
+### req: js/003
+003	The runtime consists of an Op interpreter (`ReplaceHtml`, `SetText`, `PatchAtom`, `Navigate`, `Focus`, `AddClass`, `RemoveClass`, `RemoveKeyed`, `CustomOp`) reading from a postcard byte stream.
+
+---
+
+## check
+
+### req: check/001
+001	All cross-file references verified at `cargo check`. Unknown handle → hard error. Unknown slot → hard error. Type mismatch between slot and atom → hard error.
+
+### req: check/002
+002	Dead handle warning: `#[slhx::handler]` never referenced by any template. Dead slot warning: template node never targeted by any handler.
+
+### req: check/003
+003	Renaming a slot or handle breaks `cargo check` immediately with a span pointing to the Rust handler or template source.
+
+### req: check/004
+004	Page-scoped slot lookup: JS runtime resolves `data-sid` only within the current Page root element.
+
+---
+
+## sync
+
+### req: sync/001
+001	`slhx-sync` is an optional crate for collaborative / multiplayer state. Provides presence tracking, patch reconciliation, conflict resolution (server-authoritative), and offline queueing. Not part of core.
+
+### req: sync/002
+002	`SyncEffect::send_patch(atom, patch)` queues a state diff for server sync. If offline, the patch is stored in a local queue and sent when connection resumes. If online, it is sent immediately via WebSocket/SSE.
+
+### req: sync/003
+003	`Effect::ack(atom)` acknowledges a successful server-side mutation, allowing the client to clear its local optimistic queue for that atom.
+
+### req: sync/004
+004	`Effect::broadcast(channel, effect_batch)` sends an `EffectBatch` to all subscribers of a named channel. Used for presence updates and live collaboration. The server framework manages the transport (WS/SSE).
+
+### req: sync/005
+005	`#[slhx_sync::presence]` is an attribute macro on functions that return `impl IntoEffect` when a user joins or leaves a shared session. Emits `Effect::broadcast` over a presence channel scoped to the session.
+
+### req: sync/006
+006	`slhx-sync` uses a flat patch model per atom, not CRDT by default. Server is authoritative; clients apply server-canonical state on conflict. Optional CRDT backend may be provided by a future `slhx-crdt` crate.
+
+---
+
+## interop
+
+### req: interop/001
+001	`Effect::event` (see req:effect/006) is the single bridge between slhx and third-party JS. External widgets, charts, and maps listen via native `CustomEvent`. slhx core does not inspect or manage them. [north_star]
+
+### req: interop/002
+002	Web Components and custom elements are valid opaque leaf nodes. slhx does not inspect shadow DOM. Escape hatches are leaves, never app foundations.
+
+### req: interop/003
+003	WASM islands (`#[slhx::island]`) compile handler code to WASM for client-local execution. The island is a leaf in the DOM; slhx core is unaware of WASM except via the same `EffectBatch` contract.
+
+---
+
+## test
+
+### req: test/001
+001	`EffectWriter` implements a test backend so handlers can be unit-tested without a browser: `slhx_test::run(handler, input)` returns an `EffectInspector` with `contains(op)`, `has_slot(slot)`, `has_atom(atom)`, etc.
+
+---
+
+## navigation
+
+### req: nav/001
+001	Navigation is an effect, not a router framework: `Effect::navigate(url, mode, scroll, title)`. Core supports `Push`, `Replace`, `Redirect`. Actual route matching, guards, loaders, and nested routes are outside core.
+
+### req: nav/002
+002	Navigation modes: `Push` (history.pushState), `Replace` (replaceState), `Redirect` (server-side 302). Scroll behaviour: `Preserve`, `Top`, `Element(ResourceId)`. Title is optional.
+
+---
+
+## escape_hatch
+
+### req: escape_hatch/001
+001	Three sanctioned escape hatches exist: (1) Web Components as opaque leaf nodes, (2) `Effect::event` for imperative JS interop, (3) WASM islands for CPU-intensive client logic. All three are leaves in the slhx tree, never the app foundation.
+
+---
+
+## derive_handler
+
+### req: derive_handler/001
+001	`#[slhx::handler]` validates: handle name exists in symbol table, params match form surface or `data-*` attributes, return type implements `IntoEffect`. Generate code registers the function in a static lookup table keyed by numeric handle id.
+
+### req: derive_handler/002
+002	Handler param inference from `data-*` attributes: when a template declares `data-card-id="{card.id}"` on a node with `data-slhx-handle`, the handler may declare `card_id: CardId` as a parameter. slhx-build checks attribute → param name and type mapping.
+
+---
+
+## derive_app
+
+### req: derive_app/001
+001	`#[slhx::app]` marks the root application struct containing all global atoms. It is the registry entry point for `slhx_build`. Zero or single instance per process.
+
+---
+
+## ts
+
+### req: ts/001
+001	TypeScript definitions for `slhx-js` runtime are shipped as a single `.d.ts` file. Types mirror the postcard `EffectBatch` schema for advanced consumers. Tooling must not depend on these types for core functionality; they are developer convenience only.
+
+---
+
+## milestone
+
+### req: ms/001
+001	**Milestone app: Local-first Multiplayer Kanban.** A board with drag-and-drop cards, 60fps pointer-follow, optimistic updates, offline queue, conflict reconciliation, live presence, and SSR-first rendering — all without React/Vue/VDOM, in a single typed Rust codebase. This acts as the north-star integration test for slhx + hemplate + slhx-sync. [north_star]
+
+---
+
+## misc
+
+### req: misc/001
+001	Workspace layout: `slhx-core` (types + postcard schema, no_std), `slhx-derive` (proc-macros), `slhx-build` (surface consumer + code generation), `slhx-axum` (integration), `slhx-js` (runtime single file), `slhx-transition` (optional), `slhx-sync` (optional), `slhx-wasm` (optional). No kitchen-sink crate.
+
+### req: misc/002
+002	All crates compile on stable Rust. MSRV 1.80. `slhx-core` has zero proc-macro dependencies.
+
+### req: misc/003
+003	No auth, no routing, no session storage inside slhx core. `slhx-axum` provides typed route mounting; actual routing is axum/tower.
+
+### req: misc/004
+004	Three execution modes supported: server-first (request/response), client-local WASM (requestAnimationFrame, no round-trip), and hybrid sync (local + remote via `slhx-sync`). Modes are opt-in per handler, not global.
+
+### req: misc/005
+005	The only user-facing proc-macro is `#[slhx::handler]`. No `!` call-syntax macros. Attribute macros only.
+
+### req: misc/006
+006	Source spans are present on every Surface node, attribute, and scope. Error messages cite file, line, and column. This is non-negotiable for DX.
+
+### req: misc/007
+007	All slhx HTML attributes use `data-` prefix (`data-slhx-handle`, `data-slhx-slot`, `data-slhx-atom`, `data-slhx-root`). No unprefixed custom attributes. Valid HTML, tool-friendly, zero custom syntax.
+
+### req: misc/008
+008	Id allocation is deterministic from canonical symbol paths. Ids are stable across builds unless the symbol path changes. Deploy mismatch between server and client is caught by a build-schema version check, not silent failure.
+
+### req: misc/009
+009	Core design rule: add one primitive only if it deletes five special cases. `ScopeKey` deletes: loop keying, component scoping, modal instances, nested forms, portal boundaries. `ResourceId` deletes: special opcodes per kind, separate registries, separate wire formats, separate test APIs. `Effect::event` deletes: plugin API, custom JS bridges, chart adapters, map SDK wrappers.
diff --git a/examples/kanban.md b/examples/kanban.md
new file mode 100644
index 0000000..13d7950
--- /dev/null
+++ b/examples/kanban.md
@@ -0,0 +1,352 @@
+# Milestone: Local-first Multiplayer Kanban
+
+A board with drag-and-drop cards, 60fps pointer-follow, optimistic updates,
+offline queue, conflict reconciliation, live presence, and SSR-first rendering —
+all without React/Vue/VDOM, in a single typed Rust codebase.
+
+This is the north-star integration test for slhx + hemplate + slhx-sync.
+
+---
+
+## 1. Template: `board.heml`
+
+```html
+<section data-slhx-slot="board" data-slhx-atom="board">
+    <header>
+        <h1>{self.title}</h1>
+
+        <form data-slhx-handle="create_card">
+            <input name="title" type="text" required>
+            <select name="column">
+                @for column in self.columns key column.id {
+                    <option value="{column.id}">{column.title}</option>
+                }
+            </select>
+            <button>Add card</button>
+        </form>
+    </header>
+
+    <div class="columns" data-slhx-slot="columns">
+        @for column in self.columns key column.id {
+            <section
+                class="column"
+                data-slhx-slot="column"
+                data-column-id="{column.id}"
+            >
+                <h2>{column.title}</h2>
+
+                <div
+                    class="cards"
+                    data-slhx-dropzone="column"
+                    data-column-id="{column.id}"
+                >
+                    @for card in column.cards key card.id {
+                        <article
+                            class="card"
+                            data-slhx-slot="card"
+                            data-slhx-handle="drag_card"
+                            data-card-id="{card.id}"
+                            draggable="true"
+                        >
+                            <strong>{card.title}</strong>
+                            <small>{card.assignee}</small>
+                        </article>
+                    }
+                </div>
+            </section>
+        }
+    </div>
+
+    <aside data-slhx-slot="presence">
+        @for user in self.online_users key user.id {
+            <span>{user.name}</span>
+        }
+    </aside>
+</section>
+```
+
+Notes on keyed scopes:
+
+- `@for column key column.id` — **required** for slhx-addressable nodes inside
+- `@for card key card.id` — **required**
+- A slot inside a keyed loop is addressed as `(SlotId, KeyValue)`, never `querySelector(".card:nth-child(3)")`
+- Without `key`, slhx rejects the build — no runtime selector fallback
+
+---
+
+## 2. What hemplate exports
+
+hemplate does **not** interpret `data-slhx-*`. It records raw facts:
+
+```rust
+Node {
+    id: NodeId(12),
+    element: "article",
+    attrs: [
+        ("class", "card"),
+        ("data-slhx-slot", "card"),
+        ("data-slhx-handle", "drag_card"),
+        ("data-card-id", "{card.id}"),
+        ("draggable", "true"),
+    ],
+    scope: ScopeId(For { binding: "card", key_expr: "card.id" }),
+}
+
+FormSurface {
+    handle_attr: Some("create_card"),
+    controls: [
+        Control { name: "title", kind: Text, required: true },
+        Control { name: "column", kind: Select, required: true },
+    ],
+}
+```
+
+slhx reads this from `hemplate.surface.postcard` and generates typed constants:
+
+```rust
+pub const CARD: KeyedSlot<CardId, CardView> = KeyedSlot::new(3);
+pub const CREATE_CARD: Handle<CreateCardForm> = Handle::new(0);
+```
+
+No string desync. No runtime mapping.
+
+---
+
+## 3. App State
+
+```rust
+#[slhx::app]
+pub struct BoardApp {
+    pub board: Atom<BoardState>,
+    pub drag: Atom<Option<DragState>>,
+    pub online_users: Atom<Vec<UserPresence>>,
+}
+```
+
+The same struct runs on server (SSR) and in WASM (client-local effects).
+
+---
+
+## 4. Normal Form: Server-first
+
+```rust
+#[derive(SlhxForm)]
+pub struct CreateCardForm {
+    pub title: String,
+    pub column: ColumnId,
+}
+
+#[slhx::handler]
+pub fn create_card(
+    form: Form<CreateCardForm>,
+    app: &mut BoardApp,
+) -> impl IntoEffect {
+    let card = Card { id: CardId::new(), title: form.title, assignee: "Thomas".into() };
+
+    app.board.update(|board| board.insert_card(form.column, card.clone()));
+
+    Effect::batch((
+        Effect::append_keyed(slots::CARD, card.id, CardView::from(card)),
+        // slhx-sync: queue atomic board state diff for sync
+        SyncEffect::send_patch(atoms::BOARD, Patch::insert_card(form.column, card)),
+    ))
+}
+```
+
+HTML submits as usual. Server returns `EffectBatch`. Browser applies DOM ops.
+
+---
+
+## 5. Drag: 60fps client-local WASM
+
+```rust
+#[slhx::handler(client)]
+pub fn drag_card(
+    event: DragEvent,
+    app: &mut BoardApp,
+) -> impl IntoEffect {
+    app.drag.set(Some(DragState {
+        card_id: event.card_id,
+        from_column: event.column_id,
+        pointer_x: event.x,
+        pointer_y: event.y,
+    }));
+
+    Effect::batch((
+        Effect::class_keyed(slots::CARD, event.card_id, "dragging", true),
+        Effect::transform_keyed(
+            slots::CARD, event.card_id,
+            Transform::translate(event.x, event.y),
+        ),
+    ))
+}
+```
+
+Zero round-trip. Zero custom JS. Pure Rust → EffectBatch → DOM.
+
+---
+
+## 6. Drop: optimistic update + sync
+
+```rust
+#[slhx::handler(client)]
+pub fn drop_card(
+    event: DropEvent,
+    app: &mut BoardApp,
+) -> impl IntoEffect {
+    let patch = app.board.update(|board| {
+        board.move_card(event.card_id, event.to_column, event.before_card)
+    });
+
+    app.drag.set(None);
+
+    Effect::batch((
+        Effect::move_keyed(
+            slots::CARD, event.card_id,
+            slots::COLUMN, event.to_column,
+            InsertBefore(event.before_card),
+        ),
+        Effect::class_keyed(slots::CARD, event.card_id, "dragging", false),
+        // slhx-sync: queue patch, send when online
+        SyncEffect::send_patch(atoms::BOARD, patch),
+    ))
+}
+```
+
+A pure htmx+SSR app cannot model this: 60fps pointer → local transient drag → optimistic update → offline queue → reconciliation. You'd need custom JS or a parallel React/Vue layer.
+
+slhx models it in one type graph.
+
+---
+
+## 7. Server reconciliation
+
+```rust
+#[slhx_sync::handler]
+pub fn apply_board_patch(
+    patch: BoardPatch,
+    app: &mut BoardApp,
+    user: UserId,
+) -> impl IntoEffect {
+    let result = app.board.update(|board| board.apply_patch_from(user, patch));
+
+    match result {
+        PatchResult::Accepted { changed_cards } => Effect::batch((
+            Effect::ack(atoms::BOARD),
+            Effect::broadcast(
+                Channel::Board(app.board.id()),
+                Effect::batch(changed_cards.into_iter().map(|c|
+                    Effect::replace_keyed(slots::CARD, c.id, CardView::from(c))
+                )),
+            ),
+        )),
+
+        PatchResult::Conflict { canonical_board } => Effect::batch((
+            Effect::set(atoms::BOARD, canonical_board.clone()),
+            Effect::render(slots::BOARD, BoardView::from(canonical_board)),
+        )),
+    }
+}
+```
+
+Server-authoritative on conflict. No Redux sagas. No React Query cache fades.
+
+---
+
+## 8. Presence
+
+```rust
+#[slhx_sync::presence]
+pub fn user_joined(user: UserPresence) -> impl IntoEffect {
+    Effect::append_keyed(slots::PRESENCE_USER, user.id, PresenceBadge::from(user))
+}
+```
+
+Browser receives raw `EffectBatch` over WebSocket/SSE:
+
+```text
+Op::AppendKeyed(slot=PRESENCE_USER, key=user_id, html=...)
+Op::RemoveKeyed(slot=PRESENCE_USER, key=user_id)
+```
+
+The runtime does not know "presence". It executes ops.
+
+---
+
+## 9. What the browser receives
+
+Initial SSR:
+
+```html
+<section data-sid="0" data-aid="0">
+    ...
+    <article data-sid="3" data-sk="42" data-hid="1">
+        Fix login bug
+    </article>
+    ...
+</section>
+<script src="/slhx.js"></script>
+<script type="application/slhx-state">
+BASE64URL_POSTCARD_INITIAL_ATOMS
+</script>
+```
+
+Runtime attachment:
+
+```js
+document.addEventListener("submit", dispatch)
+document.addEventListener("click", dispatch)
+document.addEventListener("pointerdown", dispatch)
+document.addEventListener("pointermove", dispatch)
+document.addEventListener("pointerup", dispatch)
+```
+
+No framework download. No VDOM. No hydration. No game loop.
+
+---
+
+## 10. Why this is not a React/Vue/htmx app
+
+| Concern | React/Vue | htmx+SSR | slhx |
+|---|---|---|---|
+| SSR | RSC/Vue SSR | native | native (hemplate) |
+| 60fps drag | 100ms re-render + React-DnD | custom JS | WASM handler, EffectBatch |
+| Optimistic update | useOptimistic | impossible | `board.update` → `SyncEffect::send_patch` |
+| Offline support | Service Worker + custom | impossible | patch queue in `slhx-sync` |
+| Conflict resolution | manual / Yjs CRDT | impossible | server-authoritative patch |
+| Presence | WebSocket + custom state | SSE possible | `Effect::broadcast` over channel |
+| Keyed DOM | React key | not a concern | `KeydSlot<T, K>` compile-time |
+| Forms | React Hook Form | HTML native, but no validation bridge | `Fork<T>` derived from `.heml` surface |
+| Routing | React Router / Vue Router | HTML links, but no state routing | `Effect::navigate` with scroll/title |
+| Total JS shipped | ~300KB+ | ~20KB htmx + custom | ~3KB slhx.js interpreter |
+
+---
+
+## 11. The claim
+
+```text
+A local-first multiplayer board where all high-frequency UI runs as Rust/WASM effects,
+all durable state syncs through slhx-sync,
+all HTML is hemplate-rendered,
+and the browser runtime only executes typed postcard DOM ops.
+```
+
+Not:
+
+```text
+server Rust here
+client TypeScript there
+shared schema somewhere
+validation duplicated
+DOM identity by selectors
+state sync by convention
+```
+
+But:
+
+```text
+Rust owns types.
+hemplate owns structure.
+slhx owns interaction.
+browser executes ops.
+```