@vielzeug/codex 1.0.3 → 1.0.4

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug — Full Documentation
 
-> Complete documentation for all 30 Vielzeug packages. Version: 1.0.2
+> Complete documentation for all 31 Vielzeug packages. Version: 1.0.3
 
 ---
 
@@ -1211,6 +1211,569 @@ const price = currency({ amount: 123456n, currency: 'USD' }); // $1,234.56
 - Type checking utilities (id: `typed-is`)
 
 
+---
+
+## @vielzeug/assay
+
+**Category:** testing
+**Keywords:** testing, dom, events, queries, waitfor, custom-elements, jsdom
+**Key exports:** within, query, queryAll, queryByTestId, queryAllByTestId, queryByText, queryAllByText, queryInShadow, queryAllInShadow, queryPart, getSlotted, fire (+7 more)
+**Related:** ore, refine
+
+### Overview
+
+## Why Assay?
+
+Testing DOM-level code (custom elements, vanilla event handlers, framework-rendered output) usually means hand-rolling `dispatchEvent` boilerplate and ad-hoc polling loops, or pulling in a full testing-library dependency tied to one framework's rendering model. Assay extracts just the generic, framework-agnostic pieces — scoped queries, event dispatch, async waiting — as a standalone, zero-dependency package.
+
+```ts
+// Before — hand-rolled event dispatch and polling in every test file
+const btn = panel.querySelector('button.submit')!;
+
+btn.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+
+const deadline = Date.now() + 1000;
+while (Date.now()  setTimeout(r, 50));
+}
+
+// After
+import { fire, waitFor, within } from '@vielzeug/assay';
+
+const { query, queryByText } = within(panel);
+
+fire.click(query('button.submit')!);
+await waitFor(() => queryByText('Saved') !== null);
+```
+
+| Feature                | Assay                                            | @testing-library/dom                    |
+| ----------------------- | ------------------------------------------------ | ---------------------------------------- |
+| Bundle size             |        | ~15 kB                                   |
+| Framework-agnostic      |       |  |
+| Scoped queries          |  `within()` |  |
+| Low-level event dispatch|  `fire.*` | Partial (`fireEvent`)               |
+| Deterministic `waitFor` |       |  |
+| Zero dependencies       |       |      |
+
+**Use Assay when** you're testing custom elements or vanilla DOM code and want scoped queries, synchronous event dispatch, and async waiting without adopting a framework-specific testing library.
+
+**Consider alternatives when** you're already standardized on `@testing-library/dom` (or a framework-specific wrapper around it) and don't need to avoid that dependency.
+
+## Installation
+
+Assay is a testing dependency — install it alongside your test runner.
+
+```sh [pnpm]
+pnpm add -D @vielzeug/assay
+```
+
+```sh [npm]
+npm install -D @vielzeug/assay
+```
+
+```sh [yarn]
+yarn add -D @vielzeug/assay
+```
+
+## Quick Start
+
+```ts
+import { fire, waitFor, within } from '@vielzeug/assay';
+
+const panel = document.querySelector('.panel')!;
+const { query, queryByText } = within(panel);
+
+fire.click(query('button.submit')!);
+
+await waitFor(() => queryByText('Saved') !== null);
+```
+
+## Features
+
+- `within(element)` — scoped `query`/`queryAll`/`queryByText`/`queryAllByText`/`queryByTestId`/`queryAllByTestId` for any element or shadow root, each also available as a free function (`query(root, selector)`, etc.) for when you already have a root.
+- `queryInShadow`/`queryAllInShadow`/`queryPart` — shadow-DOM-aware queries that return `null`/`[]` instead of throwing when the host has no shadow root.
+- `getSlotted(host, slotName?)` — light-DOM children assigned to a named slot, or every slotted child.
+- `fire.*` — low-level synchronous DOM event dispatchers (`click`, `input`, `keyDown`, `pointerDown`/`pointerMove`/`pointerCancel`, `custom`, and more), each with sensible `bubbles`/`cancelable` defaults and a consistent `boolean` return value — no exceptions.
+- `waitFor(fn, options?)` — polls until a callback returns truthy or a bare `expect()` call doesn't throw; always rejects with `AssayTimeoutError` on timeout, with the original failure preserved as `.cause`.
+- `waitForEvent(element, name, timeout?)` — resolves with the next matching event, or rejects with `AssayTimeoutError`.
+- `nextTick()`/`wait(ms?)` — microtask and macrotask timing helpers for reactive updates and debounced code.
+- `AssayError` / `AssayTimeoutError` — a single error hierarchy for every timeout this package raises.
+- No DOM-framework coupling — works with vanilla custom elements, `@vielzeug/ore` components, or any other DOM output.
+
+## Documentation
+
+- [Usage Guide](./usage.md)
+- [API Reference](./api.md)
+
+## See Also
+
+- [Ore](/ore/) — web-component authoring library whose `@vielzeug/ore/testing` sub-path re-exports Assay's query/event/wait primitives
+- [Refine](/refine/) — accessible component library built on Ore, testable with the same Assay primitives
+
+### API Reference
+
+## API Overview
+
+| Symbol              | Purpose                                              | Execution mode | Common gotcha |
+| -------------------- | ----------------------------------------------------- | -------------- | -------------- |
+| `within(element)`    | Scoped query helpers for one element/subtree           | Sync            | Returns a fresh `QueryScope` per call — cheap, but don't cache it across DOM mutations you care about |
+| `query()` / `queryAll()` | Free-function equivalents of `within(root).query`/`.queryAll` | Sync    | Use these when you already have a root and don't need the rest of `QueryScope` |
+| `queryByTestId()` / `queryAllByTestId()` | Match a `data-testid` attribute        | Sync            | Free-function equivalents of `within(root).queryByTestId`/`.queryAllByTestId` |
+| `queryByText()`      | First element matching trimmed text content            | Sync            | Matches exact trimmed text, not substrings |
+| `queryAllByText()`   | Every element matching trimmed text content            | Sync            | Same exact-match caveat as `queryByText()` |
+| `queryInShadow()` / `queryAllInShadow()` | Query inside a host's shadow root       | Sync            | Returns `null`/`[]` (not a throw) when the host has no shadow root |
+| `queryPart()`        | Query a shadow-DOM element by its `part` attribute      | Sync            | Shorthand for `queryInShadow(host, '[part="x"]')` |
+| `getSlotted()`       | Light-DOM children assigned to a slot                   | Sync            | Only direct children (`:scope >`) — doesn't recurse into further-nested slots |
+| `fire.*`             | Dispatch a DOM event synchronously                     | Sync            | Doesn't wait for anything — pair with `waitFor()`/`await` for async reactions |
+| `createPointerEvent()` | Build a `PointerEvent`, falling back to `MouseEvent` | Sync            | Only needed if you're constructing an event by hand instead of using `fire.pointer*` |
+| `waitFor()`          | Poll until a callback returns truthy or resolves       | Async           | Always rejects with `AssayTimeoutError` on timeout — the original failure is `.cause`, never the thrown error's own type |
+| `waitForEvent()`     | Resolve on the next matching event                     | Async           | Rejects with `AssayTimeoutError`, not a plain `Error`, on timeout |
+| `nextTick()`         | Resolve after one microtask tick                        | Async           | Doesn't wait for `setTimeout`-scheduled work — use `wait()` for that |
+| `wait()`             | Resolve after a fixed millisecond delay                 | Async           | A fixed delay, not a condition — prefer `waitFor()` when you can express a condition instead |
+
+## Package Entry Point
+
+| Import              | Purpose                                                            |
+| -------------------- | ------------------------------------------------------------------- |
+| `@vielzeug/assay`    | The entire public API — queries, event dispatch, async waiting     |
+
+## Query Helpers
+
+### `within(element)`
+
+Creates query helpers scoped to a single element or shadow root.
+
+**Parameters**
+
+| Name      | Type       | Description                          |
+| --------- | ---------- | ------------------------------------- |
+| `element` | `Element`  | The root to scope every query to      |
+
+**Returns:** `QueryScope`
+
+**Example**
+
+```ts
+import { within } from '@vielzeug/assay';
+
+const { query, queryAll, queryByTestId, queryAllByTestId, queryByText, queryAllByText } = within(panel);
+```
+
+`QueryScope` methods:
+
+| Method                            | Returns          |
+| ---------------------------------- | ----------------- |
+| `query(selector)`                  | `Element \| null` |
+| `queryAll(selector)`               | `Element[]`       |
+| `queryByText(text, selector?)`     | `Element \| null` |
+| `queryAllByText(text, selector?)`  | `Element[]`       |
+| `queryByTestId(testId)`            | `Element \| null` |
+| `queryAllByTestId(testId)`         | `Element[]`       |
+
+`selector` defaults to `'*'` for the text-matching methods.
+
+---
+
+### `query(root, selector)` / `queryAll(root, selector)`
+
+Free-function equivalents of `within(root).query`/`.queryAll` — a thin wrapper over `root.querySelector(All)`, exported directly so every `QueryScope` method has both a scoped and unscoped form.
+
+**Returns:** `Element | null` / `Element[]`
+
+---
+
+### `queryByTestId(root, testId)` / `queryAllByTestId(root, testId)`
+
+Free-function equivalents of `within(root).queryByTestId`/`.queryAllByTestId` — matches a `data-testid` attribute.
+
+**Returns:** `Element | null` / `Element[]`
+
+---
+
+### `queryByText(root, text, selector)`
+
+The unscoped function `within()` is built on — useful when you already have a root and don't need the rest of `QueryScope`.
+
+**Parameters**
+
+| Name       | Type                   | Description                                  |
+| ---------- | ---------------------- | ---------------------------------------------- |
+| `root`     | `Element \| ShadowRoot`| Subtree to search                             |
+| `text`     | `string`               | Exact text to match against trimmed `textContent` |
+| `selector` | `string`               | CSS selector narrowing candidate elements      |
+
+**Returns:** `Element | null` — the first matching element, or `null`.
+
+---
+
+### `queryAllByText(root, text, selector)`
+
+Same matching rules as `queryByText`, returning every match.
+
+**Returns:** `Element[]`
+
+---
+
+### `queryInShadow(host, selector)` / `queryAllInShadow(host, selector)`
+
+Query inside `host.shadowRoot`. Returns `null` (or `[]` for the `All` variant) instead of throwing when `host` has no shadow root — safe to call without an `if (host.shadowRoot)` guard.
+
+**Returns:** `Element | null` / `Element[]`
+
+---
+
+### `queryPart(host, part)`
+
+Shorthand for `queryInShadow(host, '[part="' + part + '"]')`.
+
+**Returns:** `Element | null`
+
+---
+
+### `getSlotted(host, slotName?)`
+
+Returns the light-DOM children assigned to a named slot, or every slotted child (`:not([slot])`) when `slotName` is omitted.
+
+**Returns:** `Element[]`
+
+## Event Dispatch
+
+### `fire`
+
+An object of synchronous event dispatchers. Every method calls `element.dispatchEvent(...)` with an appropriately-typed `Event` subclass and sensible defaults, and returns `dispatchEvent`'s own boolean result.
+
+```ts
+import { fire } from '@vielzeug/assay';
+
+fire.click(el, opts?: PointerEventInit);
+fire.blur(el, opts?: FocusEventInit);
+fire.change(el, opts?: EventInit);
+fire.custom(el, name, opts?: CustomEventInit);
+fire.event(el, event: Event);
+fire.focus(el, name?, opts?: FocusEventInit);
+fire.input(el, opts?: EventInit);
+fire.keyboard(el, type, opts?: KeyboardEventInit);
+fire.keyDown(el, opts?: KeyboardEventInit);
+fire.keyUp(el, opts?: KeyboardEventInit);
+fire.mouse(el, type, opts?: MouseEventInit);
+fire.pointerCancel(el, opts?: PointerEventInit);
+fire.pointerDown(el, opts?: PointerEventInit);
+fire.pointerEnter(el, opts?: PointerEventInit);
+fire.pointerLeave(el, opts?: PointerEventInit);
+fire.pointerMove(el, opts?: PointerEventInit);
+fire.pointerUp(el, opts?: PointerEventInit);
+fire.submit(el, opts?: EventInit);
+fire.touch(el, type, opts?: EventInit);
+```
+
+`fire.touch` falls back to `CustomEvent` in environments without a `TouchEvent` constructor. `fire.pointer*` methods route through `createPointerEvent()`, so they fall back to `MouseEvent` the same way.
+
+---
+
+### `createPointerEvent(type, init?)`
+
+Builds a `PointerEvent`, or a `MouseEvent` when `PointerEvent` isn't available in the current environment.
+
+**Returns:** `Event`
+
+## Async Waiting
+
+### `waitFor(fn, options?)`
+
+Polls `fn` until it returns truthy, returns `undefined` (a bare `expect()` call that didn't throw), or the timeout elapses.
+
+**Parameters**
+
+| Name              | Type                | Default | Description                                  |
+| ------------------ | ------------------- | ------- | ---------------------------------------------- |
+| `fn`               | `() => unknown`      | —       | Condition to poll                             |
+| `options.timeout`  | `number`             | `1000`  | Maximum wait time in ms                       |
+| `options.interval` | `number`             | `50`    | Delay between polling attempts in ms          |
+| `options.message`  | `string`             | —       | Prefixed in front of the default timing summary in the timeout error — never replaces it |
+
+**Returns:** `Promise`
+
+**Throws:** `AssayTimeoutError` on timeout, unconditionally — regardless of whether the last polling attempt returned a falsy value or threw. The original failure (a thrown error, or its message) is preserved as `.cause` and folded into the timeout message; `fn`'s thrown error itself is never mutated.
+
+**Example**
+
+```ts
+await waitFor(() => queryByText('Saved') !== null);
+await waitFor(() => expect(spy).toHaveBeenCalled(), { timeout: 2000 });
+```
+
+---
+
+### `waitForEvent(element, name, timeout?)`
+
+Resolves with the next event of the given name.
+
+**Parameters**
+
+| Name      | Type      | Default | Description                     |
+| --------- | --------- | ------- | --------------------------------- |
+| `element` | `Element` | —       | Element to listen on             |
+| `name`    | `string`  | —       | Event name                       |
+| `timeout` | `number`  | `1000`  | Maximum wait time in ms          |
+
+**Returns:** `Promise` — the event instance, typed as `T extends Event` (defaults to `Event`).
+
+---
+
+### `nextTick()`
+
+Resolves after one microtask tick (`queueMicrotask`) — for waiting on reactivity (signal effects, promise-chain continuations) without moving into the macrotask queue.
+
+**Returns:** `Promise`
+
+---
+
+### `wait(ms?)`
+
+Resolves after `ms` milliseconds (default `0`).
+
+**Returns:** `Promise`
+
+## Types
+
+```ts
+interface QueryScope {
+  query(selector: string): E | null;
+  queryAll(selector: string): E[];
+  queryByText(text: string, selector?: string): E | null;
+  queryAllByText(text: string, selector?: string): E[];
+  queryByTestId(testId: string): E | null;
+  queryAllByTestId(testId: string): E[];
+}
+
+interface WaitOptions {
+  timeout?: number;
+  interval?: number;
+  message?: string;
+}
+```
+
+## Errors
+
+| Error               | Thrown by                    | Notable properties |
+| -------------------- | ------------------------------ | -------------------- |
+| `AssayError`         | Base class for every Assay error — use `instanceof AssayError` to catch any of them | `AssayError.is(err)` static type guard |
+| `AssayTimeoutError`  | `waitFor()`, `waitForEvent()` when the timeout elapses | Extends `AssayError` |
+
+### Usage Guide
+
+## Basic Usage
+
+`within(element)` scopes queries to a subtree — useful for slotted content, shadow roots, or any container you don't want to re-select from `document` on every assertion.
+
+```ts
+import { within } from '@vielzeug/assay';
+
+const panel = document.querySelector('.panel')!;
+const { query, queryAll, queryByText } = within(panel);
+
+query('.title'); // Element | null, scoped to panel
+queryAll('.item'); // Element[], scoped to panel
+queryByText('Save'); // matches trimmed textContent
+```
+
+`queryByTestId`/`queryAllByTestId` match a `data-testid` attribute — useful when text content or CSS structure is likely to change but a stable test hook is worth keeping:
+
+```ts
+const { queryByTestId } = within(panel);
+
+queryByTestId('save-button')?.click();
+```
+
+Every `QueryScope` method is also available as a free function taking the root as its first argument — reach for these when you already have a root in scope and don't need the rest of `within()`'s object:
+
+```ts
+import { query, queryAll, queryByTestId, queryAllByTestId } from '@vielzeug/assay';
+
+query(panel, '.title');
+queryAll(panel, '.item');
+queryByTestId(panel, 'save-button');
+queryAllByTestId(panel, 'item-row');
+```
+
+For a custom element's shadow DOM, use `queryInShadow`/`queryAllInShadow`/`queryPart` instead — they return `null`/`[]` rather than throwing when the host has no shadow root (e.g. a `shadow: false` component), so you don't need an `if (host.shadowRoot)` guard at every call site:
+
+```ts
+import { queryAllInShadow, queryInShadow, queryPart } from '@vielzeug/assay';
+
+queryInShadow(customEl, '.internal-label');
+queryAllInShadow(customEl, '.option');
+queryPart(customEl, 'trigger'); // shorthand for queryInShadow(host, '[part="trigger"]')
+```
+
+`getSlotted()` reads the *light*-DOM children a host projects into a named slot (or every slotted child with no argument) — the complement to the shadow-DOM helpers above:
+
+```ts
+import { getSlotted } from '@vielzeug/assay';
+
+const slides = getSlotted(carousel); // default slot
+const actions = getSlotted(dialog, 'footer'); // named slot
+```
+
+## Firing Events
+
+`fire.*` dispatches real DOM events synchronously — no framework-specific event simulation layer, just `dispatchEvent` with sensible defaults (`bubbles: true`, `cancelable: true` where that matches the real event's behavior). Every method returns the same `boolean` `dispatchEvent` itself returns (`false` when a listener called `preventDefault()`), with no exceptions — useful for asserting a handler actually intercepted the event:
+
+```ts
+import { fire } from '@vielzeug/assay';
+
+fire.click(button);
+fire.input(textInput); // fires a plain 'input' Event
+fire.keyDown(textInput, { key: 'Enter' });
+fire.custom(el, 'value-change', { detail: { value: 42 } });
+
+const notPrevented = fire.click(link); // false if a listener called preventDefault()
+```
+
+Pointer events fall back to `MouseEvent` in environments without a `PointerEvent` constructor (some older jsdom versions) — Assay logs a one-time `console.warn` the first time this happens, so an environment gap doesn't show up as a confusing, unrelated test failure instead:
+
+```ts
+fire.pointerDown(slider);
+fire.pointerMove(slider, { clientX: 120 });
+fire.pointerUp(slider);
+```
+
+Dispatch a pre-built event instance directly with `fire.event` when you need full control over the event's properties:
+
+```ts
+fire.event(el, new CustomEvent('ready', { bubbles: true, detail: { ok: true } }));
+```
+
+## Waiting for Async Conditions
+
+`waitFor()` polls a callback until it returns truthy (or doesn't throw, for a bare `expect()` call) — use it for anything that updates asynchronously (a reactive framework's next render, a debounced input handler, a `fetch` completing).
+
+```ts
+import { waitFor } from '@vielzeug/assay';
+
+await waitFor(() => panel.querySelector('.status')?.textContent === 'Ready');
+
+// Works with `expect()` assertions too — a thrown assertion error means "not yet",
+// and its message is folded into the AssayTimeoutError thrown if the timeout is reached
+// (see below — the assertion's own error type never escapes waitFor() directly).
+await waitFor(() => expect(callback).toHaveBeenCalled());
+```
+
+Tune the polling interval and timeout per call — the defaults (1000ms timeout, 50ms interval) suit most reactive UI updates:
+
+```ts
+await waitFor(() => queue.isEmpty(), { interval: 10, timeout: 5000 });
+```
+
+`waitForEvent()` resolves with the next matching event instead of polling — prefer it when you're waiting on something that's guaranteed to fire an event rather than settle into an observable DOM state:
+
+```ts
+import { fire, waitForEvent } from '@vielzeug/assay';
+
+const promise = waitForEvent>(el, 'item-added');
+
+fire.click(addButton);
+
+const event = await promise;
+console.log(event.detail.id);
+```
+
+Both `waitFor()` and `waitForEvent()` reject with `AssayTimeoutError` on timeout — unconditionally, even if the last attempt inside `waitFor()` threw a different error type (an `expect()` assertion, say). Catch `AssayTimeoutError` specifically when you want to distinguish "the condition never became true" from other failures; the original failure is preserved on `.cause` if you need it:
+
+```ts
+import { AssayTimeoutError, waitForEvent } from '@vielzeug/assay';
+
+try {
+  await waitForEvent(el, 'never-fires', 100);
+} catch (err) {
+  if (err instanceof AssayTimeoutError) {
+    // expected — assert on the timeout itself, or inspect err.cause for the original failure
+  }
+}
+```
+
+`nextTick()` and `wait()` cover the two other common timing needs: waiting for reactivity to settle, and waiting for a real macrotask delay.
+
+```ts
+import { nextTick, wait } from '@vielzeug/assay';
+
+signal.value = 'updated';
+await nextTick(); // let a microtask-scheduled effect run
+
+await wait(300); // wait out a debounce timer — prefer nextTick()/waitFor() where possible
+```
+
+## Testing Custom Elements
+
+Assay has no opinion about how your DOM was produced — it works the same way against a vanilla custom element, a framework-rendered component, or plain `document.createElement` output.
+
+```ts
+import { fire, waitFor, within } from '@vielzeug/assay';
+
+customElements.define(
+  'my-counter',
+  class extends HTMLElement {
+    connectedCallback() {
+      this.innerHTML = `+10`;
+      this.querySelector('button')!.addEventListener('click', () => {
+        const span = this.querySelector('.count')!;
+
+        span.textContent = String(Number(span.textContent) + 1);
+      });
+    }
+  },
+);
+
+const el = document.createElement('my-counter');
+
+document.body.appendChild(el);
+
+const { query } = within(el);
+
+fire.click(query('button')!);
+
+await waitFor(() => query('.count')?.textContent === '1');
+
+el.remove();
+```
+
+## Working with Other Vielzeug Libraries
+
+`@vielzeug/ore`'s `./testing` sub-path re-exports Assay's `within`, `fire`, `createPointerEvent`, `waitFor`, and `waitForEvent` directly — if you're already testing Ore components, you don't need a separate Assay import:
+
+```ts
+import { fire, mount, waitFor } from '@vielzeug/ore/testing';
+
+const { query } = await mount(() => html` {}}>Click`);
+
+fire.click(query('button')!);
+```
+
+`@vielzeug/refine`'s `./testing` sub-path re-exports Assay's `queryInShadow`, `queryAllInShadow`, `queryPart`, `getSlotted`, `nextTick`, and `wait` the same way, alongside refine-specific helpers (ARIA attribute assertions, form-associated helpers) that stay in refine because they're specific to testing ore/refine component *contracts*, not generic DOM interaction:
+
+```ts
+import { getAriaState, getSlotted, nextTick } from '@vielzeug/refine/testing';
+```
+
+Import from `@vielzeug/assay` directly when testing DOM code that has nothing to do with Ore or Refine — a vanilla custom element, a framework-rendered component, or plain event-handler logic.
+
+## Best Practices
+
+- Prefer `within(element)` over repeated `element.querySelector(...)` calls — it reads better at call sites with multiple assertions against the same subtree.
+- Use `queryByTestId` for elements whose text or structure is expected to change; use `queryByText` when the visible text itself is what you're asserting on.
+- Reach for `waitForEvent()` over `waitFor()` when the thing you're waiting on is guaranteed to dispatch an event — it resolves on the first matching event instead of polling.
+- Catch `AssayTimeoutError` specifically (not a bare `Error`) when a test needs to branch on "the condition never happened" versus any other failure.
+- Keep `fire.*` calls synchronous where the real user interaction would be — `fire.click()` doesn't await anything; `await` the assertion that follows it instead.
+- Remove elements you create directly with `document.createElement` (`el.remove()`) at the end of each test — Assay itself has no auto-cleanup registry, unlike `@vielzeug/ore/testing`'s `mount()`/`cleanup()`.
+- Prefer `queryInShadow`/`queryAllInShadow` over `host.shadowRoot!.querySelector(...)` — the non-null assertion breaks the moment a component is tested with `shadow: false`, while `queryInShadow` degrades to `null` instead of throwing.
+
+### Examples
+
+## Examples
+
+- [Custom Element Interaction](./examples/custom-element-interaction.md)
+- [Waiting for Async Updates](./examples/waiting-for-async-updates.md)
+
+
 ---
 
 ## @vielzeug/clockwork
@@ -12988,17 +13551,15 @@ if (!submission.ok && submission.type === 'validation') {
 
 - Typed field paths with compile-time value inference
 - Explicit validation API: `validate()`, `validate(name)`, and `validate(fields[])`
-- Streaming validation with `validateStream()` — yields each field result as it resolves, read-only
 - Per-connection validation triggers via `connect()` with `ValidationModes` presets
 - `connect()` bindings own independent debounce timers; call `binding.dispose()` on unmount
 - `submit(handler)` — returns `{ ok: true, value }` or `{ ok: false, errors }`
 - Schema integration: pass any `safeParse`-compatible schema directly to `validator`
-- `scope(prefix)` — memoized scoped sub-forms that share parent state with relative field paths
-- `subscribeScoped()` — filtered subscription that only fires on changes within the scope's prefix
-- `snapshot()` / `restore()` — capture and replay complete form state
+- `scope(prefix)` — memoized scoped sub-forms that share parent state with relative field paths; `subscribe()` on a scoped form filters to just that prefix
+- `history.snapshot()` / `history.restore()` — capture and replay complete form state
 - `form.fields.remove(name)` — clean conditional field lifecycle
 - Full array helpers: `append`, `prepend`, `insert`, `remove`, `move`, `swap`, `replace`
-- Explicit synchronous subscriptions: `subscribe`, `subscribeField`, and `subscribeScoped`
+- Explicit synchronous subscriptions: `subscribe` (form or scoped-form state) and `subscribeField` (one field)
 - Stable frozen snapshots for `form.state` and `form.field(name)` (external-store friendly)
 - Explicit touched and error controls: `touch`, `untouch`, `touchAll`, `untouchAll`, `setError`, `resetErrors`
 - Mutation batching with `batch(fn)` and dynamic field validators via `fields.setValidator`
@@ -13030,13 +13591,12 @@ if (!submission.ok && submission.type === 'validation') {
 | `form.get()` / `form.set()`                                                 | Read/write field values by dot-path                            | Sync                                           | `set()` after `dispose()` throws                                                                                      |
 | `form.field()` / `form.state`                                               | Read field and form snapshots                                  | Sync                                           | Returns a stable frozen snapshot; re-read on each subscriber call                                                     |
 | `form.validate()`                                                           | Run validation — all fields, a subset, or a single field       | Async                                          | Each call re-runs validators from scratch                                                                             |
-| `form.validateStream()`                                                     | Streaming validation — yields each field result as it resolves | Async (iterator)                               | Read-only — does not write errors to form state                                                                       |
 | `form.submit()`                                                             | Deterministic submit flow returning a `SubmitResult`           | Async                                          | Rejects if called while already submitting — guard with `form.isSubmitting`                                           |
 | `form.connect()`                                                            | Live field binding with DOM event handlers and live getters    | Sync                                           | Do not destructure — live getters lose context; call `dispose()` on unmount                                           |
 | `form.scope()`                                                              | Memoized scoped sub-form with relative field paths             | Sync                                           | Returns the same object for repeated calls with the same prefix; `state` is scoped — flags reflect only prefix fields |
 | `form.array()`                                                              | Array mutation helpers                                         | Sync                                           | Returns a cached helper — call once and reuse                                                                         |
-| `form.subscribe()` / `form.subscribeField()` / `form.subscribeScoped()`     | Synchronous form and field subscriptions                       | Sync                                           | Callbacks receive frozen snapshots                                                                                    |
-| `form.snapshot()` / `form.restore()`                                        | Capture and replay complete form state                         | Sync                                           | Useful for undo/redo and draft saving                                                                                 |
+| `form.subscribe()` / `form.subscribeField()`                                | Synchronous form and field subscriptions                       | Sync                                           | On a scoped form, `subscribe()` is already prefix-filtered — callbacks receive frozen snapshots                       |
+| `form.history.snapshot()` / `form.history.restore()`                        | Capture and replay complete form state                         | Sync                                           | Useful for undo/redo and draft saving                                                                                 |
 | `form.batch()`                                                              | Group mutations into one notification                          | Sync                                           | Nested `batch()` calls are safe — only the outermost flush notifies                                                   |
 | `form.touch()` / `form.touchAll()`                                          | Mark fields touched                                            | Sync                                           | `touchAll()` marks every key currently in the store                                                                   |
 | `form.setError()` / `form.clearError()` / `form.resetErrors()`              | Manual error management                                        | Sync                                           | `setError()` bypasses validators; cleared on next `validate()` run for that field                                     |
@@ -13349,11 +13909,6 @@ subscribeField>(
   options?: SubscribeOptions,
 ): Unsubscribe
 
-subscribeScoped(
-  listener: (state: FormState) => void,
-  options?: SubscribeOptions,
-): Unsubscribe
-
 type SubscribeOptions = { sync?: boolean };
 type Unsubscribe = () => void;
 ```
@@ -13362,17 +13917,17 @@ Pass `{ sync: true }` to also receive the current snapshot immediately upon subs
 
 Subscriptions fire synchronously whenever the form mutates. Because state snapshots are stable (frozen, reference-equal between mutations), these integrate directly with React `useSyncExternalStore`, Vue `shallowRef`, and the Svelte store protocol.
 
-### subscribeScoped
+### subscribe on a scoped form
 
-`subscribeScoped` is available on both root forms and scoped forms:
+`subscribe` behaves differently depending on which form object it's called on:
 
 - **On a scoped form** — filters `errors`, `touchedFields`, and `validatingFields` to paths within the scope's prefix (remapped to relative paths). The listener is **only called when the scoped projection changes** — mutations outside the scope are suppressed. `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect **only the scoped fields**. `isSubmitting`, `isLoading`, and `submitCount` reflect the full form.
-- **On a root form** — behaves identically to `subscribe`; no filtering is applied.
+- **On a root form** — no filtering is applied; every mutation notifies the listener.
 
 ```ts
 const address = form.scope('address');
 
-address.subscribeScoped((state) => {
+address.subscribe((state) => {
   // state.errors uses relative keys: { city: '...' } not { 'address.city': '...' }
   // only fires when an address.* field changes
   console.log(state.errors, state.touchedFields);
@@ -13399,11 +13954,13 @@ type ArrayField = {
 
 `append()` and `prepend()` initialize the field as a one-item array when its current value is `undefined` or `null`. If the field already holds a non-array, non-nullish value (e.g. written by `set()`), both are a no-op — they never overwrite an existing scalar with an array. `insert()`, `remove()`, `move()`, `swap()`, and `replace()` are all no-ops when the field's current value is not an array.
 
-## Snapshot / Restore
+## History (Snapshot / Restore)
 
 ```ts
-snapshot(): FormSnapshot
-restore(snap: FormSnapshot): void
+history: {
+  snapshot(): FormSnapshot;
+  restore(snap: FormSnapshot): void;
+}
 
 type FormSnapshot = {
   readonly baseline: Partial, unknown>>;
@@ -13415,44 +13972,17 @@ type FormSnapshot = {
 };
 ```
 
-- `snapshot()` — captures the complete form state (values, baseline, errors, touched, dirty, submitCount) into a plain object.
-- `restore(snap)` — replaces all state with the snapshot. Aborts any in-flight validation.
+- `history.snapshot()` — captures the complete form state (values, baseline, errors, touched, dirty, submitCount) into a plain object.
+- `history.restore(snap)` — replaces all state with the snapshot. Aborts any in-flight validation.
 
-Useful for undo/redo, draft saving, and "discard changes" flows:
+Namespaced off the main `Form` surface since it's a distinctly less common operation than reading/writing values — grouped the same way `fields` already groups dynamic-field-lifecycle operations. Useful for undo/redo, draft saving, and "discard changes" flows:
 
 ```ts
-const draft = form.snapshot();
+const draft = form.history.snapshot();
 
 form.set('email', 'changed@example.com');
 
-form.restore(draft); // reverts all changes
-```
-
-## validateStream()
-
-```ts
-validateStream(signal?: AbortSignal): AsyncIterableIterator
-```
-
-Runs all field validators in parallel and yields each result as soon as its validator resolves. If a form-level validator is configured, all keys it returns are yielded last — including `field: '_form'` and any field-specific keys returned by the form validator.
-
-**Read-only**: `validateStream()` does not write to `fieldErrors` or trigger subscriber notifications. Use `validate()` when you want errors applied to form state.
-
-```ts
-for await (const { field, error } of form.validateStream()) {
-  if (error) showInlineError(field, error);
-}
-// After the loop: form.state.errors is unchanged
-```
-
-Pass an `AbortSignal` to cancel the stream:
-
-```ts
-const ctrl = new AbortController();
-for await (const result of form.validateStream(ctrl.signal)) {
-  processResult(result);
-}
-ctrl.abort(); // cancels any remaining in-flight validators
+form.history.restore(draft); // reverts all changes
 ```
 
 ## Baseline and Value Management
@@ -13648,12 +14178,15 @@ type ForgeDevtoolsOptions
 
 // Utility types
 type DeepPartial
-type FlatKeyOf
+type FlatKeyOf              // capped at MAX_TYPED_PATH_DEPTH (5) — see below
 type TypeAtPath
 type ErrorKeyOf
 type ScopedValues
+const MAX_TYPED_PATH_DEPTH  // = 5 — not user-configurable, see rationale below
 ```
 
+`FlatKeyOf` falls back to plain `string` for paths deeper than `MAX_TYPED_PATH_DEPTH` — nothing throws, you just lose autocomplete/type-checking on that specific path (a dev-only console warning fires once per deep key so this is discoverable, not silent). This is a fixed constant, not a per-form generic parameter: it exists purely to protect TypeScript compile time, which doesn't get safer by letting one form's type param regress it for everyone importing that form's module.
+
 ## Errors
 
 Forge exports a small typed error hierarchy, all extending a common `ForgeError` base:
@@ -13905,7 +14438,7 @@ await address.submit((vals) => vals); // validates and submits only address.* fi
 
 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.
+3. Use `address.subscribe(...)` for section UIs — on a scoped form `subscribe` is already prefix-filtered, so sibling/root mutations do not trigger redraws.
 
 **Key characteristics:**
 
@@ -13914,12 +14447,12 @@ await address.submit((vals) => vals); // validates and submits only address.* fi
 
 ### Scoped Subscriptions
 
-`subscribeScoped` delivers form state filtered to the scope's prefix. `errors`, `touchedFields`, and `validatingFields` use relative keys. `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect **only the scoped fields**. The listener **only fires when the scoped projection changes** — mutations outside the prefix are suppressed.
+On a scoped form, `subscribe()` delivers form state filtered to the scope's prefix. `errors`, `touchedFields`, and `validatingFields` use relative keys. `isDirty`, `isValid`, `isTouched`, and `isValidating` reflect **only the scoped fields**. The listener **only fires when the scoped projection changes** — mutations outside the prefix are suppressed. (On a root form, `subscribe()` behaves identically to today — no filtering applies.)
 
 ```ts
 const address = form.scope('address');
 
-address.subscribeScoped((state) => {
+address.subscribe((state) => {
   // state.errors → { city: 'Required' }  (not 'address.city')
   // state.isDirty → true only when an address.* field is dirty
   // does not fire when form.set('name', 'Alice') is called
@@ -13951,29 +14484,18 @@ Snapshot semantics:
 - Reference identity is preserved until a relevant mutation occurs.
 - These are directly compatible with external-store patterns such as React `useSyncExternalStore`, Vue `shallowRef`, and the Svelte store protocol.
 
-## Streaming Validation
+## History (Snapshot / Restore)
 
-`validateStream()` runs all field validators in parallel and yields each result as it resolves. It is **read-only** — it does not write errors to form state. The form-level validator, if set, is yielded last with `field: '_form'`.
+Capture and replay complete form state for undo/redo or "discard changes" flows, via the `history` namespace:
 
 ```ts
-for await (const { field, error } of form.validateStream()) {
-  if (error) showInlineError(field, error);
-}
-// form.state.errors is unchanged after the loop
-```
-
-## Snapshots and Restore
-
-Capture and replay complete form state for undo/redo or "discard changes" flows:
-
-```ts
-const draft = form.snapshot();
+const draft = form.history.snapshot();
 
 // ... user edits ...
 form.set('email', 'different@example.com');
 
 // Revert all changes, including errors, touched, dirty, and submitCount
-form.restore(draft);
+form.history.restore(draft);
 ```
 
 ## Arrays
@@ -14219,7 +14741,6 @@ const formWithSchema = createForm({
 - Field & Form Validation (id: `form-validation`)
 - Schema Integration - safeParse Auto-detection (id: `schema-integration`)
 - Scoped Sub-Forms (scope) (id: `scoped-sub-forms`)
-- Streaming Validation (validateStream) (id: `validate-stream`)
 
 
 ---
@@ -17706,7 +18227,7 @@ effect(() => {
 
 **Category:** i18n
 **Keywords:** internationalization, translations, pluralization, locale, i18n, l10n, async-loading
-**Key exports:** createI18n, createFormatter, hydrateI18n, serializeI18n, validateCatalog, LinguaError, LinguaDisposedError, LinguaInvalidCountError, LinguaCountInVarsError, LinguaMissingLocaleError, LinguaInvalidLocaleError, LinguaNamespaceMissingError (+1 more)
+**Key exports:** createI18n, createFormatter, validateCatalog, LinguaError, LinguaDisposedError, LinguaInvalidCountError, LinguaCountInVarsError, LinguaMissingLocaleError, LinguaInvalidLocaleError, LinguaNamespaceMissingError, LinguaRestoreError
 **Related:** ripple, wayfinder, courier
 
 ### Overview
@@ -17821,7 +18342,7 @@ i18n.getSupportedLocales();
 - Namespace lazy loading: `registerNamespace(ns, factory)` + `loadNamespace(ns, locale?)` — or use `extend(ns, factory, locale?)` as a convenience that does both; deduplicates per `ns + locale`; use for per-route or per-feature keys
 - Scoped translation helpers: `scope(prefix)` returns a `{ fmt, t, tp, has }` helper bound to a key prefix
 - Unified key existence check: `has(key)` returns `true` for leaf keys, branch keys, and pipe-plural base keys in the active fallback chain
-- Loaded-locale predicate: `isLoaded(locale)` returns `true` when a catalog is fully resolved — safe for `serializeI18n()` guards
+- Loaded-locale predicate: `isLoaded(locale)` returns `true` when a catalog is fully resolved — safe for `getState()` guards
 - Registered-locale predicate: `isRegistered(locale)` distinguishes "never configured" from "async loader not yet called"
 - Instance disposal: `dispose()` clears all subscribers and catalog state — prevents memory leaks in route-scoped SPA instances
 - Typed error handling: every thrown/rejected error is `instanceof LinguaError`, with named subclasses (`LinguaDisposedError`, `LinguaMissingLocaleError`, `LinguaNamespaceMissingError`, …) for specific `instanceof` branching
@@ -17830,6 +18351,7 @@ i18n.getSupportedLocales();
 - Deterministic fallback chain using active locale plus configured fallback locales
 - Separate missing handlers: `onMissingKey(key, locale)` and `onMissingVar(varName, key, locale)`
 - Formatting via `createFormatter(source)` — exported from the main entry alongside `createI18n`
+- Automatic dev-mode plural-form validation: every catalog registered or loaded is checked against CLDR rules for its locale, logged via `console.warn` — zero setup, and never bundled into production
 
 ## Documentation
 
@@ -17869,13 +18391,11 @@ i18n.getSupportedLocales();
 | `i18n.loadNamespace()`    | Load a registered namespace for a locale                                           | Async          | Deduplicates concurrent and repeated calls; throws `LinguaNamespaceMissingError` if namespace not registered        |
 | `i18n.isNamespaceLoaded()`  | Check if a namespace is loaded for the active (or given) locale                  | Sync           | Returns `false` if not registered or not yet loaded for this locale                                                |
 | `i18n.isNamespaceRegistered()` | Check if a namespace factory has been registered                              | Sync           | `true` after `registerNamespace()` or `extend()`; `false` before                                                   |
-| `i18n.getState()`         | Extract a serializable snapshot of loaded catalogs + active locale                 | Sync           | Equivalent to `serializeI18n(i18n)` — preferred for public API access                                              |
-| `i18n.restoreState()`     | Hydrate instance from serialized state                                             | Sync           | Equivalent to `hydrateI18n(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                                                            |
+| `i18n.getState()`         | Extract a serializable snapshot of loaded catalogs + active locale                 | Sync           | Loader-only locales are omitted — check `isLoaded()` before calling                                                |
+| `i18n.restoreState()`     | Hydrate instance from serialized state                                             | Sync           | Throws `LinguaRestoreError` if `state.locale` has no catalog                                                       |
 | Error classes             | Named error subclasses (`LinguaDisposedError`, `LinguaMissingLocaleError`, …)      | —              | All runtime errors are `instanceof LinguaError`; use `instanceof` for specific handling                            |
 | `createFormatter()`       | Create a standalone Intl formatter                                                 | Sync           | Available from the main entry or `@vielzeug/lingua/format` — pass a getter `() => i18n.locale` to follow locale changes |
-| `validateCatalog()`       | Check a catalog for missing CLDR plural forms and missing `{count}` interpolations | Sync           | Import from `@vielzeug/lingua/validate` — not for production                                                       |
+| `validateCatalog()`       | Check a catalog for missing CLDR plural forms and missing `{count}` interpolations | Sync           | Import from `@vielzeug/lingua/validate` for CI enforcement — `createI18n()` already runs the same check automatically in dev builds |
 
 ## Package Entry Points
 
@@ -18073,7 +18593,7 @@ Returns `true` if a namespace factory has been registered under `ns` via `regist
 getState(): I18nState
 ```
 
-Extracts a serializable snapshot of all **fully loaded** catalogs and the active locale. Equivalent to `serializeI18n(i18n)` but preferred because it is called directly on the instance without requiring an import.
+Extracts a serializable snapshot of all **fully loaded** catalogs and the active locale.
 
 **Warning:** Only fully resolved catalogs are included. Loader-only locales not yet preloaded are omitted. Use `i18n.isLoaded(locale)` to verify before calling.
 
@@ -18088,13 +18608,15 @@ const state = i18n.getState();
 restoreState(state: I18nState): void
 ```
 
-Hydrates this instance from an `I18nState` produced by `getState()` or `serializeI18n()`. Equivalent to `hydrateI18n(i18n, state)` but preferred because it is called directly on the instance.
+Hydrates this instance from an `I18nState` produced by `getState()`.
 
 - Replaces all catalogs with those from `state`.
 - Sets the active locale to `state.locale`.
 - Clears all namespace loaded-markers so that `extend()` / `loadNamespace()` can re-apply namespaces.
 - Notifies subscribers.
 
+Unlike `register()` and construction, this does **not** run the automatic dev-mode plural-form check (see [`validateCatalog()`](#validatecatalog)) — `state` is assumed to already have been registered, and therefore already checked, once on whatever system produced it.
+
 Throws `LinguaRestoreError` if `state.locale` has no catalog in `state.catalogs`.
 Throws `LinguaDisposedError` if called on a disposed instance.
 
@@ -18218,13 +18740,13 @@ isLoaded(locale: Locale): boolean
 
 Returns `true` if the catalog for `locale` is fully resolved (i.e. not a pending async loader). Returns `false` for unregistered locales, pending loaders, and invalid locale tags — never throws.
 
-Primary use case: guarding `serializeI18n()` in SSR to avoid silently omitting locales that were registered as async loaders but never preloaded.
+Primary use case: guarding `getState()` in SSR to avoid silently omitting locales that were registered as async loaders but never preloaded.
 
 ```ts
 // SSR guard — ensure all locales are loaded before serialising
 const locales = i18n.getSupportedLocales();
 await Promise.all(locales.filter((l) => !i18n.isLoaded(l)).map((l) => i18n.preload(l)));
-const state = serializeI18n(i18n); // now includes all locales
+const state = i18n.getState(); // now includes all locales
 ```
 
 ### `isRegistered()`
@@ -18246,7 +18768,7 @@ Use `isRegistered` + `isLoaded` together to distinguish the three states:
 ```ts
 if (!i18n.isRegistered('fr')) throw new Error('fr locale not configured');
 if (!i18n.isLoaded('fr')) await i18n.preload('fr');
-const state = serializeI18n(i18n); // 'fr' guaranteed to be present
+const state = i18n.getState(); // 'fr' guaranteed to be present
 ```
 
 ### `disposalSignal`
@@ -18330,6 +18852,8 @@ Checks a flat or nested message catalog against CLDR plural rules for `locale`.
 
 Returns an empty array when there are no issues.
 
+**Automatic dev-mode checks:** `createI18n()` already calls this internally, in dev builds only, every time a catalog becomes fully available — at construction (`createI18n({ catalogs })`), via `register()`, or once an async loader resolves — logging any warning through `console.warn`. Call `validateCatalog()` directly only when you want CI to fail the build on a warning rather than just log it; the automatic check already covers everyday authoring feedback with zero setup. The automatic check loads `validate.ts`'s logic as a separate, lazily-fetched chunk — it's never part of your production bundle either way.
+
 **Note:** A branch is treated as a plural branch when any of its child keys is a CLDR form (`zero`, `one`, `two`, `few`, `many`, `other`). A mixed-use branch (e.g. `{ count: 'x', one: 'y' }`) will also be flagged and may produce spurious warnings for non-CLDR sibling keys.
 
 `validateCatalog` also checks for a common authoring error: a form template for `other`, `two`, `few`, or `many` that does not contain `{count}`. Since `tp()` injects `count` automatically, omitting it from a non-singleton form is almost always a mistake. These warnings use `form: ':missing-count'` (e.g. `'other:missing-count'`). The `zero` and `one` forms are exempt — intentionally omitting `{count}` is normal there (e.g. `'No messages'`, `'One message'`).
@@ -18449,7 +18973,7 @@ type I18nState = {
 };
 ```
 
-Produced by `getState()` / `serializeI18n()` and consumed by `restoreState()` / `hydrateI18n()`. Catalogs are stored as flat dot-notation maps.
+Produced by `getState()` and consumed by `restoreState()`. Catalogs are stored as flat dot-notation maps.
 
 ### `NamespaceFactory`
 
@@ -18608,50 +19132,25 @@ type ListFormatOptions = {
 };
 ```
 
-## serializeI18n
+## SSR: `getState()` / `restoreState()`
 
-```ts
-import { serializeI18n } from '@vielzeug/lingua';
-
-serializeI18n(i18n: I18n): I18nState
-```
-
-Serialises the current loaded catalogs and active locale into an `I18nState` object. Use this on the server before embedding state in the HTML response. Loader-only locales that have not been preloaded are silently omitted — call `isLoaded()` to verify all locales are resolved before calling `serializeI18n()`.
+No standalone functions — call these directly on an instance (see [`getState()`](#getstate) / [`restoreState()`](#restorestate) above).
 
 ```ts
 // Server
 const i18n = createI18n({ catalogs: { de: deMessages, en: enMessages }, locale: 'de' });
-const state = serializeI18n(i18n);
+const state = i18n.getState();
 // Embed in the HTML response:
 // window.__I18N__ = ${JSON.stringify(state)}
 ```
 
-## hydrateI18n
-
-```ts
-import { hydrateI18n } from '@vielzeug/lingua';
-
-hydrateI18n(i18n: I18n, state: I18nState): void
-```
-
-Hydrates a client-side instance from server-serialised state. Replaces all catalogs and switches the active locale. Notifies subscribers once after hydration.
-
-Throws `LinguaRestoreError` if `state.locale` has no corresponding entry in `state.catalogs`.
-
 ```ts
 // Client
-const i18n = createI18n();
-hydrateI18n(i18n, window.__I18N__);
+const client = createI18n();
+client.restoreState(window.__I18N__);
 // Catalogs from state are immediately available; no network request needed.
 ```
 
-**Parameters:**
-
-| Parameter | Type        | Description                                |
-| --------- | ----------- | ------------------------------------------ |
-| `i18n`    | `I18n`      | The instance to hydrate.                   |
-| `state`   | `I18nState` | State object produced by `serializeI18n()` |
-
 ## Error Classes
 
 All errors thrown by the `@vielzeug/lingua` runtime extend `LinguaError`. Use `instanceof LinguaError` to catch any lingua error, or `instanceof` the specific subclass for precise handling.
@@ -18679,7 +19178,7 @@ try {
 | `LinguaMissingLocaleError`  | `preload()` / `setLocale()` — locale has no registered source                   |
 | `LinguaInvalidLocaleError`  | Any API receiving an invalid BCP 47 tag                                         |
 | `LinguaNamespaceMissingError` | Namespace requested but not loaded for the current locale                     |
-| `LinguaRestoreError`        | `hydrateI18n()` / `restoreState()` — `state.locale` absent from `state.catalogs` |
+| `LinguaRestoreError`        | `restoreState()` — `state.locale` absent from `state.catalogs` |
 
 ### Usage Guide
 
@@ -18843,7 +19342,9 @@ Without `onMissingKey`, missing keys return the key string. Without `onMissingVa
 
 ## Validating Catalogs
 
-Use `validateCatalog()` during development or CI to detect plural branches that are missing CLDR forms for a target locale. Import it from the dedicated `@vielzeug/lingua/validate` entry — never from the main entry or it will end up in your production bundle.
+`createI18n()` already runs this check automatically in dev builds — every time a catalog becomes available (construction, `register()`, or an async loader resolving), it's checked against CLDR plural rules and any issue is logged via `console.warn`. This costs nothing in production: the check runs behind the same dev-only gate as the rest of `@vielzeug/lingua`'s dev warnings, and the validation logic itself only loads as a separate on-demand chunk, never bundled into your app.
+
+For CI enforcement (failing a build rather than just warning), call `validateCatalog()` directly. Import it from the dedicated `@vielzeug/lingua/validate` entry — never from the main entry or it will end up in your production bundle.
 
 ```ts
 import { validateCatalog } from '@vielzeug/lingua/validate';
@@ -18882,7 +19383,7 @@ Key characteristics:
 
 ## SSR Hydration
 
-Prefer the instance methods `getState()` and `restoreState()` — they are equivalent to `serializeI18n` / `hydrateI18n` but require no extra imports:
+Use the instance methods `getState()` on the server and `restoreState()` on the client:
 
 ```ts
 import { createI18n } from '@vielzeug/lingua';
@@ -18899,7 +19400,7 @@ i18n.restoreState(window.__I18N__);
 // Catalogs from state are immediately available; no network request needed.
 ```
 
-`restoreState()` replaces all catalogs, switches the active locale, clears namespace loaded-markers, and notifies subscribers once. The free functions `serializeI18n()` and `hydrateI18n()` are equivalent alternatives.
+`restoreState()` replaces all catalogs, switches the active locale, clears namespace loaded-markers, and notifies subscribers once.
 
 **Warning:** `getState()` silently omits locales registered as async loaders but not yet preloaded. Use `isLoaded()` to guard:
 
@@ -19044,12 +19545,12 @@ router.subscribe(() => {
 - Keep translation keys flat or one level deep — deeply nested keys are harder to refactor.
 - Set `fallback` to a locale with 100% coverage so missing keys degrade gracefully.
 - Use `extend(ns, factory, locale?)` or `registerNamespace()` + `loadNamespace()` for per-route or per-feature key sets.
-- Use `isLoaded(locale)` before `getState()` / `serializeI18n()` in SSR to avoid silently omitting async-loader locales.
+- Use `isLoaded(locale)` before `getState()` in SSR to avoid silently omitting async-loader locales.
 - Use `isRegistered(locale)` to check if a locale is configured; use `isLoaded(locale)` to check if it is ready.
 - Call `dispose()` on route-level or request-scoped `fork()` instances when they are no longer needed.
 - Use `{ signal }` in `subscribe()` for lifecycle-safe subscriptions; use the returned `Unsubscribe` otherwise.
 - Use `onMissingKey` and `onMissingVar` in development to surface authoring errors early; omit them in production.
-- Import `validateCatalog` from `@vielzeug/lingua/validate` in CI only — never in application code.
+- `createI18n()` already validates plural forms automatically in dev builds — only import `validateCatalog` from `@vielzeug/lingua/validate` directly if you want CI to fail the build on a warning.
 - Share one `i18n` instance per app entry point; avoid creating separate instances per component.
 
 ### Examples
@@ -19083,7 +19584,7 @@ router.subscribe(() => {
 - Pluralization Rules (id: `pluralization`)
 - Preload Pattern (id: `preload-pattern`)
 - scope(), has(), isLoaded(), extend() (id: `scope-bind`)
-- serializeI18n() / hydrateI18n() — SSR hydration (id: `ssr-hydration`)
+- getState() / restoreState() — SSR hydration (id: `ssr-hydration`)
 - createFormatter() — standalone (no createI18n) (id: `standalone-formatter`)
 - Variable Interpolation (id: `variable-interpolation`)
 
@@ -20913,7 +21414,7 @@ define('x-tooltip', {
 
 **Category:** ui-primitives
 **Keywords:** web-components, custom-elements, reactive, templates, signals, lifecycle
-**Key exports:** define, prop, html, css, ref, createContext, inject, injectStrict, provide, onMounted, onCleanup, useEmit (+10 more)
+**Key exports:** define, prop, html, css, ref, createContext, inject, injectStrict, provide, onMounted, onCleanup, useEmit (+15 more)
 **Related:** ripple, refine, orbit
 
 ### Overview
@@ -21035,9 +21536,9 @@ define('my-counter', {
 
 | Import                      | Purpose                                                                       |
 | --------------------------- | ----------------------------------------------------------------------------- |
-| `@vielzeug/ore`            | Core component API and utilities (`define`, `prop`, `html`, `css`, context)  |
+| `@vielzeug/ore`            | Core component API and utilities (`define`, `prop`, `html`, `css`, context), plus the everyday template directives (`each`, `when`, `model`, `classMap`, `styleMap`) |
 | `@vielzeug/ore/devtools`   | `debugFlush` — verbose flush for timing diagnostics (dev only)                |
-| `@vielzeug/ore/directives` | `each`, `when`, `model`, `live`, `raw`, `classMap`, `styleMap`                |
+| `@vielzeug/ore/directives` | The advanced/niche directives (`live`, `raw`) and the custom-directive authoring API (`createDirectiveResult`, `createSpreadObject`) |
 | `@vielzeug/ore/forms`      | `useField`, `createFormContext`, `FORM_CONTEXT_KEY`                          |
 | `@vielzeug/ore/observers`  | `resizeObserver`, `intersectionObserver`, `mediaObserver`, `mutationObserver` |
 | `@vielzeug/ore/testing`    | `mount`, `fire`, `user`, `waitFor`, `cleanup`, and helpers                    |
@@ -21088,9 +21589,9 @@ All symbols below (except `useField`/`createFormContext`, under `@vielzeug/ore/f
 
 | Import                       | Purpose                                                            |
 | ---------------------------- | ------------------------------------------------------------------ |
-| `@vielzeug/ore`            | Core authoring/runtime API                                         |
+| `@vielzeug/ore`            | Core authoring/runtime API, including the everyday template directives (`each`, `when`, `classMap`, `styleMap`, `model`) |
 | `@vielzeug/ore/devtools`   | `debugFlush` — verbose flush for timing diagnostics                |
-| `@vielzeug/ore/directives` | Standalone directive imports (`each`, `when`, `classMap`, …)       |
+| `@vielzeug/ore/directives` | The advanced/niche directives (`raw`, `live`) plus the custom-directive authoring API (`createDirectiveResult`, `createSpreadObject`) |
 | `@vielzeug/ore/forms`      | Form-association helpers (`useField`, `createFormContext`)        |
 | `@vielzeug/ore/observers`  | Resize, intersection, mutation, and media observers                |
 | `@vielzeug/ore/testing`    | DOM-oriented test helpers                                          |
@@ -21344,7 +21845,7 @@ Slot signals update reactively when assigned content changes, including when slo
 - `ref()` — Create a `Signal` element reference. Set to the element via `ref=` in templates.
 - `createId(prefix = 'id')` — Generate a unique incremental string ID (e.g. `'id-1'`, `'id-2'`). Each call returns a new ID — it does not deduplicate by prefix.
 - `createStableId(prefix = 'id')` — Generate a unique ID that also embeds a short random tag shared across all IDs generated in the session (e.g. `'field-a3k21'`), reducing collision risk when multiple app instances run on the same page. Like `createId()`, every call returns a new ID.
-- `resetIdCounter()` — Reset the `createStableId()` counter to 0. Call in test `beforeEach` for deterministic IDs.
+- `resetStableIdCounter()` — Reset the `createStableId()` counter to 0. Call in test `beforeEach` for deterministic IDs. Scoped to `createStableId()` only — `createId()` has no public reset (it's for uniqueness, not cross-test determinism).
 
 ## Form-Associated API
 
@@ -21736,12 +22237,11 @@ define('profile-name', {
 
 ## directives
 
-Ore includes `each`, `classMap`, `styleMap`, `when`, `live`, and `raw` — import them from `@vielzeug/ore/directives`.
+Ore includes `each`, `classMap`, `styleMap`, `when`, and `model` — the everyday template directives most components need, imported directly from `@vielzeug/ore` alongside `define`/`html`. The advanced/niche ones (`live`, `raw`) live behind a separate `@vielzeug/ore/directives` import — see below.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
-import { classMap, each, styleMap, when } from '@vielzeug/ore/directives';
-import { define, html } from '@vielzeug/ore';
+import { classMap, define, each, html, styleMap, when } from '@vielzeug/ore';
 
 define('task-list', {
   setup() {
@@ -21913,8 +22413,7 @@ define('button-wrapper', {
 ## slots and emits
 
 ```ts
-import { when } from '@vielzeug/ore/directives';
-import { define, html, useEmit, useSlots } from '@vielzeug/ore';
+import { define, html, useEmit, useSlots, when } from '@vielzeug/ore';
 
 define('card-with-footer', {
   setup(_props) {
@@ -26841,7 +27340,7 @@ label.dispose();
 - **`.replace(fn)`** — derive next state from current via a function; same-reference return is a no-op
 - **`.reset()`** — restore the initial state baseline
 - **`.lens(path)`** — cached writable `Signal` for a property or dot-path; writes produce an immutable copy
-- **`storeWithHistory(storeOrInit, options?)`** — store with explicit snapshot history; accepts an existing `Store` (not owned) or a plain object; call `.push()` / `.pushNamed(label)` to save checkpoints; `undo()`, `redo()`, `historyAt(i)` returns `HistoryEntry`; reactive `canUndo` / `canRedo`
+- **`storeWithHistory(storeOrInit, options?)`** — store with explicit snapshot history; accepts an existing `Store` (not owned) or a plain object; call `.push()` / `.pushNamed(label)` to save checkpoints; `undo()`, `redo()`, `historyAt(i)` returns `HistoryEntry`; reactive `canUndo` / `canRedo`; import via `@vielzeug/ripple/history`
 - **`getDevToolsHook()`** — returns the currently installed DevTools hook, or `null`; install via `@vielzeug/ripple/devtools`
 - **Glitch-free propagation** — computed signals propagate in dependency order; effects always observe a consistent snapshot
 - **Infinite loop detection** — built-in guard against effect re-entry cycles (100 iterations default)
@@ -26885,7 +27384,7 @@ label.dispose();
 | `scope()`            | Isolated cleanup context                                              | Sync           | Must call `scope.run()` to activate; `dispose()` is LIFO                          |
 | `debugEffect()`      | Effect that logs changed sources before re-run                        | Sync           | Sub-path only: `@vielzeug/ripple/devtools`; tree-shaken from production           |
 | `store()`            | Create object-like state container                                    | Sync           | Store is a branded signal; use `.patch()`, `.replace()`, `.reset()`               |
-| `storeWithHistory()` | Store with snapshot-based undo/redo history                           | Sync           | Call `.push()` / `.pushNamed()` explicitly to record a checkpoint; `maxHistory` caps the buffer |
+| `storeWithHistory()` | Store with snapshot-based undo/redo history                           | Sync           | Sub-path only: `@vielzeug/ripple/history`; call `.push()` / `.pushNamed()` explicitly to record a checkpoint; `maxHistory` caps the buffer |
 | `installDevTools()`  | Install DevTools observation hook                                     | Sync           | Sub-path only: `@vielzeug/ripple/devtools`; pass `null` to uninstall              |
 | `getDevToolsHook()`  | Return current DevTools hook                                          | Sync           | Returns `null` if none installed                                                  |
 | `isSignal()`         | Type guard for any signal/computed/store                              | Sync           | Uses an internal symbol marker, not duck-typing                                   |
@@ -26898,6 +27397,7 @@ label.dispose();
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@vielzeug/ripple`          | All core exports and types                                                                                                                                        |
 | `@vielzeug/ripple/devtools` | `installDevTools`, `debugEffect`, and hook types (`RippleDevToolsHook`, `WriteEvent`, `NamedEvent`, `DisposeEvent`, `MutateEvent`) — dev-only, tree-shaken from prod |
+| `@vielzeug/ripple/history`  | `storeWithHistory` and its types (`StoreWithHistory`, `HistoryEntry`) — tree-shaken unless imported |
 | `@vielzeug/ripple/ssr`      | SSR tracking isolation helpers (`setTrackingProvider`, `createAsyncProvider`, `withProvider`, `runWithProvider`). Node.js only — do not import in browser builds. |
 
 ## Signal Primitives
@@ -27409,6 +27909,8 @@ Creates a reactive store for the given object state. Stores accept `effect()`, `
 
 ### `storeWithHistory`
 
+`storeWithHistory` is exported from `@vielzeug/ripple/history`, not the main entry point. This keeps it tree-shaken from bundles that never use it — for async commands or history over anything other than a `Store`, use `@vielzeug/ledger` instead.
+
 ```ts
 function storeWithHistory(
   storeOrInitial: Store | T,
@@ -27423,6 +27925,8 @@ The initial state is saved as the first snapshot automatically. Snapshots are de
 **Ownership:** when called with an initial value (`T`), the adapter creates and owns the underlying store — `dispose()` also disposes it. When called with an existing `Store`, the adapter does **not** own it — `dispose()` leaves the store alive.
 
 ```ts
+import { storeWithHistory } from '@vielzeug/ripple/history';
+
 const editor = storeWithHistory({ text: '' }, { maxHistory: 100 });
 
 editor.patch({ text: 'hello' }); // direct — StoreWithHistory extends Store
@@ -28051,6 +28555,20 @@ batch(() => {
 
 Nested `batch()` calls merge into the outermost — only one flush occurs.
 
+## Error Handling
+
+Ripple has no single error-handling mode — each primitive picks the surface that fits how it's normally consumed. This is one deliberate spectrum, not three unrelated designs:
+
+| Primitive                      | Failure surface                                 | Why                                                                                       |
+| ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `signal()` / `computed()`       | Throws synchronously                             | Sync code — the caller is already in a position to catch                                   |
+| `effect()`                      | Throws synchronously (rethrown from the run)     | Same as above — no async gap between cause and observation                                 |
+| `watch()`                       | Throws synchronously on an invalid callback return | Programmer-error guard, not a runtime failure mode                                         |
+| `effectAsync()`                 | Routes to `onError` (default: rethrown via `queueMicrotask`) | There's no synchronous caller left to catch by the time the factory rejects — needs an explicit escape hatch |
+| `resource()`                    | Never throws — lands in `ResourceState.status === 'error'` | Failures are render state (show an error UI), not exceptions to unwind past                |
+
+Rule of thumb: if you're inside a synchronous callback, ripple throws (`RippleError` subtypes — see [Errors](#errors)). If the failure only exists after an `await`, ripple gives you a place to observe it instead of throwing into a call stack that's already gone — `onError` for `effectAsync()`, `ResourceState.error` for `resource()`.
+
 ### Usage Guide
 
 ## Basic Usage
@@ -28469,7 +28987,7 @@ effect(() => {
 `storeWithHistory(initial, options?)` wraps a store with snapshot-based undo/redo. Mutations do **not** automatically push snapshots — call `.push()` (or `.pushNamed(label)`) explicitly after each logical change. History navigation with `undo()` and `redo()` never re-runs logic — it replays snapshots directly.
 
 ```ts
-import { storeWithHistory } from '@vielzeug/ripple';
+import { storeWithHistory } from '@vielzeug/ripple/history';
 
 const editor = storeWithHistory({ text: '', cursor: 0 }, { maxHistory: 100 });
 
@@ -29092,7 +29610,6 @@ effect(() => {
 - Scope & onCleanup (id: `scope-cleanup`)
 - Scope — setup shorthand (id: `scope-setup`)
 - Store — patch, lens & computed (id: `store-basics`)
-- Store History — Undo/Redo (id: `store-history`)
 - Store — fine-grained lens reactivity (id: `store-lenses`)
 - Store - Todo List (id: `store-todo-list`)
 - Watch, Lens & Map (id: `watch-and-subscribe`)
@@ -34241,7 +34758,7 @@ define('virtual-list', {
 
 **Category:** data
 **Keywords:** pagination, filtering, sorting, search, data-source, query, remote, local, cursor, infinite-scroll
-**Key exports:** createLocalSource, createRemoteSource, createCursorSource, createInfiniteSource, deriveSource, mergeSource, applyQuery, SourceDisposedError, SourcererError, SourceTimeoutError, sourceState, itemRange (+39 more)
+**Key exports:** createLocalSource, createRemoteSource, createCursorSource, createInfiniteSource, deriveSource, mergeSource, SourcererDisposedError, SourcererError, SourcererTimeoutError, sourceState, itemRange, prefetchSource (+38 more)
 **Related:** courier, ripple, wayfinder
 
 ### Overview
@@ -34341,6 +34858,8 @@ console.log(source.current, source.meta.totalItems);
 | `createCursorSource()`   | Server fetch    | Cursor tokens       | `patch()`, `ready()`, `queryKey`                                    |
 | `createInfiniteSource()` | Server fetch    | Append (`loadMore`) | `patch()`, `loadedPages`, `ready()`, `queryKey`                     |
 
+`@vielzeug/sourcerer/devtools`: opt-in `debugSource()` for `console.debug` state-transition logging across any source type, tree-shaken from production.
+
 ## Documentation
 
 - [Usage Guide](./usage.md)
@@ -34365,10 +34884,9 @@ console.log(source.current, source.meta.totalItems);
 | `createInfiniteSource()`               | Async append-mode (infinite scroll) collection                                                | Async          | `loadMore()` is a no-op once `meta.hasMore` is `false`                            |
 | `deriveSource()`                       | Create a reactive projection of another source                                                | Sync           | Derived source disposes automatically when parent disposes                        |
 | `mergeSource()`                        | Combine multiple sources into one `MergedSource`                                           | Sync           | No `meta` field — returned type is `MergedSource`, not `ReactiveSource`     |
-| `applyQuery()`                         | Apply a partial query patch to any source with `patch()` — fires one fetch                    | Async          | Ignores `page` on Cursor/InfiniteSource — no page concept there                    |
 | `SourcererError`                          | Base error class for all sourcerer errors; carries `message`, `cause`, `context`, `attempt`   | Class          | Extends `Error`; access context via getters, not object spread                    |
-| `SourceTimeoutError`                   | Error thrown when `ready()` times out; has `timeoutMs` property                               | Class          | Extends `SourcererError`; also caught by `instanceof SourcererError`                    |
-| `SourceDisposedError`                  | Error thrown by `ready()` when the source is disposed                                         | Class          | Extends `SourcererError`; catch separately from `SourceTimeoutError` if needed       |
+| `SourcererTimeoutError`                   | Error thrown when `ready()` times out; has `timeoutMs` property                               | Class          | Extends `SourcererError`; also caught by `instanceof SourcererError`                    |
+| `SourcererDisposedError`                  | Error thrown by `ready()` when the source is disposed                                         | Class          | Extends `SourcererError`; catch separately from `SourcererTimeoutError` if needed       |
 | `sourceState()`                        | Derive a discriminated union (`loading`/`error`/`success`) from any source                    | Sync           | Returns `'loading'` when `isSearchPending` is true too                            |
 | `itemRange()`                          | Compute 1-based display range from `SourceMeta`                                               | Sync           | Returns `{ start: 0, end: 0 }` when `totalItems === 0`                            |
 | `prefetchSource()`                     | SSR: fetch first page, return serialisable snapshot; source is disposed immediately           | Async          | **Throws `SourcererError`** if fetch fails                                           |
@@ -34384,11 +34902,12 @@ console.log(source.current, source.meta.totalItems);
 | `SearchOptions`                        | Options bag for `search()` — only field is `immediate?: boolean`                              | Type           | `search()` always returns `Promise`; debounced unless `{ immediate: true }` |
 | `DecodeQueryOptions`                   | Options for `decodeQuery()` — `defaultLimit` and `strict`                                     | Type           | `strict: true` throws on malformed JSON; default silently drops it                |
 
-## Package Entry Point
+## Package Entry Points
 
-| Import                | Purpose                |
-| --------------------- | ---------------------- |
-| `@vielzeug/sourcerer` | Main exports and types |
+| Import                          | Purpose                                                |
+| -------------------------------- | ------------------------------------------------------ |
+| `@vielzeug/sourcerer`            | Main exports and types                                 |
+| `@vielzeug/sourcerer/devtools`   | Opt-in `debugSource()` — tree-shaken from production   |
 
 ## Core Factories
 
@@ -34586,7 +35105,7 @@ All methods return `Promise` unless noted.
 | `patch(changes)`       | Apply one or more query changes atomically — a single recompute for any combination of `limit`, `page`, `search`, `filter`, `sort`                                                    |
 | `prev()`               | Navigate to the previous page (no-op at first page)                                                                                                                                   |
 | `query`                | Current state as a `SourceQuery` (`limit`/`page`/`search` only — filter/sort aren't part of the query snapshot) — read-only snapshot; stable between changes                                                                                                   |
-| `ready(timeout?)`      | Resolve when no async computation is pending and no debounce is scheduled; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError` |
+| `ready(timeout?)`      | Resolve when no async computation is pending and no debounce is scheduled; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError` |
 | `reset()`              | Restore initial config and return to page 1                                                                                                                                           |
 | `search(query, opts?)` | Always returns `Promise`. Debounced by default; pass `{ immediate: true }` to cancel debounce and await immediately                                                             |
 | `setData(data)`        | Replace the dataset and reset to page 1                                                                                                                                               |
@@ -34608,7 +35127,7 @@ All methods return `Promise` except `optimisticUpdate` and `subscribe`.
 | `patch(changes)`                      | Apply one or more query changes atomically — a single fetch for any combination of `limit`, `page`, `search`, `filter`, `sort`                   |
 | `prev()`                              | Previous page (no-op at first page)                                                                                                              |
 | `query`                               | Current state as a `RemoteSourceQuery` — read-only snapshot; stable between changes                                                             |
-| `ready(timeout?)`                     | Resolve when no requests are pending; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError` |
+| `ready(timeout?)`                     | Resolve when no requests are pending; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError` |
 | `refresh()`                           | Re-fetch the current query                                                                                                                       |
 | `reset()`                             | Restore initial config and refetch                                                                                                               |
 | `search(query, opts?)`                | Always returns `Promise`. Debounced by default; pass `{ immediate: true }` to cancel debounce and await immediately                        |
@@ -34640,7 +35159,7 @@ optimisticUpdate(
 | `patch(changes)`       | Apply `limit` and/or `search` atomically — a single fetch; resets cursor position                                                    |
 | `prev()`               | Go back using `prevCursor` (no-op if none)                                                                                             |
 | `query`                | Current state as a `CursorSourceQuery` — read-only snapshot; stable between changes                                                   |
-| `ready(timeout?)`      | Resolve when idle; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError`          |
+| `ready(timeout?)`      | Resolve when idle; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError`          |
 | `refresh()`            | Re-fetch current cursor position                                                                                                       |
 | `reset()`              | Clear cursors and fetch from the start                                                                                                 |
 | `search(query, opts?)` | Always returns `Promise`. Debounced by default; pass `{ immediate: true }` to cancel debounce and await. Resets cursor position. |
@@ -34656,33 +35175,22 @@ optimisticUpdate(
 | `loadMore()`           | Fetch the next page and append to `current` (no-op when `meta.hasMore === false`)                                                                               |
 | `patch(changes)`       | Apply `limit` and/or `search` atomically — **clears items immediately** and fetches from page 1                                                                 |
 | `query`                | Current state as an `InfiniteSourceQuery` — read-only snapshot; stable between changes                                                                         |
-| `ready(timeout?)`      | Resolve when idle; rejects with `SourceDisposedError` if already disposed; optional timeout rejects with `SourceTimeoutError`                                   |
+| `ready(timeout?)`      | Resolve when idle; rejects with `SourcererDisposedError` if already disposed; optional timeout rejects with `SourcererTimeoutError`                                   |
 | `reset()`              | Clear accumulated items **immediately** and fetch from page 1                                                                                                   |
 | `search(query, opts?)` | Always returns `Promise`. Debounced by default — **clears items immediately**; fetch fires after debounce. Pass `{ immediate: true }` to skip the window. |
 | `subscribe(listener)`  | Subscribe; returns unsubscribe                                                                                                                                  |
 
 ## Query Utilities
 
-### `applyQuery`
-
-```ts
-applyQuery): Promise }>(
-  source: T,
-  changes: Partial,
-): Promise
-```
-
-Applies a partial `SourceQuery` (`limit`/`page`/`search`) patch to any source that exposes a compatible `patch()` — delegates directly to `source.patch(changes)`. Fires a single fetch or recomputation for any combination of changed fields. No-op when `changes` is empty or all values are unchanged, per each source's own `patch()` implementation.
-
-`CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation) — their `patch()` only reads `limit`/`search`, so a `page` field from `decodeQuery()` output is silently ignored on those two source types.
+Restoring URL-decoded state onto a source is a direct `source.patch(decodeQuery(...))` call — no separate wrapper function. `CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation), so their `patch()` type only accepts `limit`/`search`; passing a `page` field from `decodeQuery()`'s output to either is a compile-time error, not a silent no-op.
 
 **Example:**
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const q = decodeQuery(new URLSearchParams(location.search));
-await applyQuery(source, q);
+await source.patch(q);
 ```
 
 ---
@@ -34701,13 +35209,13 @@ class SourcererError extends Error {
 }
 ```
 
-Base class for all sourcerer errors. Thrown (and stored as `meta.error`) when a fetch fails. `cause` is the original thrown value. `SourceTimeoutError` and `SourceDisposedError` both extend this class, so a single `instanceof SourcererError` check covers all sourcerer errors.
+Base class for all sourcerer errors. Thrown (and stored as `meta.error`) when a fetch fails. `cause` is the original thrown value. `SourcererTimeoutError` and `SourcererDisposedError` both extend this class, so a single `instanceof SourcererError` check covers all sourcerer errors.
 
-### `SourceTimeoutError`
+### `SourcererTimeoutError`
 
 ```ts
-class SourceTimeoutError extends SourcererError {
-  readonly name = 'SourceTimeoutError';
+class SourcererTimeoutError extends SourcererError {
+  readonly name = 'SourcererTimeoutError';
   readonly timeoutMs: number;
   // message: 'Source.ready() timed out after Nms'
 }
@@ -34715,11 +35223,11 @@ class SourceTimeoutError extends SourcererError {
 
 Thrown by `ready(timeout)` when the timeout expires before the source becomes idle. Also caught by `instanceof SourcererError`.
 
-### `SourceDisposedError`
+### `SourcererDisposedError`
 
 ```ts
-class SourceDisposedError extends SourcererError {
-  readonly name = 'SourceDisposedError';
+class SourcererDisposedError extends SourcererError {
+  readonly name = 'SourcererDisposedError';
   // message: 'Source disposed while waiting for ready()'
 }
 ```
@@ -34899,11 +35407,34 @@ Not generic — `filter`/`sort` on the result are always typed `unknown`. Narrow
 **Example:**
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 // Pass URLSearchParams directly — filter/sort come back as `unknown`, narrow before use
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 20 });
-await applyQuery(source, query);
+await source.patch(query);
+```
+
+## Devtools (`@vielzeug/sourcerer/devtools`)
+
+```ts
+debugSource>(
+  source: { current: readonly unknown[]; meta: TMeta; subscribe(listener: () => void): () => void },
+  options?: { label?: string },
+): () => void
+```
+
+Attaches a `console.debug`-based observer to any source (or `deriveSource`/`mergeSource` result) — logs a line per changed `meta` field (works generically across `SourceMeta`/`CursorMeta`/`InfiniteMeta`) and `current`'s item count. Development-only by default; a no-op when `__SOURCERER_PROD__` is set. Import from the dedicated `/devtools` sub-path so it's tree-shaken from production bundles.
+
+```ts
+import { createRemoteSource } from '@vielzeug/sourcerer';
+import { debugSource } from '@vielzeug/sourcerer/devtools';
+
+const source = createRemoteSource({ fetch: fetchUsers, limit: 20 });
+const detach = debugSource(source, { label: 'users' });
+// [sourcerer:devtools:users] meta.isLoading: false → true
+// [sourcerer:devtools:users] current: 0 → 20 items
+
+detach(); // stop logging
 ```
 
 ## Types
@@ -35007,50 +35538,50 @@ type FetchEvent = Readonly;
 
 See [Error Utilities > `SourcererError`](#sourcererror) above.
 
-### `SourceTimeoutError`
+### `SourcererTimeoutError`
 
 ```ts
-class SourceTimeoutError extends SourcererError {
-  readonly name = 'SourceTimeoutError';
+class SourcererTimeoutError extends SourcererError {
+  readonly name = 'SourcererTimeoutError';
   readonly timeoutMs: number;
   // message: 'Source.ready() timed out after Nms'
 }
 ```
 
-Thrown by `ready(timeout)` when the source has not become idle within the specified `timeout` milliseconds. Check with `instanceof SourceTimeoutError` for typed catch blocks:
+Thrown by `ready(timeout)` when the source has not become idle within the specified `timeout` milliseconds. Check with `instanceof SourcererTimeoutError` for typed catch blocks:
 
 ```ts
-import { SourceTimeoutError } from '@vielzeug/sourcerer';
+import { SourcererTimeoutError } from '@vielzeug/sourcerer';
 
 try {
   await source.ready(5000);
 } catch (err) {
-  if (err instanceof SourceTimeoutError) {
+  if (err instanceof SourcererTimeoutError) {
     console.warn('Source did not load in time:', err.message);
   }
 }
 ```
 
-### `SourceDisposedError`
+### `SourcererDisposedError`
 
 ```ts
-class SourceDisposedError extends SourcererError {
-  readonly name = 'SourceDisposedError';
+class SourcererDisposedError extends SourcererError {
+  readonly name = 'SourcererDisposedError';
   // message: 'Source disposed while waiting for ready()'
 }
 ```
 
-Thrown by `ready()` when `dispose()` is called on the source while a `ready()` call is still pending. Use `instanceof SourceDisposedError` to distinguish it from `SourceTimeoutError`:
+Thrown by `ready()` when `dispose()` is called on the source while a `ready()` call is still pending. Use `instanceof SourcererDisposedError` to distinguish it from `SourcererTimeoutError`:
 
 ```ts
-import { SourceDisposedError, SourceTimeoutError } from '@vielzeug/sourcerer';
+import { SourcererDisposedError, SourcererTimeoutError } from '@vielzeug/sourcerer';
 
 try {
   await source.ready(5000);
 } catch (err) {
-  if (err instanceof SourceDisposedError) {
+  if (err instanceof SourcererDisposedError) {
     // source was torn down — skip cleanup
-  } else if (err instanceof SourceTimeoutError) {
+  } else if (err instanceof SourcererTimeoutError) {
     console.warn('timed out');
   }
 }
@@ -35133,13 +35664,13 @@ await source.reset(); // restore initial filter/sort, reset to page 1
 
 ### Restoring from URL state
 
-Use `applyQuery()` + `decodeQuery()` to restore URL-decoded state in a single atomic recompute.
+Use `decodeQuery()` + `source.patch()` to restore URL-decoded state in a single atomic recompute.
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 10 });
-await applyQuery(source, query);
+await source.patch(query);
 ```
 
 ## Remote Source
@@ -35222,13 +35753,13 @@ await source.refresh(); // re-fetch current query
 
 ### Restoring from URL state
 
-`applyQuery()` is a no-op when `changes` is empty — safe to call on every page load.
+`source.patch()` is a no-op when `changes` is empty — safe to call on every page load.
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 25 });
-await applyQuery(source, query);
+await source.patch(query);
 ```
 
 ### Optimistic updates
@@ -35331,13 +35862,13 @@ await source.reset(); // clear all, restart from page 1
 
 ### Restoring from URL state
 
-Use `applyQuery()` + `decodeQuery()` to restore `limit` and `search`. `patch()` clears accumulated items and refetches from page 1 if any value changed.
+Use `decodeQuery()` + `source.patch()` to restore `limit` and `search`. `patch()` clears accumulated items and refetches from page 1 if any value changed.
 
 ```ts
-import { applyQuery, decodeQuery } from '@vielzeug/sourcerer';
+import { decodeQuery } from '@vielzeug/sourcerer';
 
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 20 });
-await applyQuery(source, { limit: query.limit, search: query.search });
+await source.patch({ limit: query.limit, search: query.search });
 ```
 
 ## Error Handling
@@ -35446,7 +35977,7 @@ const params = encodeQuery(source.query);
 
 // Restore from URLSearchParams directly
 const query = decodeQuery(new URLSearchParams(location.search), { defaultLimit: 25 });
-await applyQuery(source, query);
+await source.patch(query);
 ```
 
 `decodeQuery` is fault-tolerant by default — malformed `filter`/`sort` JSON is silently dropped. Pass `{ strict: true }` to throw instead.
@@ -35607,12 +36138,12 @@ effect(() => {
 - Pass the `AbortSignal` from the `fetch` callback to your HTTP client so superseded requests are cancelled.
 - Call `ready()` in server-side rendering or test setup — not in every render cycle.
 - Always call the unsubscribe function returned by `subscribe()` when the component is torn down.
-- For URL sync, use `decodeQuery()` + `applyQuery()` rather than reconstructing source state from params manually.
+- For URL sync, use `decodeQuery()` + `source.patch()` rather than reconstructing source state from params manually.
 - Use `staleTime` with `refreshInterval` for stale-while-revalidate patterns on dashboards.
 - If you use `optimisticUpdate()`, call `refresh()` after mutation confirmation; it bypasses `staleTime` while optimistic state is active.
 - Only one `optimisticUpdate()` can be active at a time — always handle the thrown error or check before calling.
 - When using `decodeQuery()`, validate the parsed `filter` and `sort` with a type guard before passing to the server — they are returned as-is without runtime validation.
-- For infinite sources, pass `{ limit: query.limit, search: query.search }` to `applyQuery()` for URL state sync — `page` is not restorable since items accumulate across pages.
+- For infinite sources, pass `{ limit: query.limit, search: query.search }` to `source.patch()` for URL state sync — `page` isn't part of `InfiniteSource`'s `patch()` type at all, since items accumulate across pages rather than jumping to one.
 
 ### Examples
 
@@ -35639,7 +36170,7 @@ effect(() => {
 - LocalSource patch() with filter/sort (id: `local-source-patch`)
 - Presets (filterContains, filterEquals, filterRange, sortBy) (id: `presets`)
 - Remote Source (id: `remote-source`)
-- sourceState & SourceTimeoutError (id: `source-state`)
+- sourceState & SourcererTimeoutError (id: `source-state`)
 
 
 ---