@vielzeug/codex 1.0.2 → 1.0.4

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug — Full Documentation
 
-> Complete documentation for all 30 Vielzeug packages. Version: 1.0.2
+> Complete documentation for all 31 Vielzeug packages. Version: 1.0.3
 
 ---
 
@@ -1211,6 +1211,569 @@ const price = currency({ amount: 123456n, currency: 'USD' }); // $1,234.56
 - Type checking utilities (id: `typed-is`)
 
 
+---
+
+## @vielzeug/assay
+
+**Category:** testing
+**Keywords:** testing, dom, events, queries, waitfor, custom-elements, jsdom
+**Key exports:** within, query, queryAll, queryByTestId, queryAllByTestId, queryByText, queryAllByText, queryInShadow, queryAllInShadow, queryPart, getSlotted, fire (+7 more)
+**Related:** ore, refine
+
+### Overview
+
+## Why Assay?
+
+Testing DOM-level code (custom elements, vanilla event handlers, framework-rendered output) usually means hand-rolling `dispatchEvent` boilerplate and ad-hoc polling loops, or pulling in a full testing-library dependency tied to one framework's rendering model. Assay extracts just the generic, framework-agnostic pieces — scoped queries, event dispatch, async waiting — as a standalone, zero-dependency package.
+
+```ts
+// Before — hand-rolled event dispatch and polling in every test file
+const btn = panel.querySelector('button.submit')!;
+
+btn.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+
+const deadline = Date.now() + 1000;
+while (Date.now()  setTimeout(r, 50));
+}
+
+// After
+import { fire, waitFor, within } from '@vielzeug/assay';
+
+const { query, queryByText } = within(panel);
+
+fire.click(query('button.submit')!);
+await waitFor(() => queryByText('Saved') !== null);
+```
+
+| Feature                | Assay                                            | @testing-library/dom                    |
+| ----------------------- | ------------------------------------------------ | ---------------------------------------- |
+| Bundle size             |        | ~15 kB                                   |
+| Framework-agnostic      |       |  |
+| Scoped queries          |  `within()` |  |
+| Low-level event dispatch|  `fire.*` | Partial (`fireEvent`)               |
+| Deterministic `waitFor` |       |  |
+| Zero dependencies       |       |      |
+
+**Use Assay when** you're testing custom elements or vanilla DOM code and want scoped queries, synchronous event dispatch, and async waiting without adopting a framework-specific testing library.
+
+**Consider alternatives when** you're already standardized on `@testing-library/dom` (or a framework-specific wrapper around it) and don't need to avoid that dependency.
+
+## Installation
+
+Assay is a testing dependency — install it alongside your test runner.
+
+```sh [pnpm]
+pnpm add -D @vielzeug/assay
+```
+
+```sh [npm]
+npm install -D @vielzeug/assay
+```
+
+```sh [yarn]
+yarn add -D @vielzeug/assay
+```
+
+## Quick Start
+
+```ts
+import { fire, waitFor, within } from '@vielzeug/assay';
+
+const panel = document.querySelector('.panel')!;
+const { query, queryByText } = within(panel);
+
+fire.click(query('button.submit')!);
+
+await waitFor(() => queryByText('Saved') !== null);
+```
+
+## Features
+
+- `within(element)` — scoped `query`/`queryAll`/`queryByText`/`queryAllByText`/`queryByTestId`/`queryAllByTestId` for any element or shadow root, each also available as a free function (`query(root, selector)`, etc.) for when you already have a root.
+- `queryInShadow`/`queryAllInShadow`/`queryPart` — shadow-DOM-aware queries that return `null`/`[]` instead of throwing when the host has no shadow root.
+- `getSlotted(host, slotName?)` — light-DOM children assigned to a named slot, or every slotted child.
+- `fire.*` — low-level synchronous DOM event dispatchers (`click`, `input`, `keyDown`, `pointerDown`/`pointerMove`/`pointerCancel`, `custom`, and more), each with sensible `bubbles`/`cancelable` defaults and a consistent `boolean` return value — no exceptions.
+- `waitFor(fn, options?)` — polls until a callback returns truthy or a bare `expect()` call doesn't throw; always rejects with `AssayTimeoutError` on timeout, with the original failure preserved as `.cause`.
+- `waitForEvent(element, name, timeout?)` — resolves with the next matching event, or rejects with `AssayTimeoutError`.
+- `nextTick()`/`wait(ms?)` — microtask and macrotask timing helpers for reactive updates and debounced code.
+- `AssayError` / `AssayTimeoutError` — a single error hierarchy for every timeout this package raises.
+- No DOM-framework coupling — works with vanilla custom elements, `@vielzeug/ore` components, or any other DOM output.
+
+## Documentation
+
+- [Usage Guide](./usage.md)
+- [API Reference](./api.md)
+
+## See Also
+
+- [Ore](/ore/) — web-component authoring library whose `@vielzeug/ore/testing` sub-path re-exports Assay's query/event/wait primitives
+- [Refine](/refine/) — accessible component library built on Ore, testable with the same Assay primitives
+
+### API Reference
+
+## API Overview
+
+| Symbol              | Purpose                                              | Execution mode | Common gotcha |
+| -------------------- | ----------------------------------------------------- | -------------- | -------------- |
+| `within(element)`    | Scoped query helpers for one element/subtree           | Sync            | Returns a fresh `QueryScope` per call — cheap, but don't cache it across DOM mutations you care about |
+| `query()` / `queryAll()` | Free-function equivalents of `within(root).query`/`.queryAll` | Sync    | Use these when you already have a root and don't need the rest of `QueryScope` |
+| `queryByTestId()` / `queryAllByTestId()` | Match a `data-testid` attribute        | Sync            | Free-function equivalents of `within(root).queryByTestId`/`.queryAllByTestId` |
+| `queryByText()`      | First element matching trimmed text content            | Sync            | Matches exact trimmed text, not substrings |
+| `queryAllByText()`   | Every element matching trimmed text content            | Sync            | Same exact-match caveat as `queryByText()` |
+| `queryInShadow()` / `queryAllInShadow()` | Query inside a host's shadow root       | Sync            | Returns `null`/`[]` (not a throw) when the host has no shadow root |
+| `queryPart()`        | Query a shadow-DOM element by its `part` attribute      | Sync            | Shorthand for `queryInShadow(host, '[part="x"]')` |
+| `getSlotted()`       | Light-DOM children assigned to a slot                   | Sync            | Only direct children (`:scope >`) — doesn't recurse into further-nested slots |
+| `fire.*`             | Dispatch a DOM event synchronously                     | Sync            | Doesn't wait for anything — pair with `waitFor()`/`await` for async reactions |
+| `createPointerEvent()` | Build a `PointerEvent`, falling back to `MouseEvent` | Sync            | Only needed if you're constructing an event by hand instead of using `fire.pointer*` |
+| `waitFor()`          | Poll until a callback returns truthy or resolves       | Async           | Always rejects with `AssayTimeoutError` on timeout — the original failure is `.cause`, never the thrown error's own type |
+| `waitForEvent()`     | Resolve on the next matching event                     | Async           | Rejects with `AssayTimeoutError`, not a plain `Error`, on timeout |
+| `nextTick()`         | Resolve after one microtask tick                        | Async           | Doesn't wait for `setTimeout`-scheduled work — use `wait()` for that |
+| `wait()`             | Resolve after a fixed millisecond delay                 | Async           | A fixed delay, not a condition — prefer `waitFor()` when you can express a condition instead |
+
+## Package Entry Point
+
+| Import              | Purpose                                                            |
+| -------------------- | ------------------------------------------------------------------- |
+| `@vielzeug/assay`    | The entire public API — queries, event dispatch, async waiting     |
+
+## Query Helpers
+
+### `within(element)`
+
+Creates query helpers scoped to a single element or shadow root.
+
+**Parameters**
+
+| Name      | Type       | Description                          |
+| --------- | ---------- | ------------------------------------- |
+| `element` | `Element`  | The root to scope every query to      |
+
+**Returns:** `QueryScope`
+
+**Example**
+
+```ts
+import { within } from '@vielzeug/assay';
+
+const { query, queryAll, queryByTestId, queryAllByTestId, queryByText, queryAllByText } = within(panel);
+```
+
+`QueryScope` methods:
+
+| Method                            | Returns          |
+| ---------------------------------- | ----------------- |
+| `query(selector)`                  | `Element \| null` |
+| `queryAll(selector)`               | `Element[]`       |
+| `queryByText(text, selector?)`     | `Element \| null` |
+| `queryAllByText(text, selector?)`  | `Element[]`       |
+| `queryByTestId(testId)`            | `Element \| null` |
+| `queryAllByTestId(testId)`         | `Element[]`       |
+
+`selector` defaults to `'*'` for the text-matching methods.
+
+---
+
+### `query(root, selector)` / `queryAll(root, selector)`
+
+Free-function equivalents of `within(root).query`/`.queryAll` — a thin wrapper over `root.querySelector(All)`, exported directly so every `QueryScope` method has both a scoped and unscoped form.
+
+**Returns:** `Element | null` / `Element[]`
+
+---
+
+### `queryByTestId(root, testId)` / `queryAllByTestId(root, testId)`
+
+Free-function equivalents of `within(root).queryByTestId`/`.queryAllByTestId` — matches a `data-testid` attribute.
+
+**Returns:** `Element | null` / `Element[]`
+
+---
+
+### `queryByText(root, text, selector)`
+
+The unscoped function `within()` is built on — useful when you already have a root and don't need the rest of `QueryScope`.
+
+**Parameters**
+
+| Name       | Type                   | Description                                  |
+| ---------- | ---------------------- | ---------------------------------------------- |
+| `root`     | `Element \| ShadowRoot`| Subtree to search                             |
+| `text`     | `string`               | Exact text to match against trimmed `textContent` |
+| `selector` | `string`               | CSS selector narrowing candidate elements      |
+
+**Returns:** `Element | null` — the first matching element, or `null`.
+
+---
+
+### `queryAllByText(root, text, selector)`
+
+Same matching rules as `queryByText`, returning every match.
+
+**Returns:** `Element[]`
+
+---
+
+### `queryInShadow(host, selector)` / `queryAllInShadow(host, selector)`
+
+Query inside `host.shadowRoot`. Returns `null` (or `[]` for the `All` variant) instead of throwing when `host` has no shadow root — safe to call without an `if (host.shadowRoot)` guard.
+
+**Returns:** `Element | null` / `Element[]`
+
+---
+
+### `queryPart(host, part)`
+
+Shorthand for `queryInShadow(host, '[part="' + part + '"]')`.
+
+**Returns:** `Element | null`
+
+---
+
+### `getSlotted(host, slotName?)`
+
+Returns the light-DOM children assigned to a named slot, or every slotted child (`:not([slot])`) when `slotName` is omitted.
+
+**Returns:** `Element[]`
+
+## Event Dispatch
+
+### `fire`
+
+An object of synchronous event dispatchers. Every method calls `element.dispatchEvent(...)` with an appropriately-typed `Event` subclass and sensible defaults, and returns `dispatchEvent`'s own boolean result.
+
+```ts
+import { fire } from '@vielzeug/assay';
+
+fire.click(el, opts?: PointerEventInit);
+fire.blur(el, opts?: FocusEventInit);
+fire.change(el, opts?: EventInit);
+fire.custom(el, name, opts?: CustomEventInit);
+fire.event(el, event: Event);
+fire.focus(el, name?, opts?: FocusEventInit);
+fire.input(el, opts?: EventInit);
+fire.keyboard(el, type, opts?: KeyboardEventInit);
+fire.keyDown(el, opts?: KeyboardEventInit);
+fire.keyUp(el, opts?: KeyboardEventInit);
+fire.mouse(el, type, opts?: MouseEventInit);
+fire.pointerCancel(el, opts?: PointerEventInit);
+fire.pointerDown(el, opts?: PointerEventInit);
+fire.pointerEnter(el, opts?: PointerEventInit);
+fire.pointerLeave(el, opts?: PointerEventInit);
+fire.pointerMove(el, opts?: PointerEventInit);
+fire.pointerUp(el, opts?: PointerEventInit);
+fire.submit(el, opts?: EventInit);
+fire.touch(el, type, opts?: EventInit);
+```
+
+`fire.touch` falls back to `CustomEvent` in environments without a `TouchEvent` constructor. `fire.pointer*` methods route through `createPointerEvent()`, so they fall back to `MouseEvent` the same way.
+
+---
+
+### `createPointerEvent(type, init?)`
+
+Builds a `PointerEvent`, or a `MouseEvent` when `PointerEvent` isn't available in the current environment.
+
+**Returns:** `Event`
+
+## Async Waiting
+
+### `waitFor(fn, options?)`
+
+Polls `fn` until it returns truthy, returns `undefined` (a bare `expect()` call that didn't throw), or the timeout elapses.
+
+**Parameters**
+
+| Name              | Type                | Default | Description                                  |
+| ------------------ | ------------------- | ------- | ---------------------------------------------- |
+| `fn`               | `() => unknown`      | —       | Condition to poll                             |
+| `options.timeout`  | `number`             | `1000`  | Maximum wait time in ms                       |
+| `options.interval` | `number`             | `50`    | Delay between polling attempts in ms          |
+| `options.message`  | `string`             | —       | Prefixed in front of the default timing summary in the timeout error — never replaces it |
+
+**Returns:** `Promise`
+
+**Throws:** `AssayTimeoutError` on timeout, unconditionally — regardless of whether the last polling attempt returned a falsy value or threw. The original failure (a thrown error, or its message) is preserved as `.cause` and folded into the timeout message; `fn`'s thrown error itself is never mutated.
+
+**Example**
+
+```ts
+await waitFor(() => queryByText('Saved') !== null);
+await waitFor(() => expect(spy).toHaveBeenCalled(), { timeout: 2000 });
+```
+
+---
+
+### `waitForEvent(element, name, timeout?)`
+
+Resolves with the next event of the given name.
+
+**Parameters**
+
+| Name      | Type      | Default | Description                     |
+| --------- | --------- | ------- | --------------------------------- |
+| `element` | `Element` | —       | Element to listen on             |
+| `name`    | `string`  | —       | Event name                       |
+| `timeout` | `number`  | `1000`  | Maximum wait time in ms          |
+
+**Returns:** `Promise` — the event instance, typed as `T extends Event` (defaults to `Event`).
+
+---
+
+### `nextTick()`
+
+Resolves after one microtask tick (`queueMicrotask`) — for waiting on reactivity (signal effects, promise-chain continuations) without moving into the macrotask queue.
+
+**Returns:** `Promise`
+
+---
+
+### `wait(ms?)`
+
+Resolves after `ms` milliseconds (default `0`).
+
+**Returns:** `Promise`
+
+## Types
+
+```ts
+interface QueryScope {
+  query(selector: string): E | null;
+  queryAll(selector: string): E[];
+  queryByText(text: string, selector?: string): E | null;
+  queryAllByText(text: string, selector?: string): E[];
+  queryByTestId(testId: string): E | null;
+  queryAllByTestId(testId: string): E[];
+}
+
+interface WaitOptions {
+  timeout?: number;
+  interval?: number;
+  message?: string;
+}
+```
+
+## Errors
+
+| Error               | Thrown by                    | Notable properties |
+| -------------------- | ------------------------------ | -------------------- |
+| `AssayError`         | Base class for every Assay error — use `instanceof AssayError` to catch any of them | `AssayError.is(err)` static type guard |
+| `AssayTimeoutError`  | `waitFor()`, `waitForEvent()` when the timeout elapses | Extends `AssayError` |
+
+### Usage Guide
+
+## Basic Usage
+
+`within(element)` scopes queries to a subtree — useful for slotted content, shadow roots, or any container you don't want to re-select from `document` on every assertion.
+
+```ts
+import { within } from '@vielzeug/assay';
+
+const panel = document.querySelector('.panel')!;
+const { query, queryAll, queryByText } = within(panel);
+
+query('.title'); // Element | null, scoped to panel
+queryAll('.item'); // Element[], scoped to panel
+queryByText('Save'); // matches trimmed textContent
+```
+
+`queryByTestId`/`queryAllByTestId` match a `data-testid` attribute — useful when text content or CSS structure is likely to change but a stable test hook is worth keeping:
+
+```ts
+const { queryByTestId } = within(panel);
+
+queryByTestId('save-button')?.click();
+```
+
+Every `QueryScope` method is also available as a free function taking the root as its first argument — reach for these when you already have a root in scope and don't need the rest of `within()`'s object:
+
+```ts
+import { query, queryAll, queryByTestId, queryAllByTestId } from '@vielzeug/assay';
+
+query(panel, '.title');
+queryAll(panel, '.item');
+queryByTestId(panel, 'save-button');
+queryAllByTestId(panel, 'item-row');
+```
+
+For a custom element's shadow DOM, use `queryInShadow`/`queryAllInShadow`/`queryPart` instead — they return `null`/`[]` rather than throwing when the host has no shadow root (e.g. a `shadow: false` component), so you don't need an `if (host.shadowRoot)` guard at every call site:
+
+```ts
+import { queryAllInShadow, queryInShadow, queryPart } from '@vielzeug/assay';
+
+queryInShadow(customEl, '.internal-label');
+queryAllInShadow(customEl, '.option');
+queryPart(customEl, 'trigger'); // shorthand for queryInShadow(host, '[part="trigger"]')
+```
+
+`getSlotted()` reads the *light*-DOM children a host projects into a named slot (or every slotted child with no argument) — the complement to the shadow-DOM helpers above:
+
+```ts
+import { getSlotted } from '@vielzeug/assay';
+
+const slides = getSlotted(carousel); // default slot
+const actions = getSlotted(dialog, 'footer'); // named slot
+```
+
+## Firing Events
+
+`fire.*` dispatches real DOM events synchronously — no framework-specific event simulation layer, just `dispatchEvent` with sensible defaults (`bubbles: true`, `cancelable: true` where that matches the real event's behavior). Every method returns the same `boolean` `dispatchEvent` itself returns (`false` when a listener called `preventDefault()`), with no exceptions — useful for asserting a handler actually intercepted the event:
+
+```ts
+import { fire } from '@vielzeug/assay';
+
+fire.click(button);
+fire.input(textInput); // fires a plain 'input' Event
+fire.keyDown(textInput, { key: 'Enter' });
+fire.custom(el, 'value-change', { detail: { value: 42 } });
+
+const notPrevented = fire.click(link); // false if a listener called preventDefault()
+```
+
+Pointer events fall back to `MouseEvent` in environments without a `PointerEvent` constructor (some older jsdom versions) — Assay logs a one-time `console.warn` the first time this happens, so an environment gap doesn't show up as a confusing, unrelated test failure instead:
+
+```ts
+fire.pointerDown(slider);
+fire.pointerMove(slider, { clientX: 120 });
+fire.pointerUp(slider);
+```
+
+Dispatch a pre-built event instance directly with `fire.event` when you need full control over the event's properties:
+
+```ts
+fire.event(el, new CustomEvent('ready', { bubbles: true, detail: { ok: true } }));
+```
+
+## Waiting for Async Conditions
+
+`waitFor()` polls a callback until it returns truthy (or doesn't throw, for a bare `expect()` call) — use it for anything that updates asynchronously (a reactive framework's next render, a debounced input handler, a `fetch` completing).
+
+```ts
+import { waitFor } from '@vielzeug/assay';
+
+await waitFor(() => panel.querySelector('.status')?.textContent === 'Ready');
+
+// Works with `expect()` assertions too — a thrown assertion error means "not yet",
+// and its message is folded into the AssayTimeoutError thrown if the timeout is reached
+// (see below — the assertion's own error type never escapes waitFor() directly).
+await waitFor(() => expect(callback).toHaveBeenCalled());
+```
+
+Tune the polling interval and timeout per call — the defaults (1000ms timeout, 50ms interval) suit most reactive UI updates:
+
+```ts
+await waitFor(() => queue.isEmpty(), { interval: 10, timeout: 5000 });
+```
+
+`waitForEvent()` resolves with the next matching event instead of polling — prefer it when you're waiting on something that's guaranteed to fire an event rather than settle into an observable DOM state:
+
+```ts
+import { fire, waitForEvent } from '@vielzeug/assay';
+
+const promise = waitForEvent>(el, 'item-added');
+
+fire.click(addButton);
+
+const event = await promise;
+console.log(event.detail.id);
+```
+
+Both `waitFor()` and `waitForEvent()` reject with `AssayTimeoutError` on timeout — unconditionally, even if the last attempt inside `waitFor()` threw a different error type (an `expect()` assertion, say). Catch `AssayTimeoutError` specifically when you want to distinguish "the condition never became true" from other failures; the original failure is preserved on `.cause` if you need it:
+
+```ts
+import { AssayTimeoutError, waitForEvent } from '@vielzeug/assay';
+
+try {
+  await waitForEvent(el, 'never-fires', 100);
+} catch (err) {
+  if (err instanceof AssayTimeoutError) {
+    // expected — assert on the timeout itself, or inspect err.cause for the original failure
+  }
+}
+```
+
+`nextTick()` and `wait()` cover the two other common timing needs: waiting for reactivity to settle, and waiting for a real macrotask delay.
+
+```ts
+import { nextTick, wait } from '@vielzeug/assay';
+
+signal.value = 'updated';
+await nextTick(); // let a microtask-scheduled effect run
+
+await wait(300); // wait out a debounce timer — prefer nextTick()/waitFor() where possible
+```
+
+## Testing Custom Elements
+
+Assay has no opinion about how your DOM was produced — it works the same way against a vanilla custom element, a framework-rendered component, or plain `document.createElement` output.
+
+```ts
+import { fire, waitFor, within } from '@vielzeug/assay';
+
+customElements.define(
+  'my-counter',
+  class extends HTMLElement {
+    connectedCallback() {
+      this.innerHTML = `+10`;
+      this.querySelector('button')!.addEventListener('click', () => {
+        const span = this.querySelector('.count')!;
+
+        span.textContent = String(Number(span.textContent) + 1);
+      });
+    }
+  },
+);
+
+const el = document.createElement('my-counter');
+
+document.body.appendChild(el);
+
+const { query } = within(el);
+
+fire.click(query('button')!);
+
+await waitFor(() => query('.count')?.textContent === '1');
+
+el.remove();
+```
+
+## Working with Other Vielzeug Libraries
+
+`@vielzeug/ore`'s `./testing` sub-path re-exports Assay's `within`, `fire`, `createPointerEvent`, `waitFor`, and `waitForEvent` directly — if you're already testing Ore components, you don't need a separate Assay import:
+
+```ts
+import { fire, mount, waitFor } from '@vielzeug/ore/testing';
+
+const { query } = await mount(() => html` {}}>Click`);
+
+fire.click(query('button')!);
+```
+
+`@vielzeug/refine`'s `./testing` sub-path re-exports Assay's `queryInShadow`, `queryAllInShadow`, `queryPart`, `getSlotted`, `nextTick`, and `wait` the same way, alongside refine-specific helpers (ARIA attribute assertions, form-associated helpers) that stay in refine because they're specific to testing ore/refine component *contracts*, not generic DOM interaction:
+
+```ts
+import { getAriaState, getSlotted, nextTick } from '@vielzeug/refine/testing';
+```
+
+Import from `@vielzeug/assay` directly when testing DOM code that has nothing to do with Ore or Refine — a vanilla custom element, a framework-rendered component, or plain event-handler logic.
+
+## Best Practices
+
+- Prefer `within(element)` over repeated `element.querySelector(...)` calls — it reads better at call sites with multiple assertions against the same subtree.
+- Use `queryByTestId` for elements whose text or structure is expected to change; use `queryByText` when the visible text itself is what you're asserting on.
+- Reach for `waitForEvent()` over `waitFor()` when the thing you're waiting on is guaranteed to dispatch an event — it resolves on the first matching event instead of polling.
+- Catch `AssayTimeoutError` specifically (not a bare `Error`) when a test needs to branch on "the condition never happened" versus any other failure.
+- Keep `fire.*` calls synchronous where the real user interaction would be — `fire.click()` doesn't await anything; `await` the assertion that follows it instead.
+- Remove elements you create directly with `document.createElement` (`el.remove()`) at the end of each test — Assay itself has no auto-cleanup registry, unlike `@vielzeug/ore/testing`'s `mount()`/`cleanup()`.
+- Prefer `queryInShadow`/`queryAllInShadow` over `host.shadowRoot!.querySelector(...)` — the non-null assertion breaks the moment a component is tested with `shadow: false`, while `queryInShadow` degrades to `null` instead of throwing.
+
+### Examples
+
+## Examples
+
+- [Custom Element Interaction](./examples/custom-element-interaction.md)
+- [Waiting for Async Updates](./examples/waiting-for-async-updates.md)
+
+
 ---
 
 ## @vielzeug/clockwork
@@ -1687,6 +2250,7 @@ type InterpretOptions = {
   onDebug?: (event: DebugEvent) => void;
   persistence?: PersistenceAdapter;
   snapshot?: MachineSnapshot;
+  validateHydratedContext?: boolean;
   traceLimit?: number;
 };
 ```
@@ -1699,6 +2263,7 @@ type InterpretOptions = {
 | `onDebug`                | `undefined`       | Callback for all debug events (guards, transitions, invokes, skips). Auto-enables a 50-entry trace buffer unless `traceLimit` is set.                           |
 | `persistence`            | `undefined`       | Save/load adapter for snapshot persistence                                                                                                                      |
 | `snapshot`               | `undefined`       | Snapshot to hydrate from on startup (takes priority over persistence)                                                                                           |
+| `validateHydratedContext`| `false`           | When `true`, runs `validateContext` against hydrated context during startup; when `false`, hydrated context is trusted and only validated on transitions.         |
 | `traceLimit`             | auto (`50`/`0`)   | Ring buffer capacity for `getTrace()`. Defaults to `50` when `onDebug` is set; `0` (disabled) otherwise. Set explicitly to override.                            |
 
 ---
@@ -1826,7 +2391,7 @@ interface MachineInstance {
 | `matches(...states)` | `boolean`                | `true` if the current state is one of the given values or a descendant of any (e.g. `matches('loading')` matches `'loading.pending'`). Returns `false` when disposed.                                     |
 | `dispose()`          | `void`                   | Aborts active invokes, clears after-timers, and disposes reactive signals. Idempotent. Does **not** clear persisted state. Equivalent to `using m = createMachine(config).start()`.                       |
 | `send(event)`        | `SendResult`             | Dispatches the event. Returns a `SendResult` with `.status`: `'transitioned'`, `'queued'`, or `'rejected'` (also when the machine is already disposed).                                                     |
-| `subscribe(fn)`      | `() => void`             | Subscribes to state/context changes. Returns an unsubscribe function. Fires only when state or context changes — **not** on the initial value. Use `getSnapshot()` to read the current state immediately. |
+| `subscribe(fn)`      | `() => void`             | Subscribes to state/context changes. Returns an unsubscribe function. Fires only when state or context changes — **not** on the initial value. Callback receives an isolated snapshot (`context` is cloned). Use `getSnapshot()` to read the current state immediately. |
 | `[Symbol.dispose]()` | `void`                   | Delegates to `dispose()`. Enables `using` declarations.                                                                                                                                                   |
 
 ---
@@ -1878,7 +2443,7 @@ type PersistenceAdapter = {
 };
 ```
 
-`save` is called after every committed transition. `load` is called once during startup if no `snapshot` option is provided.
+`save` is called after every committed transition. `load` is called once during startup if no `snapshot` option is provided. Hydrated context is not validated at startup unless `validateHydratedContext: true` is set.
 
 ---
 
@@ -2472,7 +3037,9 @@ On startup, `createMachine().start()` checks `options.snapshot` first, then `per
 
 `m[Symbol.dispose]()` does **not** clear persisted state. The machine may be recreated (e.g. after HMR or component remount) and should resume from the last saved state. To reset persistence, call your adapter's storage API directly.
 
-If context is loaded from untrusted sources (e.g. `localStorage`), run your `validateContext` guard before interpreting, or wrap `persistence.load()` with a try/catch and schema check.
+Hydrated context is trusted by default for backward compatibility. To enforce `validateContext` during hydration, pass `validateHydratedContext: true` to `.start(...)`.
+
+If context is loaded from untrusted sources (e.g. `localStorage`), enable `validateHydratedContext` or validate inside `persistence.load()` before returning the snapshot.
 
 ## Interceptors
 
@@ -2547,6 +3114,7 @@ unsub(); // stop listening
 ```
 
 The callback fires only when `state` or `context` reference changes — not on every signal read.
+Each callback receives an isolated snapshot object; mutating the callback payload does not mutate machine state.
 
 ## Debugging and Tracing
 
@@ -7052,7 +7620,7 @@ Creates a query client with caching, deduplication, prefix invalidation, and rea
 | `getState`         | `(key) => QueryState \| null`                                     | Full state snapshot                                                                  |
 | `observeMany`      | `(keys: QueryKey[]) => SyncStore[]>`                   | Observe multiple keys as one combined store; updates on any key change               |
 | `invalidate`       | `(key) => void`                                                         | Evict or background-revalidate a key/prefix                                          |
-| `remove`           | `(key: QueryKey) => void`                                               | Evict a single entry; aborts any in-flight fetch; resets observers to idle if active |
+| `remove`           | `(key: QueryKey) => void`                                               | Evict a single entry; aborts any in-flight fetch; resets observers to `'loading'` if active |
 | `cancel`           | `(key) => void`                                                         | Cancel an in-flight fetch; entry returns to `'loading'` or retains prior success data |
 | `clear`            | `() => void`                                                            | Clear all entries; active subscribers see `'loading'`                                |
 | `refetchStale`     | `() => void`                                                            | Manually revalidate all stale observed entries                                       |
@@ -7113,7 +7681,7 @@ Creates a standalone, observable mutation handle.
 | `peek`             | `() => MutationState`                 | Read current state snapshot                             |
 | `subscribe`        | `(cb: () => void) => () => void`             | Subscribe to state changes; returns unsubscribe fn      |
 | `store`            | `SyncStore>` (property) | Framework-friendly external store; stable reference     |
-| `reset`            | `() => void`                                 | Reset back to the idle state                            |
+| `reset`            | `() => void`                                 | Reset back to the `'loading'` baseline state            |
 | `dispose`          | `() => void`                                 | Abort active run, clear observers, and mark as disposed |
 | `disposed`         | `boolean` (getter)                           | Whether `dispose()` has been called                     |
 | `[Symbol.dispose]` | —                                            | Delegates to `dispose()`; enables `using` declarations  |
@@ -8285,7 +8853,7 @@ const state = qc.getState(['users', 1]);
 ```ts
 const store = qc.watchKey(['users', 1]);
 
-const initial = store.peek(); // idle state if not yet fetched
+const initial = store.peek(); // loading baseline if not yet fetched
 const stop = store.subscribe(() => {
   console.log(store.peek());
 });
@@ -8324,7 +8892,7 @@ const store = qc.observe({
 });
 
 // Synchronously read the current state
-console.log(store.peek().status); // 'idle' or 'pending'
+console.log(store.peek().status); // 'loading' (or 'success' / 'error' if already cached)
 console.log(store.peek().data); // placeholderData while fetching
 
 // Subscribe to future changes
@@ -8368,7 +8936,7 @@ function useUser(id: number) {
 For entries **without active subscribers**, invalidation evicts the cache entry immediately. For entries **with active subscribers**:
 
 - If the entry has a stored query function (registered via `fetch()`), it is background-revalidated.
-- If the entry was only populated via `set()`, it resets to `idle`.
+- If the entry was only populated via `set()`, it resets to `'loading'`.
 
 Supports **prefix matching**: invalidating `['users']` affects `['users', 1]`, `['users', 2]`, and so on.
 
@@ -8379,7 +8947,7 @@ qc.invalidate(['users']);
 
 ### `cancel(key)`
 
-Cancels an in-flight fetch without removing the cache entry. State transitions back to `'success'` if data exists, otherwise `'idle'`.
+Cancels an in-flight fetch without removing the cache entry. State transitions back to `'success'` if data exists, otherwise `'loading'`.
 
 ```ts
 qc.cancel(['users', 1]);
@@ -8387,7 +8955,7 @@ qc.cancel(['users', 1]);
 
 ### `clear()`
 
-Clears every cache entry. Active subscribers are notified with an `'idle'` state.
+Clears every cache entry. Active subscribers are notified with a `'loading'` state.
 
 ```ts
 qc.clear();
@@ -8968,7 +9536,7 @@ effect(() => console.log('user:', userStore.value.user?.name));
 
 **Category:** ui-interaction
 **Keywords:** drag-drop, sortable, file-upload, drop-zone, dnd, reorder
-**Key exports:** createDropZone, createSortable, createSortableScope, applyReorder, matchesAccept
+**Key exports:** createDropZone, createSortable, createSortableScope, createTouchDragShim, applyReorder, matchesAccept
 **Related:** ore, scroll, refine
 
 ### Overview
@@ -9016,6 +9584,7 @@ const zone = createDropZone({
 | Sortable lists      |                |  |  |
 | Drag handles        |                |  |  |
 | `using` support     |                |      |      |
+| Touch support        |  Opt-in shim  |  |  |
 | Zero dependencies   |                |  |      |
 
 **Use Dnd when** you need reliable file drop zones with MIME filtering or sortable lists in a framework-agnostic environment.
@@ -9088,6 +9657,7 @@ using sortable = createSortable({
 - **`sortable.revert()`** — register a revert function via `event.setRevert(fn)` inside `onReorder`; `sortable.revert()` invokes it and clears it for rolling back optimistic updates on server failure
 - **Boundary-safe keyboard reordering** — arrow keys at the first/last item no longer suppress `preventDefault`, so the browser can scroll the page normally
 - **Explicit connected scopes** — lists only exchange items when they share a `createSortableScope()` instance
+- **Touch support via `createTouchDragShim()`** — bridges `touchstart`/`touchmove`/`touchend`/`touchcancel` into the same synthetic `DragEvent` sequence `createSortable`/`createDropZone` already listen for; one `document`-level instance covers the whole app
 - **Explicit DOM sync** — call `sortable.sync()` after DOM mutations instead of relying on hidden observers
 - **`[Symbol.dispose]`** — both primitives support the `using` keyword for automatic cleanup
 - **Reactive-friendly options** — `disabled` is re-read on each event (reassign `options.disabled = true` to toggle); `accept` captures the array reference, so push/splice mutations are reflected without recreating the zone
@@ -9114,6 +9684,7 @@ using sortable = createSortable({
 | `createDropZone()`         | Create a typed drop-zone controller          | Sync           | Remember to destroy the controller during teardown                |
 | `createSortable()`         | Add sortable drag-and-drop behavior to lists | Sync           | Provide stable item identity for reorder operations               |
 | `createSortableScope()`    | Create a shared scope for connected lists    | Sync           | Each set of connected containers needs its own scope instance     |
+| `createTouchDragShim()`    | Bridge touch gestures to synthetic DragEvents | Sync          | Create once per app — it's a single `document`-level listener set |
 | `applyReorder()`           | Apply ordered IDs to data arrays             | Sync           | Unknown IDs are skipped; non-mentioned items are appended         |
 | `DropZoneOptions.accept`   | Filter file types before processing          | Sync           | Mismatch between MIME and extension can reject files unexpectedly |
 | `DropZoneOptions.maxFiles` | Cap accepted files per drop                  | Sync           | Excess accepted files become rejected; `onDropRejected` is called |
@@ -9217,6 +9788,15 @@ declare function createSortableScope(): SortableScope;
 
 Creates an explicit connection scope for multi-container sorting. Containers only exchange items when they share the same scope instance.
 
+### `TouchDragOptions`
+
+```ts
+interface TouchDragOptions {
+  disabled?: boolean;
+  draggableSelector?: string;
+}
+```
+
 ## `createDropZone()`
 
 ```ts
@@ -9323,7 +9903,7 @@ declare function createSortable(options: SortableOptions): Sortable;
 
 Makes the direct children of a container element reorderable via drag. Returns a `Sortable` handle.
 
-`createSortable` sets `draggable="true"` and `role="listitem"` on qualifying children and sets `role="list"` on the container at initialization. After DOM mutations, call `sortable.sync()` to re-apply sortable attributes explicitly.
+`createSortable` sets `draggable="true"`, `role="listitem"`, and `touch-action: none` (inline style) on qualifying children and sets `role="list"` on the container at initialization. After DOM mutations, call `sortable.sync()` to re-apply sortable attributes explicitly.
 
 - `element`: `HTMLElement`, required. The container whose children become sortable.
 - `getKey`: `(element: HTMLElement) => string`, required. Maps each item element to its stable string identity. Children for which `getKey` returns a falsy value are skipped.
@@ -9449,6 +10029,7 @@ Dnd reads and writes the following DOM attributes:
 - `data-dragging`: set during drag, removed on `dragend` or `dispose()`. Use it as your styling hook for drag state.
 - `data-dnd-handle`: internal marker set by `createSortable` and `sortable.sync()`, removed by `dispose()`. Lets Dnd clean up only the handle attributes it applied.
 - `aria-hidden="true"`: set on placeholder creation and removed with the placeholder. Applied to the `.dnd-placeholder` element.
+- `style.touchAction = 'none'` (inline style): set by `createSortable` and `sortable.sync()` on the item (or the handle, when `handle` is set), cleared by `dispose()`. Opts the element out of the browser's default touch gestures (scroll/pan/zoom) so a mobile browser never hijacks a drag gesture as a page scroll before `createTouchDragShim`'s own logic runs — see Usage's "Why draggable items get `touch-action: none`". No effect on mouse/pointer input.
 
 ## CSS Classes
 
@@ -9456,6 +10037,34 @@ Dnd reads and writes the following DOM attributes:
 | ----------------- | ---------------------------- | ------------------------------------------------------------- |
 | `dnd-placeholder` | `` inserted by sortable | While an item is being dragged, in the placeholder's position |
 
+## `createTouchDragShim()`
+
+```ts
+declare function createTouchDragShim(options?: TouchDragOptions): Disposable;
+```
+
+Bridges touch gestures to the synthetic `DragEvent` sequence `createSortable()`/`createDropZone()` already listen for — `touchstart`/`touchmove`/`touchend`/`touchcancel` become `dragstart`/`dragover`/`drop`/`dragend` on the same `document`. HTML5 drag-and-drop has no native touch equivalent otherwise.
+
+| Option              | Type      | Default              | Description                                                                                                                  |
+| -------------------- | --------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `disabled`           | `boolean` | —                      | When `true`, touch gestures are ignored. Read live off the same options object on each `touchstart`, like `SortableOptions.disabled`. |
+| `draggableSelector`   | `string`  | `'[draggable="true"]'` | CSS selector identifying draggable elements under the touch point. The default matches what `createSortable`/`createDropZone` already set. |
+| `showDragPreview`     | `boolean` | `true`                 | Renders a floating clone of the dragged element that follows the touch point for the whole gesture. A native mouse drag gets this for free from the browser's own drag image; this shim's `dragstart` is synthetic, so without it the dragged element would simply vanish (hidden by `createSortable`'s own `scheduleHide()`) with no visual feedback at all. Set to `false` to render fully custom feedback instead. |
+
+**Returns:** `Disposable`
+
+Notes:
+
+- Listens at the `document` level — create one instance per app, not one per sortable/drop-zone.
+- Dispatched events carry a plain object as `dataTransfer` (`dropEffect`/`effectAllowed`/`getData`/`setData`/`setDragImage`), never a real `DataTransfer` — a genuine `DataTransfer` created outside an active native drag is permanently in the spec's "disabled mode", where `dropEffect` writes are silently ignored, which `createSortable`/`createDropZone`'s own commit-vs-cancel check would otherwise always read as a cancellation.
+- The floating preview is a `cloneNode(true)` of the dragged element — it only clones light-DOM content, so an item whose visible content lives inside a shadow root will preview as an empty shell.
+
+```ts
+import { createTouchDragShim } from '@vielzeug/dnd';
+
+using touchDrag = createTouchDragShim();
+```
+
 ## `matchesAccept()`
 
 ```ts
@@ -9868,6 +10477,61 @@ try {
 }
 ```
 
+## Touch Support
+
+HTML5 drag-and-drop has no native touch story — touch devices never fire `dragstart`/`dragover`/`drop`. `createTouchDragShim` bridges `touchstart`/`touchmove`/`touchend`/`touchcancel` into that same synthetic `DragEvent` sequence at the `document` level, so `createSortable`/`createDropZone` work on touch with no per-instance wiring.
+
+```ts
+import { createTouchDragShim } from '@vielzeug/dnd';
+
+// Call once at app startup — one instance covers the whole page.
+using touchDrag = createTouchDragShim();
+```
+
+### Custom draggable selector
+
+Defaults to `[draggable="true"]` — the attribute `createSortable`/`createDropZone` already set on managed elements. Override it if you're bridging touch to elements you manage draggability on yourself.
+
+```ts
+createTouchDragShim({ draggableSelector: '.my-drag-handle' });
+```
+
+### Drag preview
+
+A native mouse-driven drag gets a floating drag image for free — the browser snapshots the dragged element the moment `dragstart` fires and keeps that image under the cursor for the whole gesture. `createTouchDragShim`'s `dragstart` is a synthetic event, so no such snapshot ever exists; without a preview of its own, the dragged element would simply disappear (hidden by `createSortable`'s own scheduled hide) with no visual feedback until the drop. `createTouchDragShim` renders one automatically — a `cloneNode(true)` of the dragged element, positioned `fixed` and translated to follow the touch point — enabled by default.
+
+```ts
+// Opt out to render fully custom feedback instead (e.g. toggling a class from your own
+// dragstart/dragend listeners):
+createTouchDragShim({ showDragPreview: false });
+```
+
+Note the preview only clones light-DOM content — an item whose visible content lives inside a shadow root will preview as an empty shell.
+
+### Why draggable items get `touch-action: none`
+
+`createSortable` sets `touch-action: none` on every element it marks as draggable (the item itself, or the handle when `handle` is set) — no configuration needed. Without it, a mobile browser can decide the very first bit of finger movement on a draggable item is a page scroll/pan — a decision made independently of, and before, `createTouchDragShim`'s own drag-start threshold and `preventDefault()` calls ever run — and hand the rest of the gesture to native scrolling. Once that happens the item never receives the `dragover` sequence needed to update the drop target, so the drop commits back to wherever it started, which looks identical to the drop simply reverting. This is most visible dragging between two containers that require any real finger travel (e.g. a Kanban column stacked below the source column on a narrow viewport) — a short in-place reorder rarely travels far enough to trigger the browser's scroll-intent heuristic, which is why this class of bug can pass casual same-container testing and only show up cross-container.
+
+This has no effect on mouse/pointer input — `touch-action` is touch-only — so it's safe even for `createSortable` instances that never pair with `createTouchDragShim`.
+
+### Disabled state
+
+```ts
+const options = { disabled: false };
+const touchDrag = createTouchDragShim(options);
+
+// options.disabled is read live on each touch event — mutate to toggle:
+options.disabled = true;
+```
+
+### Cleanup
+
+```ts
+touchDrag.dispose();
+// or:
+using touchDrag = createTouchDragShim();
+```
+
 ## Framework Integration
 
 ```tsx [React]
@@ -9957,19 +10621,22 @@ Use Dnd in custom web components by attaching behavior in component lifecycle ho
 
 ```ts
 import { createSortable } from '@vielzeug/dnd';
-import { define, onMounted, html } from '@vielzeug/ore';
+import { define, getHost, html, onMounted } from '@vielzeug/ore';
 
 define('task-list', {
-  setup(_props, { host }) {
+  setup(_props) {
+    const el = getHost();
+
     onMounted(() => {
       const sortable = createSortable({
-        element: host.el,
+        element: el,
         getKey: (el) => el.dataset.sortId!,
         onReorder: ({ ids }) => save(ids),
       });
       return () => sortable.dispose();
     });
-    return () => html``;
+
+    return html``;
   },
 });
 ```
@@ -9983,12 +10650,14 @@ define('task-list', {
 - Use `createSortableScope()` only when items should genuinely move between containers.
 - Use drag handles (`.handle` selector) when the full item surface area conflicts with other interactions such as text selection.
 - Test keyboard reordering explicitly — Dnd sets `tabindex` on items and supports arrow keys by default.
+- Call `createTouchDragShim()` once at app startup if you support touch devices — it's a single `document`-level bridge, not something to attach per `createSortable`/`createDropZone` instance.
 
 ### Examples
 
 ## Examples
 
 - [Sortable List](./examples/sortable-list.md)
+- [Touch-Enabled Sortable List](./examples/touch-enabled-sortable-list.md)
 - [File Upload Drop Zone](./examples/file-upload-drop-zone.md)
 - [Optimistic Reorder with Revert and FLIP Animation](./examples/optimistic-reorder-with-revert.md)
 - [Combined Sortable With Inline Editing](./examples/combined-sortable-with-inline-editing.md)
@@ -12882,17 +13551,15 @@ if (!submission.ok && submission.type === 'validation') {
 
 - Typed field paths with compile-time value inference
 - Explicit validation API: `validate()`, `validate(name)`, and `validate(fields[])`
-- Streaming validation with `validateStream()` — yields each field result as it resolves, read-only
 - Per-connection validation triggers via `connect()` with `ValidationModes` presets
 - `connect()` bindings own independent debounce timers; call `binding.dispose()` on unmount
 - `submit(handler)` — returns `{ ok: true, value }` or `{ ok: false, errors }`
 - Schema integration: pass any `safeParse`-compatible schema directly to `validator`
-- `scope(prefix)` — memoized scoped sub-forms that share parent state with relative field paths
-- `subscribeScoped()` — filtered subscription that only fires on changes within the scope's prefix
-- `snapshot()` / `restore()` — capture and replay complete form state
+- `scope(prefix)` — memoized scoped sub-forms that share parent state with relative field paths; `subscribe()` on a scoped form filters to just that prefix
+- `history.snapshot()` / `history.restore()` — capture and replay complete form state
 - `form.fields.remove(name)` — clean conditional field lifecycle
 - Full array helpers: `append`, `prepend`, `insert`, `remove`, `move`, `swap`, `replace`
-- Explicit synchronous subscriptions: `subscribe`, `subscribeField`, and `subscribeScoped`
+- Explicit synchronous subscriptions: `subscribe` (form or scoped-form state) and `subscribeField` (one field)
 - Stable frozen snapshots for `form.state` and `form.field(name)` (external-store friendly)
 - Explicit touched and error controls: `touch`, `untouch`, `touchAll`, `untouchAll`, `setError`, `resetErrors`
 - Mutation batching with `batch(fn)` and dynamic field validators via `fields.setValidator`
@@ -12900,7 +13567,7 @@ if (!submission.ok && submission.type === 'validation') {
 - Browser-first utility: `toFormData`
 - Framework-agnostic core — wire into React, Vue, Svelte, or vanilla JS with `subscribe()`/`connect()`, no dedicated adapter package
 - `@vielzeug/forge/validators` adapter: `fieldValidator` and `composeValidators`
-- `@vielzeug/forge/devtools`: opt-in `attachForgeDevtools()` for `console.debug` state-transition logging, tree-shaken from production
+- `@vielzeug/forge/devtools`: opt-in `debugForm()` for `console.debug` state-transition logging, tree-shaken from production
 
 ## Documentation
 
@@ -12924,13 +13591,12 @@ if (!submission.ok && submission.type === 'validation') {
 | `form.get()` / `form.set()`                                                 | Read/write field values by dot-path                            | Sync                                           | `set()` after `dispose()` throws                                                                                      |
 | `form.field()` / `form.state`                                               | Read field and form snapshots                                  | Sync                                           | Returns a stable frozen snapshot; re-read on each subscriber call                                                     |
 | `form.validate()`                                                           | Run validation — all fields, a subset, or a single field       | Async                                          | Each call re-runs validators from scratch                                                                             |
-| `form.validateStream()`                                                     | Streaming validation — yields each field result as it resolves | Async (iterator)                               | Read-only — does not write errors to form state                                                                       |
 | `form.submit()`                                                             | Deterministic submit flow returning a `SubmitResult`           | Async                                          | Rejects if called while already submitting — guard with `form.isSubmitting`                                           |
 | `form.connect()`                                                            | Live field binding with DOM event handlers and live getters    | Sync                                           | Do not destructure — live getters lose context; call `dispose()` on unmount                                           |
 | `form.scope()`                                                              | Memoized scoped sub-form with relative field paths             | Sync                                           | Returns the same object for repeated calls with the same prefix; `state` is scoped — flags reflect only prefix fields |
 | `form.array()`                                                              | Array mutation helpers                                         | Sync                                           | Returns a cached helper — call once and reuse                                                                         |
-| `form.subscribe()` / `form.subscribeField()` / `form.subscribeScoped()`     | Synchronous form and field subscriptions                       | Sync                                           | Callbacks receive frozen snapshots                                                                                    |
-| `form.snapshot()` / `form.restore()`                                        | Capture and replay complete form state                         | Sync                                           | Useful for undo/redo and draft saving                                                                                 |
+| `form.subscribe()` / `form.subscribeField()`                                | Synchronous form and field subscriptions                       | Sync                                           | On a scoped form, `subscribe()` is already prefix-filtered — callbacks receive frozen snapshots                       |
+| `form.history.snapshot()` / `form.history.restore()`                        | Capture and replay complete form state                         | Sync                                           | Useful for undo/redo and draft saving                                                                                 |
 | `form.batch()`                                                              | Group mutations into one notification                          | Sync                                           | Nested `batch()` calls are safe — only the outermost flush notifies                                                   |
 | `form.touch()` / `form.touchAll()`                                          | Mark fields touched                                            | Sync                                           | `touchAll()` marks every key currently in the store                                                                   |
 | `form.setError()` / `form.clearError()` / `form.resetErrors()`              | Manual error management                                        | Sync                                           | `setError()` bypasses validators; cleared on next `validate()` run for that field                                     |
@@ -12947,7 +13613,7 @@ if (!submission.ok && submission.type === 'validation') {
 | ---------------------------- | ---------------------------------------------------------------------------------- |
 | `@vielzeug/forge`            | `createForm`, `toFormData`, `ValidationModes`, `FORM_ERROR`, and all types          |
 | `@vielzeug/forge/validators` | `fieldValidator`, `composeValidators` — schema and validator composition helpers    |
-| `@vielzeug/forge/devtools`   | `attachForgeDevtools` — opt-in `console.debug` logging for form state transitions   |
+| `@vielzeug/forge/devtools`   | `debugForm` — opt-in `console.debug` logging for form state transitions   |
 
 ## createForm()
 
@@ -13243,11 +13909,6 @@ subscribeField>(
   options?: SubscribeOptions,
 ): Unsubscribe
 
-subscribeScoped(
-  listener: (state: FormState) => void,
-  options?: SubscribeOptions,
-): Unsubscribe
-
 type SubscribeOptions = { sync?: boolean };
 type Unsubscribe = () => void;
 ```
@@ -13256,17 +13917,17 @@ Pass `{ sync: true }` to also receive the current snapshot immediately upon subs
 
 Subscriptions fire synchronously whenever the form mutates. Because state snapshots are stable (frozen, reference-equal between mutations), these integrate directly with React `useSyncExternalStore`, Vue `shallowRef`, and the Svelte store protocol.
 
-### subscribeScoped
+### subscribe on a scoped form
 
-`subscribeScoped` is available on both root forms and scoped forms:
+`subscribe` behaves differently depending on which form object it's called on:
 
 - **On a scoped form** — filters `errors`, `touchedFields`, and `validatingFields` to paths within the scope's prefix (remapped to relative paths). The listener is **only called when the scoped projection changes** — mutations outside the scope are suppressed. `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect **only the scoped fields**. `isSubmitting`, `isLoading`, and `submitCount` reflect the full form.
-- **On a root form** — behaves identically to `subscribe`; no filtering is applied.
+- **On a root form** — no filtering is applied; every mutation notifies the listener.
 
 ```ts
 const address = form.scope('address');
 
-address.subscribeScoped((state) => {
+address.subscribe((state) => {
   // state.errors uses relative keys: { city: '...' } not { 'address.city': '...' }
   // only fires when an address.* field changes
   console.log(state.errors, state.touchedFields);
@@ -13293,11 +13954,13 @@ type ArrayField = {
 
 `append()` and `prepend()` initialize the field as a one-item array when its current value is `undefined` or `null`. If the field already holds a non-array, non-nullish value (e.g. written by `set()`), both are a no-op — they never overwrite an existing scalar with an array. `insert()`, `remove()`, `move()`, `swap()`, and `replace()` are all no-ops when the field's current value is not an array.
 
-## Snapshot / Restore
+## History (Snapshot / Restore)
 
 ```ts
-snapshot(): FormSnapshot
-restore(snap: FormSnapshot): void
+history: {
+  snapshot(): FormSnapshot;
+  restore(snap: FormSnapshot): void;
+}
 
 type FormSnapshot = {
   readonly baseline: Partial, unknown>>;
@@ -13309,44 +13972,17 @@ type FormSnapshot = {
 };
 ```
 
-- `snapshot()` — captures the complete form state (values, baseline, errors, touched, dirty, submitCount) into a plain object.
-- `restore(snap)` — replaces all state with the snapshot. Aborts any in-flight validation.
+- `history.snapshot()` — captures the complete form state (values, baseline, errors, touched, dirty, submitCount) into a plain object.
+- `history.restore(snap)` — replaces all state with the snapshot. Aborts any in-flight validation.
 
-Useful for undo/redo, draft saving, and "discard changes" flows:
+Namespaced off the main `Form` surface since it's a distinctly less common operation than reading/writing values — grouped the same way `fields` already groups dynamic-field-lifecycle operations. Useful for undo/redo, draft saving, and "discard changes" flows:
 
 ```ts
-const draft = form.snapshot();
+const draft = form.history.snapshot();
 
 form.set('email', 'changed@example.com');
 
-form.restore(draft); // reverts all changes
-```
-
-## validateStream()
-
-```ts
-validateStream(signal?: AbortSignal): AsyncIterableIterator
-```
-
-Runs all field validators in parallel and yields each result as soon as its validator resolves. If a form-level validator is configured, all keys it returns are yielded last — including `field: '_form'` and any field-specific keys returned by the form validator.
-
-**Read-only**: `validateStream()` does not write to `fieldErrors` or trigger subscriber notifications. Use `validate()` when you want errors applied to form state.
-
-```ts
-for await (const { field, error } of form.validateStream()) {
-  if (error) showInlineError(field, error);
-}
-// After the loop: form.state.errors is unchanged
-```
-
-Pass an `AbortSignal` to cancel the stream:
-
-```ts
-const ctrl = new AbortController();
-for await (const result of form.validateStream(ctrl.signal)) {
-  processResult(result);
-}
-ctrl.abort(); // cancels any remaining in-flight validators
+form.history.restore(draft); // reverts all changes
 ```
 
 ## Baseline and Value Management
@@ -13471,7 +14107,7 @@ const form = createForm({
 Opt-in `console.debug` logging for form state transitions. Not exported from the main `@vielzeug/forge` entry point — import from this sub-path so the logging code is tree-shaken from production bundles.
 
 ```ts
-function attachForgeDevtools>(
+function debugForm>(
   form: Form,
   options?: ForgeDevtoolsOptions,
 ): Unsubscribe;
@@ -13487,10 +14123,10 @@ Logs one line per observable state transition: per-field `value`/`error`/`touche
 
 ```ts
 import { createForm } from '@vielzeug/forge';
-import { attachForgeDevtools } from '@vielzeug/forge/devtools';
+import { debugForm } from '@vielzeug/forge/devtools';
 
 const form = createForm({ defaultValues: { email: '' } });
-const detach = attachForgeDevtools(form, { label: 'signup' });
+const detach = debugForm(form, { label: 'signup' });
 // [forge:devtools:signup] field "email" value: "" → "a@b.com"
 
 detach(); // stop logging
@@ -13542,12 +14178,15 @@ type ForgeDevtoolsOptions
 
 // Utility types
 type DeepPartial
-type FlatKeyOf
+type FlatKeyOf              // capped at MAX_TYPED_PATH_DEPTH (5) — see below
 type TypeAtPath
 type ErrorKeyOf
 type ScopedValues
+const MAX_TYPED_PATH_DEPTH  // = 5 — not user-configurable, see rationale below
 ```
 
+`FlatKeyOf` falls back to plain `string` for paths deeper than `MAX_TYPED_PATH_DEPTH` — nothing throws, you just lose autocomplete/type-checking on that specific path (a dev-only console warning fires once per deep key so this is discoverable, not silent). This is a fixed constant, not a per-form generic parameter: it exists purely to protect TypeScript compile time, which doesn't get safer by letting one form's type param regress it for everyone importing that form's module.
+
 ## Errors
 
 Forge exports a small typed error hierarchy, all extending a common `ForgeError` base:
@@ -13629,6 +14268,12 @@ console.log(result.valid); // true only if no errors exist after this run
 console.log(result.errors); // full current error map after the run
 ```
 
+Validation race semantics:
+
+- Forge aborts superseded runs instead of surfacing them as failures.
+- The newest validation run owns final field errors.
+- Aborted runs resolve without throwing in normal API usage.
+
 Schema integration — pass a `safeParse`-compatible schema directly to `validator`:
 
 ```ts
@@ -13778,20 +14423,36 @@ await address.validate(); // validates only address.* fields; returns scoped err
 await address.submit((vals) => vals); // validates and submits only address.* fields
 ```
 
+### Root vs Scoped Path Semantics
+
+| Surface                    | Root form (`form`) | Scoped form (`form.scope('address')`) |
+| -------------------------- | ------------------ | ------------------------------------- |
+| `get` / `set` / `field`    | absolute keys      | relative keys                         |
+| `errors` in `state`        | absolute keys      | relative keys                         |
+| `touchedFields` in `state` | absolute keys      | relative keys                         |
+| `validatingFields` in `state` | absolute keys   | relative keys                         |
+| `validate(name)` input     | absolute key       | relative key                          |
+| `validate()` result keys   | absolute keys      | relative keys                         |
+
+### Recommended Scoped Patterns
+
+1. Call `const address = form.scope('address')` once per UI/module boundary and pass that around.
+2. Use `address.validate()` / `address.submit()` instead of manually feeding `state.touchedFields` into `validate(fields[])`.
+3. Use `address.subscribe(...)` for section UIs — on a scoped form `subscribe` is already prefix-filtered, so sibling/root mutations do not trigger redraws.
+
 **Key characteristics:**
 
 - `dispose()` on a scoped form is a no-op — call `parentForm.dispose()` to tear down.
-- `scope.state` returns a **scoped projection**: `errors`, `touchedFields`, `validatingFields`, `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect only fields within the scope's prefix. `isSubmitting`, `isLoading`, and `submitCount` reflect the full form. Use `scope.validate()` or `scope.submit()` for scoped validity checks; their results contain relative keys and a scoped `valid` flag.
-- `touchedFields` in `state` contains full-prefixed paths. Prefer `scope.validate()` over `scope.validate([...state.touchedFields])` to avoid double-prefixing.
+- `scope.state` returns a **scoped projection**: `errors`, `touchedFields`, `validatingFields`, `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect only fields within the scope's prefix and use relative keys. `isSubmitting`, `isLoading`, and `submitCount` reflect the full form. Use `scope.validate()` or `scope.submit()` for scoped validity checks; their results also use relative keys.
 
 ### Scoped Subscriptions
 
-`subscribeScoped` delivers form state filtered to the scope's prefix. `errors`, `touchedFields`, and `validatingFields` use relative keys. `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect **only the scoped fields**. The listener **only fires when the scoped projection changes** — mutations outside the prefix are suppressed.
+On a scoped form, `subscribe()` delivers form state filtered to the scope's prefix. `errors`, `touchedFields`, and `validatingFields` use relative keys. `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect **only the scoped fields**. The listener **only fires when the scoped projection changes** — mutations outside the prefix are suppressed. (On a root form, `subscribe()` behaves identically to today — no filtering applies.)
 
 ```ts
 const address = form.scope('address');
 
-address.subscribeScoped((state) => {
+address.subscribe((state) => {
   // state.errors → { city: 'Required' }  (not 'address.city')
   // state.isDirty → true only when an address.* field is dirty
   // does not fire when form.set('name', 'Alice') is called
@@ -13823,29 +14484,18 @@ Snapshot semantics:
 - Reference identity is preserved until a relevant mutation occurs.
 - These are directly compatible with external-store patterns such as React `useSyncExternalStore`, Vue `shallowRef`, and the Svelte store protocol.
 
-## Streaming Validation
-
-`validateStream()` runs all field validators in parallel and yields each result as it resolves. It is **read-only** — it does not write errors to form state. The form-level validator, if set, is yielded last with `field: '_form'`.
+## History (Snapshot / Restore)
 
-```ts
-for await (const { field, error } of form.validateStream()) {
-  if (error) showInlineError(field, error);
-}
-// form.state.errors is unchanged after the loop
-```
-
-## Snapshots and Restore
-
-Capture and replay complete form state for undo/redo or "discard changes" flows:
+Capture and replay complete form state for undo/redo or "discard changes" flows, via the `history` namespace:
 
 ```ts
-const draft = form.snapshot();
+const draft = form.history.snapshot();
 
 // ... user edits ...
 form.set('email', 'different@example.com');
 
 // Revert all changes, including errors, touched, dirty, and submitCount
-form.restore(draft);
+form.history.restore(draft);
 ```
 
 ## Arrays
@@ -13900,12 +14550,12 @@ After `dispose()`, all mutating APIs throw.
 
 ## Debugging
 
-Import `attachForgeDevtools()` from the dedicated `/devtools` sub-path to log per-field value/error/touched/dirty changes and submit/loading transitions via `console.debug`:
+Import `debugForm()` from the dedicated `/devtools` sub-path to log per-field value/error/touched/dirty changes and submit/loading transitions via `console.debug`:
 
 ```ts
-import { attachForgeDevtools } from '@vielzeug/forge/devtools';
+import { debugForm } from '@vielzeug/forge/devtools';
 
-const detach = attachForgeDevtools(form, { label: 'signup' });
+const detach = debugForm(form, { label: 'signup' });
 // later, e.g. on unmount:
 detach();
 ```
@@ -14091,7 +14741,6 @@ const formWithSchema = createForm({
 - Field & Form Validation (id: `form-validation`)
 - Schema Integration - safeParse Auto-detection (id: `schema-integration`)
 - Scoped Sub-Forms (scope) (id: `scoped-sub-forms`)
-- Streaming Validation (validateStream) (id: `validate-stream`)
 
 
 ---
@@ -17578,7 +18227,7 @@ effect(() => {
 
 **Category:** i18n
 **Keywords:** internationalization, translations, pluralization, locale, i18n, l10n, async-loading
-**Key exports:** createI18n, createFormatter, hydrateI18n, serializeI18n, validateCatalog, LinguaError, LinguaDisposedError, LinguaInvalidCountError, LinguaCountInVarsError, LinguaMissingLocaleError, LinguaInvalidLocaleError, LinguaNamespaceMissingError (+1 more)
+**Key exports:** createI18n, createFormatter, validateCatalog, LinguaError, LinguaDisposedError, LinguaInvalidCountError, LinguaCountInVarsError, LinguaMissingLocaleError, LinguaInvalidLocaleError, LinguaNamespaceMissingError, LinguaRestoreError
 **Related:** ripple, wayfinder, courier
 
 ### Overview
@@ -17693,7 +18342,7 @@ i18n.getSupportedLocales();
 - Namespace lazy loading: `registerNamespace(ns, factory)` + `loadNamespace(ns, locale?)` — or use `extend(ns, factory, locale?)` as a convenience that does both; deduplicates per `ns + locale`; use for per-route or per-feature keys
 - Scoped translation helpers: `scope(prefix)` returns a `{ fmt, t, tp, has }` helper bound to a key prefix
 - Unified key existence check: `has(key)` returns `true` for leaf keys, branch keys, and pipe-plural base keys in the active fallback chain
-- Loaded-locale predicate: `isLoaded(locale)` returns `true` when a catalog is fully resolved — safe for `serializeI18n()` guards
+- Loaded-locale predicate: `isLoaded(locale)` returns `true` when a catalog is fully resolved — safe for `getState()` guards
 - Registered-locale predicate: `isRegistered(locale)` distinguishes "never configured" from "async loader not yet called"
 - Instance disposal: `dispose()` clears all subscribers and catalog state — prevents memory leaks in route-scoped SPA instances
 - Typed error handling: every thrown/rejected error is `instanceof LinguaError`, with named subclasses (`LinguaDisposedError`, `LinguaMissingLocaleError`, `LinguaNamespaceMissingError`, …) for specific `instanceof` branching
@@ -17702,6 +18351,7 @@ i18n.getSupportedLocales();
 - Deterministic fallback chain using active locale plus configured fallback locales
 - Separate missing handlers: `onMissingKey(key, locale)` and `onMissingVar(varName, key, locale)`
 - Formatting via `createFormatter(source)` — exported from the main entry alongside `createI18n`
+- Automatic dev-mode plural-form validation: every catalog registered or loaded is checked against CLDR rules for its locale, logged via `console.warn` — zero setup, and never bundled into production
 
 ## Documentation
 
@@ -17741,13 +18391,11 @@ i18n.getSupportedLocales();
 | `i18n.loadNamespace()`    | Load a registered namespace for a locale                                           | Async          | Deduplicates concurrent and repeated calls; throws `LinguaNamespaceMissingError` if namespace not registered        |
 | `i18n.isNamespaceLoaded()`  | Check if a namespace is loaded for the active (or given) locale                  | Sync           | Returns `false` if not registered or not yet loaded for this locale                                                |
 | `i18n.isNamespaceRegistered()` | Check if a namespace factory has been registered                              | Sync           | `true` after `registerNamespace()` or `extend()`; `false` before                                                   |
-| `i18n.getState()`         | Extract a serializable snapshot of loaded catalogs + active locale                 | Sync           | Equivalent to `serializeI18n(i18n)` — preferred for public API access                                              |
-| `i18n.restoreState()`     | Hydrate instance from serialized state                                             | Sync           | Equivalent to `hydrateI18n(state, i18n)` — preferred for public API access; throws `LinguaRestoreError` if locale missing |
-| `serializeI18n()`         | Serialise loaded catalogs for SSR hydration                                        | Sync           | Loader-only locales are omitted — check `isLoaded()` before calling                                                |
-| `hydrateI18n()`           | Hydrate a client instance from server-serialised state                             | Sync           | Throws `LinguaRestoreError` if `state.locale` has no catalog                                                            |
+| `i18n.getState()`         | Extract a serializable snapshot of loaded catalogs + active locale                 | Sync           | Loader-only locales are omitted — check `isLoaded()` before calling                                                |
+| `i18n.restoreState()`     | Hydrate instance from serialized state                                             | Sync           | Throws `LinguaRestoreError` if `state.locale` has no catalog                                                       |
 | Error classes             | Named error subclasses (`LinguaDisposedError`, `LinguaMissingLocaleError`, …)      | —              | All runtime errors are `instanceof LinguaError`; use `instanceof` for specific handling                            |
 | `createFormatter()`       | Create a standalone Intl formatter                                                 | Sync           | Available from the main entry or `@vielzeug/lingua/format` — pass a getter `() => i18n.locale` to follow locale changes |
-| `validateCatalog()`       | Check a catalog for missing CLDR plural forms and missing `{count}` interpolations | Sync           | Import from `@vielzeug/lingua/validate` — not for production                                                       |
+| `validateCatalog()`       | Check a catalog for missing CLDR plural forms and missing `{count}` interpolations | Sync           | Import from `@vielzeug/lingua/validate` for CI enforcement — `createI18n()` already runs the same check automatically in dev builds |
 
 ## Package Entry Points
 
@@ -17945,7 +18593,7 @@ Returns `true` if a namespace factory has been registered under `ns` via `regist
 getState(): I18nState
 ```
 
-Extracts a serializable snapshot of all **fully loaded** catalogs and the active locale. Equivalent to `serializeI18n(i18n)` but preferred because it is called directly on the instance without requiring an import.
+Extracts a serializable snapshot of all **fully loaded** catalogs and the active locale.
 
 **Warning:** Only fully resolved catalogs are included. Loader-only locales not yet preloaded are omitted. Use `i18n.isLoaded(locale)` to verify before calling.
 
@@ -17960,13 +18608,15 @@ const state = i18n.getState();
 restoreState(state: I18nState): void
 ```
 
-Hydrates this instance from an `I18nState` produced by `getState()` or `serializeI18n()`. Equivalent to `hydrateI18n(state, i18n)` but preferred because it is called directly on the instance.
+Hydrates this instance from an `I18nState` produced by `getState()`.
 
 - Replaces all catalogs with those from `state`.
 - Sets the active locale to `state.locale`.
 - Clears all namespace loaded-markers so that `extend()` / `loadNamespace()` can re-apply namespaces.
 - Notifies subscribers.
 
+Unlike `register()` and construction, this does **not** run the automatic dev-mode plural-form check (see [`validateCatalog()`](#validatecatalog)) — `state` is assumed to already have been registered, and therefore already checked, once on whatever system produced it.
+
 Throws `LinguaRestoreError` if `state.locale` has no catalog in `state.catalogs`.
 Throws `LinguaDisposedError` if called on a disposed instance.
 
@@ -18090,13 +18740,13 @@ isLoaded(locale: Locale): boolean
 
 Returns `true` if the catalog for `locale` is fully resolved (i.e. not a pending async loader). Returns `false` for unregistered locales, pending loaders, and invalid locale tags — never throws.
 
-Primary use case: guarding `serializeI18n()` in SSR to avoid silently omitting locales that were registered as async loaders but never preloaded.
+Primary use case: guarding `getState()` in SSR to avoid silently omitting locales that were registered as async loaders but never preloaded.
 
 ```ts
 // SSR guard — ensure all locales are loaded before serialising
 const locales = i18n.getSupportedLocales();
 await Promise.all(locales.filter((l) => !i18n.isLoaded(l)).map((l) => i18n.preload(l)));
-const state = serializeI18n(i18n); // now includes all locales
+const state = i18n.getState(); // now includes all locales
 ```
 
 ### `isRegistered()`
@@ -18118,7 +18768,7 @@ Use `isRegistered` + `isLoaded` together to distinguish the three states:
 ```ts
 if (!i18n.isRegistered('fr')) throw new Error('fr locale not configured');
 if (!i18n.isLoaded('fr')) await i18n.preload('fr');
-const state = serializeI18n(i18n); // 'fr' guaranteed to be present
+const state = i18n.getState(); // 'fr' guaranteed to be present
 ```
 
 ### `disposalSignal`
@@ -18202,6 +18852,8 @@ Checks a flat or nested message catalog against CLDR plural rules for `locale`.
 
 Returns an empty array when there are no issues.
 
+**Automatic dev-mode checks:** `createI18n()` already calls this internally, in dev builds only, every time a catalog becomes fully available — at construction (`createI18n({ catalogs })`), via `register()`, or once an async loader resolves — logging any warning through `console.warn`. Call `validateCatalog()` directly only when you want CI to fail the build on a warning rather than just log it; the automatic check already covers everyday authoring feedback with zero setup. The automatic check loads `validate.ts`'s logic as a separate, lazily-fetched chunk — it's never part of your production bundle either way.
+
 **Note:** A branch is treated as a plural branch when any of its child keys is a CLDR form (`zero`, `one`, `two`, `few`, `many`, `other`). A mixed-use branch (e.g. `{ count: 'x', one: 'y' }`) will also be flagged and may produce spurious warnings for non-CLDR sibling keys.
 
 `validateCatalog` also checks for a common authoring error: a form template for `other`, `two`, `few`, or `many` that does not contain `{count}`. Since `tp()` injects `count` automatically, omitting it from a non-singleton form is almost always a mistake. These warnings use `form: ':missing-count'` (e.g. `'other:missing-count'`). The `zero` and `one` forms are exempt — intentionally omitting `{count}` is normal there (e.g. `'No messages'`, `'One message'`).
@@ -18321,7 +18973,7 @@ type I18nState = {
 };
 ```
 
-Produced by `getState()` / `serializeI18n()` and consumed by `restoreState()` / `hydrateI18n()`. Catalogs are stored as flat dot-notation maps.
+Produced by `getState()` and consumed by `restoreState()`. Catalogs are stored as flat dot-notation maps.
 
 ### `NamespaceFactory`
 
@@ -18480,50 +19132,25 @@ type ListFormatOptions = {
 };
 ```
 
-## serializeI18n
+## SSR: `getState()` / `restoreState()`
 
-```ts
-import { serializeI18n } from '@vielzeug/lingua';
-
-serializeI18n(i18n: I18n): I18nState
-```
-
-Serialises the current loaded catalogs and active locale into an `I18nState` object. Use this on the server before embedding state in the HTML response. Loader-only locales that have not been preloaded are silently omitted — call `isLoaded()` to verify all locales are resolved before calling `serializeI18n()`.
+No standalone functions — call these directly on an instance (see [`getState()`](#getstate) / [`restoreState()`](#restorestate) above).
 
 ```ts
 // Server
 const i18n = createI18n({ catalogs: { de: deMessages, en: enMessages }, locale: 'de' });
-const state = serializeI18n(i18n);
+const state = i18n.getState();
 // Embed in the HTML response:
 // window.__I18N__ = ${JSON.stringify(state)}
 ```
 
-## hydrateI18n
-
-```ts
-import { hydrateI18n } from '@vielzeug/lingua';
-
-hydrateI18n(i18n: I18n, state: I18nState): void
-```
-
-Hydrates a client-side instance from server-serialised state. Replaces all catalogs and switches the active locale. Notifies subscribers once after hydration.
-
-Throws `LinguaRestoreError` if `state.locale` has no corresponding entry in `state.catalogs`.
-
 ```ts
 // Client
-const i18n = createI18n();
-hydrateI18n(i18n, window.__I18N__);
+const client = createI18n();
+client.restoreState(window.__I18N__);
 // Catalogs from state are immediately available; no network request needed.
 ```
 
-**Parameters:**
-
-| Parameter | Type        | Description                                |
-| --------- | ----------- | ------------------------------------------ |
-| `i18n`    | `I18n`      | The instance to hydrate.                   |
-| `state`   | `I18nState` | State object produced by `serializeI18n()` |
-
 ## Error Classes
 
 All errors thrown by the `@vielzeug/lingua` runtime extend `LinguaError`. Use `instanceof LinguaError` to catch any lingua error, or `instanceof` the specific subclass for precise handling.
@@ -18551,7 +19178,7 @@ try {
 | `LinguaMissingLocaleError`  | `preload()` / `setLocale()` — locale has no registered source                   |
 | `LinguaInvalidLocaleError`  | Any API receiving an invalid BCP 47 tag                                         |
 | `LinguaNamespaceMissingError` | Namespace requested but not loaded for the current locale                     |
-| `LinguaRestoreError`        | `hydrateI18n()` / `restoreState()` — `state.locale` absent from `state.catalogs` |
+| `LinguaRestoreError`        | `restoreState()` — `state.locale` absent from `state.catalogs` |
 
 ### Usage Guide
 
@@ -18715,7 +19342,9 @@ Without `onMissingKey`, missing keys return the key string. Without `onMissingVa
 
 ## Validating Catalogs
 
-Use `validateCatalog()` during development or CI to detect plural branches that are missing CLDR forms for a target locale. Import it from the dedicated `@vielzeug/lingua/validate` entry — never from the main entry or it will end up in your production bundle.
+`createI18n()` already runs this check automatically in dev builds — every time a catalog becomes available (construction, `register()`, or an async loader resolving), it's checked against CLDR plural rules and any issue is logged via `console.warn`. This costs nothing in production: the check runs behind the same dev-only gate as the rest of `@vielzeug/lingua`'s dev warnings, and the validation logic itself only loads as a separate on-demand chunk, never bundled into your app.
+
+For CI enforcement (failing a build rather than just warning), call `validateCatalog()` directly. Import it from the dedicated `@vielzeug/lingua/validate` entry — never from the main entry or it will end up in your production bundle.
 
 ```ts
 import { validateCatalog } from '@vielzeug/lingua/validate';
@@ -18754,7 +19383,7 @@ Key characteristics:
 
 ## SSR Hydration
 
-Prefer the instance methods `getState()` and `restoreState()` — they are equivalent to `serializeI18n` / `hydrateI18n` but require no extra imports:
+Use the instance methods `getState()` on the server and `restoreState()` on the client:
 
 ```ts
 import { createI18n } from '@vielzeug/lingua';
@@ -18771,7 +19400,7 @@ i18n.restoreState(window.__I18N__);
 // Catalogs from state are immediately available; no network request needed.
 ```
 
-`restoreState()` replaces all catalogs, switches the active locale, clears namespace loaded-markers, and notifies subscribers once. The free functions `serializeI18n()` and `hydrateI18n()` are equivalent alternatives.
+`restoreState()` replaces all catalogs, switches the active locale, clears namespace loaded-markers, and notifies subscribers once.
 
 **Warning:** `getState()` silently omits locales registered as async loaders but not yet preloaded. Use `isLoaded()` to guard:
 
@@ -18916,12 +19545,12 @@ router.subscribe(() => {
 - Keep translation keys flat or one level deep — deeply nested keys are harder to refactor.
 - Set `fallback` to a locale with 100% coverage so missing keys degrade gracefully.
 - Use `extend(ns, factory, locale?)` or `registerNamespace()` + `loadNamespace()` for per-route or per-feature key sets.
-- Use `isLoaded(locale)` before `getState()` / `serializeI18n()` in SSR to avoid silently omitting async-loader locales.
+- Use `isLoaded(locale)` before `getState()` in SSR to avoid silently omitting async-loader locales.
 - Use `isRegistered(locale)` to check if a locale is configured; use `isLoaded(locale)` to check if it is ready.
 - Call `dispose()` on route-level or request-scoped `fork()` instances when they are no longer needed.
 - Use `{ signal }` in `subscribe()` for lifecycle-safe subscriptions; use the returned `Unsubscribe` otherwise.
 - Use `onMissingKey` and `onMissingVar` in development to surface authoring errors early; omit them in production.
-- Import `validateCatalog` from `@vielzeug/lingua/validate` in CI only — never in application code.
+- `createI18n()` already validates plural forms automatically in dev builds — only import `validateCatalog` from `@vielzeug/lingua/validate` directly if you want CI to fail the build on a warning.
 - Share one `i18n` instance per app entry point; avoid creating separate instances per component.
 
 ### Examples
@@ -18955,7 +19584,7 @@ router.subscribe(() => {
 - Pluralization Rules (id: `pluralization`)
 - Preload Pattern (id: `preload-pattern`)
 - scope(), has(), isLoaded(), extend() (id: `scope-bind`)
-- serializeI18n() / hydrateI18n() — SSR hydration (id: `ssr-hydration`)
+- getState() / restoreState() — SSR hydration (id: `ssr-hydration`)
 - createFormatter() — standalone (no createI18n) (id: `standalone-formatter`)
 - Variable Interpolation (id: `variable-interpolation`)
 
@@ -20718,11 +21347,13 @@ function useFloat(referenceRef: { value: HTMLElement | null }, floatingRef: { va
 Use Orbit inside a Ore component to position tooltips and popovers reactively.
 
 ```ts
-import { define, html } from '@vielzeug/ore';
+import { define, getHost, html, onMounted } from '@vielzeug/ore';
 import { flip, float, offset, shift } from '@vielzeug/orbit';
 
 define('x-tooltip', {
-  setup(_props, { el, onMounted }) {
+  setup(_props) {
+    const el = getHost();
+
     onMounted(() => {
       const tooltipEl = el.querySelector('[role=tooltip]')!;
 
@@ -20783,7 +21414,7 @@ define('x-tooltip', {
 
 **Category:** ui-primitives
 **Keywords:** web-components, custom-elements, reactive, templates, signals, lifecycle
-**Key exports:** define, prop, html, css, ref, createContext, inject, injectStrict, useField, createFormContext, FORM_CONTEXT_KEY, createId (+5 more)
+**Key exports:** define, prop, html, css, ref, createContext, inject, injectStrict, provide, onMounted, onCleanup, useEmit (+15 more)
 **Related:** ripple, refine, orbit
 
 ### Overview
@@ -20854,7 +21485,7 @@ yarn add @vielzeug/ore
 
 ```ts
 import { computed, signal } from '@vielzeug/ripple';
-import { css, define, html, prop } from '@vielzeug/ore';
+import { bind, css, define, html, onMounted, prop } from '@vielzeug/ore';
 
 define('my-counter', {
   props: {
@@ -20869,7 +21500,7 @@ define('my-counter', {
       }
     `,
   ],
-  setup(props, { bind, onMounted }) {
+  setup(props) {
     const count = signal(0);
     const doubled = computed(() => count.value * 2);
 
@@ -20890,12 +21521,13 @@ define('my-counter', {
 - Signal-first runtime with `signal`, `computed`, `watch`, `batch` from `@vielzeug/ripple` — import them directly
 - Functional component authoring via `define(tag, { props, setup, styles, formAssociated })`
 - Props via `prop.*` helpers (`prop.string`, `prop.number`, `prop.bool`, `prop.oneOf`, `prop.json`, `prop.data`) or raw `PropDef` objects
-- Setup returns an `HTMLResult` directly: `return html\`...\``
-- Lifecycle hooks — `onMounted`, `onCleanup`, `onEvent`, `onElement`, `effect` — accessed through the setup context bag (`ctx`)
+- `setup(props)` takes only props and returns an `HTMLResult` directly: `return html\`...\``
+- Lifecycle hooks — `onMounted`, `onCleanup`, `onEvent`, `onElement`, `watchEffect` — plain functions imported from `@vielzeug/ore`, called directly from `setup()` or any composable it calls
 - Directives: `each` (keyed reactive list rendering), `classMap`, `styleMap`, `when`, `model`, `raw`
-- Host bindings via `ctx.bind({ attr, class, style, on })` — pass `{ target: el }` to bind any off-host element
-- Reactive ARIA sync via `ctx.aria(target, config)` — applies `aria-*` attributes reactively to any element, auto-cleanup on disconnect
-- Form-associated helpers: `useField()`, `createFormContext()` — first-class public APIs for form-aware components
+- Host bindings via `bind({ attr, class, style, on })` — pass `{ target: el }` to bind any off-host element
+- Reactive ARIA sync via `aria(target, config)` — applies `aria-*` attributes reactively to any element, auto-cleanup on disconnect
+- Context via `provide(key, value)` / `inject(key)`; typed emit/slots via `useEmit()` / `useSlots()`
+- Form-associated helpers (`@vielzeug/ore/forms`): `useField()`, `createFormContext()`
 - Observers (`@vielzeug/ore/observers`)
 - Testing utilities (`@vielzeug/ore/testing`) — `mount`, `renderHook`, `fire`, `user`, `waitFor`, `cleanup`
 - Debug utilities (`@vielzeug/ore/devtools`) — `debugFlush()` for diagnosing update timing
@@ -20904,9 +21536,10 @@ define('my-counter', {
 
 | Import                      | Purpose                                                                       |
 | --------------------------- | ----------------------------------------------------------------------------- |
-| `@vielzeug/ore`            | Core component API and utilities (`define`, `prop`, `html`, `css`, context, forms) |
+| `@vielzeug/ore`            | Core component API and utilities (`define`, `prop`, `html`, `css`, context), plus the everyday template directives (`each`, `when`, `model`, `classMap`, `styleMap`) |
 | `@vielzeug/ore/devtools`   | `debugFlush` — verbose flush for timing diagnostics (dev only)                |
-| `@vielzeug/ore/directives` | `each`, `when`, `model`, `live`, `raw`, `classMap`, `styleMap`                |
+| `@vielzeug/ore/directives` | The advanced/niche directives (`live`, `raw`) and the custom-directive authoring API (`createDirectiveResult`, `createSpreadObject`) |
+| `@vielzeug/ore/forms`      | `useField`, `createFormContext`, `FORM_CONTEXT_KEY`                          |
 | `@vielzeug/ore/observers`  | `resizeObserver`, `intersectionObserver`, `mediaObserver`, `mutationObserver` |
 | `@vielzeug/ore/testing`    | `mount`, `fire`, `user`, `waitFor`, `cleanup`, and helpers                    |
 
@@ -20926,31 +21559,40 @@ define('my-counter', {
 
 ## API Overview
 
-| Symbol                     | Purpose                                              | Execution mode | Common gotcha                                                          |
-| -------------------------- | ---------------------------------------------------- | -------------- | ---------------------------------------------------------------------- |
-| `define()`                 | Register a custom element with reactive setup        | Sync           | Tag must contain a hyphen; call before first use                       |
-| `html`                     | Tagged template literal returning HTMLResult         | Sync           | Expressions must be signals, functions, or primitives                  |
-| `prop.*`                   | Typed prop helpers (string, bool, number, …)         | Sync           | Prop values are signals — read `.value`                                |
-| `ctx.provide/inject`       | Context API for parent-to-descendant sharing         | Setup only     | Must be called synchronously during `setup()`                          |
-| `ref()`                    | Reactive reference to a DOM element                  | Sync           | Value is null until after first mount                                  |
-| `createContext()`          | Create a typed injection key                         | Sync           | Context is scoped to the component tree                                |
-| `each()`                   | Keyed list rendering with DOM diffing                | Sync           | Duplicate keys warn in dev; plain `T[]` treated as one-time static render |
-| `when()`                   | Conditional branch rendering                         | Sync           | Getter-fn computed disposed on cleanup; static bool skips subscription |
-| `model(signal)`            | Two-way binding for input/select/textarea            | Sync           | `` uses `Signal`; `select` uses `change`    |
-| `live(signal)`             | One-way binding that skips stale writes during input | Sync           | Use for controlled inputs alongside a manual `@input` handler          |
-| `ctx.onMounted(fn)`        | DOM-ready callback                                   | Setup only     | Must be called synchronously during `setup()`                          |
-| `ctx.onCleanup(fn)`        | Register teardown                                    | Setup only     | Called on component disconnect                                         |
-| `ctx.onEvent(target, …)`   | Scoped event listener with auto-cleanup              | Setup only     | No-ops on null target; removed on disconnect                           |
-| `useField(options)`        | Wire signal to form `ElementInternals`               | Setup only     | Requires `formAssociated: true` on the component definition            |
-| `ctx.aria(target, config)` | Reactively sync ARIA attributes to any element       | Setup only     | Static values applied once; getter functions tracked as effects; auto-cleanup on disconnect |
+All symbols below (except `useField`/`createFormContext`, under `@vielzeug/ore/forms`) are plain functions imported from `@vielzeug/ore`. Lifecycle/context/binding functions (`onMounted`, `onCleanup`, `onEvent`, `onElement`, `watchEffect`, `bind`, `aria`, `provide`, `useEmit`, `useSlots`, `getHost`) resolve the active component through an implicit "current component" context — they work when called synchronously during `setup()`, or from any composable function `setup()` calls (transitively), but throw if called outside that window.
+
+> `watchEffect` is not named `watch` — `@vielzeug/ripple` already exports a `watch(source, callback)` with different semantics (explicit source + old/new value pair), and the two are frequently imported in the same file.
+
+| Symbol                | Purpose                                              | Execution mode | Common gotcha                                                             |
+| ---------------------- | ----------------------------------------------------- | -------------- | -------------------------------------------------------------------------- |
+| `define()`             | Register a custom element with reactive setup         | Sync           | Tag must contain a hyphen; call before first use                          |
+| `html`                 | Tagged template literal returning HTMLResult          | Sync           | Expressions must be signals, functions, or primitives                     |
+| `prop.*`               | Typed prop helpers (string, bool, number, …)          | Sync           | Prop values are signals — read `.value`                                   |
+| `provide()`/`inject()` | Context API for parent-to-descendant sharing          | Setup only     | Must be called synchronously during `setup()`                             |
+| `ref()`                | Reactive reference to a DOM element                   | Sync           | Value is null until after first mount                                     |
+| `createContext()`      | Create a typed injection key                          | Sync           | Context is scoped to the component tree                                   |
+| `each()`               | Keyed list rendering with DOM diffing                 | Sync           | Duplicate keys warn in dev; plain `T[]` treated as one-time static render  |
+| `when()`               | Conditional branch rendering                          | Sync           | Getter-fn computed disposed on cleanup; static bool skips subscription    |
+| `model(signal)`        | Two-way binding for input/select/textarea             | Sync           | `` uses `Signal`; `select` uses `change`       |
+| `live(signal)`         | One-way binding that skips stale writes during input  | Sync           | Use for controlled inputs alongside a manual `@input` handler             |
+| `onMounted(fn)`        | DOM-ready callback                                    | Setup only     | Must be called synchronously during `setup()`                             |
+| `onCleanup(fn)`        | Register teardown                                     | Setup only     | Called on component disconnect                                            |
+| `onEvent(target, …)`   | Scoped event listener with auto-cleanup               | Setup only     | No-ops on null target; removed on disconnect                              |
+| `useField(options)`    | Wire signal to form `ElementInternals`                | Setup only     | Requires `formAssociated: true` on the component definition; `@vielzeug/ore/forms` |
+| `onFormReset(fn)`      | Run work when the ancestor `` resets            | Setup only     | Fires every reset (not one-shot); only for `formAssociated: true` components |
+| `aria(target, config)` | Reactively sync ARIA attributes to any element        | Setup only     | Static values applied once; getter functions tracked as effects; auto-cleanup on disconnect |
+| `useEmit()`     | Typed `emit()` bound to the current host              | Setup only     | Call once per component; returns `dispatchEvent`'s boolean (`false` if a listener called `preventDefault()`) |
+| `useSlots()`| Reactive slot presence/element signals                | Setup only     | Safe to call more than once — the underlying registry is created once    |
+| `getHost()`            | The current component's host element                 | Setup only     | Prefer a higher-level helper (`bind`, `aria`, …) when one exists          |
 
 ## Package Entry Points
 
 | Import                       | Purpose                                                            |
 | ---------------------------- | ------------------------------------------------------------------ |
-| `@vielzeug/ore`            | Core authoring/runtime API                                         |
+| `@vielzeug/ore`            | Core authoring/runtime API, including the everyday template directives (`each`, `when`, `classMap`, `styleMap`, `model`) |
 | `@vielzeug/ore/devtools`   | `debugFlush` — verbose flush for timing diagnostics                |
-| `@vielzeug/ore/directives` | Standalone directive imports (`each`, `when`, `classMap`, …)       |
+| `@vielzeug/ore/directives` | The advanced/niche directives (`raw`, `live`) plus the custom-directive authoring API (`createDirectiveResult`, `createSpreadObject`) |
+| `@vielzeug/ore/forms`      | Form-association helpers (`useField`, `createFormContext`)        |
 | `@vielzeug/ore/observers`  | Resize, intersection, mutation, and media observers                |
 | `@vielzeug/ore/testing`    | DOM-oriented test helpers                                          |
 
@@ -20962,35 +21604,36 @@ define('my-counter', {
 define(tag: string, definition: ComponentDefinition): void;
 ```
 
-The `setup()` function receives typed prop signals and a context bag:
+The `setup()` function receives only typed prop signals:
 
 ```ts
-type SetupContextBag = {
-  aria: (target: Element, config: AriaConfig) => () => void; // Reactive ARIA attr sync; auto-cleanup on disconnect
-  bind: HostBindFn; // Apply reactive bindings to the host or any target element
-  el: HTMLElement; // The host element
-  emit: EmitFn; // Dispatch typed custom events
-  inject: (key: InjectionKey, fallback?: T) => T | undefined; // Resolve context from nearest ancestor
-  onCleanup: (fn: CleanupFn) => void; // Register teardown; called on disconnect
-  onElement: (ref, cb) => void; // Run callback when a ref resolves to an element
-  onEvent: (target, event, listener, options?) => void; // Scoped event listener; auto-removed on disconnect
-  onMounted: (fn: OnMountedCallback) => void; // DOM-ready callback
-  provide: (key: InjectionKey, value: T) => void; // Register context on the host element
-  slots: ComponentSlots; // Reactive slot signals
-  watch: (fn: EffectCallback) => () => void; // Scoped reactive effect; auto-cleaned on disconnect
-};
+setup(props) {
+  return html`${props.label}`;
+}
 ```
 
-Lifecycle hooks (`onMounted`, `onCleanup`, `onEvent`, `onElement`, `watch`) are accessed exclusively through the setup context bag. They must be called synchronously during `setup()`.
-
-`setup()` returns an `HTMLResult` directly (not a function):
+Everything else — lifecycle hooks, host bindings, context, slots, emit — is a plain function imported from `@vielzeug/ore`, called directly from `setup()` (or a composable it calls):
 
 ```ts
-setup(props, ctx) {
-  return html`${props.label}`;
-}
+import { define, html, onMounted, useEmit, useSlots } from '@vielzeug/ore';
+
+define('my-card', {
+  setup(_props) {
+    const emit = useEmit();
+    const slots = useSlots();
+
+    onMounted(() => console.log('mounted'));
+
+    // emit() returns dispatchEvent's boolean — false if a listener called preventDefault()
+    const notCancelled = emit('close');
+
+    return html`${when(slots.has('header'), () => html``)}`;
+  },
+});
 ```
 
+`useEmit()` and `useSlots()` are factory hooks — call them once per component to get a typed `emit`/`slots` bound to the current host. `useSlots()` is safe to call more than once (the underlying slot registry is created once per instance and reused).
+
 ### ComponentDefinition
 
 ```ts
@@ -20999,26 +21642,12 @@ type ComponentDefinition = {
   loading?: () => HTMLResult; // Template shown while async setup is pending
   onError?: (error: OreLifecycleError, element: HTMLElement) => HTMLResult | void;
   props?: PropsDef;
-  setup: (
-    props: InferProps>,
-    ctx: SetupContextBag,
-  ) => HTMLResult | Promise;
+  setup: (props: InferProps>) => HTMLResult | Promise;
   shadow?: Partial | false; // false = light DOM (no shadow root)
   styles?: (string | CSSStyleSheet | CSSResult)[];
 };
 ```
 
-Pass `SlotNames` as a type parameter to `define()` to get typed `ctx.slots` access:
-
-```ts
-define, Record, 'header' | 'footer'>('my-card', {
-  setup(_props, { slots }) {
-    const hasHeader = slots.has('header'); // typed ✓
-    return html`...`;
-  },
-});
-```
-
 #### Async setup
 
 When `setup()` returns a `Promise`, `loading()` is rendered immediately. The real template replaces it once the promise resolves.
@@ -21037,10 +21666,12 @@ define('user-profile', {
 
 ## Runtime Helpers
 
-`onMounted`, `onCleanup`, `onEvent`, `onElement`, and `watch` are available on the setup context bag. Destructure them from the second argument to `setup()`.
+`onMounted`, `onCleanup`, `onEvent`, `onElement`, and `watchEffect` are plain functions imported from `@vielzeug/ore`. Call them directly during `setup()`.
 
 ```ts
-setup(props, { onMounted, onCleanup, onEvent, onElement, watch }) {
+import { html, onCleanup, onEvent, onMounted } from '@vielzeug/ore';
+
+setup(props) {
   onMounted(() => {
     // DOM is ready; return a function for mount-scoped cleanup
     return () => { /* cleanup on unmount */ };
@@ -21054,20 +21685,18 @@ setup(props, { onMounted, onCleanup, onEvent, onElement, watch }) {
 }
 ```
 
-When writing composable helpers called from inside `setup()`, thread the hooks explicitly via function parameters rather than relying on a shared context:
+Because these resolve the active component through an implicit context (rather than a value threaded through parameters), composable helper functions can call them directly too — no need to pass hooks in as options:
 
 ```ts
-type MyHelperOptions = {
-  onCleanup: (fn: () => void) => void;
-};
+import { onCleanup } from '@vielzeug/ore';
 
-function useMyHelper(options: MyHelperOptions) {
-  options.onCleanup(() => { /* teardown */ });
+function useMyHelper() {
+  onCleanup(() => { /* teardown */ });
 }
 
 // In setup:
-setup(_props, { onCleanup }) {
-  useMyHelper({ onCleanup });
+setup(_props) {
+  useMyHelper();
   return html`...`;
 }
 ```
@@ -21149,7 +21778,7 @@ Event bindings support dot-separated modifiers: `@click.prevent.stop=${handler}`
 
 ## Host Bindings
 
-The setup context provides `bind: HostBindFn`:
+`bind(config, options?)` is a plain function imported from `@vielzeug/ore`:
 
 ```ts
 bind({
@@ -21175,9 +21804,9 @@ bind(
 
 Event listener options (`once`, `capture`, `passive`) are also accepted in the second argument. Cleanup is auto-registered with the component scope when called during setup.
 
-### ctx.aria()
+### aria()
 
-For reactive ARIA attribute syncing, use `ctx.aria(target, config)`. Shorthand keys are normalised to `aria-*` automatically (`expanded` → `aria-expanded`; `role` is passed verbatim):
+For reactive ARIA attribute syncing, use `aria(target, config)`. Shorthand keys are normalised to `aria-*` automatically (`expanded` → `aria-expanded`; `role` is passed verbatim):
 
 ```ts
 // Inside setup — cleanup auto-registered
@@ -21204,22 +21833,24 @@ Slot signals update reactively when assigned content changes, including when slo
 ## Context API
 
 - `createContext(description?)` — Create a typed injection key
-- `ctx.provide(key, value)` — Provide a value to descendants; called via the setup context bag
+- `provide(key, value)` — Provide a value to descendants
 - `inject(key)` — Resolve from nearest ancestor; returns `undefined` if not found
 - `inject(key, fallback)` — Resolve with a fallback value
 - `injectStrict(key)` — Resolve or throw if absent
 
-`ctx.provide()` and `inject()` must be called synchronously during `setup()`. Calling them outside a setup context throws `'Lifecycle hooks must be called synchronously during component setup'`. Context resolution walks the ancestor chain including shadow DOM boundaries.
+`provide()` and `inject()` must be called synchronously during `setup()`. Calling them outside a setup context throws `'Lifecycle hooks must be called synchronously during component setup'`. Context resolution walks the ancestor chain including shadow DOM boundaries. `inject()` resolves and caches its result once per consumer — provide a `Readable` (signal/computed) rather than a raw value if descendants need to observe later changes; re-calling `provide()` with a new raw value afterward is not seen by consumers that already resolved it (a dev-mode warning fires when a key is provided twice on the same element).
 
 ## Utilities
 
 - `ref()` — Create a `Signal` element reference. Set to the element via `ref=` in templates.
 - `createId(prefix = 'id')` — Generate a unique incremental string ID (e.g. `'id-1'`, `'id-2'`). Each call returns a new ID — it does not deduplicate by prefix.
 - `createStableId(prefix = 'id')` — Generate a unique ID that also embeds a short random tag shared across all IDs generated in the session (e.g. `'field-a3k21'`), reducing collision risk when multiple app instances run on the same page. Like `createId()`, every call returns a new ID.
-- `resetIdCounter()` — Reset the `createStableId()` counter to 0. Call in test `beforeEach` for deterministic IDs.
+- `resetStableIdCounter()` — Reset the `createStableId()` counter to 0. Call in test `beforeEach` for deterministic IDs. Scoped to `createStableId()` only — `createId()` has no public reset (it's for uniqueness, not cross-test determinism).
 
 ## Form-Associated API
 
+Import from `@vielzeug/ore/forms`.
+
 ### `useField(options)`
 
 Wire a form-associated element to `ElementInternals`. Requires `formAssociated: true` on the component definition. The `disabled` state tracking via `internals.states` (CustomStateSet) is skipped with a dev warning if the API is unavailable in the current environment.
@@ -21234,7 +21865,12 @@ type FormFieldOptions = {
    * @default false
    */
   emptyStringForNull?: boolean;
+  /** Called when the ancestor  resets (see onFormReset) — restore local field state here. */
+  onReset?: () => void;
   toFormValue?: (value: T) => File | FormData | string | null;
+  /** Recomputed reactively and passed straight to internals.setValidity(). null = always valid. */
+  validationMessage?: Readable;
+  validity?: Readable;
   value: Signal | Readable;
 };
 
@@ -21247,11 +21883,23 @@ type FormFieldHandle = {
 };
 ```
 
+Pass `validity`/`validationMessage` to make `required`-style constraints participate in native constraint validation (`checkValidity()`/`reportValidity()`, and ``'s submit blocking):
+
+```ts
+const isBlank = (v: string) => v.trim() === '';
+
+useField({
+  validationMessage: computed(() => (required.value && isBlank(value.value) ? 'This field is required.' : '')),
+  validity: computed(() => (required.value && isBlank(value.value) ? { valueMissing: true } : null)),
+  value,
+});
+```
+
 ### Form Context
 
 Coordinate form state across child field components:
 
-- `createFormContext(options?)` — Create a `FormController`; call `ctx.provide(FORM_CONTEXT_KEY, ctrl)` to make it available to descendants
+- `createFormContext(options?)` — Create a `FormController`; call `provide(FORM_CONTEXT_KEY, ctrl)` to make it available to descendants
 - `FORM_CONTEXT_KEY` — the `InjectionKey` used to provide/inject the form context
 
 ```ts
@@ -21284,7 +21932,9 @@ Import from `@vielzeug/ore/testing`.
 | ------------------------ | ------------------------------------------------------------------------------------------ |
 | `mount(setup, options?)` | Mount a component and return a test fixture                                                |
 | `cleanup()`              | Remove all mounted elements and reset test state                                           |
-| `install(afterEach)`     | Register auto-cleanup; pass `afterEach` from your test framework                           |
+| `install(afterEach)`     | Register auto-cleanup and the `ElementInternals`/`FormData`/`.reset()` jsdom polyfill (see below); pass `afterEach` from your test framework |
+| `installFormInternalsPolyfill()` | Called automatically by `install()`. Call directly only if you need the polyfill without auto-cleanup |
+| `walkFlatTree(root, visit)` | Walks the flat tree (expanding `` via `assignedElements()`) — for finding slotted content across a shadow boundary that `querySelectorAll()` can't cross |
 | `flush(options?)`        | Drain reactive updates and animation frames                                                |
 | `FLUSH_DEEP`             | Pre-built options for deep async chains (`maxTurns: 12`)                                   |
 | `mock(tag, template?)`   | Register a no-op stub custom element                                                       |
@@ -21297,6 +21947,8 @@ Import from `@vielzeug/ore/testing`.
 
 > **Test isolation:** `cleanup()` resets mounted elements, `live()` signal tracking, and the raw HTML sanitizer. Call it in `afterEach` to prevent state leaking between tests.
 
+> **Form-associated component testing:** jsdom implements none of the `ElementInternals` form-association API — `install()` polyfills `setFormValue`/`setValidity`/`checkValidity`/`reportValidity`/`validationMessage`/`states`, mixes `checkValidity`/`reportValidity`/`validity`/`validationMessage` onto the host element itself (real browsers do this for any `formAssociated: true` element), makes `FormData` collect a form-associated element's set value, and makes `.reset()` invoke `formResetCallback()`. Every patch is a guarded no-op when its target already exists, so it's safe to call `install()` even in a suite with no form-associated components — and safe for a downstream package (e.g. a component library built on `ore`) to rely on instead of hand-rolling its own copy.
+
 #### `Fixture` interface
 
 ```ts
@@ -21321,11 +21973,11 @@ interface Fixture {
 
 #### `renderHook`
 
-Useful for testing composable lifecycle hooks (`onMounted`, `effect`, `inject`, etc.) without a template:
+Useful for testing composable lifecycle hooks (`onMounted`, `watchEffect`, `inject`, etc.) without a template. `onMounted`/`onCleanup`/`watchEffect`/... work exactly as inside a real `setup()`, since they resolve the same implicit current-component context:
 
 ```ts
 // Without props
-const { result, flush, dispose } = await renderHook((_props, { onMounted }) => {
+const { result, flush, dispose } = await renderHook(() => {
   const count = signal(0);
   onMounted(() => {
     count.value = 1;
@@ -21374,48 +22026,32 @@ type InferProps = {
   readonly [K in keyof D]-?: Readable>;
 };
 
-type SetupContextBag = Record,
-  SlotNames extends string = string,
-> = {
-  aria: (target: Element, config: AriaConfig) => () => void; // Reactive ARIA attr sync; auto-cleanup on disconnect
-  bind: (config: HostBindConfig, options?: BindOptions) => () => void; // Bindings for host or any target element
-  el: HTMLElement; // The host element
-  emit: EmitFn; // Dispatch typed custom events
-  inject: {
-    (key: InjectionKey): T | undefined;
-    (key: InjectionKey, fallback: T): T;
-  };
-  onCleanup: (fn: CleanupFn) => void; // Register teardown; called on disconnect
-  onElement: (ref: Readable, cb: (el: T) => CleanupFn | void) => () => void;
-  onEvent: {
-    (
-      target: EventTarget | null | undefined,
-      event: K,
-      listener: (e: HTMLElementEventMap[K]) => void,
-      options?: AddEventListenerOptions,
-    ): void;
-    (
-      target: EventTarget | null | undefined,
-      event: string,
-      listener: EventListener,
-      options?: AddEventListenerOptions,
-    ): void;
-  };
-  onMounted: (fn: OnMountedCallback) => void; // DOM-ready callback; runs after first render
-  provide: (key: InjectionKey, value: T) => void; // Register a context value on the host element
-  slots: ComponentSlots; // Reactive slot signals
-  watch: (fn: EffectCallback) => () => void; // Scoped reactive effect; auto-cleaned on disconnect
-};
+// Runtime hooks — all plain functions imported from '@vielzeug/ore', not fields on an object.
+declare function onMounted(fn: OnMountedCallback): void; // DOM-ready callback; runs after first render
+declare function onCleanup(fn: CleanupFn): void; // Register teardown; called on disconnect
+declare function onElement(ref: Readable, cb: (el: T) => CleanupFn | void): () => void;
+declare function onEvent(
+  target: EventTarget | null | undefined,
+  event: string,
+  listener: EventListener,
+  options?: AddEventListenerOptions,
+): void;
+declare function onFormReset(fn: () => void): void; // Runs on every ancestor  reset; formAssociated only
+declare function watchEffect(fn: EffectCallback): () => void; // Scoped reactive effect; auto-cleaned on disconnect
+declare function bind(config: HostBindConfig, options?: BindOptions): () => void; // Bindings for host or any target element
+declare function aria(target: Element, config: AriaConfig): () => void; // Reactive ARIA attr sync; auto-cleanup on disconnect
+declare function provide(key: InjectionKey, value: T): void; // Register a context value on the host element
+declare function inject(key: InjectionKey, fallback?: T): T | undefined;
+declare function getHost(): HTMLElement; // The current component's host element
+declare function useEmit = Record>(): EmitFn;
+declare function useSlots(): ComponentSlots;
 
 type ComponentDefinition = {
   formAssociated?: boolean;
   loading?: () => HTMLResult; // Shown while async setup is pending
   onError?: (error: OreLifecycleError, el: HTMLElement) => HTMLResult | void;
   props?: PropsDef;
-  setup: (
-    props: InferProps>,
-    ctx: SetupContextBag,
-  ) => HTMLResult | Promise;
+  setup: (props: InferProps>) => HTMLResult | Promise;
   shadow?: Partial | false; // false = light DOM
   styles?: (string | CSSStyleSheet | CSSResult)[];
 };
@@ -21478,15 +22114,19 @@ define('status-chip', {
 });
 ```
 
-The setup context bag provides `el`, `aria`, `bind`, `emit`, `slots`, `onMounted`, `onCleanup`, `onEvent`, `onElement`, and `watch`:
+Everything besides `props` — lifecycle hooks, host bindings, context, slots, emit — is a plain function imported from `@vielzeug/ore`, called directly from `setup()` (or a composable it calls):
 
 ```ts
+import { define, getHost, html, bind, useEmit, useSlots } from '@vielzeug/ore';
+
 define('my-widget', {
-  setup(_props, { el, bind, emit, slots }) {
-    // el — the host HTMLElement
-    // bind — host binding helper (attr, class, style, on)
-    // emit — typed event emitter
-    // slots — reactive slot observation
+  setup(_props) {
+    const el = getHost(); // the host HTMLElement
+    const emit = useEmit(); // typed event emitter
+    const slots = useSlots(); // reactive slot observation
+
+    bind({ attr: { role: 'group' } }); // host binding helper (attr, class, style, on)
+
     return html``;
   },
 });
@@ -21518,16 +22158,17 @@ batch(() => {
 
 ## onMounted and lifecycle
 
-Use `ctx.onMounted()` for DOM-dependent initialization that must run after the template is mounted. Use `ctx.onElement(ref, cb)` for work tied to a specific DOM node. `ctx.onEvent()` attaches a listener that is automatically removed on disconnect.
+Use `onMounted()` for DOM-dependent initialization that must run after the template is mounted. Use `onElement(ref, cb)` for work tied to a specific DOM node. `onEvent()` attaches a listener that is automatically removed on disconnect.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { define, html, ref } from '@vielzeug/ore';
+import { define, html, onElement, onEvent, onMounted, ref, useSlots } from '@vielzeug/ore';
 
 define('deferred-init', {
-  setup(_props, { slots, onMounted, onElement, onEvent }) {
+  setup(_props) {
     const tabIndex = signal(0);
     const inputRef = ref();
+    const slots = useSlots();
 
     onMounted(() => {
       const items = slots.elements('items').value;
@@ -21596,12 +22237,11 @@ define('profile-name', {
 
 ## directives
 
-Ore includes `each`, `classMap`, `styleMap`, `when`, `live`, and `raw` — import them from `@vielzeug/ore/directives`.
+Ore includes `each`, `classMap`, `styleMap`, `when`, and `model` — the everyday template directives most components need, imported directly from `@vielzeug/ore` alongside `define`/`html`. The advanced/niche ones (`live`, `raw`) live behind a separate `@vielzeug/ore/directives` import — see below.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { classMap, each, styleMap, when } from '@vielzeug/ore/directives';
-import { define, html } from '@vielzeug/ore';
+import { classMap, define, each, html, styleMap, when } from '@vielzeug/ore';
 
 define('task-list', {
   setup() {
@@ -21667,14 +22307,14 @@ define('live-search', {
 
 ## host bindings
 
-The setup context provides `bind` for wiring the host element.
+`bind()` wires reactive attrs, classes, styles, and events to the host element.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { define, html } from '@vielzeug/ore';
+import { bind, define, html } from '@vielzeug/ore';
 
 define('x-toggle', {
-  setup(_props, { bind }) {
+  setup(_props) {
     const open = signal(false);
 
     bind({
@@ -21692,14 +22332,14 @@ The `bind` config supports `attr`, `class`, `style`, and `on` sections.
 
 ## ARIA bindings
 
-Use `ctx.aria(target, config)` to reactively sync ARIA attributes to any element. Shorthand keys are normalised to `aria-*` automatically — `expanded` becomes `aria-expanded`, `role` is set verbatim.
+Use `aria(target, config)` to reactively sync ARIA attributes to any element. Shorthand keys are normalised to `aria-*` automatically — `expanded` becomes `aria-expanded`, `role` is set verbatim.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { define, html } from '@vielzeug/ore';
+import { aria, bind, define, html, onMounted } from '@vielzeug/ore';
 
 define('x-disclosure', {
-  setup(_props, { aria, bind, onMounted }) {
+  setup(_props) {
     const open = signal(false);
     const panelId = 'disclosure-panel';
 
@@ -21745,10 +22385,10 @@ Pass `{ target: el }` as a second argument to bind attributes, classes, styles,
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { define, html, ref } from '@vielzeug/ore';
+import { bind, define, html, onMounted, ref } from '@vielzeug/ore';
 
 define('button-wrapper', {
-  setup(_props, { bind, onMounted }) {
+  setup(_props) {
     const visible = signal(false);
     const btnRef = ref();
 
@@ -21773,11 +22413,13 @@ define('button-wrapper', {
 ## slots and emits
 
 ```ts
-import { when } from '@vielzeug/ore/directives';
-import { define, html } from '@vielzeug/ore';
+import { define, html, useEmit, useSlots, when } from '@vielzeug/ore';
+
+define('card-with-footer', {
+  setup(_props) {
+    const slots = useSlots();
+    const emit = useEmit();
 
-define, Record, 'header' | 'footer'>('card-with-footer', {
-  setup(_props, { slots, emit }) {
     return html`
       
         
@@ -21790,18 +22432,18 @@ define, Record, 'header' | 'footer'>('card-with-footer', {
 });
 ```
 
-Pass `SlotNames` as a type parameter to `define()` to get typed `slots.has()` and `slots.elements()` calls.
+Pass a `SlotNames` type parameter to `useSlots()` to get typed `slots.has()` and `slots.elements()` calls.
 
 ## context provide/inject
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { createContext, define, html, injectStrict } from '@vielzeug/ore';
+import { createContext, define, html, injectStrict, provide } from '@vielzeug/ore';
 
 const COUNT_CTX = createContext>>('count');
 
 define('count-provider', {
-  setup(_props, { provide }) {
+  setup(_props) {
     const count = signal(0);
     provide(COUNT_CTX, count);
 
@@ -21822,7 +22464,8 @@ define('count-consumer', {
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { define, html, prop, useField } from '@vielzeug/ore';
+import { define, html, prop } from '@vielzeug/ore';
+import { useField } from '@vielzeug/ore/forms';
 
 define('rating-input', {
   formAssociated: true,
@@ -21862,15 +22505,15 @@ define('user-profile', {
 
 ## platform observers
 
-Observer helpers from `@vielzeug/ore/observers` require real DOM nodes, so call them inside `ctx.onMounted()`.
+Observer helpers from `@vielzeug/ore/observers` require real DOM nodes, so call them inside `onMounted()`.
 
 ```ts
 import { effect } from '@vielzeug/ripple';
-import { define, html, ref } from '@vielzeug/ore';
+import { define, html, onMounted, ref } from '@vielzeug/ore';
 import { intersectionObserver, mediaObserver, resizeObserver } from '@vielzeug/ore/observers';
 
 define('x-observed', {
-  setup(_props, { onMounted }) {
+  setup(_props) {
     const boxRef = ref();
 
     onMounted(() => {
@@ -21988,10 +22631,11 @@ Use `@vielzeug/forge` for typed form state alongside Ore's `useField()` for form
 ```ts
 import { createForm } from '@vielzeug/forge';
 import { s } from '@vielzeug/spell';
-import { createFormContext, define, html, FORM_CONTEXT_KEY } from '@vielzeug/ore';
+import { define, html, provide } from '@vielzeug/ore';
+import { createFormContext, FORM_CONTEXT_KEY } from '@vielzeug/ore/forms';
 
 define('signup-form', {
-  setup(_props, { provide }) {
+  setup(_props) {
     const formCtx = createFormContext({
       onSubmit: async (e) => {
         e?.preventDefault();
@@ -22013,13 +22657,13 @@ define('signup-form', {
 ## Best Practices
 
 - Setup returns `html\`...\`` directly — not a function wrapping the template.
-- Use `ctx.watch()` for reactive subscriptions tied to component lifetime — it auto-registers cleanup on disconnect.
-- Use `ctx.onElement(ref, cb)` instead of `ctx.onMounted` when the work is tied to a single DOM node.
-- Bind host attributes and classes via `ctx.bind()` rather than mutating the element directly.
+- Use `watchEffect()` for reactive subscriptions tied to component lifetime — it auto-registers cleanup on disconnect.
+- Use `onElement(ref, cb)` instead of `onMounted` when the work is tied to a single DOM node.
+- Bind host attributes and classes via `bind()` rather than mutating the element directly.
 - Provide context at the nearest ancestor — avoid global context singletons.
-- Call `ctx.onCleanup()` for every resource allocated in `setup()` (WebSockets, intervals, external subscriptions).
+- Call `onCleanup()` for every resource allocated in `setup()` (WebSockets, intervals, external subscriptions).
 - Use `live(signal)` for form inputs to prevent clobbering user-in-progress edits.
-- Thread lifecycle hooks explicitly into composable helpers via function parameters — do not rely on implicit module-level context.
+- Extract composable helper functions freely — `onMounted`/`onCleanup`/`bind`/... resolve the active component through implicit context, so they work from any function called (transitively) during `setup()`, with no need to pass them in as parameters.
 - Test with `@vielzeug/ore/testing` helpers (`mount`, `flush`, `waitFor`) rather than direct DOM manipulation.
 
 ### Examples
@@ -25927,8 +26571,8 @@ When the buffer is full, the **oldest** frame is evicted to make room for the ne
 
 **Category:** ui-components
 **Keywords:** web-components, accessible, themeable, ui, components, design-system
-**Key exports:** ore-accordion, ore-accordion-item, ore-alert, ore-async, ore-avatar, ore-avatar-group, ore-badge, ore-box, ore-breadcrumb, ore-breadcrumb-item, ore-button, ore-button-group (+48 more)
-**Related:** ore, orbit, forge
+**Key exports:** ore-accordion, ore-accordion-item, ore-alert, ore-async, ore-avatar, ore-avatar-group, ore-badge, ore-box, ore-breadcrumb, ore-breadcrumb-item, ore-button, ore-button-group (+55 more)
+**Related:** ore, orbit, forge, keymap
 
 ### Overview
 
@@ -26034,17 +26678,17 @@ Headless widget controllers (`createTextField`, `createListControl`, `createOver
 
 ### Components
 
-**Content:** `ore-avatar`, `ore-avatar-group`, `ore-breadcrumb`, `ore-card`, `ore-carousel`, `ore-carousel-slide`, `ore-icon`, `ore-pagination`, `ore-separator`, `ore-table`, `ore-text`
+**Content:** `ore-avatar`, `ore-avatar-group`, `ore-breadcrumb`, `ore-card`, `ore-carousel`, `ore-carousel-slide`, `ore-chat-message`, `ore-icon`, `ore-list`, `ore-list-item`, `ore-pagination`, `ore-separator`, `ore-table`, `ore-text`
 
 **Disclosure:** `ore-accordion`, `ore-accordion-item`, `ore-tabs`, `ore-tab-item`, `ore-tab-panel`
 
-**Feedback:** `ore-alert`, `ore-async`, `ore-badge`, `ore-chip`, `ore-password-strength`, `ore-progress`, `ore-skeleton`, `ore-toast`
+**Feedback:** `ore-alert`, `ore-async`, `ore-badge`, `ore-chip`, `ore-password-strength`, `ore-progress`, `ore-skeleton`, `ore-toast`, `ore-typing-indicator`
 
-**Inputs:** `ore-button`, `ore-button-group`, `ore-calendar`, `ore-checkbox`, `ore-checkbox-group`, `ore-column`, `ore-combobox`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-form`, `ore-input`, `ore-number-input`, `ore-otp-input`, `ore-radio`, `ore-radio-group`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
+**Inputs:** `ore-button`, `ore-button-group`, `ore-calendar`, `ore-checkbox`, `ore-checkbox-group`, `ore-column`, `ore-combobox`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-form`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-radio`, `ore-radio-group`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
 
 **Layout:** `ore-box`, `ore-grid`, `ore-grid-item`, `ore-navbar`, `ore-sidebar`
 
-**Overlay:** `ore-dialog`, `ore-drawer`, `ore-menu`, `ore-popover`, `ore-tooltip`
+**Overlay:** `ore-command-palette`, `ore-command-palette-item`, `ore-dialog`, `ore-drawer`, `ore-menu`, `ore-popover`, `ore-tooltip`
 
 ## Features
 
@@ -26072,6 +26716,7 @@ Headless widget controllers (`createTextField`, `createListControl`, `createOver
 - [Ore](/ore/) — Web component runtime that powers Refine
 - [Orbit](/orbit/) — Floating UI positioning used in Refine's overlays
 - [Forge](/forge/) — Form state management for use with Refine inputs
+- [Keymap](/keymap/) — Keyboard shortcut manager that powers the command palette's global trigger
 
 ### API Reference
 
@@ -26131,11 +26776,13 @@ import '@vielzeug/refine/button-group';
 import '@vielzeug/refine/calendar';
 import '@vielzeug/refine/card';
 import '@vielzeug/refine/carousel';
+import '@vielzeug/refine/chat-message';
 import '@vielzeug/refine/checkbox';
 import '@vielzeug/refine/checkbox-group';
 import '@vielzeug/refine/chip';
 import '@vielzeug/refine/copy-command';
 import '@vielzeug/refine/combobox';
+import '@vielzeug/refine/command-palette';
 import '@vielzeug/refine/datagrid';
 import '@vielzeug/refine/date-picker';
 import '@vielzeug/refine/dialog';
@@ -26146,7 +26793,10 @@ import '@vielzeug/refine/grid';
 import '@vielzeug/refine/grid-item';
 import '@vielzeug/refine/icon';
 import '@vielzeug/refine/input';
+import '@vielzeug/refine/list';
+import '@vielzeug/refine/list-item';
 import '@vielzeug/refine/menu';
+import '@vielzeug/refine/message-composer';
 import '@vielzeug/refine/navbar';
 import '@vielzeug/refine/number-input';
 import '@vielzeug/refine/otp-input';
@@ -26172,6 +26822,7 @@ import '@vielzeug/refine/textarea';
 import '@vielzeug/refine/time-picker';
 import '@vielzeug/refine/toast';
 import '@vielzeug/refine/tooltip';
+import '@vielzeug/refine/typing-indicator';
 ```
 
 ## Shared Exported Symbols
@@ -26231,20 +26882,24 @@ Per-component API — attributes, events, slots, CSS custom properties:
 - [Progress](./components/progress.md)
 - [Skeleton](./components/skeleton.md)
 - [Toast](./components/toast.md)
+- [Typing Indicator](./components/typing-indicator.md)
 
 ### Content
 - [Avatar](./components/avatar.md)
 - [Breadcrumb](./components/breadcrumb.md)
 - [Card](./components/card.md)
 - [Carousel](./components/carousel.md)
+- [Chat Message](./components/chat-message.md)
 - [Copy Command](./components/copy-command.md)
 - [Icon](./components/icon.md)
+- [List (+ List Item)](./components/list.md)
 - [Pagination](./components/pagination.md)
 - [Separator](./components/separator.md)
 - [Table](./components/table.md)
 - [Text](./components/text.md)
 
 ### Overlay
+- [Command Palette](./components/command-palette.md)
 - [Dialog](./components/dialog.md)
 - [Drawer](./components/drawer.md)
 - [Menu](./components/menu.md)
@@ -26261,6 +26916,7 @@ Per-component API — attributes, events, slots, CSS custom properties:
 - [File Input](./components/file-input.md)
 - [Form](./components/form.md)
 - [Input](./components/input.md)
+- [Message Composer](./components/message-composer.md)
 - [Number Input](./components/number-input.md)
 - [OTP Input](./components/otp-input.md)
 - [Radio (+ Radio Group)](./components/radio.md)
@@ -26313,7 +26969,7 @@ createTextField(options: TextFieldOptions): TextFieldHandle
 
 Controller for `` and ``. Manages value sync, validation triggers, character counter, and event wiring.
 
-Key members: `value` (writable signal), `wire(el, signal?)`, `clear()`, `counter`.
+Key members: `value` (writable signal), `wire(el, signal?)`, `clear()`, `reset()`, `counter`, `validity`/`validationMessage` (feed straight into `useField({ validity, validationMessage })`), `attachFormField(formField)` (call once the `useField()` handle exists, to wire up validation triggers and form `reset()` restoration).
 
 ### `createChoiceField(options)`
 
@@ -26323,7 +26979,9 @@ createChoiceField(options: ChoiceFieldOptions): ChoiceFieldHandle
 
 Controller for single and multi-select inputs. Normalises `string | string[]` values.
 
-Key members: `selectedValues`, `selectedValue`, `selectValue()`, `toggleValue()`, `removeValue()`, `clear()`, `setValues()`, `formValue`.
+Key members: `selectedValues`, `selectedValue`, `selectValue()`, `toggleValue()`, `removeValue()`, `clear()`, `setValues()`, `formValue`, `reset()` (see below), `validity`/`validationMessage` (feed straight into `useField({ validity, validationMessage })`, `{ valueMissing: true }` while `required` and nothing selected), `attachFormField(formField)` (call once the `useField()` handle exists).
+
+`reset()` has two states, not one: before the user ever changes the selection, it re-syncs from whatever `value` currently holds (same as `createTextField`'s `reset()` — e.g. an async-loaded default arriving after mount is still a legitimate target). Once the user changes the selection for the first time, it freezes to the value captured at field creation and stops tracking `value` — this matters for `ore-radio-group`/`ore-checkbox-group` specifically, which reflect the current selection back onto the host's `value`/`values` attribute for `:host([value])` styling, so past that point `value` itself changes on every selection and can't double as "the default to revert to" the way an uncontrolled ``'s `value` attribute can. `ore-select`/`ore-combobox` don't reflect their selection back onto `value` at all, so for them this distinction is moot in practice — but the primitive can't know that in advance, so it applies the same safe two-state rule uniformly.
 
 ### `createCheckable(options)`
 
@@ -26333,7 +26991,7 @@ createCheckable(options: CheckableOptions): CheckableHandle
 
 Controller for checkboxes and radios. Handles checked/indeterminate state, group delegation, and keyboard activation.
 
-Key members: `checked`, `indeterminate`, `toggle()`, `handleClick()`, `handleKeydown()`.
+Key members: `checked`, `indeterminate`, `toggle()`, `handleClick()`, `handleKeydown()`, `reset()` (same two-state rule as `createChoiceField`'s — tracks `checked`/`indeterminate` live until the first `toggle()`, then freezes, since `checked` is reflected back onto the host attribute too), `validity`/`validationMessage` (`{ valueMissing: true }` while `required` and unchecked, indeterminate counts as unchecked), `attachFormField(formField)`.
 
 ### `createOverlayControl(options)`
 
@@ -26367,6 +27025,8 @@ createListControl(options: ListNavigationOptions): ListControl
 
 Keyboard-navigable list without open state. Supports vertical/horizontal/omni navigation, disabled-item skipping, looping, and typeahead. Navigation methods return the resolved index, or `-1` when no enabled item was found.
 
+Pass `direction` (`'ltr' | 'rtl'` or a getter) to mirror the default Left/Right arrow-key bindings for `'horizontal'`/`'both'` orientation, per WAI-ARIA APG (e.g. `direction: () => elementDirection(getHost())`). Has no effect when an explicit `keys` override is supplied.
+
 ### Other Headless Exports
 
 | Export                       | Description                                                        |
@@ -26379,7 +27039,6 @@ Keyboard-navigable list without open state. Supports vertical/horizontal/omni na
 | `createDataGridControl()`    | Data grid state (sorting, selection, column management, pagination)|
 | `createTypeahead()`          | Standalone typeahead buffer with debounced reset                   |
 | `createDropdownPositioner()` | Floating dropdown positioner (wraps Orbit)                         |
-| `createDialogFocusControl()` | Dialog-specific focus entry and restoration                        |
 | `createInteraction()`        | Unified click/keyboard press handler for interactive elements      |
 | `dispatchKeyboardAction()`   | Low-level keymap dispatcher                                        |
 | `createSelectionControl()`   | Single/multi/none row-selection controller (used by the data grid) |
@@ -26681,7 +27340,7 @@ label.dispose();
 - **`.replace(fn)`** — derive next state from current via a function; same-reference return is a no-op
 - **`.reset()`** — restore the initial state baseline
 - **`.lens(path)`** — cached writable `Signal` for a property or dot-path; writes produce an immutable copy
-- **`storeWithHistory(storeOrInit, options?)`** — store with explicit snapshot history; accepts an existing `Store` (not owned) or a plain object; call `.push()` / `.pushNamed(label)` to save checkpoints; `undo()`, `redo()`, `historyAt(i)` returns `HistoryEntry`; reactive `canUndo` / `canRedo`
+- **`storeWithHistory(storeOrInit, options?)`** — store with explicit snapshot history; accepts an existing `Store` (not owned) or a plain object; call `.push()` / `.pushNamed(label)` to save checkpoints; `undo()`, `redo()`, `historyAt(i)` returns `HistoryEntry`; reactive `canUndo` / `canRedo`; import via `@vielzeug/ripple/history`
 - **`getDevToolsHook()`** — returns the currently installed DevTools hook, or `null`; install via `@vielzeug/ripple/devtools`
 - **Glitch-free propagation** — computed signals propagate in dependency order; effects always observe a consistent snapshot
 - **Infinite loop detection** — built-in guard against effect re-entry cycles (100 iterations default)
@@ -26725,7 +27384,7 @@ label.dispose();
 | `scope()`            | Isolated cleanup context                                              | Sync           | Must call `scope.run()` to activate; `dispose()` is LIFO                          |
 | `debugEffect()`      | Effect that logs changed sources before re-run                        | Sync           | Sub-path only: `@vielzeug/ripple/devtools`; tree-shaken from production           |
 | `store()`            | Create object-like state container                                    | Sync           | Store is a branded signal; use `.patch()`, `.replace()`, `.reset()`               |
-| `storeWithHistory()` | Store with snapshot-based undo/redo history                           | Sync           | Call `.push()` / `.pushNamed()` explicitly to record a checkpoint; `maxHistory` caps the buffer |
+| `storeWithHistory()` | Store with snapshot-based undo/redo history                           | Sync           | Sub-path only: `@vielzeug/ripple/history`; call `.push()` / `.pushNamed()` explicitly to record a checkpoint; `maxHistory` caps the buffer |
 | `installDevTools()`  | Install DevTools observation hook                                     | Sync           | Sub-path only: `@vielzeug/ripple/devtools`; pass `null` to uninstall              |
 | `getDevToolsHook()`  | Return current DevTools hook                                          | Sync           | Returns `null` if none installed                                                  |
 | `isSignal()`         | Type guard for any signal/computed/store                              | Sync           | Uses an internal symbol marker, not duck-typing                                   |
@@ -26738,6 +27397,7 @@ label.dispose();
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@vielzeug/ripple`          | All core exports and types                                                                                                                                        |
 | `@vielzeug/ripple/devtools` | `installDevTools`, `debugEffect`, and hook types (`RippleDevToolsHook`, `WriteEvent`, `NamedEvent`, `DisposeEvent`, `MutateEvent`) — dev-only, tree-shaken from prod |
+| `@vielzeug/ripple/history`  | `storeWithHistory` and its types (`StoreWithHistory`, `HistoryEntry`) — tree-shaken unless imported |
 | `@vielzeug/ripple/ssr`      | SSR tracking isolation helpers (`setTrackingProvider`, `createAsyncProvider`, `withProvider`, `runWithProvider`). Node.js only — do not import in browser builds. |
 
 ## Signal Primitives
@@ -27249,6 +27909,8 @@ Creates a reactive store for the given object state. Stores accept `effect()`, `
 
 ### `storeWithHistory`
 
+`storeWithHistory` is exported from `@vielzeug/ripple/history`, not the main entry point. This keeps it tree-shaken from bundles that never use it — for async commands or history over anything other than a `Store`, use `@vielzeug/ledger` instead.
+
 ```ts
 function storeWithHistory(
   storeOrInitial: Store | T,
@@ -27263,6 +27925,8 @@ The initial state is saved as the first snapshot automatically. Snapshots are de
 **Ownership:** when called with an initial value (`T`), the adapter creates and owns the underlying store — `dispose()` also disposes it. When called with an existing `Store`, the adapter does **not** own it — `dispose()` leaves the store alive.
 
 ```ts
+import { storeWithHistory } from '@vielzeug/ripple/history';
+
 const editor = storeWithHistory({ text: '' }, { maxHistory: 100 });
 
 editor.patch({ text: 'hello' }); // direct — StoreWithHistory extends Store
@@ -27891,6 +28555,20 @@ batch(() => {
 
 Nested `batch()` calls merge into the outermost — only one flush occurs.
 
+## Error Handling
+
+Ripple has no single error-handling mode — each primitive picks the surface that fits how it's normally consumed. This is one deliberate spectrum, not three unrelated designs:
+
+| Primitive                      | Failure surface                                 | Why                                                                                       |
+| ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `signal()` / `computed()`       | Throws synchronously                             | Sync code — the caller is already in a position to catch                                   |
+| `effect()`                      | Throws synchronously (rethrown from the run)     | Same as above — no async gap between cause and observation                                 |
+| `watch()`                       | Throws synchronously on an invalid callback return | Programmer-error guard, not a runtime failure mode                                         |
+| `effectAsync()`                 | Routes to `onError` (default: rethrown via `queueMicrotask`) | There's no synchronous caller left to catch by the time the factory rejects — needs an explicit escape hatch |
+| `resource()`                    | Never throws — lands in `ResourceState.status === 'error'` | Failures are render state (show an error UI), not exceptions to unwind past                |
+
+Rule of thumb: if you're inside a synchronous callback, ripple throws (`RippleError` subtypes — see [Errors](#errors)). If the failure only exists after an `await`, ripple gives you a place to observe it instead of throwing into a call stack that's already gone — `onError` for `effectAsync()`, `ResourceState.error` for `resource()`.
+
 ### Usage Guide
 
 ## Basic Usage
@@ -28309,7 +28987,7 @@ effect(() => {
 `storeWithHistory(initial, options?)` wraps a store with snapshot-based undo/redo. Mutations do **not** automatically push snapshots — call `.push()` (or `.pushNamed(label)`) explicitly after each logical change. History navigation with `undo()` and `redo()` never re-runs logic — it replays snapshots directly.
 
 ```ts
-import { storeWithHistory } from '@vielzeug/ripple';
+import { storeWithHistory } from '@vielzeug/ripple/history';
 
 const editor = storeWithHistory({ text: '', cursor: 0 }, { maxHistory: 100 });
 
@@ -28932,7 +29610,6 @@ effect(() => {
 - Scope & onCleanup (id: `scope-cleanup`)
 - Scope — setup shorthand (id: `scope-setup`)
 - Store — patch, lens & computed (id: `store-basics`)
-- Store History — Undo/Redo (id: `store-history`)
 - Store — fine-grained lens reactivity (id: `store-lenses`)
 - Store - Todo List (id: `store-todo-list`)
 - Watch, Lens & Map (id: `watch-and-subscribe`)
@@ -31276,7 +31953,7 @@ Scout builds a **trigram inverted index** at construction time. Query time is O(
 | ------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------- |
 | Bundle size              | ~3 KB                                          |                                                | ~23 KB                                         |
 | Zero dependencies        |      |  `@vielzeug/ripple` peer (reactive layer only) |      |
-| Algorithm                | Levenshtein                                    | Trigram + Dice coefficient                                                                | Bitap                                          |
+| Algorithm                | Levenshtein                                    | Trigram + overlap coefficient                                                             | Bitap                                          |
 | Query time               | O(n·m)                                         | O(candidates)                                                                             | O(n·m)                                         |
 | Stateful index           |          |                                                 |      |
 | Match highlighting       |          |                                                 |      |
@@ -31388,7 +32065,7 @@ function createIndex(items: T[], options: ScoutIndexOptions): ScoutIndex
 | --- | --- | --- |
 | `items` | `T[]` | Initial corpus to index. |
 | `options.fields` | `ReadonlyArray>` | Fields to index. Required; at least one entry. |
-| `options.threshold` | `number` | Min Dice score for a result (default `0.2`). |
+| `options.threshold` | `number` | Min overlap score for a result (default `0.2`). |
 | `options.limit` | `number` | Max results returned by `search()` (default `50`). |
 | `options.minQueryLength` | `number` | Min chars before trigram scoring; shorter queries use O(n) containment scan (default `3`). |
 
@@ -31533,7 +32210,7 @@ function createReactiveSearch(
 | `items` | `T[]` | Initial corpus to index. |
 | `options.fields` | `ReadonlyArray>` | Fields to index. Required. |
 | `options.debounce` | `number` | Debounce ms (default `200`). |
-| `options.threshold` | `number` | Min Dice score (default `0.2`). |
+| `options.threshold` | `number` | Min overlap score (default `0.2`). |
 | `options.limit` | `number` | Max results (default `50`). |
 | `options.minQueryLength` | `number` | Min chars before trigram scoring (default `3`). |
 
@@ -31903,12 +32580,18 @@ index.search('日本語'); // matches the first document
 Pass `limit`, `threshold`, and `minQueryLength` in options to control result count and quality.
 
 ```ts
-// At most 10 results, minimum Dice score 0.3
+// At most 10 results, minimum overlap score 0.3
 const results = index.search('widget', { limit: 10, threshold: 0.3 });
 ```
 
 Per-call options override the index-level defaults set in `createIndex`.
 
+Scores come from the overlap (Szymkiewicz–Simpson) coefficient — the fraction of the *shorter*
+trigram set (almost always the query) found in the longer one. This is deliberate for the
+autocomplete/command-palette use case `createIndex` targets: a short query that's a clean prefix
+of a much longer field value (e.g. `'fin'` against `'Finalize Q3 budget report'`) scores on how
+much of the query matched, not diluted by how much longer the target field happens to be.
+
 ### Controlling short-query behaviour
 
 Queries shorter than `minQueryLength` (default `3`) fall back to an O(n) substring containment scan. Short-query matches return `score = 1.0`.
@@ -32561,6 +33244,7 @@ interface VirtualizerState {
 | `scrollToOffset`   | `(offset: number, options?: { behavior?: ScrollBehavior }) => void` | Scroll to a raw pixel offset                                         |
 | `scrollToTop`      | `(options?: { behavior?: ScrollBehavior }) => void`                 | Scroll to offset `0`                                                 |
 | `scrollToBottom`   | `(options?: { behavior?: ScrollBehavior }) => void`                 | Scroll to the end of the list                                        |
+| `isAtEnd`          | `(threshold?: number) => boolean`                                   | `true` when within `threshold` px (default `0`) of the end — check before appending items to decide whether to auto-follow (chat "stick to bottom") |
 | `invalidate`       | `() => void`                                                        | Clear all measurements and rebuild from estimates                    |
 | `dispose`          | `() => void`                                                        | Detach listeners; idempotent                                         |
 | `disposed`         | `boolean`                                                           | `true` after `dispose()` is called                                   |
@@ -32696,9 +33380,34 @@ ctrl.dispose();
 | `overscan`         | `number \| { start?: number; end?: number }`  | `3`      | Extra items outside the viewport; number = symmetric       |
 | `sticky`           | `(index: number, item: T) => boolean`         | —        | Mark items as sticky headers                               |
 | `clear`            | `(listEl: HTMLElement) => void`               | —        | Custom teardown for listEl; defaults to `textContent = ''` |
+| `stickToBottom`    | `boolean \| StickToBottomOptions`                       | —        | Auto-scroll to the end after `setItems()` whenever the list was already at (or near) the end — the chat "stick to bottom on new message" pattern |
 
 Without `getItemKey`, each `setItems()` call drops cached measurements.
 
+### `StickToBottomOptions`
+
+| Option      | Type      | Default | Description                                                                |
+| ----------- | --------- | ------- | --------------------------------------------------------------------------- |
+| `enabled`   | `boolean` | `true`  | Enable/disable at runtime — pass the object form to toggle without removing it |
+| `threshold` | `number`  | `48`    | Distance in pixels from the end still considered "at the end"              |
+
+`stickToBottom` fires on **any** `setItems()` call made while the list is at the end — not just when the item count grows. This also follows a streaming last item that grows in place (same array length, bigger content) without you needing to detect that case yourself. It never fires while the user has scrolled away from the end, so reading older messages is never interrupted.
+
+```ts
+const chat = createDomVirtualList({
+  estimateSize: 48,
+  getItemKey: (_, m) => m.id,
+  listElement: listEl,
+  render: renderMessages,
+  scrollElement: scrollEl,
+  stickToBottom: true, // or { threshold: 80 } for a larger "still at bottom" tolerance
+});
+
+chat.setItems(messages); // scrolls to bottom on first load
+// … later, a new message arrives (or the last one grows while streaming) …
+chat.setItems([...messages, newMessage]); // follows along only if the user was already at the bottom
+```
+
 ### `DomVirtualListRenderArgs`
 
 ```ts
@@ -32734,6 +33443,9 @@ Extends `Virtualizer` (minus `prepend` and `update`) with `setItems()`. All virt
 | `invalidate`       | Clear measurements and rebuild from estimates                                               |
 | `scrollToIndex`    | Scroll to an item                                                                           |
 | `scrollToOffset`   | Scroll to a pixel offset                                                                    |
+| `scrollToTop`      | Scroll to offset `0`                                                                        |
+| `scrollToBottom`   | Scroll to the end of the list                                                                |
+| `isAtEnd`          | `true` when within `threshold` px of the end                                                |
 | `dispose`          | Teardown; idempotent                                                                        |
 | `disposed`         | `true` after `dispose()` is called (live getter)                                            |
 | `[Symbol.dispose]` | Delegates to `dispose()`                                                                    |
@@ -33613,6 +34325,76 @@ virt.scrollToTop();
 virt.scrollToBottom({ behavior: 'smooth' });
 ```
 
+### Chat "stick to bottom on new message"
+
+`createDomVirtualList`'s `stickToBottom` option automates the common chat/log pattern: follow new messages while the user is at the bottom, but never yank them away from history they scrolled up to read.
+
+```ts
+import { createDomVirtualList } from '@vielzeug/scroll';
+
+const chat = createDomVirtualList({
+  estimateSize: 48,
+  getItemKey: (_, m) => m.id,
+  listElement: listEl,
+  render: renderMessages,
+  scrollElement: scrollEl,
+  stickToBottom: true, // or { threshold: 80 } to widen the "still at bottom" tolerance
+});
+
+chat.setItems(messages);
+
+// New message arrives — follows only if the user hasn't scrolled up.
+socket.on('message', (msg) => {
+  messages = [...messages, msg];
+  chat.setItems(messages);
+});
+```
+
+It also follows a **streaming** last message that grows in place (tokens appended to the same message object, array length unchanged) — every `setItems()` call re-checks "was the list at the end before this update?", not just count changes. Build `isAtEnd()` from `createVirtualizer` directly for custom cases (e.g. showing a "jump to latest" button only while scrolled away):
+
+```ts
+const showJumpButton = !virt.isAtEnd();
+```
+
+## Infinite Scroll — Loading More at the End
+
+Use `isAtEnd(threshold)` to fetch the next page as the user nears the bottom. `isAtEnd()` reports scroll position only — it keeps returning `true` while a fetch is in flight — so guard it with your own `loading` flag to avoid firing the same request twice.
+
+```ts
+import { createVirtualizer, type Virtualizer } from '@vielzeug/scroll';
+
+let rows = await fetchPage(0);
+let loading = false;
+
+let virt: Virtualizer;
+virt = createVirtualizer(scrollEl, {
+  count: rows.length,
+  estimateSize: 36,
+  onChange: ({ items, totalSize }) => {
+    listEl.style.height = `${totalSize}px`;
+    listEl.innerHTML = '';
+
+    for (const item of items) {
+      const el = document.createElement('div');
+      el.style.cssText = `position:absolute;top:${item.start}px;left:0;right:0;height:36px;`;
+      el.textContent = rows[item.index]?.label ?? '';
+      listEl.appendChild(el);
+    }
+
+    if (!loading && virt.isAtEnd(200)) {
+      loading = true;
+      fetchPage(rows.length).then((nextRows) => {
+        rows = [...rows, ...nextRows];
+        virt.update({ count: rows.length });
+        loading = false;
+      });
+    }
+  },
+});
+```
+
+`isAtEnd(200)` fires once the viewport is within 200px of the bottom — tune the threshold to your row height and fetch latency. `loading` is the only guard needed: it's cleared once the new page lands, and `update({ count })` re-triggers `onChange`, which re-checks `isAtEnd()` against the new total on the next scroll.
+
 ## Shared Measurement Cache
 
 When the same items are displayed across multiple virtualizer instances (e.g. a list and a detail panel that share row heights), pass a shared `MeasurementCache` created by `createMeasurementCache()`. Measurements recorded by one virtualizer are immediately available to all others using the same cache.
@@ -33699,7 +34481,7 @@ Scroll is rendering-layer agnostic. The pattern is always the same: create the v
 
 ```tsx [React]
 import { createVirtualizer, type Virtualizer } from '@vielzeug/scroll';
-import { useEffect, useRef } from 'react';
+import { useEffect, useLayoutEffect, useRef } from 'react';
 
 interface Row {
   id: number;
@@ -33734,7 +34516,10 @@ function VirtualList({ rows }: { rows: Row[] }) {
     return () => virt.dispose();
   }, []); // attach once
 
-  useEffect(() => {
+  // useLayoutEffect, not useEffect: syncs count before paint. With useEffect,
+  // the DOM (and anything reading `rows`) paints once with the new length before
+  // the virtualizer's internal count catches up, which can render stale/out-of-bounds indices.
+  useLayoutEffect(() => {
     virtRef.current?.update({ count: rows.length });
   }, [rows.length]);
 
@@ -33877,6 +34662,7 @@ class VirtualList extends LitElement {
 ### Pitfalls
 
 - **React:** Putting `rows` in the `useEffect` dependency array causes the virtualizer to be destroyed and recreated on every data update. Only include the scroll element reference. Call `virt.update({ count })` from a separate `useEffect` for data changes.
+- **React:** Use `useLayoutEffect`, not `useEffect`, for the `count`-sync effect. `useEffect` fires after paint — a new `count` can reach the DOM (e.g. via other state derived from `rows`) before `update({ count })` runs, rendering stale or out-of-bounds indices for one frame.
 - **Vue 3:** `ref.value` is `null` inside `setup()` — the DOM doesn't exist yet. Always create the virtualizer inside `onMounted`, not in `setup()`.
 - **Svelte:** In Svelte 5, `$effect` with `bind:this` runs after the DOM is painted. The `bind:this` variable is available when the `$effect` runs — no extra tick needed.
 - **Web Components:** `firstUpdated` fires once after the first render. Use `updated()` for subsequent prop changes — Lit calls it every time `rows` changes.
@@ -33972,7 +34758,7 @@ define('virtual-list', {
 
 **Category:** data
 **Keywords:** pagination, filtering, sorting, search, data-source, query, remote, local, cursor, infinite-scroll
-**Key exports:** createLocalSource, createRemoteSource, createCursorSource, createInfiniteSource, deriveSource, mergeSource, applyQuery, SourceDisposedError, SourcererError, SourceTimeoutError, sourceState, itemRange (+39 more)
+**Key exports:** createLocalSource, createRemoteSource, createCursorSource, createInfiniteSource, deriveSource, mergeSource, SourcererDisposedError, SourcererError, SourcererTimeoutError, sourceState, itemRange, prefetchSource (+38 more)
 **Related:** courier, ripple, wayfinder
 
 ### Overview
@@ -34072,6 +34858,8 @@ console.log(source.current, source.meta.totalItems);
 | `createCursorSource()`   | Server fetch    | Cursor tokens       | `patch()`, `ready()`, `queryKey`                                    |
 | `createInfiniteSource()` | Server fetch    | Append (`loadMore`) | `patch()`, `loadedPages`, `ready()`, `queryKey`                     |
 
+`@vielzeug/sourcerer/devtools`: opt-in `debugSource()` for `console.debug` state-transition logging across any source type, tree-shaken from production.
+
 ## Documentation
 
 - [Usage Guide](./usage.md)
@@ -34090,16 +34878,15 @@ console.log(source.current, source.meta.totalItems);
 
 | Symbol                                 | Purpose                                                                                       | Execution mode | Common gotcha                                                                     |
 | -------------------------------------- | --------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------- |
-| `createLocalSource()`                  | In-memory reactive collection with filter, sort, and search                                   | Sync           | Default `searchFn` is fuzzy, not substring                                        |
+| `createLocalSource()`                  | In-memory reactive collection with filter, sort, and search                                   | Sync           | Default `searchFn` JSON-stringifies each item for substring matching              |
 | `createRemoteSource()`                 | Async server-backed collection with page navigation                                           | Async          | Fetches on creation; set `autoFetch: false` to delay                              |
 | `createCursorSource()`                 | Async collection navigated by cursor tokens                                                   | Async          | `next()`/`prev()` are no-ops when the cursor is absent                            |
 | `createInfiniteSource()`               | Async append-mode (infinite scroll) collection                                                | Async          | `loadMore()` is a no-op once `meta.hasMore` is `false`                            |
 | `deriveSource()`                       | Create a reactive projection of another source                                                | Sync           | Derived source disposes automatically when parent disposes                        |
 | `mergeSource()`                        | Combine multiple sources into one `MergedSource`                                           | Sync           | No `meta` field — returned type is `MergedSource`, not `ReactiveSource`     |
-| `applyQuery()`                         | Apply a partial query patch to any source with `patch()` — fires one fetch                    | Async          | Ignores `page` on Cursor/InfiniteSource — no page concept there                    |
 | `SourcererError`                          | Base error class for all sourcerer errors; carries `message`, `cause`, `context`, `attempt`   | Class          | Extends `Error`; access context via getters, not object spread                    |
-| `SourceTimeoutError`                   | Error thrown when `ready()` times out; has `timeoutMs` property                               | Class          | Extends `SourcererError`; also caught by `instanceof SourcererError`                    |
-| `SourceDisposedError`                  | Error thrown by `ready()` when the source is disposed                                         | Class          | Extends `SourcererError`; catch separately from `SourceTimeoutError` if needed       |
+| `SourcererTimeoutError`                   | Error thrown when `ready()` times out; has `timeoutMs` property                               | Class          | Extends `SourcererError`; also caught by `instanceof SourcererError`                    |
+| `SourcererDisposedError`                  | Error thrown by `ready()` when the source is disposed                                         | Class          | Extends `SourcererError`; catch separately from `SourcererTimeoutError` if needed       |
 | `sourceState()`                        | Derive a discriminated union (`loading`/`error`/`success`) from any source                    | Sync           | Returns `'loading'` when `isSearchPending` is true too                            |
 | `itemRange()`                          | Compute 1-based display range from `SourceMeta`                                               | Sync           | Returns `{ start: 0, end: 0 }` when `totalItems === 0`                            |
 | `prefetchSource()`                     | SSR: fetch first page, return serialisable snapshot; source is disposed immediately           | Async          | **Throws `SourcererError`** if fetch fails                                           |
@@ -34107,6 +34894,7 @@ console.log(source.current, source.meta.totalItems);
 | `filterContains()`                     | Preset predicate: case-insensitive substring match                                            | Sync           | Matches against a getter's string value                                           |
 | `filterEquals()`                       | Preset predicate: strict equality match                                                       | Sync           | Uses `Object.is` semantics                                                        |
 | `filterRange()`                        | Preset predicate: inclusive min/max range                                                     | Sync           | Works with numbers and Dates                                                      |
+| `searchBy()`                           | Preset search builder: field-based matching for `LocalSourceConfig.searchFn`                  | Sync           | Prefer this over default JSON-stringify search on large collections               |
 | `sortBy()`                             | Preset comparator: sort by a getter value                                                     | Sync           | Supports `'asc'` / `'desc'`; handles strings, numbers, Dates                      |
 | `encodeQuery()`                        | Serialize source query to URL params                                                          | Sync           | Filter and sort are JSON-stringified                                              |
 | `decodeQuery()`                        | Deserialize URL params (or `URLSearchParams`) to a source query                               | Sync           | Malformed JSON is silently dropped by default                                     |
@@ -34114,11 +34902,12 @@ console.log(source.current, source.meta.totalItems);
 | `SearchOptions`                        | Options bag for `search()` — only field is `immediate?: boolean`                              | Type           | `search()` always returns `Promise`; debounced unless `{ immediate: true }` |
 | `DecodeQueryOptions`                   | Options for `decodeQuery()` — `defaultLimit` and `strict`                                     | Type           | `strict: true` throws on malformed JSON; default silently drops it                |
 
-## Package Entry Point
+## Package Entry Points
 
-| Import                | Purpose                |
-| --------------------- | ---------------------- |
-| `@vielzeug/sourcerer` | Main exports and types |
+| Import                          | Purpose                                                |
+| -------------------------------- | ------------------------------------------------------ |
+| `@vielzeug/sourcerer`            | Main exports and types                                 |
+| `@vielzeug/sourcerer/devtools`   | Opt-in `debugSource()` — tree-shaken from production   |
 
 ## Core Factories
 
@@ -34144,7 +34933,7 @@ type LocalSourceConfig = {
 };
 ```
 
-The default `searchFn` performs a case-insensitive JSON substring match — i.e. it stringifies each item with `JSON.stringify` and checks if the query string appears anywhere in the result. Provide a custom `searchFn` for domain-specific relevance or exact field matching.
+The default `searchFn` performs a case-insensitive JSON substring match — it stringifies each item with `JSON.stringify` and checks if the query string appears anywhere in the result. For better performance and intent clarity, prefer `searchBy(...)` when searching known fields.
 
 `filterAsync` and `sortAsync` run after their synchronous counterparts. They set `meta.isLoading = true` during computation and accept an `AbortSignal` — a new call aborts any running async computation.
 
@@ -34197,7 +34986,7 @@ type RemoteConfig = {
 ```
 
 `queryKey` defaults to a stable JSON serialization with recursively sorted keys.
-`staleTime` compares the **query key** — navigating to a different page always fetches even within the stale window.
+`staleTime` compares the **query key** — navigating to a different page always fetches even within the stale window. If an `optimisticUpdate()` is active, `refresh()` bypasses `staleTime` to settle the optimistic state.
 
 **Returns:** `RemoteSource` — async server-backed source with page navigation and optimistic update support.
 
@@ -34316,7 +35105,7 @@ All methods return `Promise` unless noted.
 | `patch(changes)`       | Apply one or more query changes atomically — a single recompute for any combination of `limit`, `page`, `search`, `filter`, `sort`                                                    |
 | `prev()`               | Navigate to the previous page (no-op at first page)                                                                                                                                   |
 | `query`                | Current state as a `SourceQuery` (`limit`/`page`/`search` only — filter/sort aren't part of the query snapshot) — read-only snapshot; stable between changes                                                                                                   |
-| `ready(timeout?)`      | Resolve when no async computation is pending and no debounce is scheduled; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError` |
+| `ready(timeout?)`      | Resolve when no async computation is pending and no debounce is scheduled; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError` |
 | `reset()`              | Restore initial config and return to page 1                                                                                                                                           |
 | `search(query, opts?)` | Always returns `Promise`. Debounced by default; pass `{ immediate: true }` to cancel debounce and await immediately                                                             |
 | `setData(data)`        | Replace the dataset and reset to page 1                                                                                                                                               |
@@ -34338,7 +35127,7 @@ All methods return `Promise` except `optimisticUpdate` and `subscribe`.
 | `patch(changes)`                      | Apply one or more query changes atomically — a single fetch for any combination of `limit`, `page`, `search`, `filter`, `sort`                   |
 | `prev()`                              | Previous page (no-op at first page)                                                                                                              |
 | `query`                               | Current state as a `RemoteSourceQuery` — read-only snapshot; stable between changes                                                             |
-| `ready(timeout?)`                     | Resolve when no requests are pending; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError` |
+| `ready(timeout?)`                     | Resolve when no requests are pending; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError` |
 | `refresh()`                           | Re-fetch the current query                                                                                                                       |
 | `reset()`                             | Restore initial config and refetch                                                                                                               |
 | `search(query, opts?)`                | Always returns `Promise`. Debounced by default; pass `{ immediate: true }` to cancel debounce and await immediately                        |
@@ -34370,7 +35159,7 @@ optimisticUpdate(
 | `patch(changes)`       | Apply `limit` and/or `search` atomically — a single fetch; resets cursor position                                                    |
 | `prev()`               | Go back using `prevCursor` (no-op if none)                                                                                             |
 | `query`                | Current state as a `CursorSourceQuery` — read-only snapshot; stable between changes                                                   |
-| `ready(timeout?)`      | Resolve when idle; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError`          |
+| `ready(timeout?)`      | Resolve when idle; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError`          |
 | `refresh()`            | Re-fetch current cursor position                                                                                                       |
 | `reset()`              | Clear cursors and fetch from the start                                                                                                 |
 | `search(query, opts?)` | Always returns `Promise`. Debounced by default; pass `{ immediate: true }` to cancel debounce and await. Resets cursor position. |
@@ -34386,33 +35175,22 @@ optimisticUpdate(
 | `loadMore()`           | Fetch the next page and append to `current` (no-op when `meta.hasMore === false`)                                                                               |
 | `patch(changes)`       | Apply `limit` and/or `search` atomically — **clears items immediately** and fetches from page 1                                                                 |
 | `query`                | Current state as an `InfiniteSourceQuery` — read-only snapshot; stable between changes                                                                         |
-| `ready(timeout?)`      | Resolve when idle; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError`                                   |
+| `ready(timeout?)`      | Resolve when idle; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError`                                   |
 | `reset()`              | Clear accumulated items **immediately** and fetch from page 1                                                                                                   |
 | `search(query, opts?)` | Always returns `Promise`. Debounced by default — **clears items immediately**; fetch fires after debounce. Pass `{ immediate: true }` to skip the window. |
 | `subscribe(listener)`  | Subscribe; returns unsubscribe                                                                                                                                  |
 
 ## Query Utilities
 
-### `applyQuery`
-
-```ts
-applyQuery): Promise }>(
-  source: T,
-  changes: Partial,
-): Promise
-```
-
-Applies a partial `SourceQuery` (`limit`/`page`/`search`) patch to any source that exposes a compatible `patch()` — delegates directly to `source.patch(changes)`. Fires a single fetch or recomputation for any combination of changed fields. No-op when `changes` is empty or all values are unchanged, per each source's own `patch()` implementation.
-
-`CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation) — their `patch()` only reads `limit`/`search`, so a `page` field from `decodeQuery()` output is silently ignored on those two source types.
+Restoring URL-decoded state onto a source is a direct `source.patch(decodeQuery(...))` call — no separate wrapper function. `CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation), so their `patch()` type only accepts `limit`/`search`; passing a `page` field from `decodeQuery()`'s output to either is a compile-time error, not a silent no-op.
 
 **Example:**
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const q = decodeQuery(new URLSearchParams(location.search));
-await applyQuery(source, q);
+await source.patch(q);
 ```
 
 ---
@@ -34431,13 +35209,13 @@ class SourcererError extends Error {
 }
 ```
 
-Base class for all sourcerer errors. Thrown (and stored as `meta.error`) when a fetch fails. `cause` is the original thrown value. `SourceTimeoutError` and `SourceDisposedError` both extend this class, so a single `instanceof SourcererError` check covers all sourcerer errors.
+Base class for all sourcerer errors. Thrown (and stored as `meta.error`) when a fetch fails. `cause` is the original thrown value. `SourcererTimeoutError` and `SourcererDisposedError` both extend this class, so a single `instanceof SourcererError` check covers all sourcerer errors.
 
-### `SourceTimeoutError`
+### `SourcererTimeoutError`
 
 ```ts
-class SourceTimeoutError extends SourcererError {
-  readonly name = 'SourceTimeoutError';
+class SourcererTimeoutError extends SourcererError {
+  readonly name = 'SourcererTimeoutError';
   readonly timeoutMs: number;
   // message: 'Source.ready() timed out after Nms'
 }
@@ -34445,11 +35223,11 @@ class SourceTimeoutError extends SourcererError {
 
 Thrown by `ready(timeout)` when the timeout expires before the source becomes idle. Also caught by `instanceof SourcererError`.
 
-### `SourceDisposedError`
+### `SourcererDisposedError`
 
 ```ts
-class SourceDisposedError extends SourcererError {
-  readonly name = 'SourceDisposedError';
+class SourcererDisposedError extends SourcererError {
+  readonly name = 'SourcererDisposedError';
   // message: 'Source disposed while waiting for ready()'
 }
 ```
@@ -34629,11 +35407,34 @@ Not generic — `filter`/`sort` on the result are always typed `unknown`. Narrow
 **Example:**
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 // Pass URLSearchParams directly — filter/sort come back as `unknown`, narrow before use
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 20 });
-await applyQuery(source, query);
+await source.patch(query);
+```
+
+## Devtools (`@vielzeug/sourcerer/devtools`)
+
+```ts
+debugSource>(
+  source: { current: readonly unknown[]; meta: TMeta; subscribe(listener: () => void): () => void },
+  options?: { label?: string },
+): () => void
+```
+
+Attaches a `console.debug`-based observer to any source (or `deriveSource`/`mergeSource` result) — logs a line per changed `meta` field (works generically across `SourceMeta`/`CursorMeta`/`InfiniteMeta`) and `current`'s item count. Development-only by default; a no-op when `__SOURCERER_PROD__` is set. Import from the dedicated `/devtools` sub-path so it's tree-shaken from production bundles.
+
+```ts
+import { createRemoteSource } from '@vielzeug/sourcerer';
+import { debugSource } from '@vielzeug/sourcerer/devtools';
+
+const source = createRemoteSource({ fetch: fetchUsers, limit: 20 });
+const detach = debugSource(source, { label: 'users' });
+// [sourcerer:devtools:users] meta.isLoading: false → true
+// [sourcerer:devtools:users] current: 0 → 20 items
+
+detach(); // stop logging
 ```
 
 ## Types
@@ -34737,50 +35538,50 @@ type FetchEvent = Readonly;
 
 See [Error Utilities > `SourcererError`](#sourcererror) above.
 
-### `SourceTimeoutError`
+### `SourcererTimeoutError`
 
 ```ts
-class SourceTimeoutError extends SourcererError {
-  readonly name = 'SourceTimeoutError';
+class SourcererTimeoutError extends SourcererError {
+  readonly name = 'SourcererTimeoutError';
   readonly timeoutMs: number;
   // message: 'Source.ready() timed out after Nms'
 }
 ```
 
-Thrown by `ready(timeout)` when the source has not become idle within the specified `timeout` milliseconds. Check with `instanceof SourceTimeoutError` for typed catch blocks:
+Thrown by `ready(timeout)` when the source has not become idle within the specified `timeout` milliseconds. Check with `instanceof SourcererTimeoutError` for typed catch blocks:
 
 ```ts
-import { SourceTimeoutError } from '@vielzeug/sourcerer';
+import { SourcererTimeoutError } from '@vielzeug/sourcerer';
 
 try {
   await source.ready(5000);
 } catch (err) {
-  if (err instanceof SourceTimeoutError) {
+  if (err instanceof SourcererTimeoutError) {
     console.warn('Source did not load in time:', err.message);
   }
 }
 ```
 
-### `SourceDisposedError`
+### `SourcererDisposedError`
 
 ```ts
-class SourceDisposedError extends SourcererError {
-  readonly name = 'SourceDisposedError';
+class SourcererDisposedError extends SourcererError {
+  readonly name = 'SourcererDisposedError';
   // message: 'Source disposed while waiting for ready()'
 }
 ```
 
-Thrown by `ready()` when `dispose()` is called on the source while a `ready()` call is still pending. Use `instanceof SourceDisposedError` to distinguish it from `SourceTimeoutError`:
+Thrown by `ready()` when `dispose()` is called on the source while a `ready()` call is still pending. Use `instanceof SourcererDisposedError` to distinguish it from `SourcererTimeoutError`:
 
 ```ts
-import { SourceDisposedError, SourceTimeoutError } from '@vielzeug/sourcerer';
+import { SourcererDisposedError, SourcererTimeoutError } from '@vielzeug/sourcerer';
 
 try {
   await source.ready(5000);
 } catch (err) {
-  if (err instanceof SourceDisposedError) {
+  if (err instanceof SourcererDisposedError) {
     // source was torn down — skip cleanup
-  } else if (err instanceof SourceTimeoutError) {
+  } else if (err instanceof SourcererTimeoutError) {
     console.warn('timed out');
   }
 }
@@ -34830,13 +35631,23 @@ createLocalSource(data, {
   debounceMs: 300, // debounce delay for source.search() (default: 300)
   filter: (u) => u.active, // initial synchronous filter predicate
   sort: (a, b) => a.name.localeCompare(b.name), // initial sorter
-  searchFn: (items, query) => items.filter(/* custom match */), // override default search
+  searchFn: searchBy([(u) => u.name, (u) => u.email]), // override default search
   // Async variants — enable Web Worker offloading via @vielzeug/familiar:
   filterAsync: async (items, signal) => items.filter(/* expensive filter */),
   sortAsync: async (items, signal) => [...items].sort(/* expensive sort */),
 });
 ```
 
+For large in-memory datasets, prefer the `searchBy(...)` preset over the default `JSON.stringify` search:
+
+```ts
+import { createLocalSource, searchBy } from '@vielzeug/sourcerer';
+
+const source = createLocalSource(users, {
+  searchFn: searchBy([(u) => u.name, (u) => u.email]),
+});
+```
+
 `filterAsync` and `sortAsync` run after their synchronous counterparts. They set `meta.isLoading = true` during computation and accept an `AbortSignal` — a new call aborts any running async computation.
 
 ### Mutations
@@ -34853,13 +35664,13 @@ await source.reset(); // restore initial filter/sort, reset to page 1
 
 ### Restoring from URL state
 
-Use `applyQuery()` + `decodeQuery()` to restore URL-decoded state in a single atomic recompute.
+Use `decodeQuery()` + `source.patch()` to restore URL-decoded state in a single atomic recompute.
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 10 });
-await applyQuery(source, query);
+await source.patch(query);
 ```
 
 ## Remote Source
@@ -34907,6 +35718,7 @@ createRemoteSource({
 ```
 
 `staleTime` compares the **query key** — navigating to a different page always fetches even when the previous result is still within the stale window.
+When an `optimisticUpdate()` is active, `refresh()` always fetches even within `staleTime` so the optimistic state can settle deterministically.
 
 ### The `fetch` callback
 
@@ -34941,13 +35753,13 @@ await source.refresh(); // re-fetch current query
 
 ### Restoring from URL state
 
-`applyQuery()` is a no-op when `changes` is empty — safe to call on every page load.
+`source.patch()` is a no-op when `changes` is empty — safe to call on every page load.
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 25 });
-await applyQuery(source, query);
+await source.patch(query);
 ```
 
 ### Optimistic updates
@@ -35050,13 +35862,13 @@ await source.reset(); // clear all, restart from page 1
 
 ### Restoring from URL state
 
-Use `applyQuery()` + `decodeQuery()` to restore `limit` and `search`. `patch()` clears accumulated items and refetches from page 1 if any value changed.
+Use `decodeQuery()` + `source.patch()` to restore `limit` and `search`. `patch()` clears accumulated items and refetches from page 1 if any value changed.
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 20 });
-await applyQuery(source, { limit: query.limit, search: query.search });
+await source.patch({ limit: query.limit, search: query.search });
 ```
 
 ## Error Handling
@@ -35165,7 +35977,7 @@ const params = encodeQuery(source.query);
 
 // Restore from URLSearchParams directly
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 25 });
-await applyQuery(source, query);
+await source.patch(query);
 ```
 
 `decodeQuery` is fault-tolerant by default — malformed `filter`/`sort` JSON is silently dropped. Pass `{ strict: true }` to throw instead.
@@ -35326,11 +36138,12 @@ effect(() => {
 - Pass the `AbortSignal` from the `fetch` callback to your HTTP client so superseded requests are cancelled.
 - Call `ready()` in server-side rendering or test setup — not in every render cycle.
 - Always call the unsubscribe function returned by `subscribe()` when the component is torn down.
-- For URL sync, use `decodeQuery()` + `applyQuery()` rather than reconstructing source state from params manually.
+- For URL sync, use `decodeQuery()` + `source.patch()` rather than reconstructing source state from params manually.
 - Use `staleTime` with `refreshInterval` for stale-while-revalidate patterns on dashboards.
+- If you use `optimisticUpdate()`, call `refresh()` after mutation confirmation; it bypasses `staleTime` while optimistic state is active.
 - Only one `optimisticUpdate()` can be active at a time — always handle the thrown error or check before calling.
 - When using `decodeQuery()`, validate the parsed `filter` and `sort` with a type guard before passing to the server — they are returned as-is without runtime validation.
-- For infinite sources, pass `{ limit: query.limit, search: query.search }` to `applyQuery()` for URL state sync — `page` is not restorable since items accumulate across pages.
+- For infinite sources, pass `{ limit: query.limit, search: query.search }` to `source.patch()` for URL state sync — `page` isn't part of `InfiniteSource`'s `patch()` type at all, since items accumulate across pages rather than jumping to one.
 
 ### Examples
 
@@ -35357,7 +36170,7 @@ effect(() => {
 - LocalSource patch() with filter/sort (id: `local-source-patch`)
 - Presets (filterContains, filterEquals, filterRange, sortBy) (id: `presets`)
 - Remote Source (id: `remote-source`)
-- sourceState & SourceTimeoutError (id: `source-state`)
+- sourceState & SourcererTimeoutError (id: `source-state`)
 
 
 ---
@@ -35366,7 +36179,7 @@ effect(() => {
 
 **Category:** validation
 **Keywords:** schema, validation, parsing, json-schema, locale, typescript, descriptors
-**Key exports:** s, Schema, PipeSchema, SpellValidationError, ErrorCode, errorsAt, fail, descriptorToJsonSchema, schemaToJsonSchema, setMessages, setLogger, resetMessages (+1 more)
+**Key exports:** s, Schema, PipeSchema, SpellValidationError, ErrorCode, errorsAt, fail, descriptorToJsonSchema, schemaToJsonSchema, createParseContext, setMessages, setLogger (+4 more)
 **Related:** forge, courier, vault
 
 ### Overview
@@ -35501,7 +36314,9 @@ const user = User.parse(payload);
 | `Schema.parseAsync()` / `safeParseAsync()`          | Validate including async `validate()` callbacks                               | Async               | Required when any nested rule uses an async `validate()` callback.  |
 | `descriptorToJsonSchema()`                          | Convert a `SchemaDescriptor` to JSON Schema                                   | Sync setup          | Uses `toDescriptor()` output, not custom transforms.                |
 | `schemaToJsonSchema()`                              | Convert a `Schema` instance directly to JSON Schema                           | Sync setup          | Calls `toDescriptor()` internally; same limitations apply.          |
-| `setMessages()` / `setLogger()` / `resetMessages()` | Override validation messages and warning logger                               | Sync setup          | `setMessages()` replaces the active message set each call.          |
+| `setMessages()` / `setLogger()` / `resetMessages()` | Override validation messages and warning logger globally                       | Sync setup          | `setMessages()` replaces the active message set each call.          |
+| `createParseContext()`                              | Create request-scoped message overrides for a parse call                       | Sync setup          | Overrides apply only to calls that receive the returned context.    |
+| `withMessages()` / `withLogger()`                   | Run a callback with temporary global message/logger overrides                  | Sync/async setup    | Restores previous global state after the callback settles.          |
 | `SpellValidationError`                                   | Inspect validation failures                                                   | Sync/async failures | `format()` returns nested objects, `flatten()` returns path arrays. |
 | `prependIssuePath()`                                | Prefix a path segment to an array of issues                                   | Sync                | Use inside custom parsers that delegate to inner schemas.           |
 
@@ -35518,7 +36333,7 @@ Use this table to scan every runtime export.
 | Category                  | Exports                                                                                                                                                                                                                                                                                                                          |
 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Classes                   | `Schema`, `PipeSchema`, `SpellError`, `SpellValidationError`                                                                                                                                                                                                                                                                                        |
-| Message and error helpers | `ErrorCode`, `errorsAt`, `fail`, `prependIssuePath`, `setMessages`, `setLogger`, `resetMessages`                                                                                                                                                                                                                                 |
+| Message and error helpers | `ErrorCode`, `errorsAt`, `fail`, `prependIssuePath`, `setMessages`, `setLogger`, `resetMessages`, `createParseContext`, `withMessages`, `withLogger`                                                                                                                                                                                                                                 |
 | Descriptor helpers        | `descriptorToJsonSchema`, `schemaToJsonSchema`                                                                                                                                                                                                                                                                                   |
 | Pure validators           | `hasMaxLength`, `hasMinLength`, `isArray`, `isBoolean`, `isDate`, `isInteger`, `isMultipleOf`, `isNegative`, `isNonNegative`, `isNullOrUndefined`, `isNumber`, `isPositive`, `isString`, `isInRange`                                                                                                                             |
 | String format validators  | `isBase64`, `isBase64url`, `isCuid`, `isCuid2`, `isDuration`, `isEmail`, `isEmoji`, `isHex`, `isHexColor`, `isIp`, `isIsoDate`, `isIsoDateTime`, `isJwt`, `isNanoid`, `isNumeric`, `isSemver`, `isSlug`, `isTime`, `isUlid`, `isUrl`, `isUuid`                                                                                   |
@@ -35616,7 +36431,7 @@ Builder reference:
 | `s.or(a, b)`            | `UnionSchema`              | Alias for `s.union()` with exactly two schemas.                                                                                                                                 |
 | `s.and(a, b)`           | `IntersectSchema`          | Alias for `s.intersect()` with two schemas.                                                                                                                                     |
 | `s.intersect(...items)` | `IntersectSchema`          | Merges compatible outputs deeply and safely.                                                                                                                                    |
-| `s.variant(key, map)`   | `VariantSchema`            | Discriminated object union. Async field validators on branch objects are silently skipped — use `s.object()` with `parseAsync()` directly if you need async branch-field rules. |
+| `s.variant(key, map)`   | `VariantSchema`            | Discriminated object union with async-aware branch parsing in `parseAsync()`.                                                                                                                          |
 | `s.lazy(getter)`        | `LazySchema`            | Recursive schema definitions.                                                                                                                                                   |
 | `s.instanceof(cls)`     | `InstanceOfSchema`      | Runtime class instance checks.                                                                                                                                                  |
 
@@ -36496,7 +37311,7 @@ const Signup = s.object({ confirm: s.string(), password: s.string() }).validate(
 });
 ```
 
-Async rules work in the same method. Spell awaits them only in `parseAsync()` — async callbacks passed to `validate()` are silently skipped in synchronous `parse()`.
+Async rules work in the same method. Spell awaits them in `parseAsync()`, including nested schemas (for example inside `s.variant(...)` branches). Async callbacks passed to `validate()` are still skipped in synchronous `parse()`.
 
 ```ts
 import { s } from '@vielzeug/spell';
@@ -36599,7 +37414,7 @@ Descriptors are serializable snapshots of the schema structure. Use `toDescripto
 
 ## Messages
 
-Use `setMessages()` to replace the active validation message catalog. Each call replaces the current overrides — it does not accumulate.
+Use `setMessages()` to replace the active validation message catalog globally. Each call replaces the current overrides — it does not accumulate.
 
 ```ts
 import { resetMessages, setMessages } from '@vielzeug/spell';
@@ -36627,6 +37442,35 @@ setLogger(null); // silence
 setLogger((msg) => myLogger.warn(msg)); // redirect
 ```
 
+Use `createParseContext()` when you need request-scoped message overrides without mutating global state.
+
+```ts
+import { createParseContext, s } from '@vielzeug/spell';
+
+const User = s.object({ email: s.string().email() });
+
+User.safeParse(
+  { email: 'ada@example.com', extra: true },
+  createParseContext({ object: { invalidKeys: () => 'No unknown keys in this endpoint' } }),
+);
+```
+
+Use `withMessages()` / `withLogger()` to apply temporary global overrides inside a bounded sync or async callback.
+
+```ts
+import { s, withLogger, withMessages } from '@vielzeug/spell';
+
+const Email = s.string().email();
+
+await withMessages({ string: { email: () => 'Scoped email' } }, async () => {
+  Email.safeParse('bad'); // issue message uses "Scoped email"
+});
+
+withLogger((msg) => myLogger.warn(msg), () => {
+  s.string().regex(/^a$/).regex(/^b$/);
+});
+```
+
 To integrate with `@vielzeug/lingua`, call `setMessages()` from your locale change callback:
 
 ```ts
@@ -40270,888 +41114,267 @@ const db = createIndexedDB({
 ## @vielzeug/ward
 
 **Category:** auth
-**Keywords:** rbac, permissions, roles, access-control, authorization, wildcards, predicates
-**Key exports:** createWard, allow, deny, ruleFor, predicate, owns, matchesPattern, patternCovers, guardRequest, guardRequestWith, WardPredicateError, WILDCARD (+20 more)
-**Related:** rune, wayfinder, conduit
 
 ### Overview
 
-## Why Ward?
-
-Spreading authorization checks across route handlers, service methods, and UI components leads to inconsistent enforcement, no central place to audit permissions, and rules that drift as the codebase grows.
-
-```ts
-// Before — ad-hoc checks scattered across handlers
-function deletePost(user: User, post: Post) {
-  if (user.role !== 'admin' && user.id !== post.authorId) {
-    throw new Error('Forbidden');
-  }
-  // no logging, no explain, no wildcard, no composition
-}
-
-// After — Ward declarative rules with typed enforcement
-import { allow, createWard, predicate } from '@vielzeug/ward';
-
-const ward = createWard([
-  ...allow('admin', '*', ['*']),
-  ...allow('author', 'post', ['delete', 'edit'], { when: predicate.owns('authorId') }),
-]);
-
-const guard = ward.forUser(currentUser);
-guard.explain('post', 'delete', post); // WardDecision — auditable
-guard.allowedActions('post', ['delete', 'edit'], post); // ['delete', 'edit'] or []
-```
-
-| Feature                           | Ward                                                   | CASL                                       | AccessControl                                                         |
-| --------------------------------- | ------------------------------------------------------ | ------------------------------------------ | --------------------------------------------------------------------- |
-| Bundle size                       |              | ~11 kB                                     | ~7 kB                                                                 |
-| Typed rule contracts              |              | Partial                                    | Partial                                                               |
-| Deterministic deny precedence     |              |  |                             |
-| Rule predicates with request data |              |  |  (manual patterns) |
-| Wildcard action support           |              |  |                             |
-| Principal-bound API               |  (`forUser`) | Partial                                    |                                 |
-| Explainable decisions             |              | Partial                                    |                                 |
-| Zero dependencies                 |              |      |                                 |
-
-**Use Ward when** you want predictable authorization decisions with typed rules and explicit introspection APIs.
-
-**Consider larger policy frameworks when** you need ecosystem-specific integrations or policy storage outside application code.
-
-## Installation
-
-```sh [pnpm]
-pnpm add @vielzeug/ward
-```
-
-```sh [npm]
-npm install @vielzeug/ward
-```
-
-```sh [yarn]
-yarn add @vielzeug/ward
-```
+`@vielzeug/ward` is a zero-dependency authorization engine for role/resource/action policies.
 
 ## Quick Start
 
 ```ts
-import { ANONYMOUS, WILDCARD, allow, createWard, deny, predicate } from '@vielzeug/ward';
+import { ANONYMOUS, WILDCARD, allow, createWard, deny, owns } from '@vielzeug/ward';
 
 const ward = createWard([
-  // Multi-role rule: viewer and editor can both read
-  ...allow(['viewer', 'editor'], 'posts', ['read']),
-  // Editor can update their own posts
-  ...allow('editor', 'posts', ['update'], { when: predicate.owns('authorId') }),
-  // High-priority deny overrides any allow rule for blocked principals
+  ...allow([ANONYMOUS, 'viewer'], 'posts', ['read']),
+  ...allow('editor', 'posts', ['update'], { when: owns('authorId') }),
   ...deny('blocked', WILDCARD, [WILDCARD], { priority: 100 }),
-  // Anonymous visitors can read posts
-  ...allow(ANONYMOUS, 'posts', ['read']),
-]);
-
-const editor = { id: 'u1', roles: ['editor'] };
-
-// Full decision — narrow on .allowed for type-safe access to .reason / .rule
-const decision = ward.explain(editor, 'posts', 'update', { authorId: 'u2' });
-if (!decision.allowed) console.log(decision.reason); // 'no-matching-rule' | 'explicit-deny'
-
-// Decision trace — all candidates with index, score, priority, won (no logger fired)
-const trace = ward.trace(editor, 'posts', 'read');
-trace.candidates.forEach((c) => console.log(`Rule[${c.index}]`, c.rule.effect, c.score, c.won));
-
-// Detect policy conflicts at startup
-const conflicts = ward.detectConflicts();
-if (conflicts.length > 0) console.warn('Policy conflicts:', conflicts);
-
-const bound = ward.forUser(editor);
-
-bound.allowedActions('posts', ['read', 'update', 'delete']);
-bound.explain('posts', 'update', { authorId: 'u2' });
-bound.checkAll([
-  { resource: 'posts', action: 'read' },
-  { resource: 'posts', action: 'update', data: { authorId: 'u1' } },
-]);
-bound.rulesInScope('posts');
-```
-
-## Features
-
-- One rule primitive: `WardRule` passed directly to `createWard(rules)`
-- **Rule factories**: `allow(role, resource, actions, opts?)` and `deny(...)` — readable, spreadable arrays
-- **Grouped predicate namespace**: `predicate.owns()`, `predicate.and()`, `predicate.or()`, `predicate.not()`
-- **Multi-role rules**: `role` accepts a string or an array of strings (OR semantics)
-- Decision methods: `ward.explain(principal, resource, action, data?)` — full `WardDecision` object
-- Batch decisions: `ward.checkAll(principal, checks)`
-- Full decision trace: `ward.trace(principal, resource, action, data?)` — all candidates with `index`, `score`, `priority`, `won`; **does not fire the logger**
-- Rule introspection: `ward.rulesInScope(principal, resource, data?)`
-- Action enumeration: `ward.allowedActions(principal, resource, knownActions, data?)`
-- Policy conflict detection: `ward.detectConflicts()` — lazy, cached, O(n²)
-- Explicit wildcard support with `WILDCARD`
-- Anonymous checks via `null` principal plus `ANONYMOUS` role rules
-- Ownership helper via `owns(attributeKey)` or `predicate.owns(attributeKey)`
-- Principal-bound API via `ward.forUser(principal)` — principal snapshotted at bind time
-- Framework-agnostic guards: `guardRequest`, `guardRequestWith`
-- **Debug logging** via `debugWard()` (`@vielzeug/ward/devtools`) — logs `explain` and `checkAll` decisions with `[ward:decision]` prefixes; tree-shaken from production bundles
-
-## Documentation
-
-- [Usage Guide](./usage.md)
-- [API Reference](./api.md)
-- [Examples](./examples.md)
-
-## See Also
-
-- [Wayfinder](../wayfinder/index.md) for route-level authorization middleware.
-- [Rune](../rune/index.md) for structured audit logs of permission checks.
-- [Herald](../herald/index.md) for event-driven permission workflows.
-
-### API Reference
-
-## API Overview
-
-| Symbol                                                                   | Purpose                                              | Execution | Common gotcha                                                                        |
-| ------------------------------------------------------------------------ | ---------------------------------------------------- | --------- | ------------------------------------------------------------------------------------ |
-| `createWard(rules, options?)`                                            | Create an immutable ward instance                    | Sync      | Rules cannot be mutated after creation                                               |
-| `allow(role, resource, actions, options?)`                               | Create allow rules — returns `WardRule[]`            | Sync      | Spread into `createWard([ ...allow(...) ])` — returns an array                       |
-| `deny(role, resource, actions, options?)`                                | Create deny rules — returns `WardRule[]`             | Sync      | Same spreading pattern as `allow`                                                    |
-| `ruleFor(effect, role, resource, actions, options?)`                     | Low-level rule factory (effect as first arg)         | Sync      | Prefer `allow`/`deny` for readability                                                |
-| `predicate.owns(attributeKey)`                                           | Ownership predicate — `data[key] === principal.id`   | Sync      | Returns `false` when `data` is absent, not an object, or key not an own property     |
-| `predicate.and(...preds)`                                                | Combine predicates with AND                          | Sync      | Zero arguments → always returns `true` (vacuously)                                   |
-| `predicate.or(...preds)`                                                 | Combine predicates with OR                           | Sync      | Zero arguments → always returns `false`                                              |
-| `predicate.not(pred)`                                                    | Invert a predicate                                   | Sync      | —                                                                                    |
-| `owns(attributeKey)`                                                     | Top-level alias for `predicate.owns`                 | Sync      | Prefer `predicate.owns` when using other `predicate.*` helpers                       |
-| `matchesPattern(pattern, value)`                                         | Test a pattern against a concrete string             | Sync      | Works for both resources and actions (namespace wildcards)                           |
-| `patternCovers(broad, narrow)`                                           | Test whether one pattern statically covers another   | Sync      | Used by `detectConflicts`; exported for custom tooling                               |
-| `ward.checkAll(principal, checks)`                                       | Evaluate multiple decisions in one call              | Sync      | Returns `WardDecisionResult[]` — each entry includes originating `resource`+`action` |
-| `ward.explain(principal, resource, action, data?)`                       | Full decision object with deny reason                | Sync      | `rule` only present on `'allow'` and `'explicit-deny'` variants; fires logger        |
-| `ward.trace(principal, resource, action, data?)`                         | Decision trace with all matching candidates          | Sync      | **Does not fire the logger** — use `explain` when logger output is needed            |
-| `ward.allowedActions(principal, resource, knownActions, data?)`          | List allowed actions; no logger                      | Sync      | Wildcard-action rules require a non-empty `knownActions`                             |
-| `ward.rulesInScope(principal, resource, data?)`                          | Rules in scope for introspection; no logger          | Sync      | Without `data`, predicate rules appear unfiltered                                    |
-| `ward.detectConflicts()`                                                 | Lazily detect and cache policy conflicts             | Sync      | O(n²); predicate-gated rules excluded from static analysis                           |
-| `ward.forUser(principal)`                                                | Create a principal-bound ward view                   | Sync      | Principal is deep-snapshotted at bind time                                           |
-| `guardRequest(ward, principal, resource, action, data?)`                 | Framework-agnostic sync guard — direct principal     | Sync      | Use `guardRequestWith` when the principal must be extracted from a request object    |
-| `guardRequestWith(ward, req, extractPrincipal, resource, action, data?)` | Framework-agnostic async guard — request + extractor | Async     | Extractor may be async (e.g. JWT verification)                                       |
-
-## Package Entry Points
-
-| Import                    | Purpose                                  |
-| ------------------------- | ---------------------------------------- |
-| `@vielzeug/ward`          | Main exports and types                   |
-| `@vielzeug/ward/devtools` | `debugWard` — decision logger (dev only) |
-
-## Constants
-
-- `WILDCARD = '*'`
-- `ANONYMOUS = 'anonymous'`
-
-`WILDCARD` can be used as role, resource, or action.
-
-## WardRule Fields
-
-| Field      | Type                          | Required                                   | Description                                                                                                                                                                                                 |
-| ---------- | ----------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `role`     | `string \| readonly string[]` |  | One role or an array of roles. A rule matches if the principal holds **any** of the listed roles (OR semantics). Use `WILDCARD` for all authenticated principals, `ANONYMOUS` for unauthenticated requests. |
-| `resource` | `string`                      |  | Resource identifier. Use `WILDCARD` to match any resource.                                                                                                                                                  |
-| `action`   | `string`                      |  | Action identifier. Use `WILDCARD` to match any action.                                                                                                                                                      |
-| `effect`   | `'allow' \| 'deny'`           |  | Whether the rule grants or denies access.                                                                                                                                                                   |
-| `priority` | `number`                      | —                                          | Higher value wins. Optional when authoring a rule (defaults to `0`); always present on rules returned from decisions/trace/conflicts. Must be a finite number.                                              |
-| `when`     | `WardPredicate`        | —                                          | Runtime predicate evaluated only for authenticated principals.                                                                                                                                              |
-
-### Multi-Role Rules
-
-When `role` is an array, the rule matches if the principal holds **any** of the listed roles. This lets you consolidate rules that share identical permissions across several roles:
-
-```ts
-// Instead of three separate allow rules, write one:
-const ward = createWard([
-  { role: ['viewer', 'editor', 'admin'], resource: 'posts', action: 'read', effect: 'allow' },
-  { role: ['editor', 'admin'], resource: 'posts', action: 'update', effect: 'allow' },
-  { role: 'admin', resource: 'posts', action: 'delete', effect: 'allow' },
 ]);
-```
-
-`ANONYMOUS` works inside multi-role arrays too:
-
-```ts
-// Allows both unauthenticated visitors and authenticated viewers to read
-{ role: [ANONYMOUS, 'viewer'], resource: 'posts', action: 'read', effect: 'allow' }
-```
-
-For specificity scoring, a multi-role rule is treated as specific (score 1) unless the array contains `WILDCARD`.
-
-## Core Functions
-
-### `createWard()`
-
-```ts
-createWard(
-  rules?: readonly WardRule[],
-  options?: WardOptions,
-): Ward
-```
 
-Creates an immutable ward instance with the given rules. All rules are compiled once at creation time — pass a new array to update the policy.
-
-**Parameters — `WardOptions`:**
-
-| Option         | Type                                   | Default     | Description                                                                                                              |
-| -------------- | -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `logger`       | `(context: WardLoggerContext) => void` | `undefined` | Called after every decision method (`explain`, `checkAll`, `trace`). Not called by `allowedActions` or `rulesInScope`. |
-| `onConflict`   | `(conflict: WardConflict) => void`     | `undefined` | Called synchronously for each conflict detected at creation time.                                                        |
-| `strict`       | `boolean`                              | `false`     | Throws immediately if any rule conflicts are detected.                                                                   |
-| `maxConflicts` | `number`                               | `Infinity`  | Caps the number of conflicts returned by `detectConflicts()`. Set to `0` to disable conflict detection entirely.         |
-
-**Winner selection** when multiple rules match:
-
-1. Higher `priority` wins.
-2. On priority tie, higher specificity wins (`exact > ns:* > *`, applied independently to role, resource, and action).
-3. On specificity tie, `deny` beats `allow`.
-4. On absolute tie (identical priority, specificity, and effect), the rule declared **first in the array** wins.
-
-**Returns:** `Ward`
-
-**Example:**
-
-```ts
-import { createWard, owns } from '@vielzeug/ward';
-
-const ward = createWard([
-  { role: 'viewer', resource: 'posts', action: 'read', effect: 'allow' },
-  { role: 'editor', resource: 'posts', action: 'update', effect: 'allow', when: owns('authorId') },
-]);
-```
-
-## Ward Methods
-
-### `checkAll()`
-
-```ts
-ward.checkAll(
-  principal: Principal,
-  checks: readonly WardCheck[],
-): WardDecisionResult[]
-```
-
-Evaluates each check independently and returns one `WardDecisionResult` per entry in the same order. Each result includes the originating `resource` and `action` fields, so callers do not need to zip the input array by index. Returns `[]` for an empty array without validating the principal.
-
-**Returns:** `WardDecisionResult[]`
-
-**Example:**
-
-```ts
-const decisions = ward.checkAll({ id: 'u1', roles: ['editor'] }, [
-  { resource: 'posts', action: 'read' },
-  { resource: 'posts', action: 'update', data: { authorId: 'u1' } },
-]);
-```
-
----
-
-### `allowedActions()`
-
-```ts
-ward.allowedActions(
-  principal: Principal,
-  resource: string,
-  knownActions: readonly TAction[],
-  data?: TData,
-): TAction[]
-```
-
-Returns the subset of `knownActions` that the principal is currently allowed to perform on `resource`. Evaluates wildcard-action rules against each entry in `knownActions`. Deduplicates the input list.
-
-`allowedActions` does **not** invoke the logger. Use `checkAll` if you need an auditable batch decision.
-
-**Returns:** `TAction[]`
-
-**Example:**
-
-```ts
-// Resolves wildcard-action rules against the provided list
-const actions = ward.allowedActions({ id: 'u1', roles: ['editor'] }, 'posts', ['read', 'update', 'delete']);
+const principal = { id: 'u1', roles: ['editor'] };
 
-// With runtime data for predicate-gated rules
-const owned = ward.allowedActions({ id: 'u1', roles: ['editor'] }, 'posts', ['read', 'update', 'delete'], {
-  authorId: 'u1',
+const decision = ward.explain({
+  principal,
+  resource: 'posts',
+  action: 'update',
+  data: { authorId: 'u2' },
 });
 ```
 
----
-
-### `explain()`
-
-```ts
-ward.explain(
-  principal: Principal,
-  resource: string,
-  action: TAction,
-  data?: TData,
-): WardDecision
-```
-
-Returns a full decision object including the winning rule (for allow and explicit deny). The returned `rule` object is **frozen** — mutations throw `TypeError`. Uses `'rule' in decision` to safely narrow across all three variants.
+`explain()` returns a discriminated decision (`allowed: true | false`) and optional matching `rule`.
 
-**Returns:** `WardDecision`
+## Bound View
 
-**Example:**
+Use `forUser()` when checking many permissions for the same principal:
 
 ```ts
-const decision = ward.explain({ id: 'u1', roles: ['editor'] }, 'posts', 'delete');
+const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
 
-if (!decision.allowed) {
-  console.log(decision.reason); // 'no-matching-rule' | 'explicit-deny'
-  if (decision.reason === 'explicit-deny') {
-    console.log(decision.rule.effect); // safe — rule is present
-  }
-}
+bound.explain({ resource: 'posts', action: 'read' });
+bound.allowedActions({ resource: 'posts', knownActions: ['read', 'update', 'delete'] as const });
 ```
 
----
-
-### `trace()`
+## Middleware Guards
 
 ```ts
-ward.trace(
-  principal: Principal,
-  resource: string,
-  action: TAction,
-  data?: TData,
-): WardTrace
-```
-
-Returns the complete decision trace: every rule that matched before the winner was selected, plus the final `WardDecision`. Each candidate exposes `priority`, `score`, `rule`, and a `won` flag.
-
-`trace()` fires the logger with the same context as `explain()`. Switching from `explain` to `trace` for richer diagnostics does not silently drop audit records.
-
-**Returns:** `WardTrace`
-
-**Example:**
-
-```ts
-const { decision, candidates } = ward.trace({ id: 'u1', roles: ['editor'] }, 'posts', 'read');
+import { guardRequest, guardRequestWith } from '@vielzeug/ward';
 
-candidates.forEach(({ rule, priority, score, won }) => {
-  console.log(rule.effect, priority, score, won ? '← winner' : '');
+const direct = guardRequest({
+  ward,
+  principal,
+  resource: 'posts',
+  action: 'read',
 });
-```
-
----
-
-### `rulesInScope()`
 
-```ts
-ward.rulesInScope(
-  principal: Principal,
-  resource: string,
-  data?: TData,
-): ReadonlyArray>>
-```
-
-Returns all rules matching the principal/resource combination regardless of action. When `data` is provided, predicate rules are also evaluated and excluded if they do not match. Without `data`, predicate-gated rules appear unfiltered. Does not invoke the logger.
-
-**Returns:** `ReadonlyArray>>`
-
-**Example:**
-
-```ts
-const rules = ward.rulesInScope({ id: 'u1', roles: ['editor'] }, 'posts');
-const narrowed = ward.rulesInScope({ id: 'u1', roles: ['editor'] }, 'posts', { authorId: 'u1' });
-```
-
----
-
-### `detectConflicts()`
-
-```ts
-ward.detectConflicts(): WardConflict[]
-```
-
-Returns all rule conflicts in the policy. Lazily computed and cached — every call after the first returns the same array reference. O(n²) in the number of rules.
-
-Two conflict kinds, narrowable by `kind`:
-
-- **`'duplicate'`** — two predicate-free rules share the same (role set, resource, action). Fields: `ruleA`/`indexA` (first-declared, wins) and `ruleB`/`indexB` (unreachable).
-- **`'shadowed'`** — a higher-ranked predicate-free rule covers the narrower rule's patterns entirely. Fields: `shadowingRule`/`shadowingIndex` (always wins) and `shadowedRule`/`shadowedIndex` (can never win).
-
-Rules with a `when` predicate are excluded from both checks — their applicability can only be determined at runtime.
-
-**Returns:** `WardConflict[]`
-
-**Example:**
-
-```ts
-const conflicts = ward.detectConflicts();
-
-conflicts.forEach((c) => {
-  if (c.kind === 'duplicate') {
-    console.warn(`Rule[${c.indexB}] is an unreachable duplicate of Rule[${c.indexA}]`);
-  } else {
-    console.warn(`Rule[${c.shadowedIndex}] is shadowed by Rule[${c.shadowingIndex}]`);
-  }
+const extracted = await guardRequestWith({
+  ward,
+  req,
+  extractPrincipal: async (request) => request.user ?? null,
+  resource: 'posts',
+  action: 'read',
 });
 ```
 
----
-
-### `forUser()`
-
-```ts
-ward.forUser(principal: UserPrincipal): BoundWard
-```
-
-Creates a principal-bound view of the ward. The principal — including nested `attributes` — is deep-snapshotted at call time; subsequent mutations to the original object have no effect on the bound view.
-
-**Returns:** `BoundWard`
-
-**Methods on `BoundWard`:**
-
-| Method           | Signature                                      | Description                    |
-| ---------------- | ---------------------------------------------- | ------------------------------ |
-| `checkAll`       | `(checks) => WardDecisionResult[]`             | Batch decisions                |
-| `allowedActions` | `(resource, knownActions, data?) => TAction[]` | Action enumeration (no logger) |
-| `explain`        | `(resource, action, data?) => WardDecision`    | Full decision with reason      |
-| `rulesInScope`   | `(resource, data?) => ReadonlyArray>` | Rule introspection (no logger) |
-| `trace`          | `(resource, action, data?) => WardTrace`       | Decision trace (does not fire the logger) |
-
-**Example:**
-
-```ts
-const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
+See the [usage guide](./usage.md), [API reference](./api.md), and [examples](./examples/blog-roles.md).
 
-bound.explain('posts', 'read').allowed;
-bound.checkAll([
-  { resource: 'posts', action: 'read' },
-  { resource: 'posts', action: 'update', data: { authorId: 'u1' } },
-]);
-bound.allowedActions('posts', ['read', 'update', 'delete']);
-bound.allowedActions('posts', ['read', 'update', 'delete'], { authorId: 'u1' });
-bound.explain('posts', 'delete');
-bound.trace('posts', 'read');
-bound.rulesInScope('posts');
-```
+### API Reference
 
-## Helper Functions
+## Core Factory
 
-### `allow()` / `deny()`
+### `createWard(rules, options?)`
 
 ```ts
-allow(
-  role: string | readonly string[],
-  resource: string | typeof WILDCARD,
-  actions: readonly (TAction | typeof WILDCARD)[],
-  options?: { priority?: number; when?: WardPredicate },
-): WardRule[]
-
-deny(
-  role: string | readonly string[],
-  resource: string | typeof WILDCARD,
-  actions: readonly (TAction | typeof WILDCARD)[],
-  options?: { priority?: number; when?: WardPredicate },
-): WardRule[]
+createWard(
+  rules: ReadonlyArray>>,
+  options?: WardOptions,
+): Ward;
 ```
 
-Ergonomic rule factories — one `WardRule` per action, with `effect` fixed to `'allow'` or `'deny'`. Spread the result into the array passed to `createWard`.
+Creates an immutable ward instance.
 
-**Returns:** `WardRule[]`
+## Rule Builders
 
-**Example:**
+### `allow(role, resource, actions, options?)`
+### `deny(role, resource, actions, options?)`
+### `ruleFor(effect, role, resource, actions, options?)`
 
-```ts
-import { WILDCARD, allow, createWard, deny, owns } from '@vielzeug/ward';
-
-const ward = createWard([
-  ...allow(['viewer', 'editor'], 'posts', ['read']),
-  ...allow('editor', 'posts', ['update'], { when: owns('authorId'), priority: 5 }),
-  ...deny('blocked', WILDCARD, [WILDCARD], { priority: 100 }),
-]);
-```
+All three return `WardRule[]` (one rule per action).
 
----
+## Ward Methods
 
-### `ruleFor()`
+### `checkAll(principal, checks)`
 
 ```ts
-ruleFor(
-  effect: 'allow' | 'deny',
-  role: string | readonly string[],
-  resource: string | typeof WILDCARD,
-  actions: readonly (TAction | typeof WILDCARD)[],
-  options?: { priority?: number; when?: WardPredicate },
-): WardRule[]
+checkAll(
+  principal: UserPrincipal,
+  checks: ReadonlyArray>,
+): WardDecisionResult[];
 ```
 
-Low-level rule factory with `effect` as the first argument. `allow()` and `deny()` are thin wrappers over `ruleFor()` — prefer them for readability; use `ruleFor()` when the effect is only known dynamically.
-
-**Returns:** `WardRule[]`
-
-**Example:**
+### `explain(input)`
 
 ```ts
-import { ruleFor } from '@vielzeug/ward';
-
-ruleFor('allow', 'viewer', 'posts', ['read', 'update']);
-ruleFor('deny', ['blocked', 'suspended'], WILDCARD, [WILDCARD], { priority: 100 });
+explain(input: WardExplainInput): WardDecision;
 ```
 
----
-
-### `owns()` / `predicate`
+`WardExplainInput`:
 
 ```ts
-owns(attributeKey: keyof TData & string): WardPredicate
-
-const predicate: {
-  and(...preds: WardPredicate[]): WardPredicate;
-  not(pred: WardPredicate): WardPredicate;
-  or(...preds: WardPredicate[]): WardPredicate;
-  owns(attributeKey: keyof TData & string): WardPredicate;
-};
+{
+  principal: UserPrincipal;
+  resource: string;
+  action: TAction;
+  data?: TData;
+}
 ```
 
-`owns()` returns a predicate that allows the action when `principal.id === data[attributeKey]`. Returns `false` when `data` is absent, not an object, or the attribute is not an own property (guards against prototype-inherited values). `predicate.owns` is the same function, grouped under the `predicate` namespace alongside the combinators:
-
-- `predicate.and(...preds)` — all predicates must return `true`. Zero arguments → `true` (vacuously).
-- `predicate.or(...preds)` — at least one predicate must return `true`. Zero arguments → `false`.
-- `predicate.not(pred)` — inverts a predicate.
-
-`owns()` (and any `when` predicate) must only be used with rules that require authentication (non-`ANONYMOUS` role). Predicates are skipped for unauthenticated requests — pairing `owns` with `ANONYMOUS` produces a rule that can never match.
-
-**Example:**
+### `trace(input)`
 
 ```ts
-import { allow, predicate } from '@vielzeug/ward';
-
-allow('editor', 'posts:*', ['update'], { when: predicate.owns('authorId') });
-allow('user', 'posts:*', ['read'], { when: predicate.and(predicate.owns('authorId'), isBusinessHours) });
+trace(input: WardTraceInput): WardTrace;
 ```
 
----
+Same request shape as `explain()`. Returns winner + candidate list. Does not fire logger.
 
-### `matchesPattern()`
+### `allowedActions(input)`
 
 ```ts
-matchesPattern(pattern: string, value: string): boolean
+allowedActions(
+  input: WardAllowedActionsInput,
+): TKnown[];
 ```
 
-Tests whether a pattern matches a concrete value string. Works for both resource patterns and action patterns.
-
-**Pattern semantics:**
-
-| Pattern     | Matches                                                              |
-| ----------- | -------------------------------------------------------------------- |
-| `*`         | Any value                                                            |
-| `posts`     | Exactly `posts`                                                      |
-| `posts:*`   | Any value starting with `posts:` (e.g. `posts:123`, `posts:draft:1`) |
-| `posts:123` | Exactly `posts:123`                                                  |
-| `read:*`    | Any action starting with `read:` (e.g. `read:own`, `read:all`)       |
-
-**Example:**
+Input shape:
 
 ```ts
-import { matchesPattern } from '@vielzeug/ward';
-
-matchesPattern('posts:*', 'posts:123'); // true
-matchesPattern('posts:*', 'comments:1'); // false
-matchesPattern('read:*', 'read:own'); // true
+{
+  principal: UserPrincipal;
+  resource: string;
+  knownActions: readonly TKnown[];
+  data?: TData;
+}
 ```
 
----
-
-### `patternCovers()`
+### `rulesInScope(input)`
 
 ```ts
-patternCovers(broad: string, narrow: string): boolean
+rulesInScope(input: WardRulesInScopeInput): ReadonlyArray>>;
 ```
 
-Returns `true` if every concrete value matching `narrow` also matches `broad`. This is the static coverage relation used by `detectConflicts`. Exported for custom policy analysis tooling.
-
-**Example:**
+Input shape:
 
 ```ts
-import { patternCovers } from '@vielzeug/ward';
-
-patternCovers('*', 'posts:*'); // true
-patternCovers('posts:*', 'posts:123'); // true
-patternCovers('posts:*', '*'); // false
-patternCovers('posts', 'posts:*'); // false
+{
+  principal: UserPrincipal;
+  resource: string;
+  data?: TData;
+}
 ```
 
----
-
-### Middleware Factories
-
-#### `guardRequest()`
+### `detectConflicts()`
 
 ```ts
-guardRequest(
-  ward: Ward,
-  principal: Principal,
-  resource: string,
-  action: TAction,
-  data?: TData,
-): GuardResult
+detectConflicts(): WardConflict[];
 ```
 
-Framework-agnostic synchronous guard for a known principal. Returns a `GuardResult`:
+### `forUser(principal)`
 
 ```ts
-type GuardResult =
-  | { granted: true; principal: Principal }
-  | { granted: false; decision: WardDecision; principal: Principal; reason: 'explicit-deny' | 'no-matching-rule' };
+forUser(principal: UserPrincipal): BoundWard;
 ```
 
-Use `guardRequestWith` when the principal must be resolved asynchronously from a request object.
+Returns a principal-bound view.
 
-**Example:**
+## `BoundWard` Methods
 
 ```ts
-import { guardRequest } from '@vielzeug/ward';
-
-const result = guardRequest(ward, principal, 'posts', 'update');
-
-if (!result.granted) {
-  return response.status(403).json({ reason: result.reason });
+interface BoundWard {
+  checkAll(checks: ReadonlyArray>): WardDecisionResult[];
+  explain(input: BoundWardExplainInput): WardDecision;
+  trace(input: BoundWardTraceInput): WardTrace;
+  allowedActions(input: BoundWardAllowedActionsInput): TKnown[];
+  rulesInScope(input: BoundWardRulesInScopeInput): ReadonlyArray>>;
 }
 ```
 
----
-
-#### `guardRequestWith()`
+Bound input shapes remove `principal`:
 
 ```ts
-guardRequestWith(
-  ward: Ward,
-  req: TReq,
-  extractPrincipal: (req: TReq) => Principal | Promise,
-  resource: string,
-  action: TAction,
-  data?: TData,
-): Promise>
+{ resource: string; action: TAction; data?: TData }           // explain/trace
+{ resource: string; knownActions: readonly TKnown[]; data?: TData } // allowedActions
+{ resource: string; data?: TData }                            // rulesInScope
 ```
 
-Framework-agnostic async guard that first extracts the principal from a request object. The extractor may be async (e.g. to verify a JWT). Use `guardRequest` when the principal is already resolved.
-
-**Example:**
-
-```ts
-import { guardRequestWith } from '@vielzeug/ward';
+## Predicate Helpers
 
-const result = await guardRequestWith(ward, req, (req) => req.user ?? null, 'posts', 'update');
+### `predicate.owns(attributeKey)`
+### `predicate.and(...predicates)`
+### `predicate.or(...predicates)`
+### `predicate.not(predicate)`
+### `owns(attributeKey)` (alias)
 
-if (!result.granted) {
-  return response.status(403).json({ reason: result.reason });
-}
-```
+Predicates run synchronously. Returning a Promise throws `WardPredicateError`.
 
-## Types
+## Pattern Helpers
 
-### `UserPrincipal`
+### `matchesPattern(pattern, value): boolean`
+### `patternCovers(broad, narrow): boolean`
 
-```ts
-type UserPrincipal = {
-  id: string;
-  roles: readonly string[];
-  attributes?: Record;
-};
-```
+## Middleware Guards
 
-### `Principal`
+### `guardRequest(input)`
 
 ```ts
-type Principal = UserPrincipal | null;
+guardRequest(
+  input: GuardRequestInput,
+): GuardResult;
 ```
 
-`null` represents an unauthenticated (anonymous) user.
-
-### `RuleContext`
+Input:
 
 ```ts
-type RuleContext = {
+{
+  ward: Ward;
   principal: UserPrincipal;
+  resource: string;
+  action: TAction;
   data?: TData;
-};
-```
-
-### `WardPredicate`
-
-```ts
-type WardPredicate = (ctx: RuleContext) => boolean;
-```
-
-### `WardRule`
-
-The single rule shape — used both when authoring rules passed to `createWard` and when reading rules back from decisions, `trace()`, `rulesInScope()`, and `detectConflicts()`.
-
-```ts
-type WardRule = {
-  action: TAction | typeof WILDCARD;
-  effect: 'allow' | 'deny';
-  priority?: number; // defaults to 0
-  resource: string | typeof WILDCARD;
-  role: string | readonly string[];
-  when?: WardPredicate;
-};
-```
-
-Internally, `createWard` normalizes each rule at compile time — `role` becomes a deduplicated `readonly string[]` and `priority` defaults to `0` — and freezes the result. Rules read back from `explain()`, `trace()`, `rulesInScope()`, or `detectConflicts()` are these normalized, frozen objects (`Readonly>`); mutating them throws `TypeError`.
-
-### `WardDecision`
-
-Three distinct variants — use discriminated narrowing:
-
-```ts
-type WardDecision =
-  | { allowed: true; rule: WardRule }
-  | { allowed: false; reason: 'explicit-deny'; rule: WardRule }
-  | { allowed: false; reason: 'no-matching-rule' }; // no rule field
-```
-
-```ts
-const d = ward.explain(principal, 'posts', 'delete');
-
-if (d.allowed) {
-  console.log(d.rule.effect); // 'allow'
-} else if (d.reason === 'explicit-deny') {
-  console.log(d.rule.effect); // 'deny'
-} else {
-  // d.reason === 'no-matching-rule' — no rule field present
 }
-
-// Generic narrowing:
-if ('rule' in d) console.log(d.rule);
 ```
 
-### `WardCheck`
+### `guardRequestWith(input)`
 
 ```ts
-type WardCheck = {
-  resource: string;
-  action: TAction;
-  data?: TData;
-};
+guardRequestWith(
+  input: GuardRequestWithInput,
+): Promise>;
 ```
 
-### `WardLoggerContext`
-
-Structurally identical to `WardDecision` plus the request fields — narrow `rule` with the same `if (ctx.allowed)` pattern used for decisions:
+Input:
 
 ```ts
-type WardLoggerContext = WardDecision & {
+{
+  ward: Ward;
+  req: TReq;
+  extractPrincipal: PrincipalExtractor;
+  resource: string;
   action: TAction;
   data?: TData;
-  principal: Principal;
-  resource: string;
-};
-```
-
-```ts
-logger: (ctx) => {
-  if (ctx.allowed) {
-    console.log(ctx.rule.role); // no ?. needed — 'allowed: true' always carries a rule
-  } else if (ctx.reason === 'explicit-deny') {
-    console.log(ctx.rule.role); // 'explicit-deny' also carries a rule
-  }
-},
-```
-
-### `WardOptions`
-
-```ts
-type WardOptions = {
-  logger?: (context: WardLoggerContext) => void;
-  onConflict?: (conflict: WardConflict) => void;
-  strict?: boolean;
-  maxConflicts?: number;
-};
-```
-
-### `ConflictKind` / `WardConflict`
-
-`WardConflict` is a discriminated union, narrowable by `kind`:
-
-```ts
-type ConflictKind = 'duplicate' | 'shadowed';
-
-type WardConflict =
-  | {
-      kind: 'duplicate';
-      indexA: number; // first-declared rule (always wins)
-      indexB: number; // second-declared rule (unreachable)
-      ruleA: Readonly>;
-      ruleB: Readonly>;
-    }
-  | {
-      kind: 'shadowed';
-      shadowedIndex: number; // the rule that can never win
-      shadowedRule: Readonly>;
-      shadowingIndex: number; // the rule that always wins instead
-      shadowingRule: Readonly>;
-    };
+}
 ```
 
-### `WardTrace` / `WardTraceCandidate`
-
-```ts
-type WardTraceCandidate = {
-  index: number; // original index in the input array passed to createWard
-  priority: number;
-  rule: Readonly>;
-  score: number;
-  won: boolean;
-};
+## Devtools
 
-type WardTrace = {
-  candidates: WardTraceCandidate[];
-  decision: WardDecision;
-};
-```
+### `debugWard(ward, logger?)`
 
-## `debugWard(rules, options?)` 
+Sub-path import: `@vielzeug/ward/devtools`.
 
 ```ts
 import { debugWard } from '@vielzeug/ward/devtools';
-
-const permit = debugWard(rules);
-
-permit.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'read');
-// [ward:decision] allow             (allow)   viewer  posts  read
-
-permit.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'delete');
-// [ward:decision] no-matching-rule            viewer  posts  delete
-```
-
-Wraps `createWard()` with a `logger` pre-wired to `console.debug`. Returns the same `Ward` instance — all methods are identical to `createWard()`. Debug output fires on `explain()` and `checkAll()`; `trace()` never fires the logger (by design — see `trace()` above).
-
-Import from the dedicated sub-path so the `console.debug` reference is tree-shaken from production bundles when not imported.
-
-Accepts the same `options` as `createWard()` except `logger`, which is reserved for the debug output. All other options (`maxConflicts`, `onConflict`, `strict`) pass through unchanged.
-
-### `WardDecisionResult`
-
-```ts
-type WardDecisionResult = WardDecision & {
-  action: TAction;
-  resource: string;
-};
-```
-
-The return type of `checkAll()` — a `WardDecision` with the originating `resource` and `action` attached, so callers do not need to zip the result by index.
-
-### `WardRequest`
-
-```ts
-type WardRequest = Record;
 ```
 
-Base constraint for the request object type used in `guardRequestWith`. Any object type satisfies this constraint.
-
-### `Ward` / `BoundWard`
-
-`Ward` is returned by `createWard()`. `BoundWard` is returned by `ward.forUser()` and omits `forUser` and `detectConflicts`. Full method signatures are documented in the sections above.
-
 ### Usage Guide
 
-## Basic Usage
-
-Create a ward instance with an array of rules. Rules are compiled once at creation time.
+## Create a Ward
 
 ```ts
 import { WILDCARD, createWard } from '@vielzeug/ward';
@@ -41159,592 +41382,124 @@ import { WILDCARD, createWard } from '@vielzeug/ward';
 const ward = createWard([
   { role: 'viewer', resource: 'posts', action: 'read', effect: 'allow' },
   { role: 'editor', resource: 'posts', action: 'update', effect: 'allow' },
-  // High-priority deny blocks the blocked role from every action on posts
   { role: 'blocked', resource: 'posts', action: WILDCARD, effect: 'deny', priority: 100 },
 ]);
-
-ward.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'read').allowed; // true
-ward.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'update').allowed; // false
-ward.explain({ id: 'u2', roles: ['blocked'] }, 'posts', 'read').allowed; // false
-```
-
-To update the policy, create a new instance — rules are immutable after creation.
-
-## Rule Factories
-
-Use `allow()` / `deny()` as an alternative to raw rule objects. Each produces one `WardRule` per action — spread the result into the array passed to `createWard`. They read naturally: "allow editor to read/update posts".
-
-```ts
-import { allow, createWard, owns } from '@vielzeug/ward';
-
-const ward = createWard([
-  ...allow(['viewer', 'editor'], 'posts', ['read']),
-  ...allow('editor', 'posts', ['update', 'delete'], { when: owns('authorId') }),
-]);
-```
-
-Pass `{ priority: n }` and/or `{ when: predicate }` as the fourth argument. `deny()` is the same shape with `effect: 'deny'` fixed:
-
-```ts
-import { WILDCARD, deny } from '@vielzeug/ward';
-
-deny('blocked', 'posts', [WILDCARD], { priority: 100 });
-```
-
-`ruleFor(effect, role, resource, actions, options?)` is the low-level factory that `allow()`/`deny()` wrap — use it when the effect is only known dynamically.
-
-## Hierarchical Resources
-
-Use colon-namespaced patterns to scope rules to resource instances:
-
-```ts
-const ward = createWard([
-  // Applies to any resource under 'posts:' namespace
-  { role: 'editor', resource: 'posts:*', action: 'update', effect: 'allow' },
-  // Applies only to one specific post
-  { role: 'viewer', resource: 'posts:123', action: 'read', effect: 'allow' },
-]);
-
-ward.explain(editor, 'posts:456', 'update').allowed; // true  — matches posts:*
-ward.explain(viewer, 'posts:123', 'read').allowed; // true  — exact match
-ward.explain(viewer, 'posts:456', 'read').allowed; // false — no matching rule
-```
-
-The same namespace-wildcard syntax works for actions (action hierarchy):
-
-```ts
-// 'read:*' matches 'read:own', 'read:all', 'read:draft:1', etc.
-const ward = createWard([{ role: 'viewer', resource: 'posts', action: 'read:*', effect: 'allow' }]);
-
-ward.explain(viewer, 'posts', 'read:own').allowed; // true
-ward.explain(viewer, 'posts', 'read:all').allowed; // true
-ward.explain(viewer, 'posts', 'write').allowed; // false
 ```
 
-`matchesPattern(pattern, value)` is exported for custom integration code. `patternCovers(broad, narrow)` is exported to test whether one pattern statically covers another (used by `detectConflicts`).
+Rules are immutable after creation. Create a new ward to update policy.
 
-## Check Permissions
+## Explain a Decision
 
 ```ts
-const principal = { id: 'u1', roles: ['editor'] };
-
-ward.explain(principal, 'posts', 'read').allowed;
-ward.explain(principal, 'posts', 'delete').allowed;
-ward.explain(null, 'posts', 'read').allowed;
-```
-
-`principal` must be either:
-
-- `null` for anonymous users
-- `{ id: string, roles: readonly string[] }` for authenticated users
-
-Malformed principal values throw errors.
-
-## Bind a User with `forUser`
-
-`BoundWard` does not expose `detectConflicts()`. Run `ward.detectConflicts()` on the parent ward before calling `forUser()` — typically at startup or during policy initialization.
-
-```ts
-const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
-
-bound.explain('posts', 'read').allowed;
-bound.explain('posts', 'update', { authorId: 'u1' }).allowed;
-```
-
-`forUser()` returns a reusable bound ward object and snapshots roles/attributes at binding time.
-
-## Check Multiple Actions
-
-Ward has no dedicated "all"/"any" helper — use `checkAll()` and reduce with `Array.every` / `Array.some`:
-
-```ts
-const checks = [
-  { action: 'read', resource: 'posts' },
-  { action: 'update', resource: 'posts', data: { authorId: 'u1' } },
-] as const;
-
-const decisions = ward.checkAll({ id: 'u1', roles: ['editor'] }, checks);
+const decision = ward.explain({
+  principal: { id: 'u1', roles: ['editor'] },
+  resource: 'posts',
+  action: 'update',
+  data: { authorId: 'u1' },
+});
 
-const allAllowed = decisions.every((d) => d.allowed);
-const anyAllowed = decisions.some((d) => d.allowed);
+if (decision.allowed) {
+  console.log(decision.rule);
+} else {
+  console.log(decision.reason); // 'no-matching-rule' | 'explicit-deny'
+}
 ```
 
-## Batch Decisions with `checkAll`
+## Batch Decisions
 
 ```ts
-const decisions = ward.checkAll({ id: 'u1', roles: ['editor'] }, [
+const results = ward.checkAll({ id: 'u1', roles: ['editor'] }, [
   { resource: 'posts', action: 'read' },
   { resource: 'posts', action: 'update', data: { authorId: 'u1' } },
 ]);
-
-const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
-const boundDecisions = bound.checkAll([
-  { resource: 'posts', action: 'read' },
-  { resource: 'posts', action: 'delete' },
-]);
-```
-
-`checkAll()` returns a `WardDecisionResult[]` — each entry is a `WardDecision` with the originating `resource` and `action` fields attached, so callers do not need to zip the result by index.
-
-## List Allowed Actions
-
-`allowedActions(principal, resource, knownActions, data?)` returns the subset of `knownActions` that the principal is allowed to perform on `resource`.
-
-`knownActions` is required because Ward cannot enumerate actions on its own — an action defined with `WILDCARD` has no finite list of concrete values. Passing `knownActions` resolves wildcard-action rules against that set:
-
-```ts
-// Returns the subset of the provided list that is allowed
-const actions = ward.allowedActions({ id: 'u1', roles: ['admin'] }, 'posts', ['read', 'update', 'delete']);
-
-// With runtime data for predicate-gated rules
-const ownedActions = ward.allowedActions({ id: 'u1', roles: ['editor'] }, 'posts', ['read', 'update', 'delete'], {
-  authorId: 'u1',
-});
 ```
 
-`allowedActions` does not invoke the logger — it is a side-effect-free enumeration helper.
-
-## Inspect Rule Scope with `rulesInScope`
+## Bound Ward (`forUser`)
 
 ```ts
-const rules = ward.rulesInScope({ id: 'u1', roles: ['editor'] }, 'posts');
-const narrowed = ward.rulesInScope({ id: 'u1', roles: ['editor'] }, 'posts', { authorId: 'u1' });
-
 const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
-const boundRules = bound.rulesInScope('posts');
-```
-
-`rulesInScope()` is introspection-only. It returns rules in scope for the principal/resource pair and never mutates the ward.
-If you pass `data`, Ward also filters predicate rules by whether they match that runtime payload.
-
-## Explain Denials and Winners
 
-```ts
-const decision = ward.explain({ id: 'u1', roles: ['editor'] }, 'posts', 'delete');
-
-if (!decision.allowed) {
-  console.log(decision.reason); // 'no-matching-rule' | 'explicit-deny'
-  // decision.rule is only present for 'explicit-deny', not 'no-matching-rule'
-  if (decision.reason === 'explicit-deny') {
-    console.log(decision.rule.effect); // 'deny'
-  }
-}
+bound.explain({ resource: 'posts', action: 'read' });
+bound.trace({ resource: 'posts', action: 'update', data: { authorId: 'u1' } });
+bound.rulesInScope({ resource: 'posts' });
+bound.allowedActions({ resource: 'posts', knownActions: ['read', 'update', 'delete'] as const });
 ```
 
-`explain()` returns a **3-variant discriminated union**:
+`forUser()` snapshots the principal. Re-bind when roles/identity change.
 
-| Variant       | `allowed` | `reason`             | `rule`                |
-| ------------- | --------- | -------------------- | --------------------- |
-| Allow         | `true`    | —                    | The winning rule      |
-| Explicit deny | `false`   | `'explicit-deny'`    | The winning deny rule |
-| No match      | `false`   | `'no-matching-rule'` | Not present           |
+## Allowed Actions
 
-Use `'rule' in decision` to safely access the rule across all variants.
-
-## Trace Decisions
-
-`trace()` returns the complete decision trace: every rule that matched the request before the winner was selected, with per-candidate scoring details.
+`allowedActions()` evaluates a provided action set:
 
 ```ts
-const { decision, candidates } = ward.trace({ id: 'u1', roles: ['editor'] }, 'posts', 'read');
-
-candidates.forEach(({ rule, priority, score, won }) => {
-  console.log(rule.effect, priority, score, won ? '← winner' : '');
+const actions = ward.allowedActions({
+  principal: { id: 'u1', roles: ['admin'] },
+  resource: 'posts',
+  knownActions: ['read', 'update', 'delete'] as const,
 });
 ```
 
-`trace()` does **not** fire the logger — it is a side-channel-free inspection tool. Use `explain()` when you need the logger to fire and only need the final decision.
-
-`trace()` is also available on `BoundWard`: `bound.trace(resource, action, data?)`.
-
-## Detect Policy Conflicts
+It does not fire the logger.
 
-`detectConflicts()` performs a static O(n²) analysis of your rule set and returns all detected conflicts. The result is lazily computed — every call after the first returns the same array reference.
+## Rule Introspection
 
 ```ts
-const conflicts = ward.detectConflicts();
-
-conflicts.forEach((c) => {
-  if (c.kind === 'duplicate') {
-    console.warn(`Rule[${c.indexB}] is an unreachable duplicate of Rule[${c.indexA}]`);
-  } else {
-    console.warn(`Rule[${c.shadowedIndex}] is shadowed by Rule[${c.shadowingIndex}]`);
-  }
+const scoped = ward.rulesInScope({
+  principal: { id: 'u1', roles: ['editor'] },
+  resource: 'posts',
 });
 ```
 
-Two conflict kinds, narrowable by `kind`:
-
-- **`'duplicate'`** — two predicate-free rules have the same (role set, resource, action). The second (`ruleB`/`indexB`) can never fire because the first (`ruleA`/`indexA`) always wins.
-- **`'shadowed'`** — a higher-ranked predicate-free rule (`shadowingRule`/`shadowingIndex`) covers the other's (`shadowedRule`/`shadowedIndex`) patterns entirely. The shadowed rule can never win.
-
-Rules with a `when` predicate are excluded from both checks because their applicability is determined at runtime, not statically.
+Use optional `data` to filter predicate-gated matches.
 
-To surface conflicts eagerly at startup:
+## Trace Candidates
 
 ```ts
-// Warn on conflicts
-const ward = createWard(rules, {
-  onConflict: (c) =>
-    console.warn(c.kind === 'duplicate' ? `[ward] duplicate: Rule[${c.indexB}]` : `[ward] shadowed: Rule[${c.shadowedIndex}]`),
+const trace = ward.trace({
+  principal: { id: 'u1', roles: ['editor', 'blocked'] },
+  resource: 'posts',
+  action: 'read',
 });
 
-// Throw on first conflict (strict mode)
-const ward = createWard(rules, { strict: true });
-
-// Cap O(n²) cost for large auto-generated policies
-const ward = createWard(rules, { maxConflicts: 20 });
-```
-
-## Use Dynamic Conditions with `when`
-
-```ts
-const ward = createWard([
-  {
-    role: 'editor',
-    resource: 'posts',
-    action: 'update',
-    effect: 'allow',
-    when: ({ principal, data }) => principal.id === data?.authorId,
-  },
-]);
-```
-
-`when` only runs for authenticated principals. For anonymous (`null`) checks, predicates are skipped and the rule does not match. Do not pair `owns()` or any `when` predicate with an `ANONYMOUS`-role rule — it can never match.
-
-### Ownership Checks with `owns`
-
-```ts
-import { createWard, owns } from '@vielzeug/ward';
-
-const ward = createWard([
-  {
-    role: 'editor',
-    resource: 'posts',
-    action: 'update',
-    effect: 'allow',
-    when: owns('authorId'),
-  },
-]);
-```
-
-`owns()` is a convenience helper for the common `principal.id === data[attributeKey]` pattern.
-
-### Attribute-Based Conditions (ABAC)
-
-```ts
-const ward = createWard([
-  {
-    role: 'editor',
-    resource: 'posts',
-    action: 'publish',
-    effect: 'allow',
-    when: ({ principal }) => principal.attributes?.tier === 'pro',
-  },
-]);
-```
-
-`principal.attributes` can store arbitrary user metadata for runtime policy checks.
-
-## Multi-Role Rules
-
-The `role` field accepts either a single string or an array of strings. A rule matches if the principal holds **any** of the listed roles (OR semantics).
-
-Multi-role rules reduce repetition when several roles share identical permissions:
-
-```ts
-import { createWard } from '@vielzeug/ward';
-
-const ward = createWard([
-  // One rule instead of three separate allow rules
-  { role: ['viewer', 'editor', 'admin'], resource: 'posts', action: 'read', effect: 'allow' },
-  { role: ['editor', 'admin'], resource: 'posts', action: 'update', effect: 'allow' },
-  { role: 'admin', resource: 'posts', action: 'delete', effect: 'allow' },
-]);
-
-ward.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'read').allowed; // true
-ward.explain({ id: 'u2', roles: ['editor'] }, 'posts', 'update').allowed; // true
-ward.explain({ id: 'u2', roles: ['editor'] }, 'posts', 'delete').allowed; // false
-```
-
-`ANONYMOUS` works inside multi-role arrays. The rule matches both unauthenticated visitors and any authenticated role listed alongside it:
-
-```ts
-import { ANONYMOUS, createWard } from '@vielzeug/ward';
-
-const ward = createWard([{ role: [ANONYMOUS, 'viewer'], resource: 'posts', action: 'read', effect: 'allow' }]);
-
-ward.explain(null, 'posts', 'read').allowed; // true (anonymous)
-ward.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'read').allowed; // true (viewer)
-ward.explain({ id: 'u2', roles: ['admin'] }, 'posts', 'read').allowed; // false (not in list)
-```
-
-## Anonymous and Wildcards
-
-```ts
-import { ANONYMOUS, WILDCARD } from '@vielzeug/ward';
-
-const ward = createWard([
-  { role: ANONYMOUS, resource: 'posts', action: 'read', effect: 'allow' },
-  { role: WILDCARD, resource: 'status', action: 'read', effect: 'allow' },
-]);
-```
-
-Use `ANONYMOUS` for anonymous-only rules and `WILDCARD` for any role/resource/action.
-
-## Logger and Auditing
-
-```ts
-const ward = createWard([{ role: 'viewer', resource: 'posts', action: 'read', effect: 'allow' }], {
-  logger: (ctx) => {
-    const subject = ctx.principal === null ? 'anonymous' : ctx.principal.id;
-    const outcome = ctx.allowed ? 'allow' : ctx.reason;
-    console.log(subject, ctx.resource, ctx.action, outcome);
-  },
+trace.candidates.forEach((c) => {
+  console.log(c.index, c.priority, c.score, c.won);
 });
 ```
 
-The logger runs after `explain()` and `checkAll()` (including through a `BoundWard`). It does **not** run after `trace()`.
-Enumeration and introspection helpers (`allowedActions()`, `rulesInScope()`, `detectConflicts()`) stay side-effect free.
+`trace()` does not fire the logger.
 
-`WardLoggerContext` is structurally identical to `WardDecision` plus the request fields, so `rule` narrows the same way — present when `allowed` is `true` or `reason` is `'explicit-deny'`:
+## Predicate Helpers
 
 ```ts
-logger: (ctx) => {
-  if (ctx.allowed || ctx.reason === 'explicit-deny') {
-    console.log(ctx.rule.role); // no ?. needed — rule is present
-  }
-},
-```
-
-- `allowed: true` — a matching allow rule won
-- `allowed: false, reason: 'explicit-deny'` — a matching deny rule won
-- `allowed: false, reason: 'no-matching-rule'` — no rule matched at all (default deny)
-
-This lets you distinguish explicit blocks from gaps in your policy in audit logs and metrics.
-
-## Decision Precedence
-
-Ward uses one deterministic model:
-
-1. If no rule matches, decision is deny.
-2. Higher `priority` wins.
-3. For equal `priority`, higher specificity wins — `exact > namespace-wildcard (ns:*) > global-wildcard (*)`, applied independently to role, resource, and action.
-4. For equal `priority` and specificity, deny overrides allow.
-5. On absolute tie (identical priority, specificity, and effect), the rule declared **first in the array** wins.
-
-## Exact Matching
-
-Ward uses exact string matching for role/resource/action.
-
-```ts
-const ward = createWard([{ role: 'admin', resource: 'posts', action: 'read', effect: 'allow' }]);
-
-ward.explain({ id: 'u1', roles: ['admin'] }, 'posts', 'read').allowed; // true
-ward.explain({ id: 'u1', roles: ['ADMIN'] }, 'posts', 'read').allowed; // false
-```
-
-Adopt one identifier convention (for example all lowercase) at your app boundary.
-
-## Framework Integration
-
-```tsx [React]
-import { createContext, useContext, type ReactNode } from 'react';
-import { createWard } from '@vielzeug/ward';
-
-type User = { id: string; roles: string[] };
-
-const ward = createWard([
-  { role: 'admin', resource: '*', action: '*', effect: 'allow' },
-  { role: 'editor', resource: 'posts', action: 'write', effect: 'allow' },
-]);
-
-const UserContext = createContext(null);
-
-function useWard(resource: string, action: string) {
-  const user = useContext(UserContext);
-  if (!user) return false;
-  return ward.explain(user, resource, action).allowed;
-}
-
-function EditButton({ postId }: { postId: string }) {
-  const canEdit = useWard('posts', 'write');
-  if (!canEdit) return null;
-  return Edit {postId};
-}
-```
-
-```ts [Vue 3]
-import { computed } from 'vue';
-import { createWard } from '@vielzeug/ward';
-
-type User = { id: string; roles: string[] };
-
-const ward = createWard([
-  { role: 'admin', resource: '*', action: '*', effect: 'allow' },
-  { role: 'editor', resource: 'posts', action: 'write', effect: 'allow' },
-]);
-
-function useWard(user: { value: User | null }, resource: string, action: string) {
-  return computed(() => (user.value ? ward.explain(user.value, resource, action).allowed : false));
-}
-```
-
-```svelte [Svelte]
-
-  import { createWard } from '@vielzeug/ward';
-
-  type User = { id: string; roles: string[] };
-
-  export let user: User;
-
-  const ward = createWard([
-    { role: 'admin', resource: '*', action: '*', effect: 'allow' },
-    { role: 'editor', resource: 'posts', action: 'write', effect: 'allow' },
-  ]);
-
-  $: canEdit = ward.explain(user, 'posts', 'write').allowed;
+import { owns, predicate } from '@vielzeug/ward';
 
-{#if canEdit}Edit{/if}
+const isOwner = owns('authorId');
+const canEdit = predicate.and(isOwner, ({ principal }) => principal !== null);
 ```
 
-### Pitfalls
-
-- **React:** If the ward is created inside a component that re-renders often, `createWard()` runs on every render. Memoize with `useMemo(() => createWard(...), [role])`, or define it once at module scope as in the example above.
-- **Vue 3:** Injecting `ward` as a plain value (not a `ComputedRef`) means role changes don't propagate to child components. Always inject as a reactive ref.
-- **Svelte:** `setContext` must be called synchronously during component initialization. Calling it inside a reactive statement (`$:`) works only for setting the initial value — child components reading the context must use `getContext` in their own `` block.
-
-## Middleware Integration
+Async predicates are rejected at runtime with `WardPredicateError`.
 
-Ward has no framework-specific middleware — `guardRequest` and `guardRequestWith` are small, framework-agnostic helpers you wire into a 2–3 line adapter for whichever server you use.
+## Framework Guards
 
 ```ts
 import { guardRequest, guardRequestWith } from '@vielzeug/ward';
 
-// Principal is already resolved (e.g. from session) — sync, no await needed
-const result = guardRequest(ward, principal, 'posts', 'update');
-
-// Principal must be extracted from a request object (e.g. verify JWT) — async
-const result = await guardRequestWith(ward, req, getPrincipal, 'posts', 'update');
-
-if (!result.granted) {
-  return new Response(JSON.stringify({ reason: result.reason }), { status: 403 });
-}
-```
-
-### Express / Connect
-
-```ts
-app.use('/posts', async (req, res, next) => {
-  const result = await guardRequestWith(ward, req, (r) => r.user ?? null, 'posts:*', 'update');
-  result.granted ? next() : res.status(403).json({ reason: result.reason });
-});
-```
-
-### Hono
-
-```ts
-app.put('/posts/:id', async (c, next) => {
-  const result = guardRequest(ward, c.get('user') ?? null, `posts:${c.req.param('id')}`, 'update');
-  return result.granted ? next() : c.json({ reason: result.reason }, 403);
+const direct = guardRequest({
+  ward,
+  principal: { id: 'u1', roles: ['viewer'] },
+  resource: 'posts',
+  action: 'read',
 });
-```
-
-## Debug Mode
 
-Import `debugWard` from the dedicated sub-path to create a ward with decision logging pre-enabled. The sub-path is tree-shaken from production bundles when not imported.
-
-```ts
-import { debugWard } from '@vielzeug/ward/devtools';
-
-const permit = debugWard([
-  { role: 'viewer', resource: 'posts', action: 'read', effect: 'allow' },
-  { role: 'editor', resource: 'posts', action: 'update', effect: 'allow' },
-]);
-
-permit.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'read');
-// [ward:decision] allow             (allow)   viewer  posts  read
-
-permit.explain({ id: 'u1', roles: ['viewer'] }, 'posts', 'update');
-// [ward:decision] no-matching-rule            viewer  posts  update
-
-permit.explain(null, 'posts', 'read');
-// [ward:decision] no-matching-rule            anonymous  posts  read
-```
-
-The ward returned is identical to `createWard()` — all methods (`explain`, `checkAll`, `forUser`, etc.) work the same way.
-
-Alternatively, pass a custom `logger` directly to `createWard()` to route decisions to a structured logger:
-
-```ts
-const permit = createWard(rules, {
-  logger: (ctx) => myLogger.debug('access decision', ctx),
+const extracted = await guardRequestWith({
+  ward,
+  req,
+  extractPrincipal: async (request) => request.user ?? null,
+  resource: 'posts',
+  action: 'read',
 });
 ```
 
-Debug logging fires on `explain()` and `checkAll()` (including through a `BoundWard`). It does **not** fire on `trace()`, or on the side-effect-free helpers `allowedActions()`, `rulesInScope()`, and `detectConflicts()`.
-
-## Working with Other Vielzeug Libraries
-
-### With Wayfinder
-
-Use ward guards inside Wayfinder middleware to protect routes.
-
-```ts
-import { createWard } from '@vielzeug/ward';
-import { createRouter } from '@vielzeug/wayfinder';
-
-type User = { id: string; roles: string[] };
-
-const ward = createWard([{ role: 'admin', resource: 'settings', action: 'read', effect: 'allow' }]);
-
-const router = createRouter({
-  routes: {
-    settings: {
-      path: '/settings',
-      handler: ({ data }) => renderSettings(data),
-    },
-  },
-  middleware: [
-    (ctx, next) => {
-      const user: User = getSessionUser(); // your auth provider
-      if (!ward.explain(user, 'settings', 'read').allowed) {
-        return ctx.navigate({ path: '/login' });
-      }
-      return next();
-    },
-  ],
-});
-```
-
-### With Rune
-
-Use ward's `logger` option to audit every access decision.
-
-```ts
-import { createWard } from '@vielzeug/ward';
-import { createLogger } from '@vielzeug/rune';
-
-const log = createLogger({ namespace: 'ward' });
-
-const ward = createWard(
-  [
-    /* rules */
-  ],
-  {
-    logger: (decision) => log.info('access decision', decision),
-  },
-);
-```
-
-## Best Practices
-
-- Keep roles and resources explicit and predictable.
-- Use `priority` sparingly for explicit overrides.
-- Keep `when` predicates pure and side-effect free.
-- Prefer one ward instance per app boundary and keep rules centralized.
-- Use `forUser({ ... })` for repeated checks in UI or request scopes.
-
 ### Examples
 
 ## Examples