@vielzeug/codex 1.0.2 → 1.0.3

package/data/llms-full.txt

@@ -1687,6 +1687,7 @@ type InterpretOptions = {
   onDebug?: (event: DebugEvent) => void;
   persistence?: PersistenceAdapter;
   snapshot?: MachineSnapshot;
+  validateHydratedContext?: boolean;
   traceLimit?: number;
 };
 ```
@@ -1699,6 +1700,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 +1828,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 +1880,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 +2474,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 +2551,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 +7057,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 +7118,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 +8290,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 +8329,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 +8373,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 +8384,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 +8392,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 +8973,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 +9021,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 +9094,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 +9121,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 +9225,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 +9340,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 +9466,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 +9474,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 +9914,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 +10058,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 +10087,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)
@@ -12900,7 +13006,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
 
@@ -12947,7 +13053,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()
 
@@ -13471,7 +13577,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 +13593,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
@@ -13629,6 +13735,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,11 +13890,27 @@ 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. Prefer `address.subscribeScoped(...)` for section UIs 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
 
@@ -13900,12 +14028,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();
 ```
@@ -17742,7 +17870,7 @@ i18n.getSupportedLocales();
 | `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 |
+| `i18n.restoreState()`     | Hydrate instance from serialized state                                             | Sync           | Equivalent to `hydrateI18n(i18n, state)` — 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                                                            |
 | Error classes             | Named error subclasses (`LinguaDisposedError`, `LinguaMissingLocaleError`, …)      | —              | All runtime errors are `instanceof LinguaError`; use `instanceof` for specific handling                            |
@@ -17960,7 +18088,7 @@ 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()` or `serializeI18n()`. Equivalent to `hydrateI18n(i18n, state)` but preferred because it is called directly on the instance.
 
 - Replaces all catalogs with those from `state`.
 - Sets the active locale to `state.locale`.
@@ -20718,11 +20846,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 +20913,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 (+10 more)
 **Related:** ripple, refine, orbit
 
 ### Overview
@@ -20854,7 +20984,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 +20999,7 @@ define('my-counter', {
       }
     `,
   ],
-  setup(props, { bind, onMounted }) {
+  setup(props) {
     const count = signal(0);
     const doubled = computed(() => count.value * 2);
 
@@ -20890,12 +21020,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 +21035,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)  |
 | `@vielzeug/ore/devtools`   | `debugFlush` — verbose flush for timing diagnostics (dev only)                |
 | `@vielzeug/ore/directives` | `each`, `when`, `model`, `live`, `raw`, `classMap`, `styleMap`                |
+| `@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,23 +21058,31 @@ 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
 
@@ -20951,6 +21091,7 @@ define('my-counter', {
 | `@vielzeug/ore`            | Core authoring/runtime API                                         |
 | `@vielzeug/ore/devtools`   | `debugFlush` — verbose flush for timing diagnostics                |
 | `@vielzeug/ore/directives` | Standalone directive imports (`each`, `when`, `classMap`, …)       |
+| `@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 +21103,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 +21141,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 +21165,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 +21184,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 +21277,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 +21303,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,12 +21332,12 @@ 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
 
@@ -21220,6 +21348,8 @@ Slot signals update reactively when assigned content changes, including when slo
 
 ## 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 +21364,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 +21382,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 +21431,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 +21446,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 +21472,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 +21525,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 +21613,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 +21657,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;
@@ -21667,14 +21807,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 +21832,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 +21885,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();
 
@@ -21774,10 +21914,13 @@ define('button-wrapper', {
 
 ```ts
 import { when } from '@vielzeug/ore/directives';
-import { define, html } from '@vielzeug/ore';
+import { define, html, useEmit, useSlots } 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 +21933,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 +21965,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 +22006,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 +22132,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 +22158,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 +26072,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 +26179,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 +26217,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 +26277,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 +26294,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 +26323,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 +26383,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 +26417,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 +26470,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 +26480,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 +26492,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 +26526,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 +26540,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) |
@@ -31276,7 +31436,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 +31548,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 +31693,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 +32063,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 +32727,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 +32863,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 +32926,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 +33808,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 +33964,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 +33999,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 +34145,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.
@@ -34090,7 +34359,7 @@ 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`                            |
@@ -34107,6 +34376,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                                     |
@@ -34144,7 +34414,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 +34467,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.
 
@@ -34830,13 +35100,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
@@ -34907,6 +35187,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
 
@@ -35328,6 +35609,7 @@ effect(() => {
 - 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.
 - 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.
@@ -35366,7 +35648,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 +35783,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 +35802,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 +35900,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 +36780,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 +36883,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 +36911,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 +40583,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()` returns a discriminated decision (`allowed: true | false`) and optional matching `rule`.
 
-### `explain()`
+## Bound View
 
-```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.
-
-**Returns:** `WardDecision`
-
-**Example:**
+Use `forUser()` when checking many permissions for the same principal:
 
 ```ts
-const decision = ward.explain({ id: 'u1', roles: ['editor'] }, 'posts', 'delete');
-
-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
-  }
-}
-```
-
----
-
-### `trace()`
+const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
 
-```ts
-ward.trace(
-  principal: Principal,
-  resource: string,
-  action: TAction,
-  data?: TData,
-): WardTrace
+bound.explain({ resource: 'posts', action: 'read' });
+bound.allowedActions({ resource: 'posts', knownActions: ['read', 'update', 'delete'] as const });
 ```
 
-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:**
+## Middleware Guards
 
 ```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) |
+See the [usage guide](./usage.md), [API reference](./api.md), and [examples](./examples/blog-roles.md).
 
-**Example:**
-
-```ts
-const bound = ward.forUser({ id: 'u1', roles: ['editor'] });
-
-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';
+All three return `WardRule[]` (one rule per action).
 
-const ward = createWard([
-  ...allow(['viewer', 'editor'], 'posts', ['read']),
-  ...allow('editor', 'posts', ['update'], { when: owns('authorId'), priority: 5 }),
-  ...deny('blocked', WILDCARD, [WILDCARD], { priority: 100 }),
-]);
-```
-
----
+## 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.
+## Predicate Helpers
 
-**Example:**
+### `predicate.owns(attributeKey)`
+### `predicate.and(...predicates)`
+### `predicate.or(...predicates)`
+### `predicate.not(predicate)`
+### `owns(attributeKey)` (alias)
 
-```ts
-import { guardRequestWith } from '@vielzeug/ward';
+Predicates run synchronously. Returning a Promise throws `WardPredicateError`.
 
-const result = await guardRequestWith(ward, req, (req) => req.user ?? null, 'posts', 'update');
+## Pattern Helpers
 
-if (!result.granted) {
-  return response.status(403).json({ reason: result.reason });
-}
-```
+### `matchesPattern(pattern, value): boolean`
+### `patternCovers(broad, narrow): boolean`
 
-## Types
+## Middleware Guards
 
-### `UserPrincipal`
+### `guardRequest(input)`
 
 ```ts
-type UserPrincipal = {
-  id: string;
-  roles: readonly string[];
-  attributes?: Record;
-};
-```
-
-### `Principal`
-
-```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 +40851,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
+Rules are immutable after creation. Create a new ward to update policy.
 
-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".
+## Explain a Decision
 
 ```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`).
-
-## Check Permissions
-
-```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**:
-
-| 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           |
+`forUser()` snapshots the principal. Re-bind when roles/identity change.
 
-Use `'rule' in decision` to safely access the rule across all variants.
+## Allowed Actions
 
-## 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?)`.
+It does not fire the logger.
 
-## Detect Policy Conflicts
-
-`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`:
+Use optional `data` to filter predicate-gated matches.
 
-- **`'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.
-
-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' },
-]);
+import { owns, predicate } from '@vielzeug/ward';
 
-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;
-
-{#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.
+Async predicates are rejected at runtime with `WardPredicateError`.
 
-## Middleware Integration
-
-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 });
+const direct = guardRequest({
+  ward,
+  principal: { id: 'u1', roles: ['viewer'] },
+  resource: 'posts',
+  action: 'read',
 });
-```
-
-### 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 extracted = await guardRequestWith({
+  ward,
+  req,
+  extractPrincipal: async (request) => request.user ?? null,
+  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),
-});
-```
-
-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