@vielzeug/codex 26.10.7 → 26.10.9

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.8
 
 ---
 
@@ -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
@@ -147,7 +147,7 @@ console.log(parsed.entries);
 | 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/worker` | Catalog factory, issuer signing-key/session service binding and event types |
 | `@vielzeug/archive/auth` | Issuer factory and binding types |
 
 ## Collections
@@ -243,8 +243,13 @@ export default createArchiveWorker([notes]);
 | `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.
@@ -404,8 +409,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
@@ -927,8 +934,8 @@ well-formed, or the route answers 503 without naming what is missing:
 | ------------------------ | ---------------------------------------------------------------- |
 | `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   |
+| `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 |
@@ -941,6 +948,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
@@ -1377,6 +1392,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 +1421,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 +1443,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 +1471,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 +1765,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 +1849,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 +2069,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 +2171,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 +2199,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 +2298,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 +2503,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 +4707,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 +4739,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 +4987,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 +4998,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 +5252,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 +5419,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 +15852,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 +15900,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 +16015,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 +16054,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 +16078,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 +16199,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 +16213,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 +16233,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 +16259,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 +16269,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 +16447,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 +16620,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 +16635,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 +16644,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 +16692,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`.
 
-Use `live(signal)` for inputs that should preserve in-progress user edits instead of overwriting the DOM on stale writes.
+## 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 })} />
+`;
+```
+
+## 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 +17099,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 +20818,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 +20922,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 +21035,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 +21072,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 +21297,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 +21335,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 +21356,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 +21402,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 +21434,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 +21458,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 +21547,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 +21599,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 +21614,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 +21642,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 +21689,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 +21698,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 +21730,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 +21817,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 +21874,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 +22006,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 +22031,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 +22050,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 +28809,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 +28838,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 +28926,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 +28938,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 +29023,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 +29089,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 +29112,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 +29282,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 +29302,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 +29418,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 +29588,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 +29596,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`)
 
 ---