@vielzeug/codex 26.10.7 → 26.10.10

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 42 packages. Version: 26.10.6
+> Complete documentation for 42 packages. Version: 26.10.9
 
 ---
 
@@ -105,7 +105,7 @@ console.log(parsed.entries);
 - `archiveAuthHealthSchema` + `AUTH_SCHEMA_VERSION` — typed issuer readiness checked against the issuer DDL stamp
 - `archiveErrorResponseSchema` — the one error envelope, code-typed across the wire
 - `createAuthWorker` — scanner-safe confirmation, live session-version enforcement, durable budgets, metadata export and coordinated erasure
-- `AUTH_ISSUER_SERVICE` — required uncached issuer check after local catalog JWT verification
+- `AUTH_ISSUER_SERVICE` — signing-key retrieval and an uncached issuer check after local catalog JWT verification
 - `ArchiveDerivationError` — distinguishes faulty collection code from invalid submitted content
 - Moderation — reader reports, the operator soft-hide and the report queue, keyed on a verified `roles` claim
 - `worker.tap()` / `issuer.tap()` — typed sanitized runtime events; neither core logs by default
@@ -129,26 +129,26 @@ console.log(parsed.entries);
 
 ## API Overview
 
-| Symbol | Purpose | Execution mode | Common gotcha |
-| --- | --- | --- | --- |
-| `defineArchiveCollection` | Compose validation, indexing, identity and wire schemas | Sync | Invalid content derives to `null`; callback faults throw |
-| `createArchiveWorker` | Build the catalog Worker | Sync | Collection names must be unique |
-| `createAuthWorker` | Build the passwordless issuer | Sync | `AUTH_ARCHIVE` is required |
-| `worker.tap`, `issuer.tap` | Observe sanitized runtime outcomes | Sync | Neither core logs by default; observer exceptions are swallowed |
-| `ArchiveDerivationError` | Identify a collection implementation/runtime fault | Sync | Faults become sanitized 500s, not content-validation 422s |
-| `ARCHIVE_LIMITS` | Shared application bounds | Sync | Page bounds do not cap total exports |
-| `archiveErrorResponseSchema`, `archiveAuthHealthSchema` | Validate error and issuer-health responses | Sync | Unknown error codes and health states reject |
-| `ArchiveError`, `ArchiveDefinitionError` | Public base and invalid-definition errors | Sync | Thrown locally, not transmitted as error objects |
-| `sessionCookieValue` | Compose shared session-cookie attributes | Sync | Deployments must choose `secure` from their environment |
-| `isWellFormedText` | Check control characters and lone surrogates | Sync | Does not trim or impose a length bound |
+| Symbol                                                  | Purpose                                                 | Execution mode | Common gotcha                                                   |
+| ------------------------------------------------------- | ------------------------------------------------------- | -------------- | --------------------------------------------------------------- |
+| `defineArchiveCollection`                               | Compose validation, indexing, identity and wire schemas | Sync           | Invalid content derives to `null`; callback faults throw        |
+| `createArchiveWorker`                                   | Build the catalog Worker                                | Sync           | Collection names must be unique                                 |
+| `createAuthWorker`                                      | Build the passwordless issuer                           | Sync           | `AUTH_ARCHIVE` is required                                      |
+| `worker.tap`, `issuer.tap`                              | Observe sanitized runtime outcomes                      | Sync           | Neither core logs by default; observer exceptions are swallowed |
+| `ArchiveDerivationError`                                | Identify a collection implementation/runtime fault      | Sync           | Faults become sanitized 500s, not content-validation 422s       |
+| `ARCHIVE_LIMITS`                                        | Shared application bounds                               | Sync           | Page bounds do not cap total exports                            |
+| `archiveErrorResponseSchema`, `archiveAuthHealthSchema` | Validate error and issuer-health responses              | Sync           | Unknown error codes and health states reject                    |
+| `ArchiveError`, `ArchiveDefinitionError`                | Public base and invalid-definition errors               | Sync           | Thrown locally, not transmitted as error objects                |
+| `sessionCookieValue`                                    | Compose shared session-cookie attributes                | Sync           | Deployments must choose `secure` from their environment         |
+| `isWellFormedText`                                      | Check control characters and lone surrogates            | Sync           | Does not trim or impose a length bound                          |
 
 ## Package Entry Point
 
-| Import | Purpose |
-| --- | --- |
-| `@vielzeug/archive` | Browser-safe collections, constants, schemas and errors |
-| `@vielzeug/archive/worker` | Catalog factory, issuer-session service binding and event types |
-| `@vielzeug/archive/auth` | Issuer factory and binding types |
+| Import                     | Purpose                                                                     |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `@vielzeug/archive`        | Browser-safe collections, constants, schemas and errors                     |
+| `@vielzeug/archive/worker` | Catalog factory, issuer signing-key/session service binding and event types |
+| `@vielzeug/archive/auth`   | Issuer factory and binding types                                            |
 
 ## Collections
 
@@ -160,14 +160,14 @@ Creates a frozen collection and its contract; malformed names, versions or vocab
 function defineArchiveCollection(definition: ArchiveCollectionDefinition): ArchiveCollection;
 ```
 
-| Parameter | Contract |
-| --- | --- |
-| `name` | Lowercase `[a-z0-9-]{1,32}` |
-| `contentVersion` | Positive safe integer |
-| `payloadSchema` | Spell schema whose output is a stable JSON object |
-| `filters`, `tags` | Optional readonly arrays; omitted means empty vocabulary |
-| `canonicalize` | Optional pure, idempotent, schema-valid normalization |
-| `index` | Derive `filter`, `tags` and searchable `title` without mutating the payload |
+| Parameter         | Contract                                                                    |
+| ----------------- | --------------------------------------------------------------------------- |
+| `name`            | Lowercase `[a-z0-9-]{1,32}`                                                 |
+| `contentVersion`  | Positive safe integer                                                       |
+| `payloadSchema`   | Spell schema whose output is a stable JSON object                           |
+| `filters`, `tags` | Optional readonly arrays; omitted means empty vocabulary                    |
+| `canonicalize`    | Optional pure, idempotent, schema-valid normalization                       |
+| `index`           | Derive `filter`, `tags` and searchable `title` without mutating the payload |
 
 **Returns:** `ArchiveCollection`.
 
@@ -188,14 +188,14 @@ if (derived === null) throw new Error('Invalid recipe');
 console.log(derived.contentHash);
 ```
 
-| Method / property | Result |
-| --- | --- |
-| `derive(raw)` | `Promise` |
-| `contract.entry` | Public entry schema |
-| `contract.ownedEntry`, `ownedEntries` | Owner view with `clientKey` and `hidden` |
-| `contract.page` | Entries and the forward cursor |
+| Method / property                      | Result                                              |
+| -------------------------------------- | --------------------------------------------------- |
+| `derive(raw)`                          | `Promise`                |
+| `contract.entry`                       | Public entry schema                                 |
+| `contract.ownedEntry`, `ownedEntries`  | Owner view with `clientKey` and `hidden`            |
+| `contract.page`                        | Entries and the forward cursor                      |
 | `contract.publishInput`, `updateInput` | Publish and revision-guarded update request schemas |
-| `filters`, `tags` | Frozen vocabulary snapshots |
+| `filters`, `tags`                      | Frozen vocabulary snapshots                         |
 
 `derive` returns `null` for invalid JSON objects, schema-invalid input, invalid titles, too many tags and oversized canonical payloads. Unexpected schema, callback or hashing failures throw `ArchiveDerivationError`. Non-idempotent or schema-invalid canonicalization, unstable schema transformations, index mutation and out-of-vocabulary projections are also derivation faults. Routes map `null` to 422 `invalid-payload` and faults to a sanitized 500 `internal`.
 Schema output that is lossy or no longer JSON is a derivation fault, not invalid
@@ -229,22 +229,28 @@ import { createArchiveWorker, type ArchiveWorkerEnv } from '@vielzeug/archive/wo
 import { s } from '@vielzeug/spell';
 
 const notes = defineArchiveCollection({
-  name: 'notes', contentVersion: 1,
+  name: 'notes',
+  contentVersion: 1,
   payloadSchema: s.object({ title: s.string().min(1).max(128) }),
   index: ({ title }) => ({ title, filter: null, tags: [] }),
 });
 export default createArchiveWorker([notes]);
 ```
 
-| Method | Contract |
-| --- | --- |
-| `fetch(request, env, ctx)` | Returns `Promise` |
+| Method                            | Contract                                                                         |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `fetch(request, env, ctx)`        | Returns `Promise`                                                      |
 | `scheduled(controller, env, ctx)` | Sweeps expired retry keys and revocation tombstones; emits failures and rethrows |
-| `tap(handler, { signal? }?)` | Returns unsubscribe; a pre-aborted signal registers nothing |
+| `tap(handler, { signal? }?)`      | Returns unsubscribe; a pre-aborted signal registers nothing                      |
 
 `AUTH_ISSUER_SERVICE` is a required `fetch`-shaped service binding to the issuer.
+The catalog fetches signing keys from the configured `JWT_JWKS_URL` through that
+binding, not through global `fetch`. The URL still selects the issuer's JWKS
+route and must satisfy the environment's transport rules. Key requests use GET
+without a session cookie and do not follow redirects.
 The catalog verifies the signed JWT locally, then asks the issuer to validate its
-current account session version. It does not cache successful issuer verdicts.
+current account session version. JOSE caches signing keys; the catalog does not
+cache successful issuer session verdicts.
 If the service exchange fails or exceeds its fixed 5000 ms timeout (body decoding
 included), the catalog returns `503 auth-unavailable`; the timeout does not cancel
 work already started by the issuer.
@@ -295,11 +301,11 @@ import { createAuthWorker, type AuthWorkerEnv } from '@vielzeug/archive/auth';
 export default createAuthWorker();
 ```
 
-| Method | Contract |
-| --- | --- |
-| `fetch(request, env, ctx?)` | Returns `Promise` |
+| Method                             | Contract                                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| `fetch(request, env, ctx?)`        | Returns `Promise`                                                     |
 | `scheduled(controller, env, ctx?)` | Removes expired links, closed send windows and unverified unreferenced accounts |
-| `tap(handler, { signal? }?)` | Observes typed `AuthEvent`; returns unsubscribe; pre-aborted signals are inert |
+| `tap(handler, { signal? }?)`       | Observes typed `AuthEvent`; returns unsubscribe; pre-aborted signals are inert  |
 
 Magic links expire after 15 minutes and work once. The durable per-email budget allows three sends per hour; consumption, expiration and send failure do not refund it. Ordinary sessions last at most 30 days. Operator sessions use `OPERATOR_SESSION_MAX_AGE_SECONDS` (900 seconds). `OPERATOR_EMAILS` controls newly minted role claims.
 
@@ -326,12 +332,44 @@ contract; `/auth` exports the factory and issuer binding types.
 Opening a magic link performs a safe GET that displays a click-confirmation page,
 not redemption. Only a marked POST from an exact allowed origin or
 `PUBLIC_ORIGIN` consumes `{ token }` and returns 204 with the session cookie. The
-confirmation page navigates to `/signed-in` after success; the POST is not a
-redirect. Confirmation responses are `no-store` with no-referrer and restrictive
-CSP; the page removes the token from the address bar and loads no external assets.
+confirmation page navigates to the fixed `${PUBLIC_ORIGIN}/signed-in` destination;
+your application must serve that page because the issuer serves only the
+confirmation endpoint. The POST is not a redirect. Confirmation responses are
+`no-store` with no-referrer and a restrictive CSP; inline script and styles
+require a fresh response nonce, with no
+`unsafe-inline`. The page removes the token from the address bar before rendering
+the controls and loads no external assets. `APP_NAME` supplies escaped page and
+email branding; the confirmation has keyboard focus, live status announcements,
+44-pixel minimum action heights, a warm near-white paper and copper light scheme,
+a deep neutral dark scheme, serif headings, sans-serif body text and reduced-motion
+styles. Without JavaScript, it links to `${PUBLIC_ORIGIN}/account` as “Request a
+new sign-in link” but cannot redeem a link.
 GET displays confirmation for any syntactically valid token, including a used
 token; only POST establishes whether the link is still redeemable. POST accepts
-exactly `{ token }` and rejects query parameters.
+exactly `{ token }` and rejects query parameters. With valid issuer configuration,
+invalid or missing GET tokens, duplicate token parameters and unsupported query
+parameters return HTTP 400 with branded HTML recovery, not a JSON error. POST
+errors retain the JSON `ArchiveErrorResponse` schema and their HTTP status.
+
+The button announces pending sign-in and blocks duplicate submissions. HTTP 410
+replaces it with a new-link action; HTTP 400 also disables resubmission. Every
+failure offers the fixed `${PUBLIC_ORIGIN}/account` recovery link labelled
+“Request a new sign-in link”. Like `/signed-in`, `/account` is a fixed reference
+issuer convention: the application must serve its sign-in entry there, not the issuer.
+Recovery is secondary while retry remains possible, and becomes the primary action
+for invalid or expired links. It replaces the footer exit link to avoid duplicate
+navigation. The initial “Back to app” footer links to `${PUBLIC_ORIGIN}/`.
+HTTP 429 delays manual retry using unsigned integer seconds or a syntactically valid
+HTTP-date `Retry-After`, rounded up
+and bounded to 1-300 seconds (30 seconds for missing or invalid values). HTTP 503
+and network failures offer explicit retry; no failure starts an automatic request.
+All returned response bodies, including discarded stale responses, are cancelled
+without delaying recovery; cancellation failures are ignored. Each attempt aborts
+its controller on completion. Stalled requests abort after 15 seconds with a
+timeout-specific message, distinct from connection failures. Leaving the page aborts its request and
+clears timers; bfcache restoration resumes only the remaining cooldown, not a
+request. Navigation after exact 204 success is fixed at
+`${PUBLIC_ORIGIN}/signed-in`; query input never controls either destination.
 
 The issuer never logs directly. `tap` emits sanitized request and scheduled
 outcomes; observer failures are swallowed, abort detaches the observer and failed
@@ -341,39 +379,39 @@ scheduled work emits then rethrows. `AuthDiagnostic` reports only a category.
 
 Every route below is mounted under `/api/v1`. Mutation guards require an exact allowed `Origin` and `x-archive-request: 1`. Registered publishers pin `x-archive-publisher` to the identity captured when preparing private requests. The header is a freshness precondition, not authority.
 
-| Route | Contract |
-| --- | --- |
-| `GET /health` | Public catalog readiness; 200 `ok` or 503 `degraded` |
-| `POST /sign-out` | Catalog-local sign-out; `{ ok: true }` and expired session cookie, without issuer access |
-| `GET /collections/:collection` | Collection metadata |
-| `GET /collections/:collection/entries` | `author`, `filter`, `tag`, `search`, `sort`, `cursor`, `limit`; forward entry page |
-| `POST /collections/:collection/entries` | `{ clientKey, payload }`; 201 create or 200 replay |
-| `GET /collections/:collection/entries/:id` | Public entry; always `no-store` |
-| `PUT /collections/:collection/entries/:id` | Owner-only `{ expectedRevision, payload }` |
-| `DELETE /collections/:collection/entries/:id` | Owner or operator removal; 204 |
-| `PUT` / `DELETE /collections/:collection/entries/:id/like` | Like / unlike visible entries only; guarded write and response; like-state response |
-| `POST /collections/:collection/entries/:id/report` | `{ reason }`; idempotent per entry/reporter; 204 |
-| `PUT` / `DELETE /collections/:collection/entries/:id/hidden` | Operator hide / unhide; 204 |
-| `GET /collections/:collection/reports` | Operator page; `status=unresolved` (default) or `resolved`, `cursor`, `limit` |
-| `PUT /collections/:collection/reports/:id/resolved` | Operator resolves report by its unique report ID; idempotent 204 |
-| `DELETE /publishers/:id` | Operator erases Archive profile; not issuer account |
-| `GET /moderation-log` | Operator forward page; `cursor`, `limit` |
-| `GET` / `POST` / `PUT /me` | Identity, register with optional `{ name }`, rename with required `{ name }` |
-| `DELETE /me` | Profile-only cascade; 204; does not clear cookie |
-| `DELETE /me/account` | Revoke issuer/subject and atomically erase profile; 204; coordinated issuer-erasure seam |
-| `GET /me/publications?collection=…` | Owner entries including hidden state and retry keys |
-| `GET /me/likes` | Forward page `{ ids, cursor }`; `cursor`, `limit` |
-| `GET /me/likes?ids=…` | Subset lookup `{ ids }`; at most `likeStateIds` input IDs |
-| `GET /me/reports` | Own forward report page across collections; `cursor`, `limit` |
-| `GET /auth/health` | Public issuer readiness; typed `AuthHealth`, 200 `ok` or 503 `degraded`; no email or peer probe |
-| `GET /auth/session` | Internal issuer-session check for the catalog service binding; exact `{ ok: true }`, `no-store`, no PII; 401 for an invalid, stale or absent-account session |
-| `POST /auth/sign-out-all` | Requires marker, exact origin, session and captured `ACCOUNT_HEADER`; atomically increments `session_version`, deletes outstanding links, preserves account and catalog data; 200 `{ ok: true }` with an expired cookie only on durable success |
-| `GET /auth/jwks.json` | Active and configured retired public verification keys |
-| `POST /auth/sign-in` | `{ email }` (trimmed and lowercased); 202 `{ ok: true }` |
-| `GET /auth/verify?token=…` | Safe no-store click-confirmation page; no token consumption or session change |
-| `POST /auth/verify` | JSON `{ token }`, marker and exact allowed origin or `PUBLIC_ORIGIN`; consume once; 204 with session cookie |
-| `GET /auth/account` | `{ id, email, createdAt, lastSignInAt }`; no tokens or budget data |
-| `DELETE /auth/account` | Requires `ACCOUNT_HEADER` with the captured issuer account UUID; catalog `/me/account` via `AUTH_ARCHIVE`, require exact 204, then issuer user and cookie clear; 204 |
+| Route                                                        | Contract                                                                                                                                                                                                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /health`                                                | Public catalog readiness; 200 `ok` or 503 `degraded`                                                                                                                                                                                            |
+| `POST /sign-out`                                             | Catalog-local sign-out; `{ ok: true }` and expired session cookie, without issuer access                                                                                                                                                        |
+| `GET /collections/:collection`                               | Collection metadata                                                                                                                                                                                                                             |
+| `GET /collections/:collection/entries`                       | `author`, `filter`, `tag`, `search`, `sort`, `cursor`, `limit`; forward entry page                                                                                                                                                              |
+| `POST /collections/:collection/entries`                      | `{ clientKey, payload }`; 201 create or 200 replay                                                                                                                                                                                              |
+| `GET /collections/:collection/entries/:id`                   | Public entry; always `no-store`                                                                                                                                                                                                                 |
+| `PUT /collections/:collection/entries/:id`                   | Owner-only `{ expectedRevision, payload }`                                                                                                                                                                                                      |
+| `DELETE /collections/:collection/entries/:id`                | Owner or operator removal; 204                                                                                                                                                                                                                  |
+| `PUT` / `DELETE /collections/:collection/entries/:id/like`   | Like / unlike visible entries only; guarded write and response; like-state response                                                                                                                                                             |
+| `POST /collections/:collection/entries/:id/report`           | `{ reason }`; idempotent per entry/reporter; 204                                                                                                                                                                                                |
+| `PUT` / `DELETE /collections/:collection/entries/:id/hidden` | Operator hide / unhide; 204                                                                                                                                                                                                                     |
+| `GET /collections/:collection/reports`                       | Operator page; `status=unresolved` (default) or `resolved`, `cursor`, `limit`                                                                                                                                                                   |
+| `PUT /collections/:collection/reports/:id/resolved`          | Operator resolves report by its unique report ID; idempotent 204                                                                                                                                                                                |
+| `DELETE /publishers/:id`                                     | Operator erases Archive profile; not issuer account                                                                                                                                                                                             |
+| `GET /moderation-log`                                        | Operator forward page; `cursor`, `limit`                                                                                                                                                                                                        |
+| `GET` / `POST` / `PUT /me`                                   | Identity, register with optional `{ name }`, rename with required `{ name }`                                                                                                                                                                    |
+| `DELETE /me`                                                 | Profile-only cascade; 204; does not clear cookie                                                                                                                                                                                                |
+| `DELETE /me/account`                                         | Revoke issuer/subject and atomically erase profile; 204; coordinated issuer-erasure seam                                                                                                                                                        |
+| `GET /me/publications?collection=…`                          | Owner entries including hidden state and retry keys                                                                                                                                                                                             |
+| `GET /me/likes`                                              | Forward page `{ ids, cursor }`; `cursor`, `limit`                                                                                                                                                                                               |
+| `GET /me/likes?ids=…`                                        | Subset lookup `{ ids }`; at most `likeStateIds` input IDs                                                                                                                                                                                       |
+| `GET /me/reports`                                            | Own forward report page across collections; `cursor`, `limit`                                                                                                                                                                                   |
+| `GET /auth/health`                                           | Public issuer readiness; typed `AuthHealth`, 200 `ok` or 503 `degraded`; no email or peer probe                                                                                                                                                 |
+| `GET /auth/session`                                          | Internal issuer-session check for the catalog service binding; exact `{ ok: true }`, `no-store`, no PII; 401 for an invalid, stale or absent-account session                                                                                    |
+| `POST /auth/sign-out-all`                                    | Requires marker, exact origin, session and captured `ACCOUNT_HEADER`; atomically increments `session_version`, deletes outstanding links, preserves account and catalog data; 200 `{ ok: true }` with an expired cookie only on durable success |
+| `GET /auth/jwks.json`                                        | Active and configured retired public verification keys                                                                                                                                                                                          |
+| `POST /auth/sign-in`                                         | `{ email }` (trimmed and lowercased); 202 `{ ok: true }`                                                                                                                                                                                        |
+| `GET /auth/verify?token=…`                                   | Safe no-store click-confirmation HTML; with valid issuer configuration, invalid queries return 400 recovery HTML; no token consumption or session change                                                                                                                                                   |
+| `POST /auth/verify`                                          | JSON `{ token }`, marker and exact allowed origin or `PUBLIC_ORIGIN`; consume once; 204 with session cookie                                                                                                                                     |
+| `GET /auth/account`                                          | `{ id, email, createdAt, lastSignInAt }`; no tokens or budget data                                                                                                                                                                              |
+| `DELETE /auth/account`                                       | Requires `ACCOUNT_HEADER` with the captured issuer account UUID; catalog `/me/account` via `AUTH_ARCHIVE`, require exact 204, then issuer user and cookie clear; 204                                                                            |
 
 Forward pages are newest first with opaque context-bound keyset cursors. Keep the same query context when following a cursor; end at `cursor: null`. `maxPageSize` bounds each page, not the total number of liked IDs, reports or audit actions you can export. The subset-like query is not a page and cannot combine `ids` with `cursor` or `limit`.
 
@@ -404,8 +442,10 @@ clear the cookie. This revokes all sessions, including the caller's, after a
 successful response. Requests authorized before revocation may finish; there is
 no cross-database transactional or in-flight cancellation guarantee.
 
-The catalog requires `AUTH_ISSUER_SERVICE`, a service binding to the issuer. After
-local JWT signature/claims verification, it requests
+The catalog requires `AUTH_ISSUER_SERVICE`, a service binding to the issuer for
+both JWKS retrieval and live session validation. Signing-key retrieval uses
+`JWT_JWKS_URL` through the binding, so it does not depend on a public same-zone
+Worker-to-Worker fetch. After local JWT signature/claims verification, it requests
 `GET /api/v1/auth/session` through that binding on every private request. Only a
 strictly validated 401 `unauthenticated` remains a 401. Malformed, unexpected,
 provider and 5xx responses become 503 `auth-unavailable`; there is no authority
@@ -427,37 +467,37 @@ Effective hide, unhide, operator removal and publisher erasure append audit rows
 
 ## Constants and Schemas
 
-| Export | Value or parsed output |
-| --- | --- |
-| `ARCHIVE_CONTRACT_VERSION`, `ARCHIVE_SCHEMA_VERSION` | Both debut at `1`; wire and storage versions are independent |
-| `AUTH_SCHEMA_VERSION` | `1`; issuer DDL stamp checked by `/auth/health` |
-| `ARCHIVE_COLLECTION_NAME_PATTERN` | `/^[a-z0-9-]{1,32}$/` |
-| `ARCHIVE_OPERATOR_ROLE` | `'archive-operator'` |
-| `SESSION_COOKIE_NAME`, `SESSION_COOKIE_PATH` | `'archive_session'`, `'/api/v1'` |
-| `SESSION_MAX_AGE_SECONDS` | `2592000` |
-| `OPERATOR_SESSION_MAX_AGE_SECONDS` | `900`; shared root contract |
-| `ACCOUNT_HEADER` | `'X-Archive-Account'`; required issuer-account UUID on coordinated erasure |
-| `PUBLISHER_HEADER`, `REQUEST_MARKER_HEADER` | `'x-archive-publisher'`, `'x-archive-request'` |
-| `ILL_FORMED_TEXT`, `isWellFormedText(value: string): boolean` | Reject control characters and lone UTF-16 surrogates |
-| `uuidSchema`, `isoTimestampSchema`, `hex64Schema` | UUID, ISO timestamp, lowercase SHA-256 hex strings |
-| `archiveAliasSchema` | Trimmed, well-formed alias of at most 24 characters |
-| `archiveAuthorSchema` | `{ id: string; name: string }` |
-| `archiveIdentitySchema` | `ArchiveIdentity` |
-| `archiveAccountSchema` | `ArchiveAccount`; issuer metadata, excluding private fields |
-| `archiveLimitsSchema` | All numeric `ARCHIVE_LIMITS` fields |
-| `archiveHealthSchema` | `ArchiveHealth` |
-| `archiveAuthHealthSchema` | `AuthHealth` |
-| `archiveErrorResponseSchema` | `ArchiveErrorResponse` |
-| `archiveOkSchema` | `{ ok: true }` |
-| `archiveCollectionMetaSchema` | `ArchiveCollectionMeta` |
-| `archiveLikedIdsSchema` | `{ ids: string[] }` subset response |
-| `archiveLikesPageSchema` | `ArchiveLikesPage` |
-| `archiveLikeStateSchema` | `{ id: string; likeCount: number; liked: boolean }` |
-| `archiveReportsSchema`, `archiveOwnReportsSchema` | `ArchiveReports`, `ArchiveOwnReports` |
-| `archiveModerationLogSchema` | `ArchiveModerationLog` |
-| `archiveSortSchema` | `ArchiveSort` |
-| `ARCHIVE_ERROR_CODES` | Values of `ArchiveErrorCode` below |
-| `ARCHIVE_MODERATION_ACTIONS` | `['hide', 'unhide', 'remove', 'erase-publisher']` |
+| Export                                                        | Value or parsed output                                                     |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `ARCHIVE_CONTRACT_VERSION`, `ARCHIVE_SCHEMA_VERSION`          | Both debut at `1`; wire and storage versions are independent               |
+| `AUTH_SCHEMA_VERSION`                                         | `1`; issuer DDL stamp checked by `/auth/health`                            |
+| `ARCHIVE_COLLECTION_NAME_PATTERN`                             | `/^[a-z0-9-]{1,32}$/`                                                      |
+| `ARCHIVE_OPERATOR_ROLE`                                       | `'archive-operator'`                                                       |
+| `SESSION_COOKIE_NAME`, `SESSION_COOKIE_PATH`                  | `'archive_session'`, `'/api/v1'`                                           |
+| `SESSION_MAX_AGE_SECONDS`                                     | `2592000`                                                                  |
+| `OPERATOR_SESSION_MAX_AGE_SECONDS`                            | `900`; shared root contract                                                |
+| `ACCOUNT_HEADER`                                              | `'X-Archive-Account'`; required issuer-account UUID on coordinated erasure |
+| `PUBLISHER_HEADER`, `REQUEST_MARKER_HEADER`                   | `'x-archive-publisher'`, `'x-archive-request'`                             |
+| `ILL_FORMED_TEXT`, `isWellFormedText(value: string): boolean` | Reject control characters and lone UTF-16 surrogates                       |
+| `uuidSchema`, `isoTimestampSchema`, `hex64Schema`             | UUID, ISO timestamp, lowercase SHA-256 hex strings                         |
+| `archiveAliasSchema`                                          | Trimmed, well-formed alias of at most 24 characters                        |
+| `archiveAuthorSchema`                                         | `{ id: string; name: string }`                                             |
+| `archiveIdentitySchema`                                       | `ArchiveIdentity`                                                          |
+| `archiveAccountSchema`                                        | `ArchiveAccount`; issuer metadata, excluding private fields                |
+| `archiveLimitsSchema`                                         | All numeric `ARCHIVE_LIMITS` fields                                        |
+| `archiveHealthSchema`                                         | `ArchiveHealth`                                                            |
+| `archiveAuthHealthSchema`                                     | `AuthHealth`                                                               |
+| `archiveErrorResponseSchema`                                  | `ArchiveErrorResponse`                                                     |
+| `archiveOkSchema`                                             | `{ ok: true }`                                                             |
+| `archiveCollectionMetaSchema`                                 | `ArchiveCollectionMeta`                                                    |
+| `archiveLikedIdsSchema`                                       | `{ ids: string[] }` subset response                                        |
+| `archiveLikesPageSchema`                                      | `ArchiveLikesPage`                                                         |
+| `archiveLikeStateSchema`                                      | `{ id: string; likeCount: number; liked: boolean }`                        |
+| `archiveReportsSchema`, `archiveOwnReportsSchema`             | `ArchiveReports`, `ArchiveOwnReports`                                      |
+| `archiveModerationLogSchema`                                  | `ArchiveModerationLog`                                                     |
+| `archiveSortSchema`                                           | `ArchiveSort`                                                              |
+| `ARCHIVE_ERROR_CODES`                                         | Values of `ArchiveErrorCode` below                                         |
+| `ARCHIVE_MODERATION_ACTIONS`                                  | `['hide', 'unhide', 'remove', 'erase-publisher']`                          |
 
 ### `sessionCookieValue`
 
@@ -467,11 +507,11 @@ Composes a session cookie using the shared security attributes.
 function sessionCookieValue(token: string, options: { maxAgeSeconds: number; secure: boolean }): string;
 ```
 
-| Parameter | Contract |
-| --- | --- |
-| `token` | Session token, or empty string when clearing |
-| `options.maxAgeSeconds` | Cookie lifetime; `0` clears it |
-| `options.secure` | Include `Secure` for production HTTPS |
+| Parameter               | Contract                                     |
+| ----------------------- | -------------------------------------------- |
+| `token`                 | Session token, or empty string when clearing |
+| `options.maxAgeSeconds` | Cookie lifetime; `0` clears it               |
+| `options.secure`        | Include `Secure` for production HTTPS        |
 
 **Returns:** the `Set-Cookie` value with `HttpOnly`, `SameSite=Strict`, the shared path and optional `Secure`.
 
@@ -510,11 +550,22 @@ console.log(isWellFormedText('Rice'), isWellFormedText('\u0000'));
 
 ```ts
 const limits = {
-  aliasChars: 24, cursorChars: 1024, idempotencyRetentionMs: 172800000,
-  likeStateIds: 50, maxPageSize: 50, maxPublications: 50, pageSize: 10,
-  payloadBytes: 8192, publicCacheSeconds: 30, reportReasonChars: 256,
-  requestBytes: 12288, searchChars: 64, searchTerms: 6, tagsPerEntry: 16,
-  titleChars: 128, vocabChars: 64,
+  aliasChars: 24,
+  cursorChars: 1024,
+  idempotencyRetentionMs: 172800000,
+  likeStateIds: 50,
+  maxPageSize: 50,
+  maxPublications: 50,
+  pageSize: 10,
+  payloadBytes: 8192,
+  publicCacheSeconds: 30,
+  reportReasonChars: 256,
+  requestBytes: 12288,
+  searchChars: 64,
+  searchTerms: 6,
+  tagsPerEntry: 16,
+  titleChars: 128,
+  vocabChars: 64,
 };
 ```
 
@@ -585,16 +636,35 @@ type ArchiveSort = 'liked' | 'recent';
 type ArchiveDerivationStage = 'canonicalize' | 'hash' | 'index' | 'schema';
 type ArchiveIdentity = { id: string; name: string; operator: boolean } | null;
 type ArchiveAccount = {
-  id: string; email: string; createdAt: string; lastSignInAt: string | null;
+  id: string;
+  email: string;
+  createdAt: string;
+  lastSignInAt: string | null;
 };
 type ArchiveCollectionMeta = { filters: string[]; name: string; tags: string[] };
 type ArchiveLikesPage = { cursor: string | null; ids: string[] };
 type ArchiveErrorCode =
-  | 'account-changed' | 'auth-unavailable' | 'bad-request' | 'conflict' | 'forbidden' | 'gone'
-  | 'internal' | 'invalid-payload' | 'likes-disabled' | 'method-not-allowed'
-  | 'not-found' | 'publisher-changed' | 'publishing-disabled' | 'quota'
-  | 'rate-limited' | 'record-unavailable' | 'timeout' | 'too-large'
-  | 'unauthenticated' | 'unavailable' | 'unsupported-media';
+  | 'account-changed'
+  | 'auth-unavailable'
+  | 'bad-request'
+  | 'conflict'
+  | 'forbidden'
+  | 'gone'
+  | 'internal'
+  | 'invalid-payload'
+  | 'likes-disabled'
+  | 'method-not-allowed'
+  | 'not-found'
+  | 'publisher-changed'
+  | 'publishing-disabled'
+  | 'quota'
+  | 'rate-limited'
+  | 'record-unavailable'
+  | 'timeout'
+  | 'too-large'
+  | 'unauthenticated'
+  | 'unavailable'
+  | 'unsupported-media';
 type ArchiveErrorResponse = {
   error: { code: ArchiveErrorCode; message: string; requestId: string };
 };
@@ -602,11 +672,22 @@ type ArchiveHealth = {
   dbSchemaVersion: number | null;
   features: { likes: boolean; publishing: boolean };
   limits: {
-    aliasChars: number; cursorChars: number; idempotencyRetentionMs: number;
-    likeStateIds: number; maxPageSize: number; maxPublications: number;
-    pageSize: number; payloadBytes: number; publicCacheSeconds: number;
-    reportReasonChars: number; requestBytes: number; searchChars: number;
-    searchTerms: number; tagsPerEntry: number; titleChars: number; vocabChars: number;
+    aliasChars: number;
+    cursorChars: number;
+    idempotencyRetentionMs: number;
+    likeStateIds: number;
+    maxPageSize: number;
+    maxPublications: number;
+    pageSize: number;
+    payloadBytes: number;
+    publicCacheSeconds: number;
+    reportReasonChars: number;
+    requestBytes: number;
+    searchChars: number;
+    searchTerms: number;
+    tagsPerEntry: number;
+    titleChars: number;
+    vocabChars: number;
   };
   schemaVersion: 1;
   status: 'ok' | 'degraded';
@@ -621,23 +702,36 @@ type AuthHealth = {
 type ArchiveReports = {
   cursor: string | null;
   reports: {
-    id: string; createdAt: string; entryId: string; entryTitle: string;
-    reason: string; reporter: { id: string; name: string }; resolvedAt: string | null;
+    id: string;
+    createdAt: string;
+    entryId: string;
+    entryTitle: string;
+    reason: string;
+    reporter: { id: string; name: string };
+    resolvedAt: string | null;
   }[];
 };
 type ArchiveOwnReports = {
   cursor: string | null;
   reports: {
-    collection: string; createdAt: string; entryId: string; id: string;
-    reason: string; resolvedAt: string | null;
+    collection: string;
+    createdAt: string;
+    entryId: string;
+    id: string;
+    reason: string;
+    resolvedAt: string | null;
   }[];
 };
 type ArchiveModerationAction = 'hide' | 'unhide' | 'remove' | 'erase-publisher';
 type ArchiveModerationLog = {
   cursor: string | null;
   actions: {
-    id: string; action: ArchiveModerationAction; collection: string | null;
-    createdAt: string; operatorId: string; targetId: string;
+    id: string;
+    action: ArchiveModerationAction;
+    collection: string | null;
+    createdAt: string;
+    operatorId: string;
+    targetId: string;
   }[];
 };
 ```
@@ -736,7 +830,7 @@ interface AuthWorkerHandler {
   tap(handler: (event: AuthEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
 }
 type AuthDiagnostic = {
-  readonly kind: 'configuration' | 'database' | 'email' | 'catalog' | 'internal';
+  readonly kind: 'configuration' | 'database' | 'schema' | 'email' | 'catalog' | 'internal';
 };
 type AuthEvent =
   | {
@@ -766,10 +860,10 @@ window resets atomically on a later sign-in request.
 
 ## Errors
 
-| Exported class | Trigger | Properties |
-| --- | --- | --- |
-| `ArchiveError` | Base for public package errors | `name`, `message`, optional `cause` |
-| `ArchiveDefinitionError` | Invalid collection definition or duplicate registered collection names | Extends `ArchiveError` |
+| Exported class           | Trigger                                                                              | Properties                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `ArchiveError`           | Base for public package errors                                                       | `name`, `message`, optional `cause`                                                |
+| `ArchiveDefinitionError` | Invalid collection definition or duplicate registered collection names               | Extends `ArchiveError`                                                             |
 | `ArchiveDerivationError` | Unexpected schema/canonicalization/index/hash fault or violated collection invariant | Extends `ArchiveError`; readonly `stage: ArchiveDerivationStage`; optional `cause` |
 
 `ArchiveError` and `ArchiveDefinitionError` accept `(message: string, opts?: ErrorOptions)`.
@@ -844,7 +938,8 @@ if (!meResponse.ok) throw new Error('Identity unavailable');
 const me = archiveIdentitySchema.parse(await meResponse.json());
 if (me === null) throw new Error('Register a publisher first');
 const mineResponse = await fetch('/api/v1/me/publications?collection=recipes', {
-  credentials: 'same-origin', headers: { [PUBLISHER_HEADER]: me.id },
+  credentials: 'same-origin',
+  headers: { [PUBLISHER_HEADER]: me.id },
 });
 if (!mineResponse.ok) throw new Error('Own publications unavailable');
 const owned = recipesCollection.contract.ownedEntries.parse(await mineResponse.json());
@@ -923,15 +1018,15 @@ anonymous read budget or call the issuer.
 The Worker reads its environment fail-closed — every binding must be present and
 well-formed, or the route answers 503 without naming what is missing:
 
-| Variable                 | Meaning                                                          |
-| ------------------------ | ---------------------------------------------------------------- |
-| `APP_ENV`                | `local` or `production` (transport rules and the pepper policy)   |
-| `ALLOWED_ORIGINS`        | Exact canonical origins; never wildcards                          |
-| `JWT_ISSUER` / `JWT_AUDIENCE` / `JWT_JWKS_URL` | Your identity provider |
-| `AUTH_ISSUER_SERVICE`    | Required issuer service binding for live session-version checks   |
-| `LIKES_ENABLED` / `PUBLISHING_ENABLED`        | Feature flags                     |
-| `RATE_LIMIT_KEY_SECRET`  | HMAC pepper. Required ≥ 32 chars in production; local may fall back |
-| `DB` / `READ_LIMIT` / `WRITE_LIMIT`           | D1 + rate-limit bindings |
+| Variable                                       | Meaning                                                                                   |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `APP_ENV`                                      | `local` or `production` (transport rules and the pepper policy)                           |
+| `ALLOWED_ORIGINS`                              | Exact canonical origins; never wildcards                                                  |
+| `JWT_ISSUER` / `JWT_AUDIENCE` / `JWT_JWKS_URL` | Exact issuer claim, audience and issuer JWKS endpoint URL                                 |
+| `AUTH_ISSUER_SERVICE`                          | Required issuer service binding for signing-key retrieval and live session-version checks |
+| `LIKES_ENABLED` / `PUBLISHING_ENABLED`         | Feature flags                                                                             |
+| `RATE_LIMIT_KEY_SECRET`                        | HMAC pepper. Required ≥ 32 chars in production; local may fall back                       |
+| `DB` / `READ_LIMIT` / `WRITE_LIMIT`            | D1 + rate-limit bindings                                                                  |
 
 Both limiter bindings must run 60-second windows (`simple` limiters:
 `period: 60`): the platform binding does not expose its period at runtime, so the
@@ -941,6 +1036,14 @@ make the header lie.
 Generated Env types (wrangler's `worker-configuration.d.ts`) satisfy the package's
 structural `ArchiveWorkerEnv` — no `@cloudflare/workers-types` dependency, no casts.
 
+Signing keys are fetched from `JWT_JWKS_URL` through `AUTH_ISSUER_SERVICE`, not
+global `fetch`. Point the URL at the bound issuer's `/api/v1/auth/jwks.json`
+route; retain the HTTPS production or loopback HTTP local configuration rules.
+This transport supports Workers on the same Cloudflare zone without a public
+Worker-to-Worker fetch. JOSE caches signing keys, but every private request still
+checks the current issuer session version. A signing-key provider failure is
+`503 auth-unavailable`, not a reason to clear the browser's signed-in state.
+
 ## The auth issuer
 
 `createAuthWorker()` from `@vielzeug/archive/auth` is the reference passwordless
@@ -954,19 +1057,19 @@ sign-in time and claims the token. The issuer's D1 schema ships at
 `migrations_dir` there. The catalog's `JWT_ISSUER` and `JWT_JWKS_URL` must identify
 the issuer, and its audience must match the issuer's `AUDIENCE`.
 
-| Variable | Meaning |
-| --- | --- |
-| `APP_NAME` | The app's display name: the magic-link email's subject and copy name it |
-| `ALLOWED_ORIGINS` | Exact origins allowed to trigger unsafe routes (the app origin(s)) |
-| `APP_ENV` | `local` or `production` — production requires HTTPS and sets Secure cookies |
-| `AUDIENCE` / `AUTH_ISSUER` | The claims every minted session carries; the catalog verifies the same pair |
-| `AUTH_DB` / `AUTH_EMAIL` | The issuer's D1 and send-email bindings |
-| `AUTH_ARCHIVE` | Required service binding to the catalog Worker; deletion calls its profile-erasure route |
-| `AUTH_JWT_PRIVATE_JWK` | The RS256 private key as a JWK JSON string: a wrangler secret in production |
-| `AUTH_JWT_PREVIOUS_PUBLIC_JWKS` | Optional retired public RS256 JWKS; publish during rotation until old sessions expire |
-| `OPERATOR_EMAILS` | Comma-separated emails whose newly minted sessions carry the operator role |
-| `PUBLIC_ORIGIN` | App origin for links, confirmation POST origin checks and client navigation after sign-in |
-| `SENDER_ADDRESS` | The address magic links come from: a domain onboarded to Cloudflare Email Service |
+| Variable                        | Meaning                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| `APP_NAME`                      | The app's display name in magic-link email and escaped confirmation-page branding         |
+| `ALLOWED_ORIGINS`               | Exact origins allowed to trigger unsafe routes (the app origin(s))                        |
+| `APP_ENV`                       | `local` or `production` — production requires HTTPS and sets Secure cookies               |
+| `AUDIENCE` / `AUTH_ISSUER`      | The claims every minted session carries; the catalog verifies the same pair               |
+| `AUTH_DB` / `AUTH_EMAIL`        | The issuer's D1 and send-email bindings                                                   |
+| `AUTH_ARCHIVE`                  | Required service binding to the catalog Worker; deletion calls its profile-erasure route  |
+| `AUTH_JWT_PRIVATE_JWK`          | The RS256 private key as a JWK JSON string: a wrangler secret in production               |
+| `AUTH_JWT_PREVIOUS_PUBLIC_JWKS` | Optional retired public RS256 JWKS; publish during rotation until old sessions expire     |
+| `OPERATOR_EMAILS`               | Comma-separated emails whose newly minted sessions carry the operator role                |
+| `PUBLIC_ORIGIN`                 | App origin for links, confirmation POST origin checks and client navigation after sign-in |
+| `SENDER_ADDRESS`                | The address magic links come from: a domain onboarded to Cloudflare Email Service         |
 
 Under `wrangler dev` the send-email binding is simulated — the link prints to the
 issuer's console, so that console is the inbox. Demo-only Alice/Bob routes are
@@ -995,10 +1098,38 @@ Opening `GET /auth/verify?token=…` renders a no-store confirmation page and do
 not consume the link or change the session, so email scanners cannot sign in by
 fetching it. A deliberate click sends `POST /auth/verify` with JSON `{ token }`,
 the request marker and an exact allowed origin or `PUBLIC_ORIGIN`.
-Success is 204 with Set-Cookie; the page then navigates to `/signed-in`. The
-redemption update and account sign-in stamp are trigger-backed and atomic.
+Success is 204 with Set-Cookie; the page then navigates to the fixed
+`${PUBLIC_ORIGIN}/signed-in` destination. Your application must serve that page;
+the issuer only serves the confirmation endpoint. The redemption update and
+account sign-in stamp are trigger-backed and atomic.
 The page removes the token from the address bar, loads no external assets, and
-sets a restrictive CSP and `Referrer-Policy: no-referrer`.
+sets a restrictive CSP and `Referrer-Policy: no-referrer`. Its inline CSS and
+script use a fresh nonce, never `unsafe-inline`. The page follows light/dark
+preferences, supports reduced motion, focuses the confirmation action and
+announces pending, success and recovery states. Without JavaScript it links to
+`${PUBLIC_ORIGIN}/account` as “Request a new sign-in link” and does not pretend
+to complete sign-in.
+
+Archive only serves the confirmation endpoint. Your application must serve its
+sign-in entry at the fixed `${PUBLIC_ORIGIN}/account` recovery destination and
+the success page at `${PUBLIC_ORIGIN}/signed-in`. These are reference issuer
+route conventions, not configurable destinations. The initial “Back to app”
+exit links to `${PUBLIC_ORIGIN}/`. No query parameter supplies a destination.
+Expired or already-used links (POST 410) require a new link rather than a retry.
+HTTP 429 enables manual retry after a `Retry-After` cooldown bounded to 1-300
+seconds, accepting unsigned integer seconds or valid HTTP-date syntax and
+defaulting to 30 seconds for missing or invalid values, including negative or
+fractional numbers. HTTP 503 and network failures offer a retry button and a
+secondary “Request a new sign-in link” action; invalid or expired links make
+that recovery action primary. The page never
+automatically retries, aborts stalled requests after 15 seconds and releases
+requests/timers when you leave it. Response bodies, including stale responses,
+are cancelled without waiting, and completed attempts abort their controllers.
+
+With valid issuer configuration, malformed GET links return HTTP 400 with branded
+recovery HTML rather than the JSON error envelope. POST errors retain the JSON
+error schema. A well-formed expired token still gets GET 200 confirmation: its
+redemption status is determined only by the deliberate POST.
 
 `GET /auth/account` exports account metadata only. For full erasure, call
 `DELETE /auth/account` with `ACCOUNT_HEADER` (`X-Archive-Account`) set to the
@@ -1054,9 +1185,9 @@ against the same file. Point wrangler at the directory:
     {
       "binding": "DB",
       "database_name": "my-app",
-      "migrations_dir": "./node_modules/@vielzeug/archive/migrations"
-    }
-  ]
+      "migrations_dir": "./node_modules/@vielzeug/archive/migrations",
+    },
+  ],
 }
 ```
 
@@ -1377,6 +1508,8 @@ console.log(byRole, health, profile);
 - **`tryParseJson`**: preserve JSON syntax failures from `/object`
 - **`allocate`**: lossless proportional distribution from `/math`
 - **`chunk`, `zip`, `compact`**: typed collection transforms from `/array`
+- **`paginate`**: one page plus its totals from an in-memory list, in a one- or zero-based page base
+- **`sort`**: selector, `{ key: direction }`, or ordered grid criteria from one entry point
 - **`range`, `average`, `median`**: common numeric operations from `/math`
 - **`assert`, `tap`**: typed control-flow helpers from `/function`
 - **`isEqual`**: structural equality from package root
@@ -1404,6 +1537,8 @@ console.log(byRole, health, profile);
 | --- | --- | --- | --- |
 | `groupBy` | Group values by key (prototype-pollution guarded) | Sync | Root export |
 | `chunk` / `zip` / `compact` | Typed collection transforms | Sync | Available from `/array` |
+| `paginate` | Cut one page and its totals out of a list | Sync | Pages past the last return empty `items`, unclamped |
+| `sort` | Sort by a selector, keyed fields, or ordered path criteria | Sync | Criteria paths are resolved safely; mixed value types throw |
 | `range` / `average` / `median` | Numeric generation and aggregation | Sync | Available from `/math` |
 | `assert` | Assert and narrow a condition | Sync | Available from `/function` |
 | `retry` | Retry async work | Async | Rethrows final error |
@@ -1424,7 +1559,7 @@ console.log(byRole, health, profile);
 | Import | Purpose |
 | --- | --- |
 | `@vielzeug/arsenal` | Curated common utilities |
-| `@vielzeug/arsenal/array` | Immutable transforms, set operations, sorting, fuzzy search |
+| `@vielzeug/arsenal/array` | Immutable transforms, pagination, set operations, sorting, fuzzy search |
 | `@vielzeug/arsenal/async` | Retry, cancellation, task pool, timing |
 | `@vielzeug/arsenal/cache` | In-memory cache and memoization |
 | `@vielzeug/arsenal/encoding` | Base64url and native byte compression |
@@ -1452,6 +1587,35 @@ unzip(rows): tupleOfArrays
 
 `take`, `takeLast`, `drop`, and `dropLast` return new arrays and normalize negative counts to zero. Set operations accept optional selectors for object identity.
 
+### paginate
+
+```ts
+paginate(items: readonly T[], options?: PaginateOptions): PageEnvelope
+```
+
+Cuts one page out of an in-memory list and returns the items with the arithmetic that produced them. `pageOffset` selects the caller's page base: `1` (default) for one-based paging, `0` for zero-based servers such as Spring. The default `page` is the first page in that base, and the default `pageSize` is `20`. `totalPages` is at least 1, even for an empty list, so `page (array: readonly T[], selector: (item: T) => unknown, direction?: SortDirection): T[];
+sort(array: readonly T[], selectors: SortSelectors): T[];
+sort(array: readonly T[], criteria: ReadonlyArray>): T[];
+```
+
+Three forms, one entry point. The selector form sorts by one extracted value; the selectors form accepts an object mapping property keys to directions; the criteria form sorts by an ordered list of paths, which is the shape a data grid hands over when its sortable columns are runtime strings.
+
+```ts
+import { sort } from '@vielzeug/arsenal/array';
+
+const users = [{ name: 'Ada', age: 41 }, { name: 'Grace', age: 30 }];
+sort(users, (user) => user.name);
+sort(users, { name: 'asc', age: 'desc' });
+
+const rows = [
+  { address: { city: 'Berlin' }, age: 41 },
+  { address: { city: 'Aachen' }, age: 30 },
+];
+sort(rows, [{ key: 'address.city' }, { key: 'age', direction: 'desc' }]);
+```
+
+Criteria paths are resolved with `getPath`, so dotted and bracketed paths (`'address.city'`, `'tags[0]'`) work and prototype-access segments are refused. The first criterion that differs wins and earlier ties keep their input order. Ordering is delegated to `compare`, so a column that mixes value types (a number beside a string) throws a `TypeError` instead of guessing an order.
+
 ### fuzzyFilter / fuzzyScore
 
 ```ts
@@ -1717,6 +1881,16 @@ type FuzzySelection = FuzzyOptions & {
 
 type ScoredResult = { item: T; score: number };
 
+type PageEnvelope = Readonly;
+
+type PaginateOptions = Readonly;
+
+type SortDirection = 'asc' | 'desc';
+
+type SortSelectors = Partial>;
+
+type SortCriterion = Readonly;
+
 type CacheOptions = {
   capacity?: number;
   now?: () => number;
@@ -1791,6 +1965,45 @@ const byPrice = sort(products, (product) => product.price);
 console.log(publishedLabels, byId, byPrice);
 ```
 
+## Page an In-Memory List
+
+Use `paginate` when the whole list is local and a view needs one page plus its totals.
+
+```ts
+import { paginate } from '@vielzeug/arsenal/array';
+
+const rows = Array.from({ length: 45 }, (_, index) => ({ id: index + 1 }));
+
+const first = paginate(rows, { pageSize: 10 });
+const past = paginate(rows, { page: 9, pageSize: 10 });
+
+console.log(first.totalPages, past.items); // 5 []
+```
+
+`page` is echoed rather than clamped, so a stale page number reads as an empty page instead of
+silently jumping elsewhere. Pass `{ pageOffset: 0 }` for a zero-based caller and the envelope comes
+back in that same base.
+
+## Sort by Grid Criteria
+
+`sort` accepts the ordering a data grid already holds: an ordered list of column paths, each with a direction.
+
+```ts
+import { sort } from '@vielzeug/arsenal/array';
+
+const rows = [
+  { address: { city: 'Berlin' }, age: 41 },
+  { address: { city: 'Aachen' }, age: 30 },
+  { address: { city: 'Berlin' }, age: 27 },
+];
+
+const ordered = sort(rows, [{ key: 'address.city' }, { key: 'age', direction: 'desc' }]);
+```
+
+Paths are resolved safely, so nested and indexed columns work and prototype access is refused. The
+first criterion that differs decides the order and ties keep their input order. Keep each column
+typed: a column mixing numbers and strings throws a `TypeError` rather than guessing an order.
+
 ## Search Explicit Fields
 
 Search string arrays directly. Object collections require `select`, so callers define exactly what can match.
@@ -1972,8 +2185,10 @@ const settings = parsed.ok ? Settings.parse(parsed.value) : { theme: 'system' };
 - filterMap - Filter and map array elements (id: `array-filter`)
 - groupBy - Group array by key (id: `array-group`)
 - filterMap - Transform array elements (id: `array-map`)
+- paginate - Page an array (id: `array-paginate`)
 - fuzzyFilter - Explicit searchable fields (id: `array-search`)
 - fuzzyFilter - Unicode normalization (id: `array-search-normalize`)
+- sort - Selector, selectors, or grid criteria (id: `array-sort-criteria`)
 - uniq - Remove duplicates (id: `array-uniq`)
 - attempt - Safe async execution with isFail/isOk helpers (id: `async-attempt`)
 - parallel - Controlled parallel execution (id: `async-parallel`)
@@ -2072,6 +2287,8 @@ await waitUntil(() => view.queryByText('Saved') !== null);
 - `fireClick`, `fireInput`, `fireKeyDown`, and peers dispatch exact synchronous events.
 - `waitUntil`, `eventually`, and `waitForEvent` provide bounded, abortable async waiting.
 - `delay` models explicit cancellable timer scheduling.
+- `walkFlatTree` traverses the flat tree across slot boundaries jsdom's light-DOM queries miss.
+- `installFormInternalsPolyfill` gives jsdom the `ElementInternals` form-association API.
 - `AssayError`, `AssayQueryError`, and `AssayTimeoutError` provide typed failures.
 
 ## Documentation
@@ -2098,12 +2315,14 @@ await waitUntil(() => view.queryByText('Saved') !== null);
 | `fire*` / `dispatch`                         | Dispatches platform event instances         | Sync           | Does not reproduce browser default behavior      |
 | `waitUntil` / `eventually` / `waitForEvent`  | Waits for conditions, assertions, or events | Async          | Use a signal or timeout for bounded waits                     |
 | `delay`                                      | Schedules a cancellable timer               | Async          | Pass a signal to cancel a pending wait                        |
+| `walkFlatTree`                               | Walks the flat tree across slot boundaries  | Sync           | jsdom-only need: browsers already use the flat tree           |
+| `installFormInternalsPolyfill`               | Polyfills `ElementInternals` form association for jsdom | Sync | Global patches: only install in suites that need them |
 
 ## Package Entry Point
 
 | Import            | Purpose                                              |
 | ----------------- | ---------------------------------------------------- |
-| `@vielzeug/assay` | DOM queries, events, wait helpers, errors, and types |
+| `@vielzeug/assay` | DOM queries, events, wait helpers, test-environment helpers, errors, and types |
 
 ## Queries
 
@@ -2195,6 +2414,57 @@ await delay(100, { signal });
 
 `timeout` and delay milliseconds must be finite, non-negative, and no greater than 2,147,483,647 ms; `interval` must be finite, positive, and within the same timer limit. Invalid durations throw `RangeError`. `eventually()` also accepts `message` for diagnostic timeout context.
 
+## Test-environment helpers
+
+### `walkFlatTree(root, visit)`
+
+```ts
+function walkFlatTree(root: Element, visit: (element: HTMLElement) => void): void;
+```
+
+Walks the flat tree below `root`, calling `visit` for each assigned or ordinary descendant (not for `root` itself).
+At each `` it expands `assignedElements()` instead of descending into its (always empty, in jsdom) literal
+children. jsdom only
+implements the light DOM tree, so `querySelectorAll()` never crosses a slot into its assigned elements; real
+browsers use the flat tree for that. This helper closes the gap for tests that must find form-associated (or
+otherwise slotted) elements through shadow boundaries.
+
+```ts
+const named: HTMLElement[] = [];
+
+walkFlatTree(form, (el) => {
+  if (el.hasAttribute('name')) named.push(el);
+});
+```
+
+### `installFormInternalsPolyfill()`
+
+```ts
+function installFormInternalsPolyfill(): () => void;
+```
+
+jsdom implements none of the `ElementInternals` form-association API: not `setFormValue`, not `setValidity`, not
+the `checkValidity`/`reportValidity`/`validity`/`validationMessage` mixin real browsers put on every
+`formAssociated: true` element, not even `FormData` collecting a form-associated element's set value, or
+`.reset()` invoking `formResetCallback()`. Every one of those gaps is exercised by `useField()` from
+`@vielzeug/ore`, so any package testing a form-associated component needs all of them.
+
+Call it from a test setup when the suite tests form-associated components; it returns an `uninstall()` that
+restores every patched global. The patches are global monkey-patches and skip APIs already implemented by the
+environment, so suites without form-associated components shouldn't install them. If `ElementInternals` is absent,
+the installer is a no-op. A downstream package should
+rely on this instead of hand-rolling its own copy.
+
+```ts
+// vitest.setup.ts
+import { installFormInternalsPolyfill } from '@vielzeug/assay';
+import { install } from '@vielzeug/ore/testing';
+import { afterAll, afterEach } from 'vitest';
+
+install(afterEach);
+afterAll(installFormInternalsPolyfill());
+```
+
 ## Types
 
 ```ts
@@ -2349,6 +2619,36 @@ expect(onSave).toHaveBeenCalledOnce();
 Refine's testing entry point contains only Refine-specific assertions and typed mount wrappers. Import Assay helpers
 directly instead of routing generic DOM operations through another package.
 
+When a suite tests a form-associated custom element (one built on `useField()` from `@vielzeug/ore`), install the
+form-internals polyfill in the setup file so jsdom gains the `ElementInternals` API it lacks:
+
+```ts
+// vitest.setup.ts
+import { installFormInternalsPolyfill } from '@vielzeug/assay';
+import { install } from '@vielzeug/ore/testing';
+import { afterAll, afterEach } from 'vitest';
+
+install(afterEach);
+afterAll(installFormInternalsPolyfill());
+```
+
+## Traverse slotted content in jsdom
+
+Use `walkFlatTree()` when a test must visit descendants assigned through slots. It expands each slot into its assigned
+elements, including nested slots, instead of relying on jsdom's light-DOM-only `querySelectorAll()`.
+
+```ts
+import { walkFlatTree } from '@vielzeug/assay';
+
+const named: HTMLElement[] = [];
+walkFlatTree(form, (element) => {
+  if (element.hasAttribute('name')) named.push(element);
+});
+```
+
+The callback receives descendants in the flat tree, not the root element or slot elements themselves. Browsers already
+use the flat tree for DOM algorithms; this helper is for test code that needs equivalent traversal in jsdom.
+
 ## Best Practices
 
 - Scope multiple assertions with `within()` rather than repeatedly querying the document.
@@ -4523,6 +4823,7 @@ try {
 - **`withBearerAuth()` / `withRequestId()` / `withLogging()`**: composable middleware configured at construction.
 - **`tap()`**: signal-owned structured transport observation.
 - **Error taxonomy**: HTTP, network, timeout, abort, parse, and schema failures are distinct, actionable classes.
+- **RFC 9457 problem details**: an `application/problem+json` error body parses onto `CourierHttpError.problem` while the HTTP status stays authoritative.
 - **`cancelAll()` / `dispose()`**: abort active requests and tear down the transport.
 
 ## Documentation
@@ -4554,6 +4855,9 @@ try {
 | `withRequestId()` | Adds request identifier middleware | Sync | Default generator uses `crypto.randomUUID()` |
 | `withLogging()` | Logs request result metadata | Sync | Requires explicit logger; URLs may contain sensitive query values |
 | `tap()` | Observe structured transport events | Sync | Observation only; optional signal owns lifetime |
+| `CourierHttpError.problem` | Parsed RFC 9457 problem details from an error body | Sync | Present only when the response is `application/problem+json` |
+| `ProblemDetail` | RFC 9457 problem members and extension members | Sync | Extension values are `unknown`; Courier does not validate their shapes |
+| `problemDetailError()` | Build an HTTP error that carries problem details | Sync | Intended for mocks and middleware, not for parsing a response |
 
 ## Package Entry Point
 
@@ -4799,7 +5103,7 @@ type PrefetchConfig = Omit,
 | Error | Trigger | Notable properties |
 | --- | --- | --- |
 | `CourierError` | Base class for all Courier errors | Use `instanceof` to narrow |
-| `CourierHttpError` | Non-2xx HTTP response | `status`, `data`, `headers`, `method`, `url`; `CourierHttpError.is(e, status?)` narrows by status |
+| `CourierHttpError` | Non-2xx HTTP response | `status`, `data`, `headers`, `method`, `url`, `problem`; `CourierHttpError.is(e, status?)` narrows by status |
 | `CourierNetworkError` | Request failure without response | `method`, `url`, `cause` |
 | `CourierTimeoutError` | Timeout signal aborts request | `method`, `url`, `cause` |
 | `CourierAbortError` | Caller or client cancellation | `method`, `url`, `cause` |
@@ -4810,6 +5114,72 @@ type PrefetchConfig = Omit,
 
 Errors thrown directly by custom middleware are preserved rather than reclassified.
 
+### Problem details
+
+```ts
+export type ProblemDetail = Readonly;
+
+export const PROBLEM_JSON_MEDIA_TYPE = 'application/problem+json';
+
+export function isProblemMediaType(contentType: string | null | undefined): boolean;
+
+export function problemDetailError(
+  problem: ProblemDetail,
+  options?: { message?: string; method?: string; status?: number; url?: string },
+): CourierHttpError;
+```
+
+When a non-2xx response answers with `application/problem+json` (RFC 9457), `CourierHttpError.problem`
+holds a shallow-frozen copy of the parsed JSON object and the error message prefers `detail`, then
+`title`, then the response status text (or `HTTP ` when status text is empty). Any other error
+body keeps the shape it already had on `data`, with `problem` left `undefined`. Courier checks that
+the parsed body is an object; it does not validate the types or contents of registered or extension
+members. RFC 9457 treats an omitted `type` as `about:blank`, but Courier does not insert that value
+into the object.
+
+| Member | Purpose | Common gotcha |
+| --- | --- | --- |
+| `ProblemDetail` | The five registered RFC 9457 members plus extensions | Every member is optional; extension values have type `unknown` |
+| `CourierHttpError.problem` | Parsed problem document | For response errors, it is a frozen shallow copy and is `undefined` unless the media type matches and the body is an object |
+| `PROBLEM_JSON_MEDIA_TYPE` | Registered media type constant | Compare with `isProblemMediaType()`, not `===`, to allow parameters |
+| `isProblemMediaType()` | Match `application/problem+json` and its parameterised forms | Plain `application/json` never matches |
+| `problemDetailError()` | Build a problem-carrying `CourierHttpError` without a server | Status defaults to numeric `problem.status`, then `500`; a supplied `options.status` takes precedence |
+
+```ts
+problemDetailError(problem, options?)
+```
+
+`problemDetailError()` returns a `CourierHttpError` with the supplied problem object on both
+`error.problem` and `error.data`. Its defaults are `method: 'GET'`, `url: ''`, and status from
+`problem.status` when numeric or `500` otherwise. The error message uses `options.message`, then
+`problem.detail`, `problem.title`, and finally `HTTP `. Unlike a parsed response problem,
+the supplied object is not copied or frozen.
+
+The HTTP status line stays authoritative: `error.status` is the response status even when
+`problem.status` disagrees. A JSON array or primitive leaves `data` as that parsed value; malformed
+JSON leaves `data` as its raw text. Neither produces a partial `problem`.
+
+```ts
+import { createCourier, CourierHttpError, problemDetailError, type ProblemDetail } from '@vielzeug/courier';
+
+const courier = createCourier({ baseUrl: '/api' });
+
+try {
+  await courier.post('/invoices');
+} catch (error) {
+  if (CourierHttpError.is(error)) {
+    const problem: ProblemDetail | undefined = error.problem;
+    console.log(error.status, problem?.title, problem?.detail, problem?.type);
+  }
+}
+
+const mockedError = problemDetailError(
+  { title: 'Insufficient credit', detail: 'Choose a lower amount.', status: 402 },
+  { method: 'POST', url: '/invoices' },
+);
+console.log(mockedError.status, mockedError.problem?.detail);
+```
+
 ### Usage Guide
 
 ## Basic Usage
@@ -4998,6 +5368,55 @@ async function loadUser(): Promise {
 - Do not display cancellation as an application error during navigation.
 - `CourierSchemaValidationError` carries the raw pre-validation `data`.
 
+## Problem Details
+
+When a server answers a failure with `application/problem+json` (RFC 9457), Courier parses the
+JSON object onto `CourierHttpError.problem` and chooses the message from `detail`, then `title`,
+then the HTTP status text. The parsed object is shallow-frozen; extension members remain `unknown`
+and Courier does not validate their contents. Nothing is configured.
+
+```ts
+import { CourierHttpError, createCourier, type ProblemDetail } from '@vielzeug/courier';
+
+const courier = createCourier({ baseUrl: '/api' });
+
+async function submitInvoice(body: unknown): Promise {
+  try {
+    await courier.post('/invoices', { body });
+    return 'Saved.';
+  } catch (error) {
+    if (!CourierHttpError.is(error)) throw error;
+
+    const problem = error.problem;
+    if (problem?.title === 'Insufficient credit') return `Blocked: ${problem.detail ?? 'no credit'}`;
+
+    // Extension members are ordinary properties on the same document.
+    const field = problem?.['errors'] as Record | undefined;
+
+    return field ? Object.values(field).join(', ') : `Request failed (${error.status}).`;
+  }
+}
+```
+
+`error.status` is always the HTTP status from the response, so a `problem.status` that disagrees
+never overrides it. `problem` stays `undefined` for any other content type, and a `problem+json`
+body that is a JSON array or primitive keeps that parsed value on `data`; malformed JSON keeps its
+raw text there. Neither case creates a partial `problem`. RFC 9457 treats an omitted `type` as
+`about:blank`, but Courier does not add a `type` property. Use `problemDetailError()` to raise the
+same error shape from a mock or middleware; it stores the supplied problem object directly on both
+`problem` and `data`.
+
+```ts
+import { problemDetailError } from '@vielzeug/courier';
+
+const mockFailure = problemDetailError(
+  { title: 'Insufficient credit', detail: 'Choose a lower amount.', status: 402 },
+  { method: 'POST', url: '/invoices' },
+);
+
+console.log(mockFailure.status, mockFailure.problem?.detail);
+```
+
 ## Composing with a State Layer
 
 Courier owns HTTP transport and optional parsed GET caching. Observable query state, optimistic mutations, collection navigation, and stream state belong to the owning state layer (e.g. Sourcerer, TanStack Query, or consumer code). Compose Courier calls into that layer instead of nesting state machines.
@@ -5116,6 +5535,7 @@ There is no `use()` method. To change middleware, create a new client. This keep
 - Cached Read and Prefetch (id: `cached-read`)
 - createCourier - Transport Client (id: `create-courier`)
 - middleware - Immutable Chain (id: `middleware`)
+- problem+json - RFC 9457 error bodies (id: `problem-details`)
 
 ---
 
@@ -15548,7 +15968,7 @@ define('my-counter', {
 - Props via `prop.*` helpers (`prop.string`, `prop.number`, `prop.bool`, `prop.oneOf`, `prop.json`, `prop.data`) or raw `PropDef` objects
 - `setup(props)` takes only props and returns an `HTMLResult` directly: `return html\`...\``
 - Lifecycle hooks: `onMounted`, `onCleanup`, `onEvent`, `onElement`, `watchEffect`: plain functions imported from `@vielzeug/ore`, called directly from `setup()` or any composable it calls
-- Directives: `each` (keyed reactive list rendering), `classMap`, `styleMap`, `when`, `live`, `unsafeHtml`
+- Directives: `each` (transactional keyed list reconciliation), `classMap`, `styleMap`, `when`, `live`, `model`, `unsafeHtml`
 - Host bindings via `bind({ attr, class, style, on })`: pass `{ target: el }` to bind any off-host element
 - Reactive ARIA sync via explicit `aria-*` keys in `bind({ attr }, { target })`, with automatic cleanup on disconnect
 - Context via `provide(key, value)` / `inject(key)`; typed emit/slots via `useEmit()` / `useSlots()`
@@ -15596,6 +16016,7 @@ All browser-runtime symbols below are imported from `@vielzeug/ore`. Lifecycle/c
 | `each()`               | Keyed list rendering with DOM diffing                 | Sync           | Duplicate keys report `ore:error`; plain `T[]` is a one-time static render  |
 | `when()`               | Conditional branch rendering                          | Sync           | Getter-fn computed disposed on cleanup; static bool skips subscription    |
 | `live(signal)`         | One-way binding that skips stale writes during input  | Sync           | Use for controlled inputs alongside a manual `@input` handler             |
+| `model(signal)`        | Two-way form-control binding (value/checked + write-back) | Sync       | Plain `value`/`checked` attribute only; pass `get` to keep numeric signals numeric   |
 | `onMounted(fn)`        | DOM-ready callback                                    | Setup only     | Must be called synchronously during `setup()`                             |
 | `onCleanup(fn)`        | Register teardown                                     | Setup only     | Called on component disconnect                                            |
 | `onEvent(target, …)`   | Scoped event listener with auto-cleanup               | Setup only     | No-ops on null target; removed on disconnect                              |
@@ -15710,12 +16131,13 @@ setup(_props) {
 | `prop.string(defaultValue?)`        | `PropDef`  | Reflects by default                                                                                          |
 | `prop.bool(defaultValue?)`          | `PropDef` | Any non-null attribute value other than `"false"` parses as `true`; `"false"` or absent attribute is `false` |
 | `prop.number(defaultValue?)`        | `PropDef`  | Returns default (not NaN) and warns in dev when attribute is not a valid number                              |
-| `prop.oneOf(allowed, defaultValue)` | `PropDef`       | Restricts to provided string union                                                                           |
+| `prop.oneOf(allowed, defaultValue?)` | `PropDef`      | Restricts to a fixed set of string or number members; `parse` falls back to `defaultValue` (or `undefined` when omitted) for anything outside the set. Numeric members match the attribute parsed as a number |
 | `prop.json(defaultValue)`           | `PropDef`       | JSON.parse from attribute; `reflect: false`                                                                  |
 | `prop.data(defaultValue?)`       | `PropDef`       | JS-only: never reads/writes an attribute; use for objects, arrays, callbacks, or any non-serialisable value |
 
 > **Choosing the right prop helper:**
 >
+> - **`prop.oneOf`**: the honest way to type a union-valued prop: the restriction is enforced at runtime (`parse` falls back for anything outside the set), not just in a type parameter a raw attribute value could violate. Pass an `as const` array of the allowed string or number members.
 > - **`prop.json`**: value can be declared in HTML (``); attribute string is `JSON.parse`d.
 > - **`prop.data`**: value is always set from JavaScript (objects, arrays, callbacks, class instances); the attribute is never read. Use this for both data and function props.
 
@@ -15748,7 +16170,16 @@ define('data-grid', {
 ### `html`
 
 Tagged template literal that returns an `HTMLResult`. Supports text interpolation, ordinary attributes (`attr=`),
-boolean attributes (`?attr=`), events (`@event=`), refs (`ref=`), and nested templates.
+boolean attributes (`?attr=`), explicit property bindings (`.prop=`), events (`@event=` with optional
+`.stop`/`.prevent`/`.once`/`.capture` modifiers), refs (`ref=`), and nested templates.
+
+`.prop=${value}` always writes the element property (never an attribute): the explicit channel for structured
+values (arrays, objects, callbacks). Prototype-polluting names (`__proto__`, `constructor`, `prototype`) are
+rejected at compile time.
+
+`@event.stop`, `.prevent`, `.once`, and `.capture` are shorthand for the matching listener behavior
+(`stopPropagation`/`preventDefault` applied before the handler runs; `once`/`capture` passed as listener
+options). An unknown modifier throws at compile time.
 
 ### `css`
 
@@ -15763,9 +16194,28 @@ Tagged template literal that returns a `CSSResult` for use in `styles`.
 | `classMap(record)`                     | Reactive class string from object map                                                                 |
 | `styleMap(record)`                     | Reactive inline style string from object map                                                          |
 | `live(signal)`                         | One-way binding that skips stale writes during active user input; use with `@input` handler           |
+| `model(signal, options?)`              | Two-way form-control binding: writes the signal to `value`/`checked` and writes user input back on the control's change event |
 | `unsafeHtml(value)`                    | HTML rendering sink; sanitize untrusted values before calling                                           |
 
-`each()` treats number and string keys as distinct. A duplicate-key update reports `ore:error` and preserves the last valid list.
+`each()` treats number and string keys as distinct. A reconciliation failure (a duplicate key, or a render function that throws) reports `ore:error` and preserves the last valid list: entries created during the failed pass are rolled back, so the previous list stays exactly on screen.
+
+### `model(signal, options?)`
+
+Two-way binding for a form control: `value=${model(signal)}`. It writes the signal to the control's `value`/`checked` property on every change and writes user input back into the signal on the control's change event (`'change'` for checkboxes, radios, and ``; `'input'` otherwise). This is the complete controlled-input loop that the `live()` + manual `@input` handler pair used to require.
+
+```ts
+const text = signal('');
+const agree = signal(false);
+const count = signal(0);
+
+html`
+  
+  
+   Number(el.value) })} />
+`;
+```
+
+`options` overrides the defaults for non-native controls: `event` sets the write-back event name and `get` reads the current value out of the element (default `el.checked` for checkboxes/radios, `el.value` otherwise). Because a native text input's `value` is always a string, pass a `get` like `(el) => Number(el.value)` to keep a numeric signal numeric. `model()` can only drive a plain `value`/`checked` attribute binding; using it on a boolean (`?checked=`) or other attribute throws.
 
 ### `unsafeHtml`
 
@@ -15865,6 +16315,8 @@ Import from `@vielzeug/ore`.
 Wire a form-associated element to `ElementInternals`. Requires `formAssociated: true` on the component definition. The `disabled` state tracking via `internals.states` (CustomStateSet) is skipped with a dev warning if the API is unavailable in the current environment.
 
 ```ts
+type FormFieldValidity = { flags: ValidityStateFlags; message: string };
+
 type FormFieldOptions = {
   disabled?: Readable;
   /**
@@ -15877,8 +16329,13 @@ type FormFieldOptions = {
   /** Called when the ancestor  resets (see onFormReset): restore local field state here. */
   onReset?: () => void;
   toFormValue?: (value: T) => File | FormData | string | null;
-  /** Recomputed reactively and passed straight to internals.setValidity(). null = always valid. */
-  validationMessage?: Readable;
+  /**
+   * Recomputed reactively and passed straight to internals.setValidity().
+   * null (or omitted) = always valid. Flags and message travel together because
+   * the platform's setValidity() contract couples them (flags without a
+   * non-empty message throw); a single { flags, message } | null input makes a
+   * desynced pair unrepresentable.
+   */
   validity?: Readable;
   value: Signal | Readable;
 };
@@ -15892,15 +16349,20 @@ type FormFieldHandle = {
 };
 ```
 
-Pass `validity`/`validationMessage` to make `required`-style constraints participate in native constraint validation
-through `checkValidity()` and `reportValidity()`:
+Pass a single `validity` signal to make `required`-style constraints participate in native constraint validation
+through `checkValidity()` and `reportValidity()`. The `{ flags, message }` pair is the one validity input: the old
+split `validity` + `validationMessage` options are gone, since they could drift apart into a state the platform
+rejects.
 
 ```ts
 const isBlank = (v: string) => v.trim() === '';
 
 useField({
-  validationMessage: computed(() => (required.value && isBlank(value.value) ? 'This field is required.' : '')),
-  validity: computed(() => (required.value && isBlank(value.value) ? { valueMissing: true } : null)),
+  validity: computed(() =>
+    required.value && isBlank(value.value)
+      ? { flags: { valueMissing: true }, message: 'This field is required.' }
+      : null,
+  ),
   value,
 });
 ```
@@ -15913,8 +16375,7 @@ Import from `@vielzeug/ore/testing`.
 | ------------------------ | ------------------------------------------------------------------------------------------ |
 | `mount(setup, options?)` | Mount a component and return a test fixture                                                |
 | `cleanup()`              | Remove all mounted elements and reset test state                                           |
-| `install(afterEach, options?)` | Register auto-cleanup; pass `{ formInternals: true }` to also install the `ElementInternals`/`FormData`/`.reset()` jsdom polyfill (see below) |
-| `installFormInternalsPolyfill()` | Installs the form-internals polyfill directly (returns an `uninstall()` that restores every patched global). Usually called via `install(afterEach, { formInternals: true })` |
+| `install(afterEach)`     | Register auto-cleanup after each test                                                      |
 | `flush(options?)`        | Drain reactive updates and animation frames                                                |
 | `renderHook(setup)`      | Run lifecycle hooks in isolation; overload accepts `propDefs` as first arg for typed props |
 | `OreTimeoutError`        | Error thrown when `flush()` cannot settle tracked Ore work                                 |
@@ -15924,7 +16385,16 @@ Import from `@vielzeug/ore/testing`.
 Import `within`, named dispatchers such as `fireClick`, and waits such as `waitUntil` or `waitForEvent` from
 `@vielzeug/assay`.
 
-> **Form-associated component testing:** jsdom implements none of the `ElementInternals` form-association API: `install(afterEach, { formInternals: true })` polyfills `setFormValue`/`setValidity`/`checkValidity`/`reportValidity`/`validationMessage`/`validity`/`states`, mixes `checkValidity`/`reportValidity`/`validity`/`validationMessage` onto the host element itself (real browsers do this for any `formAssociated: true` element), makes `FormData` collect a form-associated element's set value, and makes `.reset()` invoke `formResetCallback()`. Every patch is a guarded no-op when its target already exists, and `installFormInternalsPolyfill()` returns an `uninstall()` that restores every patched global. The polyfill is opt-in (`{ formInternals: true }`) because the patches are global: suites without form-associated components shouldn't carry them. A downstream package (e.g. a component library built on `ore`) should rely on this instead of hand-rolling its own copy.
+> **Form-associated component testing:** jsdom implements none of the `ElementInternals` form-association API.
+> `@vielzeug/assay` exports `installFormInternalsPolyfill()` for this: it polyfills
+> `setFormValue`/`setValidity`/`checkValidity`/`reportValidity`/`validationMessage`/`validity`/`states`, mixes
+> `checkValidity`/`reportValidity`/`validity`/`validationMessage` onto the host element itself (real browsers do
+> this for any `formAssociated: true` element), makes `FormData` collect a form-associated element's set value, and
+> makes `.reset()` invoke `formResetCallback()`. Every patch is a guarded no-op when its target already
+> exists, and the function returns an `uninstall()` that restores every patched global. Call it directly from a
+> test setup (alongside `install(afterEach)`) only when the suite tests form-associated components: the patches
+> are global, so suites without them shouldn't carry them. A downstream package (e.g. a component library built
+> on `ore`) should rely on it instead of hand-rolling its own copy.
 
 #### `Fixture` interface
 
@@ -16093,18 +16563,26 @@ type CSSResult = {
 
 type LiveBinding = { readonly source: Readable };
 
+type ModelOptions = {
+  /** Write-back event (default: 'change' for checkbox/radio/select, 'input' otherwise). */
+  event?: string;
+  /** Value reader (default: el.checked for checkbox/radio, el.value otherwise). */
+  get?: (el: HTMLElement) => T;
+};
+
 type EmitFn> = {
   >(event: K): boolean;
   >>(event: K, detail: T[K]): boolean;
 };
 // KeysWithoutDetail is an internal helper type, not exported.
 
+type FormFieldValidity = { flags: ValidityStateFlags; message: string };
+
 type FormFieldOptions = {
   disabled?: Readable;
   emptyStringForNull?: boolean;
   onReset?: () => void;
   toFormValue?: (value: T) => File | FormData | string | null;
-  validationMessage?: Readable;
   validity?: Readable;
   value: Signal | Readable;
 };
@@ -16258,11 +16736,13 @@ define('x-button', {
 
 ## template bindings
 
-`html` supports text, attributes, booleans, properties, events, refs, and nested templates.
+`html` supports text, attributes, booleans, properties, events, refs, and nested templates. Event bindings accept
+`.stop`, `.prevent`, `.once`, and `.capture`: the first two apply before the handler runs, while the latter two use
+native listener options. Unknown modifiers throw while Ore compiles the template.
 
 ```ts
 import { computed, signal } from '@vielzeug/ripple';
-import { define, html, ref } from '@vielzeug/ore';
+import { define, html, model, ref } from '@vielzeug/ore';
 
 define('profile-name', {
   setup() {
@@ -16271,10 +16751,7 @@ define('profile-name', {
 
     return html`
        'Current: ' + name.value)}>Name
-       'Current name ' + name.value}
-        @input=${(event: Event) => {
-          name.value = (event.target as HTMLInputElement).value;
-        }} />
+       'Current name ' + name.value} />
       Hello ${name}
     `;
   },
@@ -16283,8 +16760,7 @@ define('profile-name', {
 
 ## directives
 
-Ore exports `each`, `classMap`, `styleMap`, `when`, `live`, and `unsafeHtml` from `@vielzeug/ore`. Use ordinary
-attribute bindings plus native event handlers for two-way input state; no special model directive is required.
+Ore exports `each`, `classMap`, `styleMap`, `when`, `live`, `model`, and `unsafeHtml` from `@vielzeug/ore`.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
@@ -16332,9 +16808,50 @@ each(
 );
 ```
 
-## live form bindings
+Each reactive reconciliation is transactional. Ore creates missing entries before committing updates or removing stale
+entries; if a render callback throws, entries created during that pass are rolled back and the last successful list
+remains on screen. Ore reports the failure through `ore:error` with phase `each-reconcile`.
+
+## model: two-way form bindings
+
+Use `model(signal)` for a controlled input: it writes the signal to the control's `value`/`checked` property and
+writes user input back on the control's change event (`'change'` for checkboxes, radios, and selects; `'input'`
+otherwise). This replaces the `live()` + manual `@input` handler pair with one binding.
+
+```ts
+import { signal } from '@vielzeug/ripple';
+import { define, html, model } from '@vielzeug/ore';
+
+define('live-search', {
+  setup() {
+    const query = signal('');
+    const agree = signal(false);
+
+    return html`
+      
+      
+    `;
+  },
+});
+```
+
+A native text input's `value` is always a string, so pass a `get` reader to keep a numeric signal numeric, and an
+`event` name for custom controls that emit their own change event:
+
+```ts
+const count = signal(0);
+
+html`
+   Number(el.value) })} />
+   (el as MyPicker).selection })} />
+`;
+```
 
-Use `live(signal)` for inputs that should preserve in-progress user edits instead of overwriting the DOM on stale writes.
+## live: one-way bindings that preserve user edits
+
+Use `live(signal)` when a binding must skip a stale app-state write while the user is mid-edit, without writing
+user input back. `model()` covers the common controlled-input case; `live()` is for one-way bindings that only
+need the stale-write guard.
 
 ```ts
 import { signal } from '@vielzeug/ripple';
@@ -16698,7 +17215,7 @@ define('signup-form', {
 - Bind host attributes and classes via `bind()` rather than mutating the element directly.
 - Provide context at the nearest ancestor: avoid global context singletons.
 - Call `onCleanup()` for every resource allocated in `setup()` (WebSockets, intervals, external subscriptions).
-- Use `live(signal)` for form inputs to prevent clobbering user-in-progress edits.
+- Use `model(signal)` for two-way form inputs; use `live(signal)` for a one-way binding that must not clobber user-in-progress edits.
 - Extract composable helper functions freely: `onMounted`/`onCleanup`/`bind`/... resolve the active component through implicit context, so they work from any function called (transitively) during `setup()`, with no need to pass them in as parameters.
 - Test component mounting and lifecycle with `@vielzeug/ore/testing`; import generic DOM events, queries, and waits
   from `@vielzeug/assay`.
@@ -20417,6 +20934,7 @@ Classification guides discovery and bundle selection. It is not a reason to remo
 - **Framework agnostic**: works anywhere HTML can be rendered
 - **Tree-shakeable**: import only the component entry points you register
 - **Comprehensive surface**: inputs, content, disclosure, feedback, layout, and overlay primitives
+- **Native form integration**: form-associated controls submit values, validate supported required constraints, and reset with their form
 - **Typed framework declarations**: DOM, React, and Vue tags derive from the component property contracts
 
 ### Prerequisites
@@ -20520,6 +21038,14 @@ The declarations cover every supported tag and derive component properties from
 
 Form controls expose `.value` or `.checked` and dispatch standard `input` and `change` events. Read the property from `event.currentTarget`.
 
+Finite-choice properties use Ore's `prop.oneOf()` parsing: values outside a component's documented options resolve to
+the declared default, or `undefined` when no default is declared.
+
+Form-associated controls participate in native form submission, validity checks, and reset. A named control's value
+is available through `new FormData(form)`, and supported `required` constraints affect `form.checkValidity()`,
+`form.reportValidity()`, and submit blocking. The `error` property renders and announces feedback; it does not by
+itself set native constraint validity.
+
 Stateful overlays expose controlled `open`, optional `default-open`, and an `open-change` custom event with `{ open, reason }` detail. Component pages define additional detail fields and reasons.
 
 ## Utilities
@@ -20625,6 +21151,20 @@ grid.rows = [
 ];
 ```
 
+Enumerated properties such as `variant`, `size`, and `color` accept the values listed on each component's reference
+page. An unsupported value resolves to the property's declared default (or `undefined` when it has no default).
+
+In an Ore template, `model()` can bind a Refine field's `value` to a Ripple signal and write user input back:
+
+```ts
+import { signal } from '@vielzeug/ripple';
+import { html, model } from '@vielzeug/ore';
+import '@vielzeug/refine/input';
+
+const email = signal('');
+const field = html``;
+```
+
 ## Handle Events
 
 Form controls dispatch standard `input` and `change` events. Read their current property from `event.currentTarget`.
@@ -20648,6 +21188,37 @@ dialog?.addEventListener('open-change', (event: CustomEvent) => {
 });
 ```
 
+## Native Form Validation
+
+Refine's form-associated controls integrate with native form submission, `FormData`, validity checks, and reset.
+Use `required` for a required-value constraint; setting `error` displays and announces feedback but does not, by
+itself, invalidate the form.
+
+```html
+
+  
+  
+    Choose a role…
+    Editor
+    Admin
+  
+  Save
+
+  import '@vielzeug/refine/input';
+  import '@vielzeug/refine/select';
+  import '@vielzeug/refine/button';
+
+  const form = document.querySelector('#profile-form');
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    console.log(new FormData(form).get('email'));
+  });
+
+```
+
+The browser runs native validation before dispatching `submit`. Call `form.reportValidity()` to show validation
+feedback directly, or `form.checkValidity()` for a boolean check without the browser's validation UI.
+
 ## Compose Slots
 
 Default slots hold primary content. Named slots identify component-owned regions.
@@ -20842,16 +21413,16 @@ ripple.dispose();
 
 ## Features
 
-- `createRipple()` creates an isolated graph and lifetime boundary.
+- `createRipple({ onError })` creates an isolated graph with one runtime failure callback.
 - `signal()` stores writable values with configurable equality.
 - `computed()` derives lazy read-only values.
 - `effect()` reacts to dependency changes with cleanup support.
 - `batch()` coalesces synchronous writes and notifications.
 - `createScope()` groups owned reactive work.
 - `watch()` observes one selected source transition.
-- `tap()` provides runtime observability for all graph events.
 - `resource()` owns focused latest-request async state.
 - `fromSubscribable()` creates a disposable bridge for external `{ getSnapshot, subscribe }` sources.
+- `RippleError`, `RippleCycleError`, and `RippleDisposedError` distinguish package-originated failures.
 
 ## Documentation
 
@@ -20880,15 +21451,18 @@ ripple.dispose();
 | `createScope()` | Group owned reactive work | Sync | Call `run()` to activate it |
 | `untrack()` | Read without tracking | Sync | Read still happens immediately |
 | `watch()` | Observe selected output | Sync | Use `effect()` for broad reads |
-| `tap()` | Observe runtime events | Sync | Handler errors are swallowed |
+| `resource()` | Load from tracked reactive input | Sync factory / Async loader | `reload()` returns `void`; completion is observable state |
 | `fromSubscribable()` | Bridge external source | Sync | Returned bridge must be disposed |
 | `isReactive()` | Test Ripple's marked readable contract | Sync | Not a security or provenance check |
+| `RippleError` | Base package error | Sync | Runtime callback failures retain their original value |
+| `RippleCycleError` | Computed cycle or runaway flush | Sync | Flush failures reach `onError`, not the write site |
+| `RippleDisposedError` | Work after disposal | Sync | Cached reads remain available |
 
 ## Package Entry Point
 
 | Import | Purpose |
 | --- | --- |
-| `@vielzeug/ripple` | All primitives, types, and errors: signals, computed, effects, scopes, watch, tap, and the isolated graph factory |
+| `@vielzeug/ripple` | All primitives, types, and errors: signals, computed, effects, scopes, watch, and the isolated graph factory |
 
 ## Graph Creation
 
@@ -20898,11 +21472,14 @@ ripple.dispose();
 function createRipple(options?: RippleOptions): Ripple;
 ```
 
-Creates one isolated reactive graph. Factories on the returned object share scheduling, ownership, and error boundaries. `dispose()` is terminal: `ripple.disposed` becomes `true`, existing owned work is disposed, and creating more graph work throws `RippleDisposedRuntimeError`. Create a new graph for a new lifetime.
+Creates one isolated reactive graph. Factories on the returned object share scheduling, ownership, and error boundaries. `dispose()` is terminal: `ripple.disposed` becomes `true`, existing owned work is disposed, and creating more graph work throws `RippleDisposedError`. Create a new graph for a new lifetime.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `options.errorPolicy` | `'throw' \| 'swallow'` | Controls whether computed refresh, effect, cleanup, and listener failures rethrow. Default `'throw'`. Error events are always emitted through `tap()`. |
+| `options.onError` | `(error, context) => void` | Handles computed refresh, effect, cleanup, listener, and flush-loop failures. Default rethrows asynchronously via `queueMicrotask`; pass a no-op to silence. A failure in one node never interrupts sibling propagation. |
+
+`onError` is the only runtime option. `RippleErrorContext.kind` is `cleanup`, `computed`,
+`effect`, `flush`, or `listener`; `name` is optional. There is no event stream or error-policy option.
 
 **Returns:** `Ripple`.
 
@@ -20941,7 +21518,7 @@ console.log(isReactive(signal(0)));
 
 ## Default Graph Functions
 
-Root helpers (`signal`, `computed`, `effect`, `batch`, `createScope`, `untrack`, `watch`, `resource`, `fromSubscribable`) operate on a process-lifetime default graph. Use them only when the application has one graph for its entire lifetime: they are never disposed. For isolated, disposable graphs (tests, SSR, embedded features) use `createRipple()`.
+Root helpers (`signal`, `computed`, `effect`, `batch`, `createScope`, `untrack`, `watch`, `resource`, `fromSubscribable`) operate on a process-lifetime default graph. The graph itself has no public disposal handle; effects, scopes, resources, and bridges still require owner-managed disposal. For isolated, disposable graphs (tests, SSR, embedded features) use `createRipple()`.
 
 ### `signal(initial, options?)`
 
@@ -20973,7 +21550,7 @@ cart.update((state) => ({ ...state, items: state.items + 1 }));
 function computed(derive: () => T, options?: ComputedOptions): Readable;
 ```
 
-Creates a lazy read-only value from reactive reads in `derive`. `peek()` may trigger derivation and throw directly. During dependency propagation, a computed refresh failure is reported through `tap()` with context kind `computed` and does not prevent sibling dependents from updating. A disposed computed returns its last cached value from `peek()` without recomputing.
+Creates a lazy read-only value from reactive reads in `derive`. `peek()` may trigger derivation and throw directly. During dependency propagation, a computed refresh failure is reported to `onError` with context kind `computed` and does not prevent sibling dependents from updating. A disposed computed returns its last cached value from `peek()` without recomputing; a computed disposed before its first evaluation throws `RippleDisposedError` instead of returning a value.
 
 **Returns:** `Readable`.
 
@@ -20997,6 +21574,12 @@ function effect(callback: () => Cleanup | undefined, options?: EffectOptions): E
 
 Runs immediately and reruns when its tracked reads change. A returned cleanup runs before the next callback or disposal.
 
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options.name` | `string` | Optional label in error context |
+
+Effects flush synchronously; `EffectOptions` has no scheduler option. Use `batch()` to coalesce writes.
+
 **Returns:** `EffectHandle`.
 
 **Example:**
@@ -21080,16 +21663,31 @@ function resource(
 
 Creates a disposable readable async state and starts loading immediately. Source changes and `reload()` abort stale work before starting the next loader. The last successful value is preserved as `previous`, including when that value is `undefined`.
 
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `source` | `() => Source` | Tracks reactive input reads |
+| `loader` | `(source, context) => Promise` | Receives input and a request-owned cancellation signal |
+| `options.name` | `string` | Optional resource label |
+
+**Returns:** `Resource`. Source and loader failures become error state, not `onError` reports.
+
+**Example:**
+
 ```ts
+import { resource, signal } from '@vielzeug/ripple';
+
+const userId = signal('42');
 const user = resource(
   () => userId.value,
   (id, { signal }) => fetch(`/users/${id}`, { signal }).then((response) => response.json()),
 );
+console.log(user.value);
+user.dispose();
 ```
 
-The state is `{ status: 'pending', previous? }`, `{ status: 'success', value }`, or `{ status: 'error', error, previous? }`. Reads remain available after disposal; `reload()` and new subscriptions throw `RippleDisposedResourceError`.
+The state is `{ status: 'pending', previous? }`, `{ status: 'success', value }`, or `{ status: 'error', error, previous? }`. Reads remain available after disposal; `reload()` and new subscriptions throw `RippleDisposedError`.
 
-## Watch and Observability
+## Watch
 
 ### `watch(source, callback, options?)`
 
@@ -21117,41 +21715,6 @@ stop.dispose();
 
 ---
 
-### `ripple.tap(handler, options?)`
-
-```ts
-function tap(
-  handler: (event: RippleEvent) => void,
-  options?: { signal?: AbortSignal },
-): Unsubscribe;
-```
-
-Runtime observability for writes, computes, effects, disposals, and reported errors. Computed refresh errors are reported with context kind `computed` without interrupting sibling propagation. During graph disposal, taps remain active for owned cleanup errors and node disposal events; `dispose:graph` is emitted last. Handler errors are swallowed. The returned function unsubscribes, and an optional signal auto-detaches it.
-
-The `Ripple.tap()` method is available on instances created with `createRipple()`. After runtime disposal it returns a no-op unsubscribe.
-
-**Returns:** `Unsubscribe`.
-
-**Example:**
-
-```ts
-import { createRipple } from '@vielzeug/ripple';
-
-const ripple = createRipple({ errorPolicy: 'swallow' });
-const stop = ripple.tap((event) => {
-  if (event.type === 'error') console.error(event.context.kind, event.error);
-  if (event.type === 'write') console.log(`${event.name}: ${event.previous} → ${event.next}`);
-});
-
-const count = ripple.signal(0);
-count.value = 1;
-
-stop();
-ripple.dispose();
-```
-
----
-
 ### `fromSubscribable(source, options?)`
 
 ```ts
@@ -21167,12 +21730,20 @@ Bridges an external `{ getSnapshot, subscribe }` source into a disposable reacti
 ```ts
 import { fromSubscribable } from '@vielzeug/ripple';
 
-const routerState = fromSubscribable({
-  getSnapshot: () => router.getSnapshot(),
-  subscribe: (cb) => router.subscribe(cb),
+let current = 'idle';
+const listeners = new Set void>();
+const state = fromSubscribable({
+  getSnapshot: () => current,
+  subscribe: (listener) => {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+  },
 });
 
-routerState.dispose();
+current = 'ready';
+for (const listener of listeners) listener();
+console.log(state.value);
+state.dispose();
 ```
 
 ## Types
@@ -21187,20 +21758,13 @@ type ComputedOptions = { equals?: Equality; name?: string };
 type EffectOptions = { name?: string };
 type WatchOptions = { equals?: Equality; immediate?: boolean; name?: string };
 
-type RippleErrorContext = { readonly kind: 'cleanup' | 'computed' | 'effect' | 'listener'; readonly name?: string };
-type RippleErrorPolicy = 'throw' | 'swallow';
-type RippleOptions = { errorPolicy?: RippleErrorPolicy };
-
-type RippleEvent =
-  | { readonly type: 'compute'; readonly name?: string }
-  | { readonly type: 'effect'; readonly name?: string }
-  | { readonly type: 'write'; readonly name?: string; readonly next: unknown; readonly previous: unknown }
-  | { readonly type: 'dispose'; readonly name?: string; readonly node: 'effect' | 'graph' | 'scope' }
-  | { readonly type: 'error'; readonly error: unknown; readonly context: RippleErrorContext };
+type RippleErrorContext = { readonly kind: 'cleanup' | 'computed' | 'effect' | 'flush' | 'listener'; readonly name?: string };
+type RippleOptions = { onError?: (error: unknown, context: RippleErrorContext) => void };
 
 interface Readable {
   readonly name?: string;
   peek(): T;
+  /** Change-only: the listener is not called on subscribe, only after a tracked source changes. */
   subscribe(listener: () => void): Unsubscribe;
   readonly value: T;
 }
@@ -21241,7 +21805,6 @@ interface Ripple extends Disposable {
     options?: ResourceOptions,
   ): Resource;
   signal(initial: T, options?: SignalOptions): Signal;
-  tap(handler: (event: RippleEvent) => void, options?: { signal?: AbortSignal }): Unsubscribe;
   untrack(fn: () => T): T;
   watch(source: Readable | (() => T), callback: (value: T, previous: T | undefined) => void, options?: WatchOptions): EffectHandle;
 }
@@ -21251,12 +21814,13 @@ interface Ripple extends Disposable {
 
 | Error | Trigger | Notable properties |
 | --- | --- | --- |
-| `RippleError` | Base Ripple error | Use `instanceof RippleError` to narrow unknown values. |
-| `RippleComputedCycleError` | Computed dependency reads itself through a cycle | Extends `RippleError`. |
-| `RippleDisposedResourceError` | `reload()` or `subscribe()` used after resource disposal | Extends `RippleError`. |
-| `RippleDisposedRuntimeError` | Factory or execution API used after `ripple.dispose()` | Extends `RippleError`. |
-| `RippleDisposedScopeError` | `scope.run()` after scope disposal | Extends `RippleError`. |
-| `RippleInfiniteLoopError` | Effect flush exceeds graph iteration limit | Extends `RippleError`. |
+| `RippleError` | Base Ripple error; a new subscription to a disposed external-source bridge | Use `instanceof RippleError` to narrow unknown values. |
+| `RippleCycleError` | A computed reads itself, or a flush exceeds the iteration limit | Extends `RippleError`. A flush-loop breach is reported to `onError` (context kind `flush`) instead of throwing from the write site. |
+| `RippleDisposedError` | New graph work, writes, or subscriptions on a disposed runtime; `run()` on a disposed scope; `reload()` or new subscriptions on a disposed resource; reading a never-evaluated disposed computed | Extends `RippleError`. Cached reads and repeated disposal remain valid. |
+
+These are the three exported error classes. User callback failures are reported as their original
+values through `onError`; they are not wrapped in `RippleError`. A direct computed read can throw
+its derivation error to the caller.
 
 ### Usage Guide
 
@@ -21282,10 +21846,8 @@ Use `createRipple()` for tests, SSR requests, embedded applications, or independ
 ```ts
 import { createRipple } from '@vielzeug/ripple';
 
-const ripple = createRipple({ errorPolicy: 'swallow' });
-
-ripple.tap((event) => {
-  if (event.type === 'error') console.log(event.context.kind, event.error);
+const ripple = createRipple({
+  onError: (error, context) => console.log(context.kind, error),
 });
 
 const count = ripple.signal(0);
@@ -21371,26 +21933,28 @@ const stopWatch = ripple.watch(
 stopWatch.dispose();
 ```
 
-## Observability
+## Error Handling
 
-`tap()` receives writes, computes, effects, disposals, and reported errors. Computed refresh failures are isolated and reported without interrupting sibling propagation. During runtime disposal, owned cleanup errors and node disposal events are emitted before the final graph disposal event; handlers remain active until that sequence completes. Tap-handler errors are swallowed.
+Failures inside effect callbacks, computed derivations, cleanups, and listeners never corrupt the graph: the failing node is reported and siblings keep propagating. The `onError` option decides what reporting means. By default failures rethrow asynchronously (via `queueMicrotask`), surfacing as unhandled errors; pass a handler to route them to a logger or error boundary instead:
 
 ```ts
-const ripple = createRipple({ errorPolicy: 'swallow' });
-
-ripple.tap((event) => {
-  switch (event.type) {
-    case 'write':
-      console.log(`${event.name}: ${event.previous} → ${event.next}`);
-      break;
-    case 'error':
-      console.error(`${event.context.kind}:`, event.error);
-      break;
-  }
+const ripple = createRipple({
+  onError: (error, context) => {
+    // context.kind: 'cleanup' | 'computed' | 'effect' | 'flush' | 'listener'
+    console.error(`${context.kind}:`, error);
+  },
 });
 ```
 
-`errorPolicy` controls whether computed refresh, effect, cleanup, and listener failures rethrow (`'throw'`, default) or are silenced (`'swallow'`). Error events are emitted through `tap()` regardless of policy.
+`onError` is the only runtime option. Effect options accept only a `name`; effects do not have a
+microtask scheduler. Use `batch()` to coalesce related writes.
+
+A direct computed read can throw its derivation error to the caller. `onError` handles computed
+refresh failures during propagation, not every possible synchronous exception. The exported
+hierarchy is `RippleError`, `RippleCycleError`, and `RippleDisposedError`; callback failures retain
+their original values.
+
+A runaway effect (one that keeps re-triggering itself) is caught by the flush iteration limit and reported with context kind `flush`; the flush is abandoned and the graph stays usable for later writes.
 
 ## Bridging External Sources
 
@@ -21426,15 +21990,19 @@ const user = ripple.resource(
 
 const stop = ripple.effect(() => {
   const state = user.value;
-  if (state.status === 'success') renderUser(state.value);
-  if (state.status === 'error') renderError(state.error);
+  if (state.status === 'success') console.log(state.value);
+  if (state.status === 'error') console.error(state.error);
 });
 
 stop.dispose();
 user.dispose();
 ```
 
-Disposed resources retain readable state but reject `reload()` and new subscriptions with `RippleDisposedResourceError`. Use Sourcerer for paginated collection state and a dedicated server-state cache for shared keyed reads, retries, and invalidation.
+Source and loader failures become resource error state rather than `onError` reports.
+`reload()` returns `void`; observe state to know when loading finishes. Disposed resources retain
+readable state but throw `RippleDisposedError` from `reload()` and new subscriptions. Use Sourcerer
+for paginated collection state and a dedicated server-state cache for shared keyed reads, retries,
+and invalidation.
 
 ## Object State
 
@@ -21554,13 +22122,21 @@ ripple.dispose();
 
 ## Gotchas
 
+### `subscribe()` is change-only
+
+`Readable.subscribe(listener)` never calls the listener on subscribe: it fires only after a tracked source changes. Read the current value at the call site when you need an initial state.
+
 ### `subscribe()` forces computed evaluation
 
 `Readable.subscribe()` calls `peek()` before registering the listener. For signals this is a no-op, but for computeds it forces `refresh()`: the derivation runs immediately even if no one reads `.value`. This ensures `equals` comparison works on the first dependency change. Avoid subscribing to expensive computeds unless you need their value.
 
+### Diamonds recompute each path once per write
+
+A computed with dependents refreshes eagerly during propagation, so effects never re-run for unchanged derived values. The tradeoff: in a diamond (`a → b, c → d`), one write to `a` recomputes both `b` and `c` and then `d` once per changed path. Values a consumer observes are always consistent: a dependent reading a stale intermediate pulls the fresh value on read, so no glitched state is ever visible. Prefer keeping diamond depth shallow when a derivation is expensive.
+
 ### Computed first-run failure is recoverable
 
-If a computed's `derive` throws on its first run (e.g., a source is `null`), the computed commits the partial dependencies it tracked before the throw. When a dependency changes and the derivation can succeed, the computed refreshes and notifies its dependents. Effects that read a failing computed report the error through `tap()` and re-run when the computed recovers.
+If a computed's `derive` throws on its first run (e.g., a source is `null`), the computed commits the partial dependencies it tracked before the throw. When a dependency changes and the derivation can succeed, the computed refreshes and notifies its dependents. Effects that read a failing computed report the error through `onError` and re-run when the computed recovers.
 
 ## Best Practices
 
@@ -21571,8 +22147,7 @@ If a computed's `derive` throws on its first run (e.g., a source is `null`), the
 - Batch related synchronous writes.
 - Use `watch()` only for selected source transitions; callback-only reads are untracked.
 - Dispose external-source bridges when their owner ends.
-- Use `tap()` for runtime observability; set `errorPolicy: 'swallow'` to silence rethrow.
-- Use `resource()` for focused async state and Sourcerer for paginated collection workflows.
+- Route runtime failures with `onError` and observe async failures through resource state.
 
 ### Examples
 
@@ -21591,7 +22166,7 @@ If a computed's `derive` throws on its first run (e.g., a source is `null`), the
 - Async Resource (id: `async-resource`)
 - Create Graph, Signal, Computed & Effect (id: `basic-signal`)
 - Batch & Untrack (id: `batch-untrack`)
-- Microtask Effect (id: `effect-options`)
+- Named Effect and onError (id: `effect-options`)
 - Nested Effect Ownership (id: `scope-ownership`)
 - Immutable State (id: `store-basics`)
 - Watch Selected Value (id: `watch-selected-value`)
@@ -28350,7 +28925,9 @@ try {
 - `createPageSource()`: loads numbered pages and exposes direct navigation commands
 - `createCursorSource()`: follows opaque cursors returned by the loader
 - `createInfiniteSource()`: appends pages while preserving loaded items
+- `createResource()`: starts loading one value immediately, or awaits `reload()` with `start: false`
 - `setParams()`: replaces consumer-owned loader parameters and resets pagination
+- `PageSource.apply()`: reconciles page and structurally compared params in at most one request
 - `subscribe()`: publishes complete immutable state replacements
 
 ## Documentation
@@ -28377,7 +28954,10 @@ try {
 | `createPageSource()` | Load numbered pages | Async | Construction is inert |
 | `createCursorSource()` | Load server-issued cursor pages | Async | `after` and `before` cannot coexist initially |
 | `createInfiniteSource()` | Append numbered pages | Async | `loadMore()` is a no-op while loading or exhausted |
+| `createResource()` | Load one reactive value | Async | Starts loading during construction; `start: false` opts out |
 | `SourcererError` | Base package error | Sync | Loader errors retain their original type |
+| `SourcererConfigurationError` | Invalid pagination configuration | Sync | Pages and page sizes must be positive integers |
+| `SourcererDisposedError` | Command after source disposal | Sync | In-flight work instead settles without committing |
 
 ## Package Entry Point
 
@@ -28462,6 +29042,7 @@ await source.reload();
 
 | Method | Returns | Description |
 | --- | --- | --- |
+| `apply(update)` | `Promise` | Reconcile `{ params, page }` in at most one load; params compare structurally |
 | `first()` | `Promise` | Load page one |
 | `goTo(page)` | `Promise` | Load a positive page |
 | `last()` | `Promise` | Load the last known page |
@@ -28473,6 +29054,14 @@ await source.reload();
 | `subscribe(listener)` | `() => void` | Register a state listener and return its unsubscribe function |
 | `dispose()` | `void` | Abort work and stop notifications |
 
+`apply(update: PageSourceUpdate): Promise` compares params structurally with
+`isEqual`. Changed params use the supplied positive page without clamping, or page one when omitted.
+Unchanged params with a page use `goTo()` and clamp after the first successful load.
+An unchanged request does not refetch a committed result or duplicate an active request; it loads
+an inert source or retries an uncommitted request after failure. Omitted or `undefined` params
+preserve the requested value; use `setParams(undefined)` when `undefined` is a valid replacement.
+The update does not include page size; use `setPageSize()` separately.
+
 ---
 
 ### `createCursorSource()`
@@ -28550,6 +29139,54 @@ await source.loadMore();
 | `subscribe(listener)` | `() => void` | Register a state listener and return its unsubscribe function |
 | `dispose()` | `void` | Abort work and stop notifications |
 
+---
+
+### `createResource()`
+
+```ts
+function createResource(config: ResourceConfig): Resource
+```
+
+Returns observable state for one asynchronously loaded value. It does not suspend rendering,
+cache by key, or track external reactive inputs.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `config.load` | `(context: ResourceLoadContext) => Promise` | Loader; receives a signal aborted on disposal and on the next `reload()` |
+| `config.start` | `boolean` | Start the initial load during construction; defaults to `true` |
+
+**Returns:** `Resource`.
+
+```ts
+import { createResource } from '@vielzeug/sourcerer';
+
+const profile = createResource({
+  load: ({ signal }) => fetch('/me', { signal }).then((response) => response.json()),
+  start: false,
+});
+
+const stop = profile.subscribe((state) => console.log(state.data, state.loading, state.error));
+console.log(profile.state);
+try {
+  await profile.reload();
+} finally {
+  stop();
+  profile.dispose();
+}
+```
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `reload()` | `Promise` | Refetch with a fresh signal; rejects so callers can await it |
+| `subscribe(listener)` | `() => void` | Register a state listener and return its unsubscribe function |
+| `dispose()` | `void` | Abort the in-flight load and stop notifications |
+
+Construction starts the initial load unless `start: false`. Its failure surfaces through
+`state.error`; a later `reload()` rejects and retains the previous `data` on failure.
+A superseded or disposed request settles without touching state. Subscriptions are change-only:
+read `state` for the current snapshot, including the initial loading state. `dispose()` is idempotent,
+aborts `disposalSignal`, and leaves the last snapshot readable; subscriptions after disposal are inert.
+
 ## Types
 
 ### Page source types
@@ -28568,8 +29205,11 @@ type PageSourceConfig = Readonly): Promise>;
   } & (undefined extends TParams ? { params?: TParams } : { params: TParams })
 >;
 
+type PageSourceUpdate = Readonly;
+
 type PageSource = {
   [Symbol.dispose](): void;
+  apply(update: PageSourceUpdate): Promise;
   readonly disposalSignal: AbortSignal;
   dispose(): void;
   readonly disposed: boolean;
@@ -28588,6 +29228,28 @@ type PageSource = {
 
 The conditional config field makes `params` optional only when `TParams` includes `undefined`.
 
+### Resource types
+
+```ts
+type ResourceLoadContext = Readonly;
+
+type ResourceState = Readonly;
+
+type ResourceConfig = Readonly;
+  start?: boolean;
+}>;
+
+type Resource = {
+  [Symbol.dispose](): void;
+  readonly disposalSignal: AbortSignal;
+  dispose(): void;
+  readonly disposed: boolean;
+  reload(): Promise;
+  readonly state: ResourceState;
+  subscribe(listener: (state: ResourceState) => void): () => void;
+};
+```
+
 ### Local source types
 
 ```ts
@@ -28736,7 +29398,7 @@ console.log(source.state.params);
 source.dispose();
 ```
 
-A non-optional parameter type requires an initial `params` value. Sourcerer compares parameter values with `Object.is`; reuse a value when setting it again should be a no-op.
+A non-optional parameter type requires an initial `params` value. `setParams()` compares values with `Object.is`; `apply()` compares structurally, avoiding redundant requests from a router or reactive effect. Both can load an inert source or retry an uncommitted request. See [Apply Page and Filter Together](#apply-page-and-filter-together).
 
 While replacement parameters load, `state.params` continues to describe the committed items and `state.pendingParams` contains the requested value. Page-only navigation does not set `pendingParams`.
 
@@ -28756,6 +29418,47 @@ await source.setPageSize(50);
 
 After the first successful load, navigation is clamped to the known `pageCount`. Before that load, `goTo()` accepts any positive page because the total is unknown.
 
+## Apply Page and Filter Together
+
+A URL query, a filter form, or a router state usually carries the page and the filters at once. `apply()` accepts both in one call and issues at most one request.
+
+```ts
+import { createPageSource } from '@vielzeug/sourcerer';
+
+const names = ['Ada', 'Grace', 'Linus', 'Ada Byron'];
+const source = createPageSource({
+  load: async ({ page, pageSize, params }) => {
+    const matching = names.filter((name) => name.includes(params.search));
+    const start = (page - 1) * pageSize;
+    return { items: matching.slice(start, start + pageSize), totalItems: matching.length };
+  },
+  pageSize: 1,
+  params: { search: '' },
+});
+
+try {
+  await source.apply({ page: 2, params: { search: 'Ada' } });
+  console.log(source.state.items); // ['Ada Byron']
+  await source.apply({ params: { search: 'Ada' } });
+  console.log(source.state.pagination.page); // 2; no extra request
+  await source.apply({ params: { search: 'Grace' } });
+  console.log(source.state.pagination.page); // 1
+} finally {
+  source.dispose();
+}
+```
+
+Parameters are compared structurally, so a freshly built object with the same contents does not
+refetch a committed result or duplicate active work. An inert source still loads, and an unchanged
+request can retry after failure. When parameters change,
+`page` is validated but never clamped: the page count still describes the previous filter set, so
+clamping against it would silently move the reader elsewhere. Omit `page` in that case and the
+source returns to page one. When parameters are unchanged, `apply()` routes through `goTo()` and
+clamps to the known page count.
+
+Omitted or `undefined` params keep the requested value. Use `setParams(undefined)` when
+your parameter type allows `undefined` and you want to replace the value with it.
+
 ## Filter Local Collections
 
 Use a local source when data is already in memory. Its commands are synchronous.
@@ -28831,6 +29534,44 @@ source.dispose();
 
 `loadMore()` is a no-op while another request is active or after `pagination.hasMore` becomes false. `setParams()` and `setPageSize()` replace the feed from page one.
 
+## Load a Single Value
+
+Use a resource for one reactive value: a profile, a settings document, a pricing summary. It loads once and refetches on demand.
+
+```ts
+import { createResource } from '@vielzeug/sourcerer';
+
+type Profile = { name: string };
+const profile = createResource({
+  load: async ({ signal }) => {
+    const response = await fetch('/me', { signal });
+    if (!response.ok) throw new Error(`Profile request failed: ${response.status}`);
+    return response.json();
+  },
+  start: false,
+});
+
+const stop = profile.subscribe((state) => console.log(state.data, state.loading, state.error));
+console.log(profile.state);
+try {
+  await profile.reload();
+} catch (error) {
+  console.error(error);
+} finally {
+  stop();
+  profile.dispose();
+}
+```
+
+A resource starts loading during construction by default; the example uses `start: false` to await
+the first load explicitly. Automatic initial-load failures land in `state.error` without an
+unhandled rejection. Explicit `reload()` calls reject current failures and preserve previous `data`.
+Reloading aborts older work, whose promise settles without committing.
+
+Read `state` before subscribing when you need the initial snapshot: subscriptions notify only
+changes. A resource does not track Ripple signals or cache values by key; call `reload()` when
+external inputs change. Disposal aborts work and retains the last readable snapshot.
+
 ## Handle Requests and Errors
 
 A new remote command aborts older work. Superseded or disposed work settles without committing. A current loader failure preserves committed items, writes the error to state, and rejects the command.
@@ -28963,6 +29704,7 @@ Use Scout to compute indexed local matches, Ripple to project state into reactiv
 - [Page Params with URL State](./examples/remote-search-with-url-state.md)
 - [Cursor-Based Pagination](./examples/cursor-based-pagination.md)
 - [Infinite Scroll](./examples/infinite-scroll.md)
+- [Load a Single Value](./examples/single-value-resource.md)
 - [Framework Integration](./examples/framework-integration.md)
 - [Remote Data with Courier](./examples/sourcerer-with-courier.md)
 - [Reactive Controls with Ripple](./examples/sourcerer-with-ripple.md)
@@ -28970,12 +29712,14 @@ Use Scout to compute indexed local matches, Ripple to project state into reactiv
 
 ### REPL Examples
 
+- apply - Page and params in one call (id: `apply`)
 - Cursor Source (id: `cursor-source`)
 - Error Handling (id: `error-handling`)
 - Infinite Source (id: `infinite-source`)
 - Source Lifecycle (id: `lifecycle`)
 - Local Source (id: `local-source`)
 - Page Source (id: `page-source`)
+- createResource - One reactive value (id: `resource`)
 
 ---