@vielzeug/codex 26.10.4 → 26.10.6

package/data/llms-full.txt

@@ -1,6 +1,1301 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 41 packages. Version: 26.10.3
+> Complete documentation for 42 packages. Version: 26.10.6
+
+---
+
+## @vielzeug/archive
+
+**Category:** utilities
+
+### Overview
+
+## Why Archive?
+
+You can share content entries with ranked browsing, filters, likes and account
+erasure on Cloudflare Workers + D1. `defineArchiveCollection` supplies your JSON
+payload schema and indexing rules; the Worker supplies sessions, guards,
+idempotent publishing, cursors and rate limits.
+
+```ts
+// Before: each deployment repeats validation, indexing and route plumbing.
+
+// After: the deployment is one collection definition plus one factory call.
+import { defineArchiveCollection } from '@vielzeug/archive';
+import { createArchiveWorker } from '@vielzeug/archive/worker';
+import { s } from '@vielzeug/spell';
+
+const notes = defineArchiveCollection({
+  name: 'notes', contentVersion: 1,
+  payloadSchema: s.object({ title: s.string().min(1).max(128) }),
+  index: ({ title }) => ({ title, filter: null, tags: [] }),
+});
+export default createArchiveWorker([notes]);
+```
+
+| Feature                              | Archive                                                  | Hand-rolled Worker                  | BaaS (Firebase/Supabase)              |
+| ------------------------------------ | -------------------------------------------------------- | ------------------------------------ | ------------------------------------- |
+| Bundle size (core)                   |         | Depends on deployment code | Depends on selected SDK |
+| Zero dependencies | No — Spell and jose | Depends on implementation | No — client SDK |
+| Content knowledge in the core        |  none — one collection seam |  baked in |  rules everywhere |
+| Canonical fresh-database D1 schema   |  in the package      | Deployment-owned | Not a D1 backend |
+| Idempotent publish w/ tombstones     |  built-in      |  rebuild it |  rebuild it |
+| GDPR erasure / export endpoints      |  built-in      |  rebuild it |  partial |
+| Strict DTO re-validation on read     |  every entry   |  optional |  optional |
+
+**Use Archive when** an app needs a shareable, ranked, liked community space for
+content entries on Cloudflare Workers + D1, and can express its content as one strict
+payload schema.
+**Consider alternatives when** you need rich queries beyond filter/tag/search, live
+collaboration, or a backend you do not control — Archive is deliberately one narrow,
+hardened surface.
+
+## Installation
+
+```sh [pnpm]
+pnpm add @vielzeug/archive @vielzeug/spell
+```
+
+```sh [npm]
+npm install @vielzeug/archive @vielzeug/spell
+```
+
+```sh [yarn]
+yarn add @vielzeug/archive @vielzeug/spell
+```
+
+## Quick Start
+
+A deployment is one collection definition plus one factory call. The definition
+brings the payload schema and what to index; everything else — the emitted-entry
+envelope, the content hash, the wire contract, the routes — is composed for you.
+
+```ts
+import { defineArchiveCollection } from '@vielzeug/archive';
+import { createArchiveWorker } from '@vielzeug/archive/worker';
+import { s } from '@vielzeug/spell';
+
+// The collection's payload: one strict schema is the whole content contract.
+const payloadSchema = s.object({
+  cuisine: s.enum(['italian', 'japanese']),
+  ingredients: s.array(s.string().trim().min(1).max(64)).min(1).max(20),
+  name: s.string().trim().min(1).max(32),
+});
+
+const recipesCollection = defineArchiveCollection({
+  canonicalize: (payload) => ({ ...payload, ingredients: [...payload.ingredients].sort() }),
+  contentVersion: 1,
+  filters: ['italian', 'japanese'],
+  index: (payload) => ({
+    filter: payload.cuisine,
+    tags: [payload.ingredients.length  ({ title, filter: null, tags: [] }),
+});
+const response = await fetch('/api/v1/collections/notes/entries?sort=liked');
+if (!response.ok) throw new Error('Archive unavailable');
+const parsed = notes.contract.page.parse(await response.json());
+console.log(parsed.entries);
+```
+
+## Features
+
+- `defineArchiveCollection` — the one content seam: payload schema, canonicalization, filter/tag/title derivation, union-typed vocabularies
+- `createArchiveWorker` — the whole routes/auth/limits/SQL stack from registered collections
+- `collection.contract` — entry, page, publish/update input schemas shared by client and Worker
+- `ARCHIVE_LIMITS` + `archiveHealthSchema` — the application bounds, advertised by health and validated on both sides
+- `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
+- `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
+- `migrations/` — canonical fresh-database DDL with the storage stamp health reads back; no upgrade framework
+
+## Documentation
+
+- [Usage Guide](./usage.md) — stand up a collection, deploy the Worker, wire the client.
+- [API Reference](./api.md) — every export, all three entry points, the full route table.
+- [Examples](./examples.md) — recipes from first deployment to GDPR erasure.
+- [Release Status](./migration.md) — unreleased package and fresh-database scope.
+
+## See Also
+
+- [Spell](/spell/) — every payload schema here is a spell schema; the core composes envelopes from it.
+- [Courier](/courier/) — the HTTP client shape an app's frontend mirrors to consume these routes.
+- [Rune](/rune/) — the structured logger a deployment points `worker.tap()` events at.
+
+### API Reference
+
+## 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 |
+
+## 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, operator lifetime and binding types |
+
+## Collections
+
+### `defineArchiveCollection`
+
+Creates a frozen collection and its contract; malformed names, versions or vocabularies throw `ArchiveDefinitionError`.
+
+```ts
+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 |
+
+**Returns:** `ArchiveCollection`.
+
+**Example:** define and derive one collection without Worker bindings.
+
+```ts
+import { defineArchiveCollection } from '@vielzeug/archive';
+import { s } from '@vielzeug/spell';
+
+const recipes = defineArchiveCollection({
+  name: 'recipes',
+  contentVersion: 1,
+  payloadSchema: s.object({ name: s.string().min(1).max(32) }),
+  index: (payload) => ({ filter: null, tags: [], title: payload.name }),
+});
+const derived = await recipes.derive({ name: 'Rice' });
+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 forward/backward cursors |
+| `contract.publishInput`, `updateInput` | Publish and revision-guarded update request schemas |
+| `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
+submitted content. Invalid index-result shapes also throw.
+
+Const generics preserve the content-version literal and infer filter/tag unions from vocabulary arrays without `as const`. `NoInfer` prevents `index` from widening those unions; omitted arrays infer `never`, permitting only `filter: null` and empty tags.
+
+Objects serialize with recursively sorted keys; arrays preserve order unless your canonicalizer changes it. SHA-256 hashes the core-owned `{contentVersion, payload}` envelope. Response schemas require stored payloads to remain stable under parsing; a response-validation fault has stage `response`.
+
+`filter`, tags and searchable title are persisted projections, not computed during reads. Changing `index` or its vocabulary does not update stored rows. The active definition and persisted dataset must remain consistent; Archive has no projection-update or historical-schema API.
+
+## Worker and Maintenance
+
+### `createArchiveWorker`
+
+Returns the catalog request/scheduled handler and its observation side channel.
+
+```ts
+function createArchiveWorker(
+  collections: readonly ArchiveCollection[],
+): ArchiveWorkerHandler;
+```
+
+**Returns:** `ArchiveWorkerHandler`; duplicate names throw `ArchiveDefinitionError` at registration.
+
+**Example:** export a deployable Worker using the package's structural bindings.
+
+```ts
+import { defineArchiveCollection } from '@vielzeug/archive';
+import { createArchiveWorker, type ArchiveWorkerEnv } from '@vielzeug/archive/worker';
+import { s } from '@vielzeug/spell';
+
+const notes = defineArchiveCollection({
+  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` |
+| `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 |
+
+`AUTH_ISSUER_SERVICE` is a required `fetch`-shaped service binding to the issuer.
+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.
+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.
+
+Only anonymous entry lists can use the 30-second edge cache. Any `Cookie` or `Authorization` header disables caching, even if invalid or empty. Detail, metadata, private and error responses are `no-store`. Public reads do not verify sessions.
+
+---
+
+### `worker.tap`
+
+Observes typed request, scheduled and cache-failure events without affecting request behavior.
+
+```ts
+tap(handler: (event: ArchiveEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
+```
+
+**Returns:** an unsubscribe function; abort detaches the observer. Diagnostics contain categories and trusted configuration field names, never raw errors, SQL, subjects, aliases, tokens or URLs.
+
+**Example:** observe a Worker and detach explicitly.
+
+```ts
+import { createArchiveWorker, type ArchiveWorkerEnv } from '@vielzeug/archive/worker';
+
+const worker = createArchiveWorker([]);
+const stop = worker.tap((event) => console.log(JSON.stringify(event)));
+stop();
+```
+
+---
+
+## Identity Issuer
+
+### `createAuthWorker`
+
+Returns the passwordless email issuer with account export and coordinated erasure.
+
+```ts
+function createAuthWorker(): AuthWorkerHandler;
+```
+
+**Returns:** `AuthWorkerHandler`.
+
+**Example:** export an issuer configured through deployment bindings.
+
+```ts
+import { createAuthWorker, type AuthWorkerEnv } from '@vielzeug/archive/auth';
+
+export default createAuthWorker();
+```
+
+| 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 |
+
+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.
+
+The issuer-global admission budget is durable D1 state in `auth_sign_in_budget`:
+20 requests per 60-second window before account creation or email delivery.
+This supplements, rather than replaces, the durable per-email budget. No external
+rate-limiter binding is required.
+Admission spends are not refunded after later database or email failures.
+Request emails are trimmed and lowercased before validation. `SENDER_ADDRESS`
+must already be canonical; `OPERATOR_EMAILS` entries are trimmed and lowercased
+before validation.
+
+Sign-in requests create pending account rows with `lastSignInAt: null`. Successful
+redemption atomically claims the one-use link and stamps the account's sign-in
+time. The sweep deletes expired links and closed per-user send windows, then
+unverified accounts with neither remaining links nor send-budget references.
+Verified accounts are retained until explicit account deletion.
+
+`@vielzeug/archive/auth` exports `OPERATOR_SESSION_MAX_AGE_SECONDS = 900` alongside
+the factory and issuer binding types.
+
+`AUTH_JWT_PREVIOUS_PUBLIC_JWKS` optionally publishes retired public RS256 keys and verifies sessions minted before rotation; private members reject configuration. The package has no demo sign-in routes.
+
+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.
+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.
+
+The issuer never logs directly. `tap` emits sanitized request and scheduled
+outcomes; observer failures are swallowed, abort detaches the observer and failed
+scheduled work emits then rethrows. `AuthDiagnostic` reports only a category.
+
+## HTTP Routes
+
+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`; bidirectional 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 |
+
+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`.
+
+Full erasure creates an issuer/subject revocation tombstone for 30 days plus ten
+seconds and deletes the profile in the same transaction. Catalog authentication
+rejects that subject with 401 on ordinary private routes; registration also checks
+revocation in SQL to prevent resurrection races. Only `DELETE /me/account` may
+bypass the issuer session lookup, and only to retry erasure with the original
+signed session of the same principal while its existing revocation tombstone is
+valid; JWT signature and claims are still verified. It is not a general
+stale-session exception: initial erasure validates the issuer session. The
+issuer-facing `DELETE /auth/account` always checks the current session version
+before calling the catalog, so retrying it after completed erasure returns 401
+because the account is absent.
+Direct profile-only `DELETE /me` allows later registration using the same session.
+The sweep removes expired tombstones. Re-enrollment through the reference issuer
+creates a fresh account UUID subject; an external issuer must issue a new subject
+to re-enroll during the revocation window.
+
+The issuer stores `auth_users.session_version` as a safe non-negative integer,
+defaulting to `0`. Every session JWT carries the current value as the required
+`sessionVersion` claim. Each ordinary issuer-authenticated route compares that
+claim to the current account row; a mismatch is unauthenticated. `POST
+/api/v1/auth/sign-out-all` checks the captured issuer account UUID against the
+verified subject before atomically incrementing the version and deleting pending
+links. A changed account answers 409 `account-changed`; a failed request does not
+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
+`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
+cache. Both service directions use a fixed 5000 ms timeout that includes body
+decoding. The issuer's `/api/v1/auth/session` is an internal
+service contract, not a frontend session API.
+
+Issuer readiness is independent of catalog readiness. `GET
+/api/v1/auth/health` returns `archiveAuthHealthSchema` as `AuthHealth`; its
+read-only probe checks configuration, a signing and verification key proof,
+binding shapes, the singleton `auth_schema_meta` stamp against
+`AUTH_SCHEMA_VERSION`, and readability of expected tables, columns and triggers.
+It does not write, send email or probe the catalog service. Responses are
+sanitized.
+Configuration failure, database failure and schema mismatch return HTTP 503
+with `status: 'degraded'` and the corresponding reason.
+
+Effective hide, unhide, operator removal and publisher erasure append audit rows atomically with the state transition. Concurrent idempotent no-ops append nothing. Audit rows contain opaque IDs, not names or content, and have no foreign keys so they outlive erasure. Resolving a report sets `resolvedAt`; it is not one of the four audit action kinds.
+
+## 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, also re-exported by `/auth` |
+| `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`
+
+Composes a session cookie using the shared security attributes.
+
+```ts
+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 |
+
+**Returns:** the `Set-Cookie` value with `HttpOnly`, `SameSite=Strict`, the shared path and optional `Secure`.
+
+**Example:** clear the production cookie.
+
+```ts
+import { sessionCookieValue } from '@vielzeug/archive';
+
+const expiredCookie = sessionCookieValue('', { maxAgeSeconds: 0, secure: true });
+console.log(expiredCookie);
+```
+
+---
+
+### `isWellFormedText`
+
+Checks text for control characters and lone UTF-16 surrogates.
+
+```ts
+function isWellFormedText(value: string): boolean;
+```
+
+**Returns:** `true` when `ILL_FORMED_TEXT` does not match; it does not trim or impose bounds.
+
+**Example:** validate text independently of the alias schema.
+
+```ts
+import { isWellFormedText } from '@vielzeug/archive';
+
+console.log(isWellFormedText('Rice'), isWellFormedText('\u0000'));
+```
+
+### `ARCHIVE_LIMITS`
+
+`ARCHIVE_LIMITS` is frozen with these values:
+
+```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,
+};
+```
+
+## Types
+
+The following definitions use `Schema` from `@vielzeug/spell`. Schema-derived aliases show their complete output shape.
+
+```ts
+interface ArchiveIndexing {
+  filter: F | null;
+  tags: readonly T[];
+  title: string;
+}
+interface ArchiveCollectionDefinition {
+  canonicalize?(payload: P): P;
+  contentVersion: C;
+  filters?: readonly F[];
+  index(payload: P): ArchiveIndexing, NoInfer>;
+  name: string;
+  payloadSchema: Schema;
+  tags?: readonly T[];
+}
+interface ArchiveDerivation {
+  canonicalJson: string;
+  contentHash: string;
+  contentVersion: number;
+  filter: string | null;
+  tags: readonly string[];
+  title: string;
+}
+interface ArchiveEntry {
+  author: { id: string; name: string };
+  contentHash: string;
+  contentVersion: C;
+  id: string;
+  likeCount: number;
+  payload: P;
+  publishedAt: string;
+  revision: number;
+  schemaVersion: typeof ARCHIVE_CONTRACT_VERSION;
+  updatedAt: string;
+}
+interface ArchiveOwnedEntry extends ArchiveEntry {
+  clientKey: string;
+  hidden: boolean;
+}
+interface ArchiveContract {
+  entry: Schema>;
+  ownedEntries: Schema[] }>;
+  ownedEntry: Schema>;
+  page: Schema>>;
+  publishInput: Schema;
+  updateInput: Schema;
+}
+interface ArchiveCollection {
+  readonly contentVersion: C;
+  readonly contract: ArchiveContract;
+  readonly derive: (raw: unknown) => Promise;
+  readonly filters: readonly string[];
+  readonly name: string;
+  readonly tags: readonly string[];
+}
+interface ArchivePage {
+  cursor: string | null;
+  entries: readonly T[];
+  previous: string | null;
+}
+type ArchiveSort = 'liked' | 'recent';
+type ArchiveDerivationStage = 'schema' | 'canonicalize' | 'index' | 'hash' | 'response';
+type ArchiveIdentity = { id: string; name: string; operator: boolean } | null;
+type ArchiveAccount = {
+  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';
+type ArchiveErrorResponse = {
+  error: { code: ArchiveErrorCode; message: string; requestId: string };
+};
+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;
+  };
+  schemaVersion: 1;
+  status: 'ok' | 'degraded';
+  reason: 'database-unavailable' | 'schema-mismatch' | null;
+};
+type AuthHealth = {
+  dbSchemaVersion: number | null;
+  schemaVersion: 1;
+  status: 'ok' | 'degraded';
+  reason: 'configuration-unavailable' | 'database-unavailable' | 'schema-mismatch' | null;
+};
+type ArchiveReports = {
+  cursor: string | null;
+  reports: {
+    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;
+  }[];
+};
+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;
+  }[];
+};
+```
+
+Worker subpath types model only the binding methods the catalog calls.
+
+```ts
+interface D1Statement {
+  all(): Promise;
+  bind(...params: (string | number | null)[]): D1Statement;
+  first(): Promise;
+  run(): Promise;
+}
+interface D1Like {
+  batch(statements: D1Statement[]): Promise;
+  prepare(sql: string): D1Statement;
+}
+interface RateLimiterBinding {
+  limit(input: { key: string }): Promise;
+}
+interface ArchiveWorkerEnv {
+  AUTH_ISSUER_SERVICE: AuthIssuerServiceBinding;
+  ALLOWED_ORIGINS: string;
+  APP_ENV: string;
+  DB: D1Like;
+  JWT_AUDIENCE: string;
+  JWT_ISSUER: string;
+  JWT_JWKS_URL: string;
+  LIKES_ENABLED: string;
+  PUBLISHING_ENABLED: string;
+  RATE_LIMIT_KEY_SECRET: string;
+  READ_LIMIT: RateLimiterBinding;
+  WRITE_LIMIT: RateLimiterBinding;
+}
+interface AuthIssuerServiceBinding {
+  fetch(request: Request): Promise;
+}
+interface ArchiveExecutionContext {
+  waitUntil(promise: Promise): void;
+}
+type ArchiveDiagnostic =
+  | { readonly kind: 'configuration'; readonly field: string }
+  | { readonly kind: 'database' | 'record' | 'schema' | 'internal' | 'cache' | 'collection' };
+interface ArchiveRequestEvent {
+  code: ArchiveErrorCode | 'ok';
+  diagnostic?: ArchiveDiagnostic;
+  ms: number;
+  requestId: string;
+  route: string;
+  status: number;
+  type: 'request';
+}
+type ArchiveScheduledEvent =
+  | { removed: number; type: 'scheduled'; status: 'ok' }
+  | { type: 'scheduled'; status: 'failed'; diagnostic: ArchiveDiagnostic };
+type ArchiveEvent =
+  | ArchiveRequestEvent
+  | ArchiveScheduledEvent
+  | { readonly type: 'cache-error'; readonly diagnostic: ArchiveDiagnostic };
+interface ArchiveWorkerHandler {
+  fetch(request: Request, env: E, ctx: ArchiveExecutionContext): Promise;
+  scheduled?(controller: unknown, env: E, ctx: ArchiveExecutionContext): void | Promise;
+  tap(handler: (event: ArchiveEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
+}
+```
+
+Scheduled `removed` counts the combined expired retry-key and revocation rows.
+
+Auth subpath types describe the sibling issuer and its required service binding.
+
+```ts
+interface SendEmail {
+  send(message: { from: string; html?: string; subject: string; text: string; to: string }): Promise;
+}
+interface AuthArchiveBinding {
+  fetch(request: Request): Promise;
+}
+interface AuthWorkerEnv {
+  ALLOWED_ORIGINS: string;
+  APP_ENV: string;
+  APP_NAME: string;
+  AUDIENCE: string;
+  AUTH_ARCHIVE: AuthArchiveBinding;
+  AUTH_DB: D1Like;
+  AUTH_EMAIL: SendEmail;
+  AUTH_ISSUER: string;
+  AUTH_JWT_PREVIOUS_PUBLIC_JWKS?: string;
+  AUTH_JWT_PRIVATE_JWK: string;
+  OPERATOR_EMAILS: string;
+  PUBLIC_ORIGIN: string;
+  SENDER_ADDRESS: string;
+}
+interface AuthWorkerHandler {
+  fetch(request: Request, env: E, ctx?: ArchiveExecutionContext): Promise;
+  scheduled(controller: unknown, env: E, ctx?: ArchiveExecutionContext): Promise;
+  tap(handler: (event: AuthEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
+}
+type AuthDiagnostic = {
+  readonly kind: 'configuration' | 'database' | 'email' | 'catalog' | 'internal';
+};
+type AuthEvent =
+  | {
+      readonly type: 'request';
+      readonly requestId: string;
+      readonly route:
+        | '/auth/account'
+        | '/auth/health'
+        | '/auth/jwks.json'
+        | '/auth/session'
+        | '/auth/sign-in'
+        | '/auth/sign-out-all'
+        | '/auth/verify'
+        | 'unmatched';
+      readonly status: number;
+      readonly code: ArchiveErrorCode | 'ok';
+      readonly ms: number;
+      readonly diagnostic?: AuthDiagnostic;
+    }
+  | { readonly type: 'scheduled'; readonly status: 'ok'; readonly removed: number }
+  | { readonly type: 'scheduled'; readonly status: 'failed'; readonly diagnostic: AuthDiagnostic };
+```
+
+Issuer scheduled `removed` counts expired token rows, closed per-user send windows
+and deleted unverified accounts. The singleton admission row is retained and its
+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` |
+| `ArchiveDerivationError` | Unexpected schema/canonicalization/index/hash/response fault or violated collection invariant | Extends `ArchiveError`; readonly `stage: ArchiveDerivationStage`; optional `cause` |
+
+`ArchiveError` and `ArchiveDefinitionError` accept `(message: string, opts?: ErrorOptions)`.
+`ArchiveDerivationError` accepts `(stage: ArchiveDerivationStage, message: string, opts?: ErrorOptions)`.
+Its message and cause are local diagnostics, not response content. Worker request
+failures use the wire envelope, not these thrown classes. Internal `ApiError` and
+`AuthOperationError` are not exported.
+
+Stored entries that fail the current wire schema return 503 `record-unavailable`.
+Unexpected exceptions in the collection's response-payload callbacks instead
+throw `ArchiveDerivationError` with stage `response` and become sanitized 500s.
+
+The complete public error signatures are:
+
+```ts
+class ArchiveError extends Error {
+  constructor(message: string, opts?: ErrorOptions);
+}
+class ArchiveDefinitionError extends ArchiveError {}
+class ArchiveDerivationError extends ArchiveError {
+  readonly stage: ArchiveDerivationStage;
+  constructor(stage: ArchiveDerivationStage, message: string, opts?: ErrorOptions);
+}
+```
+
+Catalog rate-limit responses use `Retry-After: 60`; configure catalog limiter periods to 60 seconds. Issuer admission/send-budget responses instead carry seconds until their durable window reopens. Health's degraded response is the health DTO, not an error envelope: schema mismatch reports the observed version; database unavailability reports `dbSchemaVersion: null`.
+
+### Usage Guide
+
+## Basic Usage
+
+A deployment is a collection definition plus one factory call. Put the definition in a
+module both sides import — the browser needs the composed schemas, the Worker needs
+the collection itself.
+
+```ts
+// recipes-collection.ts — the one content contract, shared by both sides.
+import { defineArchiveCollection } from '@vielzeug/archive';
+import { s } from '@vielzeug/spell';
+
+const payloadSchema = s.object({
+  cuisine: s.enum(['italian', 'japanese']),
+  ingredients: s.array(s.string().trim().min(1).max(64)).min(1).max(20),
+  name: s.string().trim().min(1).max(32),
+});
+
+export const recipesCollection = defineArchiveCollection({
+  // Ingredient order is not identity: the canonical form sorts, so reordered
+  // content hashes identically and updates as a no-op.
+  canonicalize: (payload) => ({ ...payload, ingredients: [...payload.ingredients].sort() }),
+  contentVersion: 1,
+  filters: ['italian', 'japanese'],
+  index: (payload) => ({
+    filter: payload.cuisine,
+    tags: [payload.ingredients.length  console.log(JSON.stringify(event)));
+
+export default worker;
+```
+
+The browser imports the same collection for its schemas — never the worker subpath:
+
+```ts
+import { recipesCollection } from './recipes-collection';
+import { archiveIdentitySchema, PUBLISHER_HEADER } from '@vielzeug/archive';
+
+const response = await fetch('/api/v1/collections/recipes/entries');
+if (!response.ok) throw new Error('Archive unavailable');
+const page = recipesCollection.contract.page.parse(await response.json());
+const meResponse = await fetch('/api/v1/me', { credentials: 'same-origin' });
+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 },
+});
+if (!mineResponse.ok) throw new Error('Own publications unavailable');
+const owned = recipesCollection.contract.ownedEntries.parse(await mineResponse.json());
+console.log(page.entries, owned.entries);
+```
+
+## The collection contract
+
+`defineArchiveCollection` is the only place content knowledge lives. The definition is
+validated at registration — a bad `name`, `contentVersion`, or any vocabulary value
+(well-formed text, 1..`vocabChars` chars) throws there, never mid-request — and every
+ordinary invalid content returns `null` → `422 invalid-payload`. Collection
+implementation faults instead throw `ArchiveDerivationError` → sanitized
+`500 internal`:
+
+- **Parse** — accept stable JSON objects only; schema outputs must remain JSON.
+- **Canonicalize** — optional; a result that leaves the payload schema throws, so a
+  broken normalizer can never store invalid content.
+- **Index** — the returned `filter` must be declared in `filters`, every `tag` in
+  `tags` (duplicates collapse), and the `title` is trimmed and bounded
+  (`titleChars`, well-formed text). A derivation outside the declared vocabulary
+  would store a row no list query can reach — it throws instead.
+- **Size** — the canonical JSON must fit `payloadBytes`.
+- **Identity** — the content hash is SHA-256 over `{contentVersion, payload}`:
+  identical content hashes identically, a real edit always re-identifies, and the
+  core owns the envelope so collections cannot drift it.
+
+Declare vocabularies with readonly arrays (`['fire', 'ice']`) for automatic
+literal-union inference. Const generics retain the version literal and vocabulary
+unions; `NoInfer` prevents the index callback from widening them. Omitted arrays
+mean empty vocabularies: return `null` for
+the filter and no tags. Object keys are recursively sorted by the core; schema
+transformations must stabilize and `canonicalize` must be pure and idempotent.
+Non-JSON input returns `null`. Unexpected callback, schema or hashing failures,
+unstable transformations, non-idempotent canonicalization and index mutation throw
+`ArchiveDerivationError`; its `stage` identifies the failing phase.
+Lossy or non-JSON schema output and invalid index-result shapes also throw.
+
+`contentVersion` participates in content identity. Request handling validates
+only the current collection definition; it does not interpret historical schemas.
+Archive is unreleased and provides no content-upgrade APIs.
+
+Filters, tags and searchable titles are persisted data derived at publish/update
+time. Editing `index` or its vocabularies does not recompute existing projections.
+Keep the active definition and dataset consistent. For an unreleased development
+deployment, deliberately reset and reseed a fresh database when you change payload
+or projection semantics; the package does not supply a migration framework.
+Resetting destroys existing data. Perform it only as an explicit, deliberate
+development operation, not automatically during startup or deployment.
+
+**Payloads carry decisions, not content.** The payload schema should accept
+user-authored choices expressed as IDs plus user-written text — never the content's
+own copyrighted expression (card text, artwork, rules), never more than the game's
+own identifiers. For games with paid or DLC content this is the whole answer:
+ownership resolves on each viewer's device against their own library, the service
+never learns what anyone owns, and the strict schema is the enforcement seam —
+use a strict schema that rejects unknown fields, so a collection that only models IDs cannot
+accidentally start shipping paid content. For example, published game builds can
+reference cards, equipment and potions by ID plus a user-written name. The client
+renders pieces the viewer does not own as unavailable. Keep the browser-safe
+publication contract in a shared domain module consumed by both the frontend and
+its backend, without importing frontend application code into the Worker.
+
+## The Worker and its environment
+
+`createArchiveWorker(collections)` returns the full handler: anonymous public reads,
+cookie-authenticated mutations behind exact-origin and request-marker guards, local
+RS256/JWKS verification followed by an uncached issuer session-version check,
+per-IP read limits and per-subject write limits keyed by peppered HMACs, the
+30-second anonymous cache on public entry lists only, operator moderation, and a
+scheduled expiry sweep for retired publish retry keys and revocation tombstones.
+Health sits outside the rate-limit and session pipelines: probes never burn the
+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 |
+
+Both limiter bindings must run 60-second windows (`simple` limiters:
+`period: 60`): the platform binding does not expose its period at runtime, so the
+Worker's 429 `Retry-After` header is fixed at 60 seconds — a longer window would
+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.
+
+## The auth issuer
+
+`createAuthWorker()` from `@vielzeug/archive/auth` is the reference passwordless
+identity issuer a deployment runs beside the catalog Worker: one POST with an email
+sends a single-use magic link, and explicitly confirming it sets the `archive_session`
+cookie. The catalog verifies the JWT locally, then calls the issuer through
+`AUTH_ISSUER_SERVICE` to check the account's current session version. Requests create
+pending account rows; explicit link redemption atomically stamps the account's
+sign-in time and claims the token. The issuer's D1 schema ships at
+`node_modules/@vielzeug/archive/migrations/auth/`; point the issuer's
+`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 |
+
+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
+deployment wrappers, not package APIs.
+
+The issuer first admits sign-in requests through its singleton durable
+`auth_sign_in_budget` table: 20 requests per 60 seconds before creating accounts
+or delivering email. No rate-limiter binding is required. It then
+permits three sign-in emails per email in an hourly durable window.
+Later database or delivery failures do not refund global admission.
+Using or expiring a link never refunds sends; failed delivery also spends the
+allowance. Links expire after 15 minutes. Operator sessions expire after 900
+seconds, ordinary sessions after at most 30 days. Retain retired public keys during
+rotation; the active private key signs every new session. Sign-in input trims and
+lowercases email before validation. `SENDER_ADDRESS` must already be canonical;
+`OPERATOR_EMAILS` entries are trimmed and lowercased before validation.
+
+The scheduled sweep deletes expired links and closed per-user send windows, then
+pending accounts only when neither a link nor send-budget row still references
+them. Failed delivery deletes the unusable token but retains the spent allowance;
+it does not immediately remove the pending account. Verified accounts stay until
+explicit erasure. The singleton admission row remains and resets its window on a
+later admitted request.
+
+Opening `GET /auth/verify?token=…` renders a no-store confirmation page and does
+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.
+The page removes the token from the address bar, loads no external assets, and
+sets a restrictive CSP and `Referrer-Policy: no-referrer`.
+
+`GET /auth/account` exports account metadata only. For full erasure, call
+`DELETE /auth/account` with `ACCOUNT_HEADER` (`X-Archive-Account`) set to the
+issuer account UUID captured from `GET /auth/account` before confirmation.
+The issuer rejects missing or invalid UUIDs with 400 and a different signed-in
+account with 409 `account-changed`, before any erasure. This guard applies even
+before publisher registration and must stay pinned across retries.
+The issuer forwards the caller's session and publisher
+precondition through `AUTH_ARCHIVE` to `DELETE /me/account`, requires exactly 204,
+then deletes its
+own user and clears the cookie. Failure preserves the session for retry. Direct
+`DELETE /me` removes only the Archive profile and leaves the cookie intact.
+
+Several game frontends can share one issuer and catalog. Keep the cookie
+host-only on the central API host, use `credentials: 'include'` from same-site
+HTTPS game subdomains, and allow each exact frontend origin in both Workers.
+Do not share cookies through a parent-domain `Domain` attribute. The
+[multi-collection recipe](./examples/multi-collection-deployment.md) describes
+the topology, session revalidation and platform-wide account boundary.
+
+`DELETE /me/account` atomically revokes the issuer/subject and cascades profile
+deletion. Its tombstone lasts 30 days plus ten seconds; old sessions cannot read
+private data or register again, including a racing registration. The dedicated
+account-erasure route alone may bypass the issuer lookup, and only to retry with
+the same principal's original signed session while its existing tombstone is
+valid; signature and claims are still verified, and initial erasure validates the
+issuer. The issuer's `DELETE /auth/account` checks the current version before
+starting erasure; after completed erasure a retry there returns 401. A fresh
+issuer account gets a new UUID subject. External issuers must use a new subject to
+re-enroll during the revocation window. Profile-only deletion does not revoke the
+subject and permits re-registration with existing credentials.
+
+Each JWT also carries the issuer account's required safe-integer `sessionVersion`.
+The issuer compares it with `auth_users.session_version` on every ordinary
+authenticated route. A JWT with an old version is unauthenticated even before its
+expiry; the catalog asks the issuer on every private request and does not cache a
+successful verdict. A valid local JWT with an unavailable, malformed, 5xx or
+timed-out (fixed 5000 ms, including body decoding) issuer response becomes
+`503 auth-unavailable`, not anonymous identity.
+
+## The database
+
+The package ships the canonical catalog migration:
+`node_modules/@vielzeug/archive/migrations/0001_community_archive.sql` — the whole schema,
+moderation included, as one designed file. The runtime SQL in the package is
+written against exactly this schema, and the package's own integration suite runs
+against the same file. Point wrangler at the directory:
+
+```jsonc
+// wrangler.jsonc — the deployment owns its D1 database, not its DDL.
+{
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-app",
+      "migrations_dir": "./node_modules/@vielzeug/archive/migrations"
+    }
+  ]
+}
+```
+
+The issuer points to
+`node_modules/@vielzeug/archive/migrations/auth/0001_auth.sql`. Both files are
+fresh-database initialization definitions, not upgrades. The issuer DDL initializes
+`auth_users.session_version` to `0` and stamps `auth_schema_meta.applied` as
+`AUTH_SCHEMA_VERSION` (`1`). Neither file automatically deletes or resets data.
+While Archive is unreleased, its
+canonical initial schemas are edited directly. Reset and reseed an unreleased
+development database deliberately when its schema or collection semantics no
+longer match; reapplying the initial file does not update an existing dataset.
+The initialization file also stamps the storage schema
+(`archive_schema_meta`) at `ARCHIVE_SCHEMA_VERSION`, and health reads it back: a
+database with a mismatched stamp answers `status: 'degraded'` with the
+observed `dbSchemaVersion` and HTTP 503 (`reason: 'schema-mismatch'`).
+An unavailable database produces HTTP 503 with `dbSchemaVersion: null` and
+`reason: 'database-unavailable'`. The debut storage stamp is `1`. A unit
+test pins the shipped DDL's `CHECK` bounds to `ARCHIVE_LIMITS`, so the two can never
+drift silently. The stamp does not detect changes in your collection's payload
+schema, vocabulary or indexing function; you own that dataset consistency.
+
+## Routes and wire names
+
+```
+GET    /api/v1/health
+POST   /api/v1/sign-out
+GET    /api/v1/auth/health
+GET    /api/v1/auth/session                              (internal issuer check)
+POST   /api/v1/auth/sign-out-all                         (revoke every session)
+GET    /api/v1/collections/:collection                        (self-description)
+GET    /api/v1/collections/:collection/entries                (author, filter, tag, search, sort, cursor, limit)
+POST   /api/v1/collections/:collection/entries
+GET    /api/v1/collections/:collection/entries/:id
+PUT    /api/v1/collections/:collection/entries/:id            (expectedRevision)
+DELETE /api/v1/collections/:collection/entries/:id
+PUT    /api/v1/collections/:collection/entries/:id/like
+DELETE /api/v1/collections/:collection/entries/:id/like
+POST   /api/v1/collections/:collection/entries/:id/report     (reason)
+PUT    /api/v1/collections/:collection/entries/:id/hidden     (operator)
+DELETE /api/v1/collections/:collection/entries/:id/hidden     (operator)
+GET    /api/v1/collections/:collection/reports               (operator: status, cursor, limit)
+PUT    /api/v1/collections/:collection/reports/:id/resolved  (operator: report ID)
+DELETE /api/v1/publishers/:id                               (operator: erase any publisher)
+GET    /api/v1/moderation-log                               (operator: cursor, limit)
+GET    /api/v1/me             POST /me    PUT /me    DELETE /me
+GET    /api/v1/me/publications?collection=:collection     GET /api/v1/me/likes[?ids=…]
+GET    /api/v1/me/reports                                   (cursor, limit)
+GET    /api/v1/auth/account
+GET    /api/v1/auth/jwks.json
+POST   /api/v1/auth/sign-in                                 (email)
+DELETE /api/v1/auth/account                                (coordinated full erasure)
+DELETE /api/v1/me/account                                  (issuer erasure seam; revokes subject)
+GET    /api/v1/auth/verify?token=…                          (confirmation only)
+POST   /api/v1/auth/verify                                 (guarded {token} redemption)
+```
+
+Publishing is bounded by `maxPublications` live entries per `(collection, owner)`.
+The quota check runs inside the guarded insert.
+
+`/me/likes` without `ids`, `/me/reports`, operator reports and `/moderation-log`
+use forward keyset pages: follow `cursor` until `null`, preserving query context.
+`limit` defaults to `pageSize` and is at most `maxPageSize`; there is no total
+export bound. `/me/likes?ids=…` remains a subset lookup returning `{ ids }`, not a
+page, and cannot combine `ids` with `cursor` or `limit`.
+
+Shared wire names live in the package — `archive_session` cookie,
+`x-archive-publisher` and `x-archive-request` headers, `ARCHIVE_ERROR_CODES`, and
+`ARCHIVE_LIMITS` — so a client and the Worker cannot drift. Parse failures with the
+collection's composed schemas; parse errors with `archiveErrorResponseSchema`, the
+sign-out body with `archiveOkSchema`, a collection's self-description with
+`archiveCollectionMetaSchema` and the operator queue with `archiveReportsSchema`.
+Every entry's `schemaVersion` is the archive contract's version, not the
+collection's; the collection's own format version lives in its hash envelope and in
+each entry's `contentVersion`.
+
+Only anonymous entry lists carry a 30-second edge-cache contract
+(`publicCacheSeconds`). Detail is always `no-store`. Any Cookie or Authorization
+header disables caching, regardless of validity; metadata, private and error
+responses also use `no-store`.
+
+Implement UI ownership checks in your application by comparing the current
+publisher ID to the entry's `author.id`; there is no package action-policy helper.
+Server mutations remain authoritative.
+
+`POST /api/v1/sign-out` is deliberately local: it clears only this browser's
+cookie and does not contact the issuer or revoke copied sessions. To revoke every
+session, post to `/api/v1/auth/sign-out-all` with the mutation marker, an exact
+allowed `Origin`, and the issuer account UUID captured from
+`GET /api/v1/auth/account` in `X-Archive-Account`. The issuer returns 409
+`account-changed` if the active subject differs. On success it atomically increments
+`session_version`, deletes outstanding links, preserves account and catalog data,
+and returns `{ ok: true }` with an expired cookie. Requests authorized before
+revocation may finish; there is no cross-database cancellation guarantee.
+
+`GET /api/v1/auth/health` is public and read-only. It validates issuer
+configuration, key signing/verification, binding shapes, the `auth_schema_meta`
+stamp and expected tables, columns and triggers, returns `AuthHealth` through
+`archiveAuthHealthSchema`, and answers 503 `degraded` for configuration,
+database or schema failures. It never writes, sends email or probes the catalog.
+
+## Moderation
+
+Operator authority is the session token's optional `roles` claim carrying
+`ARCHIVE_OPERATOR_ROLE` (`'archive-operator'`) — minted by your issuer, verified with
+the same signature, audience and issuer checks as any session, and never a separate
+credential. Moderation routes additionally require a registered publisher row: one
+accountable identity per action.
+
+- **Report** — any registered publisher reports a visible entry with a bounded
+  free-text reason (`reportReasonChars`). Idempotent per (entry, reporter): the same
+  report twice is the same 204. Missing or hidden entries answer 404 — there is
+  nothing left to report.
+- **Hide** — an operator removes an entry from every public surface (list, detail,
+  likes) with a soft-hide: the row, its likes and its retry key stay intact. The
+  owner still sees the entry in `/me/publications` with `hidden: true`, edits and
+  key replay are frozen (403), removal stays allowed, and unhiding restores
+  everything. Already hidden or already visible answer the same 204.
+- **Queue** — the operator pages newest reports with entry title and reporter
+  identity; `status` is `unresolved` (default) or `resolved`. Each report has its
+  own `id` and nullable `resolvedAt`. Resolve it with
+  `PUT /collections/:collection/reports/:id/resolved`; repeating is a 204 no-op.
+- **Log** — every effective moderation action (hide, unhide, removal, publisher
+  erasure) appends one accountability row in the same transaction that applies it,
+  and `GET /api/v1/moderation-log` pages the newest actions to
+  operators. Rows carry only ids, the action kind and the time — no names (they
+  change), no content — and no foreign keys: the audit must outlive the erasures it
+  records. Idempotent repeats (hiding an already-hidden entry, erasing an
+  already-erased publisher) answer the same 204 with no new row, including
+  concurrent repeats: audit insertion tests the effective state inside the batch.
+
+Like and unlike both require a visible entry. Their SQL guards visibility during
+the mutation, and the response checks it again; hiding or deleting an entry
+cannot turn a racing unlike into a successful response for unavailable content.
+
+## Observability
+
+The core never logs. `worker.tap(handler, { signal? })` emits one `ArchiveEvent` per
+request — `{ type: 'request', code, ms, requestId, route, status, diagnostic? }` —
+and successful sweep — `{ type: 'scheduled', status: 'ok', removed }`. Failed
+sweeps emit `{ type: 'scheduled', status: 'failed', diagnostic }` and rethrow so
+the runtime sees failure. Cache failures emit `{ type: 'cache-error', diagnostic }`.
+The Worker swallows observer errors so
+observability cannot affect the Worker. With no handlers registered there is zero
+work. Route is a finite class like `/collections/:collection/entries`, never a
+raw path; no event carries a URL, cookie, subject, alias or token. Diagnostics are
+typed sanitized categories, not raw exceptions. A pre-aborted tap signal is inert.
+The sweep's `removed` counts expired retry keys and revocation tombstones together.
+
+The issuer also exposes `tap()` with `AuthEvent` from `@vielzeug/archive/auth`.
+It never logs directly. Events contain finite route labels, codes, counts,
+duration and sanitized `AuthDiagnostic` categories, never emails, tokens or raw
+exceptions. Scheduled failures emit then rethrow; pre-aborted taps are inert.
+Issuer sweep counts include expired tokens, closed per-user send windows and
+removed pending accounts; the singleton admission row is not removed.
+
+```ts
+import { createLogger } from '@vielzeug/rune';
+import { createArchiveWorker } from '@vielzeug/archive/worker';
+import { recipesCollection } from './recipes-collection';
+
+const log = createLogger({ namespace: 'recipes' });
+const worker = createArchiveWorker([recipesCollection]);
+worker.tap((event) => log.debug(event, `archive:${event.type}`));
+export default worker;
+```
+
+## Testing
+
+The package proves itself against real workerd + local D1:
+
+```sh
+pnpm vitest run packages/archive/src/__tests__/          # fast unit suite
+pnpm --filter @vielzeug/archive test:integration         # real workerd + local D1 + issuer coverage
+pnpm --filter @vielzeug/archive test:types               # strict types over src and the integration suite
+```
+
+Prove your own collection the way the reference deployment does: a slim deployment
+suite that publishes over your real vocabulary and asserts the derivation, plus the
+package's generic suite for the core behavior. A collection with an `index` that can
+drift out of vocabulary should unit-test `derive` directly: ordinary invalid input
+returns `null`, while implementation faults throw `ArchiveDerivationError`.
+Direct DDL tests exercise the shipped schema rather than a duplicate schema.
+
+## Framework Integration
+
+The root entry is plain TypeScript with no framework coupling; Vue, React and Svelte
+apps all consume the composed schemas the same way. A Vue 3 composable that pages a
+collection:
+
+```ts
+// useRecipes.ts — one collection's typed client in any component tree.
+import { recipesCollection } from './recipes-collection';
+import { ref, shallowRef } from 'vue';
+
+export function useRecipes() {
+  const entries = shallowRef[]>([]);
+  const cursor = ref(null);
+  async function load(sort: 'liked' | 'recent') {
+    const params = new URLSearchParams({ sort });
+    if (cursor.value !== null) params.set('cursor', cursor.value);
+    const response = await fetch(`/api/v1/collections/recipes/entries?${params}`);
+    if (!response.ok) throw new Error('The archive is unavailable.');
+    const page = recipesCollection.contract.page.parse(await response.json());
+    entries.value = [...entries.value, ...page.entries];
+    cursor.value = page.cursor;
+  }
+  return { cursor, entries, load };
+}
+```
+
+## Working with Other Vielzeug Libraries
+
+- [Spell](/spell/) — the payload schema a collection declares; the core composes the
+  envelope schemas from it, so the wire and the types cannot drift.
+- [Courier](/courier/) — the HTTP client shape an app's frontend mirrors to consume
+  these routes: strict response schemas over one typed port.
+- [Rune](/rune/) — the structured logger a deployment points `tap()` events at.
+
+## Best Practices
+
+- Compose client schemas from `collection.contract`; never hand-write the envelope.
+- Declare exactly the vocabulary your `index` derives, with union types where you
+  have them; a value outside it rejects loudly.
+- Keep `canonicalize` pure and schema-true: reordered lists in, canonical form out.
+- Initialize fresh databases with the shipped DDL and deliberately reset/reseed
+  unreleased development data when collection or storage semantics change.
+- Treat `ARCHIVE_ERROR_CODES` and `archiveErrorResponseSchema` as one tested contract.
+- Pin the expected-publisher header from the identity you captured at sign-in, never from storage alone.
+- Grant the operator role claim only through your issuer, and only to accounts that
+  are also registered publishers.
+- Wire a sanitized `tap()` sink and register the rate-limit pepper as a production secret.
+
+### Examples
+
+- [Stand Up a Content Archive](./examples/stand-up-a-content-archive.md)
+- [Content Identity and Versions](./examples/content-identity-and-versions.md)
+- [Multi-Collection Deployment](./examples/multi-collection-deployment.md)
+- [Moderate Content](./examples/moderate-content.md)
+- [Client Error Mapping](./examples/client-error-mapping.md)
+- [GDPR Erasure and Export](./examples/gdpr-erasure-and-export.md)
 
 ---
 
@@ -119,6 +1414,8 @@ console.log(byRole, health, profile);
 | `allocate` | Lossless proportional distribution | Sync | Available from `/math` |
 | `isEqual` | Structural equality | Sync | Root export |
 | `hash` | Deterministic serialization for cache keys | Sync | Available from `/object` |
+| `compressBytes` / `decompressBytes` | Native byte compression with bounded decompression | Async | Requires native compression streams; decoding requires an output limit |
+| `pack` / `unpack` | Versioned, compressed, URL-safe payload envelope | Async | Both sides bound the payload with `maxBytes`; compression falls back to raw |
 
 ## Package Entry Points
 
@@ -128,6 +1425,7 @@ console.log(byRole, health, profile);
 | `@vielzeug/arsenal/array` | Immutable transforms, 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 |
 | `@vielzeug/arsenal/function` | Assertions, composition, timing, teardown |
 | `@vielzeug/arsenal/guards` | Type guards, predicate combinators, equality guards |
 | `@vielzeug/arsenal/math` | Ranges, aggregation, statistics, interpolation, exact allocation |
@@ -245,12 +1543,107 @@ base64UrlToBytes(code); // throws on characters outside the alphabet
 utf8Bytes('Hunter äöü'); // 11: byte length of a UTF-8 string
 ```
 
-## Object
-
-### tryParseJson
+### compressBytes
 
 ```ts
-type JsonParseResult = { ok: true; value: unknown } | { error: SyntaxError; ok: false };
+compressBytes(bytes: Uint8Array, options?: CompressionOptions): Promise
+```
+
+Compresses bytes using the native `CompressionStream` API without modifying the input.
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `format` | `CompressionFormat` | `'deflate-raw'` | Compression format; the receiver must use the same format |
+
+**Returns:** Compressed bytes. Rejects with `ArsenalSerializationError` when the format or capability is unavailable, or stream processing fails. Does not fall back to another format.
+
+**Example:** Encode compressed bytes for a URL.
+
+```ts
+import { bytesToBase64Url, compressBytes } from '@vielzeug/arsenal';
+
+const bytes = new TextEncoder().encode(JSON.stringify({ name: 'Hunters' }));
+const code = bytesToBase64Url(await compressBytes(bytes));
+```
+
+---
+
+### decompressBytes
+
+```ts
+decompressBytes(bytes: Uint8Array, options: DecompressionOptions): Promise
+```
+
+Decompresses bytes using the native `DecompressionStream` API, enforcing the output limit while reading chunks.
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `format` | `CompressionFormat` | `'deflate-raw'` | Format used by the sender |
+| `maxOutputBytes` | `number` | Required | Non-negative safe integer; maximum decoded byte length |
+
+**Returns:** Decompressed bytes. Rejects with `ArsenalSerializationError` for invalid limits, corrupt or truncated data, unavailable formats/capabilities, or output exceeding the limit. A failed stream is canceled and its reader lock released. Bound encoded input separately before calling this function.
+
+**Example:** Decode text within an application-defined byte limit.
+
+```ts
+import { compressBytes, decompressBytes } from '@vielzeug/arsenal';
+
+const compressed = await compressBytes(new TextEncoder().encode('Hunters'));
+const bytes = await decompressBytes(compressed, { maxOutputBytes: 8192 });
+const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+```
+
+---
+
+### pack
+
+```ts
+pack(payload: unknown, options: ShareCodeOptions): Promise
+```
+
+Serializes `payload` as JSON and encodes it into a compact share code: `prefix` + mode marker + base64url bytes, compressed with raw DEFLATE when the compressed form is shorter and the runtime supports the streams.
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `maxBytes` | `number` | Positive safe integer; maximum serialized payload size |
+| `prefix` | `string` | 1–8 alphanumeric characters identifying the code family and version |
+
+**Returns:** The shorter of the raw (`prefix` + `r`) and compressed (`prefix` + `d`) representations. Throws `ShareCodeError` (`too-large`, `invalid`) for oversized payloads and misconfigured options.
+
+**Example:** Encode a shareable build as a code small enough for a URL.
+
+```ts
+import { pack } from '@vielzeug/arsenal';
+
+const code = await pack({ cards: ['slash', 'guard'] }, { maxBytes: 8192, prefix: 'ab1' });
+```
+
+---
+
+### unpack
+
+```ts
+unpack(code: string, options: ShareCodeOptions): Promise
+```
+
+Decodes a share code produced by `pack` with the same options. Both sides are bounded: input longer than `maxBytes` could carry is refused up front, streamed decompression stops at `maxBytes`, and non-canonical base64url is rejected by round-trip.
+
+**Returns:** The parsed JSON payload. Throws `ShareCodeError` (`invalid` for foreign or malformed codes, `too-large` for budget overruns, `compression-unavailable` when a compressed code arrives on a runtime without `DecompressionStream`). Underlying compression failures surface as `ArsenalSerializationError`.
+
+**Example:** Decode untrusted input within the byte budget.
+
+```ts
+import { unpack } from '@vielzeug/arsenal';
+
+const payload = await unpack(code, { maxBytes: 8192, prefix: 'ab1' });
+```
+
+## Object
+
+### tryParseJson
+
+```ts
+type JsonParseResult = { ok: true; value: unknown } | { error: SyntaxError; ok: false };
 
 tryParseJson(text: string): JsonParseResult
 ```
@@ -327,13 +1720,22 @@ type CacheOptions = {
   now?: () => number;
   ttlMs?: number;
 };
+
+interface CompressionOptions {
+  format?: CompressionFormat;
+}
+
+interface DecompressionOptions extends CompressionOptions {
+  maxOutputBytes: number;
+}
 ```
 
 ## Errors
 
 - `RangeError`: invalid numeric bounds, capacity, concurrency, or retry count.
 - `TypeError`: invalid value types, unsupported comparison, or required path missing.
-- `ArsenalSerializationError`: memo or hash cannot serialize supplied input.
+- `ArsenalSerializationError`: memo or hash cannot serialize supplied input; compression fails, is unavailable, receives an invalid output limit, or exceeds that limit. Stream failures retain the original error as `cause`.
+- `ShareCodeError`: a share code cannot be encoded or decoded; the `reason` field is `invalid`, `too-large`, or `compression-unavailable`.
 
 ### Usage Guide
 
@@ -500,6 +1902,27 @@ const payload = JSON.parse(base64UrlToText(code));
 
 Decoding throws on characters outside the base64url alphabet, so corrupted input fails loudly instead of decoding to garbage.
 
+## Compress Share Payloads
+
+Compress UTF-8 bytes before Base64url encoding. Set a decoded-byte limit before accepting compressed input from another device.
+
+```ts
+import { base64UrlToBytes, bytesToBase64Url, compressBytes, decompressBytes } from '@vielzeug/arsenal';
+
+const payload = JSON.stringify({ name: 'Hunters', notes: 'An expedition through Alborea. '.repeat(20) });
+const compressed = await compressBytes(new TextEncoder().encode(payload));
+const code = bytesToBase64Url(compressed);
+const bytes = await decompressBytes(base64UrlToBytes(code), { maxOutputBytes: 8192 });
+const restored = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+console.log(restored === payload);
+```
+
+Both helpers default to `deflate-raw`. You can explicitly select `gzip` or `deflate`; use the same format at both ends. The helpers reject when native streams do not support the selected format. They do not choose a fallback or define a wire protocol.
+
+For a complete versioned envelope over these primitives — prefix, compression mode marker, byte budgets on both sides — see [`pack` / `unpack`](./api.md#pack).
+
+Compression can enlarge small inputs. Compare the final encoded strings, including any format marker, before choosing a representation. Bound input size before decoding Base64url and validate decompressed JSON against your schema. The decompression limit bounds retained output, not native stream working memory.
+
 ## Working with Other Vielzeug Libraries
 
 Use Spell after `tryParseJson` for typed external data. Use Vault instead of `cache` when data must survive reloads or process restart.
@@ -533,6 +1956,7 @@ const settings = parsed.ok ? Settings.parse(parsed.value) : { theme: 'system' };
 - [Array utilities](./examples/array.md)
 - [Async utilities](./examples/async.md)
 - [Cache utilities](./examples/cache.md)
+- [Encoding utilities](./examples/encoding.md)
 - [Function utilities](./examples/function.md)
 - [Guards / Typed predicates](./examples/typed.md)
 - [Math utilities](./examples/math.md)
@@ -555,6 +1979,7 @@ const settings = parsed.ok ? Settings.parse(parsed.value) : { theme: 'system' };
 - taskPool - Bounded concurrent work (id: `async-queue`)
 - retry - Retry failed operations (id: `async-retry`)
 - waitFor - Poll until condition is true or timeout/abort fires (id: `async-waitFor`)
+- compressBytes - Bounded share payload compression (id: `encoding-compression`)
 - debounce - Trailing (default) and leading-edge options (id: `function-debounce`)
 - memo - LRU cache with size tracking and invalidation (id: `function-memo`)
 - pipe - Left-to-right function composition (id: `function-pipe`)
@@ -3207,7 +4632,13 @@ Sends one HTTP request. `config.method` defaults to `GET`; pass any method (incl
 | `timeout` | `number` | Integer milliseconds from 1 to 2,147,483,647, or `Infinity`; overrides default |
 | `fetchInit` | `Omit` | Raw fetch options for advanced use |
 
-**Returns:** Parsed response body (or `undefined` for empty bodies).
+**Returns:** Parsed response body (or `undefined` for empty bodies). With
+`responseType: 'raw'` the resolved value is the `Response` itself; a `204`/`205`
+answer whose transport carried an unexpected empty body stream is normalized to
+`body: null` — the stray stream is cancelled and headers, status, statusText,
+URL, redirect and type metadata are preserved (on the response and its clones).
+A null-body raw response owns no pending resource, so no consumption is required
+to release the request.
 
 ```ts
 const created = await courier.request('/users', {
@@ -3487,7 +4918,7 @@ Concurrent callers share physical work but own their own signal and timeout. One
 
 ## Response Parsing
 
-Courier parses successful 2xx response bodies automatically based on `content-type`, unless you set `responseType` explicitly (`'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'raw'` for the `Response` itself). Empty JSON bodies return `undefined` instead of throwing. Raw response bodies remain owned by Courier until consumed or cancelled, so `cancelAll()` and `dispose()` still abort them. Raw responses cannot be combined with `schema`. Always consume or cancel the body to release request ownership, and set `timeout: Infinity` for intentionally long-lived streams. Courier preserves URL, redirect, and type metadata on tracked responses and their clones.
+Courier parses successful 2xx response bodies automatically based on `content-type`, unless you set `responseType` explicitly (`'json'`, `'text'`, `'blob'`, `'arrayBuffer'`, or `'raw'` for the `Response` itself). Empty JSON bodies return `undefined` instead of throwing. Raw response bodies remain owned by Courier until consumed or cancelled, so `cancelAll()` and `dispose()` still abort them. Raw responses cannot be combined with `schema`. Always consume or cancel the body to release request ownership, and set `timeout: Infinity` for intentionally long-lived streams. Courier preserves URL, redirect, and type metadata on tracked responses and their clones. A `204`/`205` raw answer is normalized to `body: null` — a stray empty transport stream is cancelled for you — so a null-body raw response never carries pending body ownership and needs no consumption.
 
 ```ts
 const buffer = await courier.request('/files/{id}', {
@@ -3670,6 +5101,7 @@ There is no `use()` method. To change middleware, create a new client. This keep
 ## Examples
 
 - [Authentication](./examples/authentication.md)
+- [Service Discovery and Custom Fetch](./examples/service-discovery-and-custom-fetch.md)
 - [CRUD Operations](./examples/crud-operations.md)
 - [Disposal](./examples/disposal.md)
 - [Error Handling Patterns](./examples/error-handling-patterns.md)
@@ -16403,64 +17835,60 @@ The IndexedDB adapter is built on Vault. Use Vault directly for unrelated storag
 
 ## Why Prism?
 
-Charting libraries typically require a framework binding, bundle heavy dependencies, or force canvas rendering that can't be styled with CSS. Prism takes a different approach:
+Prism renders charts as SVG in a host element and keeps application state outside the chart. You can replace chart data explicitly, respond to container resizing, and style the output with CSS custom properties.
 
 ```ts
-// Before: Chart.js, imperative setup with a canvas you can't CSS-theme
-import Chart from 'chart.js/auto';
-const ctx = document.getElementById('myChart') as HTMLCanvasElement;
-new Chart(ctx, {
-  type: 'line',
-  data: { labels, datasets: [{ data: values }] },
-  // re-create or mutate the Chart.js instance when data changes
-});
-
-// After: Prism, responsive SVG with an explicit update boundary
 import { createLineChart } from '@vielzeug/prism';
 
-const chart = createLineChart(document.getElementById('chart')!, {
-  a11y: { ariaLabel: 'Users by day' },
-  series: [
-    {
-      data: [
-        { key: 1, value: 12 },
-        { key: 2, value: 40 },
-        { key: 3, value: 28 },
-      ],
-      name: 'Users',
-    },
-  ],
-  tooltip: true,
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+
+// Before: replace a hand-drawn SVG each time values change.
+function drawLine(values: number[]) {
+  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  const low = Math.min(...values);
+  const span = Math.max(...values) - low || 1;
+  const points = values.map((value, index) => {
+    const x = (index / Math.max(1, values.length - 1)) * 640;
+    const y = 320 - ((value - low) / span) * 320;
+    return `${index === 0 ? 'M' : 'L'}${x},${y}`;
+  });
+  svg.setAttribute('viewBox', '0 0 640 320');
+  path.setAttribute('d', points.join(' '));
+  path.setAttribute('fill', 'none');
+  path.setAttribute('stroke', 'currentColor');
+  svg.append(path);
+  host.replaceChildren(svg);
+}
+drawLine([10, 25, 18]);
+drawLine([10, 25, 18, 32]);
+
+// After: keep the chart instance and replace its series data.
+const chart = createLineChart(host, {
+  a11y: { ariaLabel: 'Revenue by month' },
+  series: [{ data: [{ key: 1, value: 10 }, { key: 2, value: 25 }, { key: 3, value: 18 }], name: 'Revenue' }],
 });
-
-chart.update([
-  {
-    data: [
-      { key: 1, value: 12 },
-      { key: 2, value: 40 },
-      { key: 3, value: 28 },
-      { key: 4, value: 65 },
-    ],
-    name: 'Users',
-  },
-]);
+chart.update([{
+  data: [{ key: 1, value: 10 }, { key: 2, value: 25 }, { key: 3, value: 18 }, { key: 4, value: 32 }],
+  name: 'Revenue',
+}]);
+chart.dispose();
 ```
 
-| Feature            | Prism                                        | Chart.js                                 | Lightweight Charts                           | D3                                           |
-| ------------------ | -------------------------------------------- | ---------------------------------------- | -------------------------------------------- | -------------------------------------------- |
-| Bundle size        |   | ~60 kB                                   | ~45 kB                                       | ~30 kB (core)                                |
-| Zero dependencies  |  (Orbit) |  |  |  (modular) |
-| Renderer           | SVG                                          | Canvas                                   | Canvas                                       | SVG/Canvas                                   |
-| Data updates        | Explicit `update()`                            | Instance mutation                        | Series mutation                              | Manual                                       |
-| CSS themeable       |  |  | Limited                                      |  |
-| Framework-neutral   |  |  |  |  |
-| Accessible SVG     |  |  |      | Manual                                       |
-| Keyboard navigation |  |  |      | Manual                                       |
-| TypeScript-first   |  | Partial                                  |  | Types available                              |
+| Feature | Prism | Hand-written SVG |
+| --- | --- | --- |
+| Bundle size |  | No chart package |
+| Zero dependencies |  (uses Orbit) |  |
+| Data updates | `ChartHandle.update()` replaces chart data | You implement the update path |
+| Responsive sizing | `ResizeObserver` recalculates the chart layout | You implement the resize behavior |
+| Chart interactions | Built-in pointer and keyboard interactions on supported charts | You implement them |
+| SVG accessibility | Informative charts support an accessible name and keyboard focus | You implement the accessible behavior |
 
-**Use Prism when** you need lightweight, framework-neutral charts with explicit updates and SVG output that can be styled with CSS. It fits dashboards, admin panels, and data-heavy applications.
+**Use Prism when** you need chart factories, responsive SVG output, and an explicit data-update boundary without adopting a charting framework.
 
-**Consider alternatives when** you need 50+ chart types (ECharts), financial trading charts (Lightweight Charts), or low-level visualization grammar (D3).
+**Consider hand-written SVG when** you need a single specialized graphic and prefer to own its scales, resizing, labels, and interactions directly.
 
 ## Installation
 
@@ -16478,63 +17906,48 @@ yarn add @vielzeug/prism
 
 ## Quick Start
 
+Create and size a host element before creating the chart. Import `theme.css` once to load Prism's default styles and CSS custom properties.
+
 ```ts
 import { createLineChart } from '@vielzeug/prism';
 import '@vielzeug/prism/theme.css';
 
-const chart = createLineChart(document.getElementById('chart')!, {
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+
+const chart = createLineChart(host, {
   a11y: { ariaLabel: 'Revenue by month' },
-  series: [
-    {
-      color: '#3b82f6',
-      data: [
-        { key: 1, value: 10 },
-        { key: 2, value: 25 },
-        { key: 3, value: 18 },
-        { key: 4, value: 32 },
-      ],
-      name: 'Revenue',
-    },
-  ],
-  xAxis: { position: 'bottom' },
-  yAxis: { position: 'left', grid: true },
+  series: [{
+    data: [{ key: 1, value: 10 }, { key: 2, value: 25 }, { key: 3, value: 18 }],
+    name: 'Revenue',
+  }],
   tooltip: true,
-  crosshair: true,
-  onHover: (event) => console.log(event?.datum),
 });
 
-// Update chart data explicitly
-chart.update([
-  {
-    color: '#3b82f6',
-    data: [{ key: 1, value: 10 }, { key: 2, value: 25 }, { key: 3, value: 18 }, { key: 4, value: 32 }, { key: 5, value: 28 }],
-    name: 'Revenue',
-  },
-]);
+chart.update([{
+  data: [{ key: 1, value: 10 }, { key: 2, value: 25 }, { key: 3, value: 18 }, { key: 4, value: 32 }],
+  name: 'Revenue',
+}]);
 
-// Cleanup when done
 chart.dispose();
 ```
 
 ## Features
 
-- **`createLineChart(container, config)`**: line chart with linear, monotone, or step interpolation
-- **`createBarChart(container, config)`**: bar chart with four layout variants: grouped, stacked, grouped-horizontal, stacked-horizontal
-- **`createAreaChart(container, config)`**: filled area with a gradient or solid fill
-- **`createPieChart(container, config)`**: pie, donut, or semi-circle donut chart; labels that do not fit their slice are hidden
-- **`createRadarChart(container, config)`**: radar chart for comparing values across 3+ axes, with per-axis ranges
-- **`createSparkline(container, config)`**: minimal inline line, area, bar, or stack chart
-- **`linearScale`, `timeScale`, `bandScale`**: standalone scales with nice tick generation
-- **`ChartHandle.update(data)`**: replace chart data synchronously without coupling to a state library
-- **`setTheme(theme, { scope })` / `resetTheme({ scope })`**: apply or clear colors, font, grid, axis, text, and tooltip tokens globally or on one subtree at runtime
-- **Axes on by default**: line, area, and bar charts render both axes with gridlines on the value axis; `xAxis: false` / `yAxis: false` opt out
-- **Animations on by default**: every chart animates entry and updates through one rAF loop, honors reduced motion, and opts out with `transition: false`
-- **Series comparison**: hover or keyboard focus reports every series at the active key in the tooltip, `onHover`, and screen-reader announcements
-- **Keyboard navigation**: arrow keys, `Enter`, and `Escape` on every labelled chart except sparklines
-- **CSS custom properties**: full theme control via `--prism-*` tokens, with dark mode built in
-- **Responsive**: auto-resizes via `ResizeObserver`
-- **`ChartHandle.tap()`**: observe resize and dispose events outside the render path, with zero cost when untapped
-- **`Symbol.dispose`**: explicit resource management following the TC39 proposal
+- **`createLineChart()` / `createAreaChart()`**: plot continuous numeric or date-keyed series
+- **`createBarChart()`**: compare categories with grouped, stacked, or horizontal bars
+- **`createScatterChart()`**: plot independent numeric `(x, y)` points
+- **`createPieChart()`**: render pie, donut, or semi-circle slices
+- **`createRadarChart()`**: compare series across fixed, labelled axes
+- **`createSparkline()`**: render compact line, area, bar, or stacked values without axes
+- **`ChartHandle.update(data)`**: replace chart data without handing state ownership to Prism
+- **`ChartHandle.dispose()` / `Symbol.dispose`**: release the SVG, observer, overlays, and chart-owned animation
+- **`ChartHandle.tap()`**: observe resize and disposal events
+- **`setTheme()` / `resetTheme()`**: set supported palette, typography, axis, grid, and tooltip tokens globally or on one element
+- **CSS custom properties**: style the chart palette, marks, axes, labels, tooltip, legend, and motion
+- **Resize observation**: recalculate SVG layout when the host element changes size
+- **Accessible interaction**: labelled interactive charts expose keyboard navigation and polite value announcements; sparklines are pointer-only without value announcements
 
 ## Documentation
 
@@ -16545,37 +17958,44 @@ chart.dispose();
 
 ## See Also
 
-- [Refine](/refine/): accessible web components that pair well with Prism for dashboards
-- [Orbit](/orbit/): floating element positioning for chart tooltips and popovers
+- [Refine](/refine/): web components and theme tokens for building controls and layouts around chart hosts
+- [Orbit](/orbit/): floating-element positioning used internally by Prism's built-in tooltip
 
 ### API Reference
 
 ## API Overview
 
+All chart factories, scale utilities, theme helpers, and error classes are synchronous. Charts render into an HTML element and return a `ChartHandle`; they do not return a promise.
+
 | Symbol | Purpose | Execution mode | Common gotcha |
 | --- | --- | --- | --- |
-| `createLineChart()` | Render a line chart | Sync | Line keys must be numbers or dates |
-| `createAreaChart()` | Render an area chart | Sync | Line keys must be numbers or dates |
-| `createBarChart()` | Render grouped or stacked bars | Sync | Stacked negative values are clamped to zero |
-| `createPieChart()` | Render pie, donut, or semi-circle slices | Sync | `onHover` receives `null` when the pointer leaves |
-| `createRadarChart()` | Compare values across 3+ axes, such as hero stats | Sync | Events report a whole axis, not one series |
-| `createSparkline()` | Render an inline line, area, bar, or stack | Sync | Omitted `a11y` makes the chart decorative |
-| `linearScale()` | Create a numeric scale | Sync | `nice` defaults to `true` |
-| `timeScale()` | Create a date scale | Sync | Invalid dates produce an invalid domain |
-| `bandScale()` | Create a categorical scale | Sync | Unknown categories map to `0` and warn in development |
-| `setTheme()` | Set Prism CSS custom properties | Sync | Writes to `document.documentElement` unless `scope` is given |
-| `resetTheme()` | Remove Prism theme overrides | Sync | Clears only properties `setTheme()` wrote, on the same target |
-| `seriesColor()` | Resolve a series palette color | Sync | Palette indexes wrap after eight colors |
+| `createLineChart()` | Render one or more continuous line series | Sync | `key` values must be numbers or dates |
+| `createAreaChart()` | Render continuous series with filled areas | Sync | Fills use a gradient by default |
+| `createScatterChart()` | Plot independent `(x, y)` points | Sync | `key` is the x-value; the y-domain is fitted to data |
+| `createBarChart()` | Render categorical bars | Sync | Negative values in stacked variants are clamped to zero |
+| `createPieChart()` | Render pie, donut, or semi-circle slices | Sync | `variant` is fixed at creation; `update()` replaces slices |
+| `createRadarChart()` | Compare series across fixed axes | Sync | Requires at least three axes to draw |
+| `createSparkline()` | Render a compact line, area, bar, or stack | Sync | Has no axes, legend, or keyboard navigation |
+| `linearScale()` | Create a numeric scale | Sync | `nice` defaults to `true`; set `nice: false` to preserve the domain |
+| `timeScale()` | Create a date scale | Sync | `nice` defaults to `true` |
+| `bandScale()` | Create an ordered categorical scale | Sync | Unknown categories map to `0` and warn in development |
+| `setTheme()` | Set Prism CSS custom properties | Sync | Writes inline styles to `document.documentElement` by default |
+| `resetTheme()` | Remove theme overrides set by `setTheme()` | Sync | Only clears the selected target |
+| `seriesColor()` | Resolve a palette CSS value | Sync | Palette positions wrap after eight |
+| `PrismError` | Base class for Prism errors | Sync | Use `instanceof` to catch any Prism error |
+| `PrismRenderError` | Report an invalid chart container or failed chart operation | Sync | Also thrown by `update()` after disposal |
 
 ## Package Entry Point
 
 | Import | Purpose |
 | --- | --- |
-| `@vielzeug/prism` | Chart factories, scales, theme helpers, errors, and public types |
-| `@vielzeug/prism/theme.css` | Default CSS custom properties and dark-mode values |
+| `@vielzeug/prism` | Chart factories, scale and theme functions, error classes, and public types |
+| `@vielzeug/prism/theme.css` | Default chart styles, CSS custom properties, dark-mode values, and reduced-motion rules |
 
 ## Chart Factories
 
+Each factory appends an SVG to `container`. A chart with no measurable container size uses a temporary `600 × 300` SVG size and emits a development warning; `ResizeObserver` applies later size changes. Unless `a11y` is informative, the SVG is hidden from the accessibility tree.
+
 ### `createLineChart()`
 
 ```ts
@@ -16585,28 +18005,32 @@ function createLineChart(
 ): ChartHandle;
 ```
 
-Renders a line chart and returns a handle that replaces the complete series array through `update()`.
+Renders line series and returns a handle whose `update()` argument replaces the complete series array. Axes render by default; the value axis has grid lines by default. Pass `false` to `xAxis` or `yAxis` to suppress that axis.
+
+Series use linear interpolation by default, omit point markers by default, and use a point radius of 3 when markers are enabled. `yAxis` defaults to `'left'`; crosshair, tooltip, and legend are disabled unless configured.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `container` | `HTMLElement` | Host that receives the SVG and optional overlays |
-| `config` | `LineChartConfig` | Initial series, axes, interaction, accessibility, and transition settings |
+| `container` | `HTMLElement` | Host that receives the chart SVG and optional overlays |
+| `config` | `LineChartConfig` | Series, axes, interaction, accessibility, and motion settings |
 
 **Returns:** `ChartHandle`.
 
 ```ts
 import { createLineChart } from '@vielzeug/prism';
 
-const chart = createLineChart(container, {
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+
+const chart = createLineChart(host, {
   a11y: { ariaLabel: 'Revenue by month' },
-  series: [{ data: [{ key: 1, value: 10 }], name: 'Revenue' }],
+  series: [{ data: [{ key: 1, value: 10 }, { key: 2, value: 15 }], name: 'Revenue' }],
 });
-
-chart.update([{ data: [{ key: 2, value: 20 }], name: 'Revenue' }]);
+chart.update([{ data: [{ key: 1, value: 10 }, { key: 2, value: 15 }, { key: 3, value: 18 }], name: 'Revenue' }]);
+chart.dispose();
 ```
 
----
-
 ### `createAreaChart()`
 
 ```ts
@@ -16616,24 +18040,67 @@ function createAreaChart(
 ): ChartHandle;
 ```
 
-Renders an area chart and returns a handle that replaces the complete series array through `update()`.
+Renders continuous area series with a gradient fill by default. `update()` replaces the complete series array.
+
+Area series use linear interpolation by default and show their top line unless `showLine: false` is set. Axes render by default, with grid lines on the value axis.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `container` | `HTMLElement` | Host that receives the SVG and optional overlays |
-| `config` | `AreaChartConfig` | Initial series, axes, interaction, accessibility, and transition settings |
+| `container` | `HTMLElement` | Host that receives the chart SVG and optional overlays |
+| `config` | `AreaChartConfig` | Series, axes, interaction, accessibility, and motion settings |
 
 **Returns:** `ChartHandle`.
 
 ```ts
 import { createAreaChart } from '@vielzeug/prism';
 
-const chart = createAreaChart(container, {
-  series: [{ data: [{ key: 1, value: 10 }], name: 'Revenue' }],
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+
+const chart = createAreaChart(host, {
+  a11y: { ariaLabel: 'Visitors over time' },
+  series: [{ data: [{ key: 1, value: 10 }, { key: 2, value: 18 }], name: 'Visitors' }],
 });
+chart.dispose();
 ```
 
----
+### `createScatterChart()`
+
+```ts
+function createScatterChart(
+  container: HTMLElement,
+  config: ScatterChartConfig,
+): ChartHandle;
+```
+
+Plots each datum independently: `key` is the numeric or date x-value and `value` is the y-value. Points are not joined. `update()` replaces the complete series array.
+
+Axes render by default, with grid lines on the value axis. The value scale is fitted to the observed data rather than forced to include zero. Tooltip, crosshair, and legend are disabled unless configured.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `container` | `HTMLElement` | Host that receives the chart SVG and optional overlays |
+| `config` | `ScatterChartConfig` | Independent points, axes, interaction, accessibility, and motion settings |
+
+**Returns:** `ChartHandle`.
+
+```ts
+import { createScatterChart } from '@vielzeug/prism';
+
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+
+const chart = createScatterChart(host, {
+  a11y: { ariaLabel: 'Height against weight' },
+  series: [{ data: [{ key: 160, value: 55 }, { key: 175, value: 70 }], name: 'Cohort A' }],
+  tooltip: true,
+});
+chart.dispose();
+```
+
+Scatter interaction reports the datum and series of the point nearest the pointer in two dimensions, without a `values` array. Keyboard navigation visits points across series in x order. Tooltip `titleFormat` receives the x-value and `valueFormat` the y-value. On mount, points grow from radius zero at their final positions; updates slide existing points and grow new ones.
 
 ### `createBarChart()`
 
@@ -16644,25 +18111,32 @@ function createBarChart(
 ): ChartHandle;
 ```
 
-Renders grouped, stacked, grouped-horizontal, or stacked-horizontal bars.
+Renders grouped, stacked, grouped-horizontal, or stacked-horizontal categories. `update()` replaces the complete series array; the variant is fixed at creation. Axes render by default, with grid lines on the value axis.
+
+The default variant is `grouped`; tooltip and legend are disabled unless configured.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `container` | `HTMLElement` | Host that receives the SVG and optional overlays |
-| `config` | `BarChartConfig` | Initial series, variant, axes, accessibility, and interaction settings |
+| `container` | `HTMLElement` | Host that receives the chart SVG and optional overlays |
+| `config` | `BarChartConfig` | Series, layout variant, axes, interaction, accessibility, and motion settings |
 
 **Returns:** `ChartHandle`.
 
 ```ts
 import { createBarChart } from '@vielzeug/prism';
 
-const chart = createBarChart(container, {
-  series: [{ data: [{ key: 'Open', value: 12 }], name: 'Tasks' }],
-  variant: 'grouped',
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+
+const chart = createBarChart(host, {
+  a11y: { ariaLabel: 'Tasks by status' },
+  series: [{ data: [{ key: 'Open', value: 12 }, { key: 'Done', value: 8 }], name: 'Tasks' }],
 });
+chart.dispose();
 ```
 
----
+For stacked variants, negative values are treated as zero and produce a development warning.
 
 ### `createPieChart()`
 
@@ -16673,26 +18147,30 @@ function createPieChart(
 ): ChartHandle;
 ```
 
-Renders pie, donut, or semi-circle slices.
+Renders pie, donut, or semi-circle slices. The default variant is `pie`; `update()` replaces the slice array. The default inner radius is zero for pies and 55% of the outer radius for donut and semi variants. Pie slices default to no padding or rounded corners; donut and semi slices default to 8px padding and corner radius.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `container` | `HTMLElement` | Host that receives the SVG and optional overlays |
-| `config` | `PieChartConfig` | Initial slices, variant, geometry, accessibility, and interaction settings |
+| `container` | `HTMLElement` | Host that receives the chart SVG and optional overlays |
+| `config` | `PieChartConfig` | Slices, shape, geometry, legend, tooltip, and interaction settings |
 
 **Returns:** `ChartHandle`.
 
 ```ts
 import { createPieChart } from '@vielzeug/prism';
 
-const chart = createPieChart(container, {
-  data: [{ label: 'Complete', value: 72 }, { label: 'Remaining', value: 28 }],
+const host = document.createElement('div');
+host.style.cssText = 'width:320px;height:240px';
+document.body.append(host);
+
+const chart = createPieChart(host, {
+  a11y: { ariaLabel: 'Orders by channel' },
+  data: [{ label: 'Direct', value: 72 }, { label: 'Referral', value: 28 }],
   variant: 'donut',
 });
+chart.dispose();
 ```
 
----
-
 ### `createRadarChart()`
 
 ```ts
@@ -16702,47 +18180,32 @@ function createRadarChart(
 ): ChartHandle;
 ```
 
-Renders one closed shape per series across three or more axes. `update()` replaces the series; the axes are fixed at creation.
+Renders one shape per series across the configured axes. `update()` replaces series data but not axes or other configuration. Fewer than three axes warn in development and draw no chart. Tooltip and legend are disabled unless configured.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `container` | `HTMLElement` | Host that receives the SVG and optional overlays |
-| `config` | `RadarChartConfig` | Axes, series, scale, grid, appearance, accessibility, and interaction settings |
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `axes` | `RadarAxisConfig[]` | N/A | Ordered axes, drawn clockwise; needs at least 3 |
-| `series` | `RadarSeriesConfig[]` | N/A | Values keyed by `axis.key` |
-| `domain` | `[number, number]` | `[0, nice max]` | Shared value range; `axis.min`/`axis.max` override it per axis |
-| `grid` | `boolean \| RadarGridConfig` | `true` | Rings, bands, and level labels; `false` hides the grid |
-| `fill` | `'gradient' \| 'none' \| 'solid'` | `'solid'` | Shape fill; `gradient` deepens toward the rim |
-| `curve` | `'linear' \| 'rounded'` | `'linear'` | Straight edges or a smooth closed curve |
-| `showPoints` | `boolean` | `true` | Vertex dots; a missing value shows a hollow dot at the centre |
-| `showValues` | `boolean` | `false` | Print each value beside its vertex |
-| `startAngle` | `number` | `0` | Degrees clockwise from 12 o'clock for the first axis |
-| `onHover` | `(event: RadarEvent \| null) => void` | N/A | Nearest axis under the pointer or keyboard focus |
-| `onClick` | `(event: RadarEvent) => void` | N/A | Axis clicked, or activated with Enter/Space |
+| `container` | `HTMLElement` | Host that receives the chart SVG and optional overlays |
+| `config` | `RadarChartConfig` | Fixed axes, series, scale, grid, appearance, and interaction settings |
 
 **Returns:** `ChartHandle`.
 
 ```ts
 import { createRadarChart } from '@vielzeug/prism';
 
-const chart = createRadarChart(container, {
+const host = document.createElement('div');
+host.style.cssText = 'width:400px;height:320px';
+document.body.append(host);
+
+const chart = createRadarChart(host, {
   a11y: { ariaLabel: 'Hero stats' },
-  axes: [
-    { key: 'str', label: 'Strength' },
-    { key: 'agi', label: 'Agility' },
-    { key: 'end', label: 'Endurance' },
-  ],
+  axes: [{ key: 'str', label: 'Strength' }, { key: 'agi', label: 'Agility' }, { key: 'end', label: 'Endurance' }],
   domain: [0, 10],
   series: [{ data: [{ key: 'str', value: 8 }, { key: 'agi', value: 6 }, { key: 'end', value: 9 }], name: 'Adam' }],
 });
+chart.dispose();
 ```
 
-Hovering or arrowing onto an axis highlights its spoke and reports every series' value on it. Without a tooltip, the chart announces the values through its own `role="status"` region. A value for an unknown axis, duplicate axis keys, or fewer than 3 axes warns in development.
-
----
+Radar defaults are a solid fill, linear curves, visible points, a four-level polygon grid with bands, no grid labels, and a first-axis angle of zero degrees. Grid labels render only when all axes share a domain.
 
 ### `createSparkline()`
 
@@ -16753,22 +18216,29 @@ function createSparkline(
 ): ChartHandle;
 ```
 
-Renders a compact chart without axes, margin, or legend.
+Renders compact data without axes, chart margins, or a legend. `update()` replaces the number or stack-segment array. The default variant is `line`; only line and area variants draw the endpoint marker by default.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `container` | `HTMLElement` | Host that receives the SVG |
-| `config` | `SparklineConfig` | Initial values, variant, appearance, accessibility, and callbacks |
+| `container` | `HTMLElement` | Host that receives the chart SVG |
+| `config` | `SparklineConfig` | Values, variant, appearance, accessibility, and pointer callbacks |
 
 **Returns:** `ChartHandle`.
 
 ```ts
 import { createSparkline } from '@vielzeug/prism';
 
-const chart = createSparkline(container, { data: [2, 5, 3, 8], variant: 'area' });
+const host = document.createElement('div');
+host.style.cssText = 'width:240px;height:48px';
+document.body.append(host);
+
+const chart = createSparkline(host, { data: [2, 5, 3, 8], variant: 'area' });
 chart.update([2, 5, 3, 8, 13]);
+chart.dispose();
 ```
 
+`StackSegment[]` is for `variant: 'stack'`. Pointer callbacks are available for numeric line, area, and bar sparklines; sparklines do not support keyboard navigation.
+
 ## Scale Factories
 
 ### `linearScale()`
@@ -16777,14 +18247,16 @@ chart.update([2, 5, 3, 8, 13]);
 function linearScale(config: LinearScaleConfig): Scale;
 ```
 
-| Field | Type | Default | Description |
+Maps a numeric domain to a numeric range. `nice` defaults to `true`; `clamp` defaults to `false` and applies to `map()`, not `invert()`.
+
+| Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `domain` | `[number, number]` | N/A | Input extent |
-| `range` | `[number, number]` | N/A | Output extent |
-| `clamp` | `boolean` | `false` | Clamp mapped and inverted values |
-| `nice` | `boolean` | `true` | Expand the domain to rounded boundaries |
+| `config.domain` | `[number, number]` | Required | Input extent |
+| `config.range` | `[number, number]` | Required | Output extent |
+| `config.clamp` | `boolean` | `false` | Clamp mapped values to the range |
+| `config.nice` | `boolean` | `true` | Expand the domain to rounded boundaries |
 
-**Returns:** `Scale`.
+**Returns:** `Scale`, with `map`, `invert`, `ticks`, `domain`, and `range`.
 
 ```ts
 import { linearScale } from '@vielzeug/prism';
@@ -16793,21 +18265,21 @@ const scale = linearScale({ domain: [0, 100], range: [0, 500] });
 scale.map(50); // 250
 ```
 
----
-
 ### `timeScale()`
 
 ```ts
 function timeScale(config: TimeScaleConfig): Scale;
 ```
 
-| Field | Type | Default | Description |
+Maps date values to a numeric range. `nice` defaults to `true` and rounds the domain to a time interval.
+
+| Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `domain` | `[Date, Date]` | N/A | Input date extent |
-| `range` | `[number, number]` | N/A | Output extent |
-| `nice` | `boolean` | `true` | Expand the domain to rounded interval boundaries |
+| `config.domain` | `[Date, Date]` | Required | Input date extent |
+| `config.range` | `[number, number]` | Required | Output extent |
+| `config.nice` | `boolean` | `true` | Expand the domain to time-interval boundaries |
 
-**Returns:** `Scale`.
+**Returns:** `Scale`, with `map`, `invert`, `ticks`, `domain`, and `range`.
 
 ```ts
 import { timeScale } from '@vielzeug/prism';
@@ -16816,45 +18288,59 @@ const scale = timeScale({
   domain: [new Date('2026-01-01'), new Date('2026-12-31')],
   range: [0, 500],
 });
+scale.map(new Date('2026-07-02'));
 ```
 
----
-
 ### `bandScale()`
 
 ```ts
 function bandScale(config: BandScaleConfig): BandScale;
 ```
 
-| Field | Type | Default | Description |
+Maps ordered string categories to the start of each band. `padding` defaults to `0.1`; `paddingOuter` defaults to the same value. Mapping an unknown category returns `0` and warns in development.
+
+| Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `domain` | `string[]` | N/A | Ordered categories |
-| `range` | `[number, number]` | N/A | Output extent |
-| `padding` | `number` | `0.1` | Inner gap ratio |
-| `paddingOuter` | `number` | `padding` | Outer gap ratio |
+| `config.domain` | `string[]` | Required | Ordered categories |
+| `config.range` | `[number, number]` | Required | Output extent |
+| `config.padding` | `number` | `0.1` | Inner gap as a ratio of bandwidth |
+| `config.paddingOuter` | `number` | `padding` | Outer gap as a ratio of bandwidth |
 
-**Returns:** `BandScale`.
+**Returns:** `BandScale`, with `map`, `ticks`, `bandwidth`, `gap`, `domain`, and `range`.
 
 ```ts
 import { bandScale } from '@vielzeug/prism';
 
 const scale = bandScale({ domain: ['A', 'B'], range: [0, 200] });
+scale.bandwidth();
 ```
 
 ## Theme Utilities
 
+`theme.css` supplies the base CSS values and styles. `setTheme()` writes inline custom properties, which take precedence over stylesheet declarations. For other visual controls, set CSS custom properties directly.
+
 ### `setTheme()`
 
 ```ts
 function setTheme(theme: PrismTheme, options?: ThemeScope): void;
 ```
 
-Sets Prism theme custom properties as inline styles on `options.scope` when given, otherwise on `document.documentElement`. Inline values outrank every stylesheet rule, including dark-mode selectors.
+Sets the provided theme values on `options.scope`, or on `document.documentElement` when omitted. Omitted scalar keys remain unchanged. Providing `colors` replaces all eight palette slots, removing unused slots.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `theme` | `PrismTheme` | Tokens to write; omitted keys are left untouched |
-| `options.scope` | `HTMLElement` | Subtree to theme instead of `:root`; charts inside it resolve their `var(--prism-*)` lookups against these values |
+| `theme` | `PrismTheme` | Palette and supported axis, grid, text, font, and tooltip properties |
+| `options.scope` | `HTMLElement` | Element that scopes the inline custom properties |
+
+**Returns:** `void`.
+
+```ts
+import { setTheme } from '@vielzeug/prism';
+
+const host = document.createElement('div');
+document.body.append(host);
+setTheme({ colors: ['#2563eb', '#16a34a'], textColor: '#111827' }, { scope: host });
+```
 
 ### `resetTheme()`
 
@@ -16862,7 +18348,21 @@ Sets Prism theme custom properties as inline styles on `options.scope` when give
 function resetTheme(options?: ThemeScope): void;
 ```
 
-Removes every custom property `setTheme()` can set from `options.scope` (default `documentElement`). Scoped and global calls are independent targets.
+Removes every custom property managed by `setTheme()` from the given scope or the document root. It does not remove CSS rules or change any other custom properties.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ThemeScope` | Optional target; defaults to `document.documentElement` |
+
+**Returns:** `void`.
+
+```ts
+import { resetTheme, setTheme } from '@vielzeug/prism';
+
+const scope = document.createElement('div');
+setTheme({ textColor: '#111827' }, { scope });
+resetTheme({ scope });
+```
 
 ### `seriesColor()`
 
@@ -16870,1383 +18370,993 @@ Removes every custom property `setTheme()` can set from `options.scope` (default
 function seriesColor(index: number, override?: string): string;
 ```
 
-Returns `override` when provided; otherwise returns `var(--prism-color-N)` with an eight-color wrap.
+Returns `override` when it is provided; otherwise returns a `var(--prism-color-N)` reference. The palette has eight positions and the index wraps around after the eighth.
 
-## Types
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `index` | `number` | Zero-based palette position |
+| `override` | `string` | Optional color returned instead of a CSS variable |
 
-### Core types
+**Returns:** `string`.
 
 ```ts
-interface ChartHandle {
-  readonly disposalSignal: AbortSignal;
-  readonly disposed: boolean;
-  readonly el: SVGSVGElement;
-  tap(handler: (event: PrismEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
-  update(data: TData): void;
-  dispose(): void;
-  [Symbol.dispose](): void;
-}
+import { seriesColor } from '@vielzeug/prism';
 
-type PrismEvent =
-  | { readonly height: number; readonly type: 'resize'; readonly width: number }
-  | { readonly type: 'dispose' };
+seriesColor(0); // 'var(--prism-color-1)'
+seriesColor(1, '#2563eb'); // '#2563eb'
+```
 
-interface ChartMargin {
-  top: number;
-  right: number;
-  bottom: number;
-  left: number;
-}
+## Chart Handle
 
-interface ChartDimensions {
-  width: number;
-  height: number;
-  margin: ChartMargin;
-}
+`ChartHandle` is returned by every chart factory. `update()` synchronously rebuilds the chart from its new data; enabled motion may animate the resulting SVG. `dispose()` is idempotent, removes the chart SVG, observers, tooltip and legend, cancels chart-owned animation, aborts `disposalSignal`, and emits one `dispose` tap event. `update()` after disposal throws `PrismRenderError`.
 
-type ChartA11y =
-  | { readonly decorative: true }
-  | { readonly ariaLabel: string; readonly decorative?: false };
-```
+`tap()` observes `resize` and `dispose` events outside the render path. It returns an unsubscribe function; an optional abort signal removes the subscription. Observer-handler exceptions are swallowed so they cannot affect chart behavior. A tap added after disposal returns a no-op unsubscribe function.
 
-`update()` renders synchronously and throws `PrismRenderError` after disposal. Omitting `a11y` makes the SVG decorative with `aria-hidden="true"`.
+`[Symbol.dispose]()` delegates to `dispose()`, allowing explicit resource management where supported.
 
-`tap()` observes runtime behavior outside the render path: it receives `resize` and `dispose` events (see `PrismEvent`). It returns an unsubscribe function; pass `options.signal` to detach automatically. Handler errors are swallowed, and tapping a disposed handle returns a no-op unsubscribe.
+All chart handles expose the same lifecycle members; interactive cartesian and pie/radar charts use a `.prism-live` status region when no tooltip is enabled. A tooltip is itself a polite status region. Sparklines have neither a tooltip nor a live value announcer.
 
----
+| Method or property | Contract |
+| --- | --- |
+| `el` | The chart's root `SVGSVGElement` |
+| `update(data)` | Replace chart data and render; throws `PrismRenderError` after disposal |
+| `dispose()` | Idempotently release chart-owned DOM, observation, and motion |
+| `disposed` | Whether the handle has been disposed |
+| `disposalSignal` | `AbortSignal` aborted during disposal |
+| `tap(handler, options?)` | Observe resize/dispose events; returns an unsubscribe function |
+| `[Symbol.dispose]()` | Calls `dispose()` |
+
+`PrismEvent` reports a changed SVG content size as `{ type: 'resize', width, height }`; the `dispose` event is emitted once before teardown completes.
+
+## Types
+
+The following are all types and interfaces exported from `@vielzeug/prism`. Definitions mirror the package entry-point contracts.
 
-### Data types
+### Animation Types
 
 ```ts
-interface Datum {
-  key: TKey;
-  value: number;
-  meta?: Record;
-  dash?: string; // stroke-dasharray for this datum's marks, e.g. '5 5'
-  opacity?: number; // opacity multiplier 0-1 for this datum's marks, e.g. 0.4
+export type EasingFn = (t: number) => number;
+export type EasingName = 'back-out' | 'ease-in' | 'ease-in-out' | 'ease-out' | 'expo-out' | 'linear';
+
+export interface TransitionConfig {
+  /** Milliseconds per animated lane. Defaults to 300 (420 for a line entrance, 400 for radar). */
+  duration?: number;
+  easing?: EasingName | ((t: number) => number);
+  /** `system` skips animation when reduced motion is preferred. */
+  preference?: 'always' | 'never' | 'system';
+  /** Per-bar delay on bar charts, per-entering-point delay (x order) on scatter charts, or per-series delay on radar charts. Bar and scatter charts cap the total added delay at about 400 ms. */
+  stagger?: number;
 }
 
-type ContinuousDatum = Datum;
+export type TransitionOption = TransitionConfig | boolean;
+```
 
-interface Series {
-  name: string;
-  data: TDatum[];
-  color?: string;
-  id?: string; // stable data-series-id on the series group; defaults to series-
-}
+### Theme Types
 
-interface ChartEvent {
-  datum: Datum;
-  series: Series;
-  originalEvent: Event;
-  values?: SeriesValue[]; // every series at the same key (line, area, bar)
+```ts
+export interface PrismTheme {
+  axisColor?: string;
+  colors?: string[];
+  fontFamily?: string;
+  gridColor?: string;
+  gridOpacity?: number;
+  textColor?: string;
+  textColorSecondary?: string;
+  tooltipBg?: string;
+  tooltipBorder?: string;
+  tooltipColor?: string;
 }
 
-interface SeriesValue {
-  datum: Datum | undefined;
-  series: Series;
+export interface ThemeScope {
+  readonly scope?: HTMLElement;
 }
 ```
 
-Line and area series use `ContinuousDatum`; bar series accept the complete `Datum` key range. On line, area, and bar charts, `datum`/`series` name the series nearest the pointer, and `values` lists every series at that key (a missing value is `undefined`). `originalEvent` is a `MouseEvent`, or a `KeyboardEvent` for keyboard navigation.
+`PrismTheme.colors` writes up to eight palette slots. The scalar fields map as follows:
 
-#### Per-datum presentation
-
-`dash` and `opacity` style an individual datum's marks without splitting the series — the usual case is a forecast tail where points past "today" are faded or dashed. They are styling-only: interaction, tooltip, and accessibility behavior never change. Support is per chart type:
+| Field | CSS custom property |
+| --- | --- |
+| `axisColor` | `--prism-axis-color` |
+| `fontFamily` | `--prism-font-family` |
+| `gridColor` | `--prism-grid-color` |
+| `gridOpacity` | `--prism-grid-opacity` |
+| `textColor` | `--prism-text-color` |
+| `textColorSecondary` | `--prism-text-color-secondary` |
+| `tooltipBg` | `--prism-tooltip-bg` |
+| `tooltipBorder` | `--prism-tooltip-border` |
+| `tooltipColor` | `--prism-tooltip-color` |
 
-| Chart | `dash` | `opacity` |
-| --- | --- | --- |
-| Bar | `stroke-dasharray` on the datum's `rect`, plus a 1px series-color stroke so the dash is visible on the fill. | Element `opacity` on the datum's `rect`. |
-| Line | The segment from this datum to the next (Chart.js-style segments). The last datum's `dash` has no segment and is ignored. | That same segment, plus this datum's own point marker. |
-| Area | The top line's segment from this datum to the next (last datum ignored). The fill keeps the series-level treatment. | Same segment on the top line. |
-| Sparkline, pie, radar | Ignored. | Ignored. |
+### Core and Data Types
 
-Consecutive datums that share one `dash`/`opacity` render as a single path run. Absent fields keep the series/theme default, and a series with no presentation fields renders byte-identically to a chart that never used them. See [Forecast / emphasis styling](./usage.md#forecast--emphasis-styling).
+```ts
+export interface ChartMargin {
+  bottom: number;
+  left: number;
+  right: number;
+  top: number;
+}
 
-#### Stable series identity
+export interface ChartDimensions {
+  height: number;
+  margin: ChartMargin;
+  width: number;
+}
 
-`Series.id` is rendered as `data-series-id` on the chart's series group (`.prism-line-series`, `.prism-bar-series`, `.prism-area-series`, `.prism-radar-series`) so tooltips, tests, and external CSS can address a series without positional assumptions. Characters outside `[A-Za-z0-9_-]` are replaced with `-`. It defaults to `series-`, which only stays stable while the series order does — set `id` to survive reordering.
-
----
-
-### Chart configurations
-
-```ts
-interface BaseChartConfig {
-  a11y?: ChartA11y;
-  legend?: boolean | LegendConfig;
-  margin?: Partial;
-  onClick?: (event: ChartEvent) => void;
-  onHover?: (event: ChartEvent | null) => void;
-  tooltip?: boolean | TooltipConfig;
-  transition?: TransitionOption; // motion is on by default; false renders synchronously
-  // Omitted renders the axis with defaults (value axis with gridlines); false suppresses it.
-  xAxis?: XAxisConfig | false;
-  yAxis?: YAxisConfig | false;
-}
-
-interface LineChartConfig extends BaseChartConfig {
-  crosshair?: boolean | CrosshairConfig;
-  rightYAxis?: Omit;
-  series: LineSeriesConfig[];
-}
-
-interface AreaChartConfig extends BaseChartConfig {
-  crosshair?: boolean | CrosshairConfig;
-  series: AreaSeriesConfig[];
-}
-
-interface BarChartConfig extends BaseChartConfig {
-  series: BarSeriesConfig[];
-  variant?: BarVariant;
-}
-
-interface PieChartConfig
-  extends Omit {
-  data: PieSliceConfig[];
-  variant?: PieVariant;
-  innerRadius?: number;
-  cornerRadius?: number;
-  padPixels?: number;
-  onClick?: (event: PieEvent) => void;
-  onHover?: (event: PieEvent | null) => void;
-}
-
-interface RadarChartConfig
-  extends Omit {
-  axes: RadarAxisConfig[];
-  series: RadarSeriesConfig[];
-  curve?: 'linear' | 'rounded';
-  domain?: [number, number];
-  fill?: 'gradient' | 'none' | 'solid';
-  grid?: boolean | RadarGridConfig;
-  showPoints?: boolean;
-  showValues?: boolean;
-  startAngle?: number;
-  onClick?: (event: RadarEvent) => void;
-  onHover?: (event: RadarEvent | null) => void;
-}
-
-interface SparklineConfig {
-  data: number[] | StackSegment[];
-  variant?: SparklineVariant;
-  a11y?: ChartA11y;
-  color?: string;
-  cornerRadius?: number;
-  curve?: 'linear' | 'monotone' | 'step';
-  fillOpacity?: number; // overrides --prism-spark-fill-opacity (area variant)
-  onClick?: (event: SparklineEvent) => void;
-  onHover?: (event: SparklineEvent | null) => void;
-  padPixels?: number;
-  showEndPoint?: boolean; // default true: dot on the latest value (line, area)
-  strokeWidth?: number;
-  transition?: TransitionOption; // motion is on by default; false renders synchronously
-}
-```
-
----
-
-### Series and slice configurations
-
-```ts
-interface LineSeriesConfig extends Series {
-  yAxis?: 'left' | 'right'; // defaults to 'left'
-  curve?: 'linear' | 'monotone' | 'step';
-  pointRadius?: number;
-  showPoints?: boolean;
-  strokeWidth?: number; // overrides --prism-line-width
-}
+export type PrismEvent =
+  | { readonly height: number; readonly type: 'resize'; readonly width: number }
+  | { readonly type: 'dispose' };
 
-interface AreaSeriesConfig extends Series {
-  curve?: 'linear' | 'monotone' | 'step';
-  fill?: 'gradient' | 'solid'; // default 'gradient', fading toward the baseline
-  fillOpacity?: number; // overrides --prism-area-opacity
-  showLine?: boolean;
+export interface ChartHandle {
+  readonly disposalSignal: AbortSignal;
+  dispose(): void;
+  readonly disposed: boolean;
+  readonly el: SVGSVGElement;
+  tap(handler: (event: PrismEvent) => void, options?: { readonly signal?: AbortSignal }): () => void;
+  update(data: TData): void;
+  [Symbol.dispose](): void;
 }
 
-interface BarSeriesConfig extends Series {
-  borderRadius?: number; // overrides --prism-bar-radius; stacked bars stay square
-}
+export type ChartA11y =
+  | { readonly decorative: true }
+  | { readonly ariaLabel: string; readonly decorative?: false };
 
-interface PieSliceConfig {
+export interface Datum {
+  dash?: string;
+  key: TKey;
+  meta?: Record;
+  opacity?: number;
   value: number;
-  color?: string;
-  label?: string;
 }
 
-interface PieEvent {
-  index: number;
-  originalEvent: Event;
-  slice: PieSliceConfig;
-}
+export type ContinuousDatum = Datum;
 
-interface RadarAxisConfig {
-  key: string;
-  label: string;
-  min?: number;
-  max?: number;
-  format?: (value: number) => string;
-}
-
-type RadarSeriesConfig = Series>;
-
-interface RadarGridConfig {
-  bands?: boolean; // default true
-  labels?: boolean; // default false; drawn only when every axis shares one domain
-  levels?: number; // default 4
-  shape?: 'circle' | 'polygon'; // default 'polygon'
+export interface Series {
+  color?: string;
+  data: TDatum[];
+  id?: string;
+  name: string;
 }
 
-interface RadarEvent {
-  axis: RadarAxisConfig;
-  index: number;
-  values: RadarAxisValue[];
+export interface ChartEvent {
+  datum: Datum;
   originalEvent: Event;
+  series: Series;
+  values?: SeriesValue[];
 }
 
-interface RadarAxisValue {
+export interface SeriesValue {
   datum: Datum | undefined;
-  series: RadarSeriesConfig;
-}
-
-interface StackSegment {
-  value: number;
-  color?: string;
-  label?: string;
-}
-
-interface SparklineEvent {
-  index: number;
-  originalEvent: Event;
-  value: number;
+  series: Series;
 }
 ```
 
-A custom radar `tooltip.render` receives `datum.meta` with `axis`, `values`, and the default `text`.
-
----
-
-### Axis, interaction, and transition configurations
-
-```ts
-type HorizontalAxisPosition = 'bottom' | 'top';
-type VerticalAxisPosition = 'left' | 'right';
-type AxisPosition = HorizontalAxisPosition | VerticalAxisPosition;
-
-interface AxisConfig {
-  grid?: boolean | GridConfig;
-  label?: string;
-  position?: TPosition;
-  tickCount?: number;
-  tickFormat?: (value: Date | number | string) => string;
-}
-
-type XAxisConfig = AxisConfig;
-type YAxisConfig = AxisConfig;
-
-interface GridConfig {
-  color?: string;
-  dash?: string;
-}
-
-interface TooltipConfig {
-  offset?: number;
-  render?: (datum: Datum, series: Series) => Node | string;
-}
+`Datum.dash` and `Datum.opacity` affect rendered marks only on the chart types that support them. On bars, `dash` adds a 1px series-color stroke so the dash is visible against the fill. `Series.id` becomes a `data-series-id` attribute on a series group; characters outside `[A-Za-z0-9_-]` are replaced with `-`. When omitted, the id is based on the series index.
 
-interface CrosshairConfig {
-  horizontal?: boolean;
-  snap?: boolean;
-  vertical?: boolean;
-}
-
-interface LegendConfig {
-  position?: LegendPosition;
-}
-
-type LegendPosition = 'bottom' | 'left' | 'right' | 'top';
-
-interface TransitionConfig {
-  duration?: number; // ms per lane; default 300
-  easing?: EasingName | EasingFn;
-  preference?: 'always' | 'never' | 'system'; // 'system' (default) skips reduced-motion
-  stagger?: number; // ms per bar (bar) or series (radar); ignored elsewhere
-}
-
-// Motion is on by default. `false` renders every update synchronously,
-// `true` uses the chart defaults, or pass a config to tune them.
-type TransitionOption = TransitionConfig | boolean;
-
-type EasingName = 'ease-in' | 'ease-in-out' | 'ease-out' | 'back-out' | 'expo-out' | 'linear';
-
-type EasingFn = (t: number) => number;
-```
+| Chart | `dash` | `opacity` |
+| --- | --- | --- |
+| Bar | Strokes that datum's bar | Applies to that bar |
+| Line | Applies to the segment from this datum to the next | Applies to that segment and its point marker |
+| Area | Applies to the top-line segment from this datum to the next | Applies to that segment |
+| Scatter | Ignored | Applies to that point |
+| Pie, radar, sparkline | Ignored | Ignored |
 
-Tooltip strings are assigned through `textContent`. Return a `Node` for structured content.
+For line and area charts, the last datum has no following segment, so its `dash` value is ignored. The chart factories group adjacent segments with the same presentation values into path runs.
 
----
+For line, area, and bar charts, `ChartEvent.values` lists each series at the active key in series order. Its `datum` is `undefined` when that series has no matching key. `originalEvent` is a pointer event or a keyboard event for keyboard activation. Scatter events identify only the nearest independent point and omit `values`.
 
-### Scale types
+### Scale Types
 
 ```ts
-interface Scale {
+export interface Scale {
   readonly domain: readonly [T, T];
-  readonly range: readonly [number, number];
-  map(value: T): number;
   invert(pixel: number): T;
+  map(value: T): number;
+  readonly range: readonly [number, number];
   ticks(count?: number): T[];
 }
 
-interface BandScale {
+export interface BandScale {
+  bandwidth(): number;
   readonly domain: readonly string[];
-  readonly range: readonly [number, number];
+  gap(): number;
   map(value: string): number;
+  readonly range: readonly [number, number];
   ticks(count?: number): string[];
-  bandwidth(): number;
-  gap(): number;
 }
 
-interface LinearScaleConfig {
-  domain: [number, number];
-  range: [number, number];
+export interface LinearScaleConfig {
   clamp?: boolean;
+  domain: [number, number];
   nice?: boolean;
+  range: [number, number];
 }
 
-interface TimeScaleConfig {
+export interface TimeScaleConfig {
   domain: [Date, Date];
-  range: [number, number];
   nice?: boolean;
+  range: [number, number];
 }
 
-interface BandScaleConfig {
+export interface BandScaleConfig {
   domain: string[];
-  range: [number, number];
   padding?: number;
   paddingOuter?: number;
+  range: [number, number];
 }
 ```
 
----
-
-### Remaining unions and theme type
+### Axis and Interaction Types
 
 ```ts
-type BarVariant = 'grouped' | 'grouped-horizontal' | 'stacked' | 'stacked-horizontal';
-type PieVariant = 'donut' | 'pie' | 'semi';
-type SparklineVariant = 'area' | 'bar' | 'line' | 'stack';
+export type HorizontalAxisPosition = 'bottom' | 'top';
+export type VerticalAxisPosition = 'left' | 'right';
+export type AxisPosition = HorizontalAxisPosition | VerticalAxisPosition;
 
-interface PrismTheme {
-  axisColor?: string; // --prism-axis-color
-  colors?: string[];
-  fontFamily?: string;
-  gridColor?: string;
-  gridOpacity?: number;
-  textColor?: string; // --prism-text-color
-  textColorSecondary?: string; // --prism-text-color-secondary
-  tooltipBg?: string; // --prism-tooltip-bg
-  tooltipBorder?: string; // --prism-tooltip-border
-  tooltipColor?: string; // --prism-tooltip-color
+export interface GridConfig {
+  color?: string;
+  dash?: string;
 }
 
-interface ThemeScope {
-  readonly scope?: HTMLElement;
+export interface AxisConfig {
+  grid?: GridConfig | boolean;
+  label?: string;
+  position?: TPosition;
+  tickCount?: number;
+  tickFormat?: (value: Date | number | string) => string;
+  tickValues?: ReadonlyArray;
 }
-```
-
-## Errors
-
-### `PrismError`
-
-Base class for every Prism-originated error. It supports standard `ErrorOptions` cause chaining.
-
-### `PrismRenderError`
 
-Extends `PrismError`. Thrown for invalid containers, failed initial renders, and attempts to update disposed charts.
+export type XAxisConfig = AxisConfig;
+export type YAxisConfig = AxisConfig;
 
-### Usage Guide
-
-## Basic Usage
-
-Every chart needs a container element with defined dimensions and the theme CSS:
-
-```ts
-import { createLineChart } from '@vielzeug/prism';
-import '@vielzeug/prism/theme.css';
-
-const container = document.querySelector('#chart')!;
-const chart = createLineChart(container, {
-  series: [
-    {
-      name: 'Revenue',
-      data: [
-        { key: 1, value: 10 },
-        { key: 2, value: 16 },
-      ],
-    },
-  ],
-});
-
-chart.dispose();
-```
-
-```html
-
-```
-
-Prism observes the container size via `ResizeObserver` and re-renders automatically on resize. If the container has zero dimensions at mount time, a `warn` is emitted in development: ensure the container has layout before calling the chart factory.
-
-## Updating Data
-
-Chart factories render synchronously and return a typed handle. Call `update()` with the same data shape used by the factory when application state changes.
-
-```ts
-import { createLineChart } from '@vielzeug/prism';
-
-const chart = createLineChart(container, {
-  series: [{ data: [{ key: 1, value: 10 }], name: 'Live' }],
-});
-
-chart.update([
-  {
-    data: [
-      { key: 1, value: 10 },
-      { key: 2, value: 20 },
-    ],
-    name: 'Live',
-  },
-]);
-```
-
-`update()` is state-library neutral. Call it from a framework effect, store subscription, event handler, or request callback. It throws after the chart is disposed instead of silently retaining detached state.
-
-## Line Charts
-
-```ts
-import { createLineChart } from '@vielzeug/prism';
-
-const chart = createLineChart(container, {
-  series: [
-    {
-      name: 'Revenue',
-      data: [
-        { key: 1, value: 100 },
-        { key: 2, value: 150 },
-        { key: 3, value: 130 },
-      ],
-      color: '#3b82f6',
-      curve: 'monotone', // 'linear' | 'monotone' | 'step'
-      strokeWidth: 2,
-      showPoints: true,
-      pointRadius: 4,
-    },
-  ],
-  xAxis: { position: 'bottom' },
-  yAxis: { position: 'left', grid: true },
-  tooltip: true,
-  crosshair: true,
-});
-```
-
-### Multiple Series
-
-```ts
-const chart = createLineChart(container, {
-  series: [
-    { name: 'Revenue', data: revenueData, color: '#3b82f6' },
-    { name: 'Expenses', data: expenseData, color: '#ef4444' },
-  ],
-  xAxis: { position: 'bottom' },
-  yAxis: { position: 'left', grid: true },
-});
-```
-
-### Independent Value Axes
-
-Assign a line series to `yAxis: 'right'` when its values need a different range. Both axes share the same X scale, while tooltips retain the original values.
-
-```ts
-const chart = createLineChart(container, {
-  series: [
-    { name: 'Health', data: [{ key: 0, value: 30 }, { key: 1, value: 20 }] },
-    { name: 'Damage', yAxis: 'right', data: [{ key: 0, value: 0 }, { key: 1, value: 300 }] },
-  ],
-  yAxis: { label: 'Health' },
-  rightYAxis: { label: 'Damage' },
-  tooltip: true,
-});
-```
-
-The primary axis is on the left when right-axis series are present. Grid configuration belongs to the primary axis. Dual-axis curve crossings do not imply equal numeric values. Preserve each marker's axis assignment when calling `update()`.
-
-### Time-based X Axis
-
-When data points use `Date` objects for `key`, Prism automatically applies a time scale. The domain spans exactly the first to the last date, so the series fills the plot width:
-
-```ts
-const chart = createLineChart(container, {
-  series: [
-    {
-      name: 'Signups',
-      data: [
-        { key: new Date('2024-01-01'), value: 50 },
-        { key: new Date('2024-02-01'), value: 80 },
-        { key: new Date('2024-03-01'), value: 120 },
-      ],
-    },
-  ],
-  xAxis: { position: 'bottom', tickFormat: (d) => (d as Date).toLocaleDateString() },
-  yAxis: { position: 'left' },
-});
-```
+export interface TooltipConfig {
+  offset?: number;
+  render?: (datum: Datum, series: Series) => Node | string;
+  titleFormat?: (key: Date | number | string) => string;
+  valueFormat?: (value: number, datum: Datum, series: Series) => string;
+}
 
-## Bar Charts
+export interface CrosshairConfig {
+  horizontal?: boolean;
+  snap?: boolean;
+  vertical?: boolean;
+}
 
-```ts
-import { createBarChart } from '@vielzeug/prism';
+export type LegendPosition = 'bottom' | 'left' | 'right' | 'top';
 
-const chart = createBarChart(container, {
-  series: [
-    {
-      name: 'Sales',
-      data: [
-        { key: 'Q1', value: 200 },
-        { key: 'Q2', value: 350 },
-        { key: 'Q3', value: 280 },
-        { key: 'Q4', value: 400 },
-      ],
-      borderRadius: 4,
-    },
-  ],
-  xAxis: { position: 'bottom' },
-  yAxis: { position: 'left', grid: true },
-  tooltip: true,
-});
+export interface LegendConfig {
+  position?: LegendPosition;
+}
 ```
 
-### Variants
+The crosshair defaults to a vertical line that snaps to the nearest datum; the horizontal line is hidden by default. With `snap: false`, only the guide follows the pointer—tooltip and callback data still refer to the nearest datum.
 
-Select the bar layout with `variant`:
+`tickValues` renders exactly the given ticks instead of scale-generated ones, and gridlines follow the same list. Values must match the axis's scale kind (numbers on a linear axis, `Date`s on a time axis, category strings on a band axis); an off-scale value warns in development. Without it, ticks come from the scale as before.
 
-| Value                  | Layout                     |
-| ---------------------- | -------------------------- |
-| `'grouped'`            | Vertical grouped (default) |
-| `'stacked'`            | Vertical stacked           |
-| `'grouped-horizontal'` | Horizontal grouped         |
-| `'stacked-horizontal'` | Horizontal stacked         |
+Numeric tick labels at a magnitude of 1e5 or above default to compact notation (`123K`, `1.23M`) so long numbers fit the default value-axis margin; pass `tickFormat: String` for raw labels. Supplying a partial `yAxis` (or the value axis of a horizontal bar chart) merges over the default, so `{ tickFormat }` alone keeps the default grid lines.
 
-```ts
-const chart = createBarChart(container, {
-  variant: 'stacked',
-  series: [
-    { name: 'Mobile', data: mobileData, color: '#3b82f6', borderRadius: 0 },
-    { name: 'Desktop', data: desktopData, color: '#10b981', borderRadius: 0 },
-  ],
-  xAxis: { position: 'bottom' },
-  yAxis: { position: 'left', grid: true },
-  tooltip: true,
-  legend: true,
-});
-```
+`titleFormat` and `valueFormat` shape the default comparison tooltip on line, area, and bar charts—the title from the focused key and each row's value—and the same formatting is applied to the tooltip's spoken summary. `render` still replaces the whole tooltip body and takes precedence. Tooltip strings are assigned as text, not parsed as HTML. For a radar chart, `tooltip.render` receives a datum whose `meta` contains the active axis, all series values, and the default announcement text.
 
-For horizontal layouts, categories appear on the Y axis and values on the X axis:
+### Chart Configuration Types
 
 ```ts
-const chart = createBarChart(container, {
-  variant: 'grouped-horizontal',
-  series: [{ name: 'Revenue', data, color: '#3b82f6' }],
-  xAxis: { position: 'bottom', grid: true },
-  yAxis: { position: 'left' },
-});
-```
-
-### Grouped Bars
-
-Multiple series with `variant: 'grouped'` (default) render side-by-side:
-
-```ts
-const chart = createBarChart(container, {
-  series: [
-    { name: '2023', data: lastYearData, color: '#94a3b8' },
-    { name: '2024', data: thisYearData, color: '#3b82f6' },
-  ],
-});
-```
-
-## Area Charts
-
-Area fills use a vertical gradient that fades toward the baseline. Set `fill: 'solid'` for a flat fill:
+export interface BaseChartConfig {
+  a11y?: ChartA11y;
+  legend?: LegendConfig | boolean;
+  margin?: Partial;
+  onClick?: (event: ChartEvent) => void;
+  onHover?: (event: ChartEvent | null) => void;
+  tooltip?: TooltipConfig | boolean;
+  transition?: TransitionOption;
+  xAxis?: XAxisConfig | false;
+  yAxis?: YAxisConfig | false;
+}
 
-```ts
-import { createAreaChart } from '@vielzeug/prism';
+export interface LineSeriesConfig extends Series {
+  curve?: 'linear' | 'monotone' | 'step';
+  pointRadius?: number;
+  showPoints?: boolean;
+  strokeWidth?: number;
+  yAxis?: 'left' | 'right';
+}
 
-const chart = createAreaChart(container, {
-  series: [
-    {
-      name: 'Users',
-      data: userData,
-      curve: 'monotone',
-      fill: 'gradient', // 'gradient' (default) | 'solid'
-      showLine: true,
-    },
-  ],
-  xAxis: { position: 'bottom' },
-  yAxis: { position: 'left', grid: true },
-  crosshair: true,
-});
-```
+export interface LineChartConfig extends BaseChartConfig {
+  crosshair?: CrosshairConfig | boolean;
+  rightYAxis?: Omit;
+  series: LineSeriesConfig[];
+}
 
-`fillOpacity` overrides the theme opacity for one series.
+export interface AreaSeriesConfig extends Series {
+  curve?: 'linear' | 'monotone' | 'step';
+  fill?: 'gradient' | 'solid';
+  fillOpacity?: number;
+  showLine?: boolean;
+}
 
-## Forecast / emphasis styling
+export interface AreaChartConfig extends BaseChartConfig {
+  crosshair?: CrosshairConfig | boolean;
+  series: AreaSeriesConfig[];
+}
 
-A single series often mixes points that should look different — actuals plus a
-forecast tail, or a run that crossed a budget. Rather than split the series,
-carry `dash` and `opacity` on the individual datums. They are styling-only:
-tooltips, hover, keyboard, and screen-reader behavior never change.
+export interface ScatterSeriesConfig extends Series {
+  pointRadius?: number;
+}
 
-For a forecast tail, map a parallel `types` array onto the datums:
+export interface ScatterChartConfig extends BaseChartConfig {
+  crosshair?: CrosshairConfig | boolean;
+  series: ScatterSeriesConfig[];
+}
 
-```ts
-import { createLineChart } from '@vielzeug/prism';
+export interface BarSeriesConfig extends Series {
+  borderRadius?: number;
+}
 
-const types = ['REAL', 'REAL', 'FORECAST', 'FORECAST'];
+export type BarVariant = 'grouped' | 'grouped-horizontal' | 'stacked' | 'stacked-horizontal';
 
-const chart = createLineChart(container, {
-  series: [
-    {
-      name: 'Cost',
-      data: values.map((value, i) => ({
-        key: months[i],
-        value,
-        ...(types[i] === 'FORECAST' ? { dash: '5 5', opacity: 0.4 } : {}),
-      })),
-    },
-  ],
-});
-```
+export interface BarChartConfig extends BaseChartConfig {
+  series: BarSeriesConfig[];
+  variant?: BarVariant;
+}
 
-On a line chart, a datum's `dash` styles the segment from that point to the
-next, so the forecast run renders dashed while the actuals stay solid; its
-`opacity` fades that segment and the point marker. The last datum's `dash` has
-no segment to paint and is ignored. On a bar chart, both fields apply to that
-datum's own bar — a `dash` adds a 1px series-color stroke so the dash reads on
-the filled rect. On an area chart they style the top line only; the fill keeps
-its series-level treatment.
+export type PieVariant = 'donut' | 'pie' | 'semi';
 
-The same mapping fades bars:
+export interface PieSliceConfig {
+  color?: string;
+  label?: string;
+  value: number;
+}
 
-```ts
-import { createBarChart } from '@vielzeug/prism';
+export interface PieEvent {
+  index: number;
+  originalEvent: Event;
+  slice: PieSliceConfig;
+}
 
-const chart = createBarChart(container, {
-  series: [
-    {
-      name: 'Cost',
-      data: values.map((value, i) => ({
-        key: months[i],
-        value,
-        ...(types[i] === 'FORECAST' ? { dash: '5 5', opacity: 0.4 } : {}),
-      })),
-    },
-  ],
-});
-```
+export interface PieChartConfig extends Omit {
+  cornerRadius?: number;
+  data: PieSliceConfig[];
+  innerRadius?: number;
+  onClick?: (event: PieEvent) => void;
+  onHover?: (event: PieEvent | null) => void;
+  padPixels?: number;
+  variant?: PieVariant;
+}
 
-Because the fields live on the data, a normal `update(newSeries)` re-applies
-them; removing the fields on the next update clears the styling. A series with
-no `dash`/`opacity` anywhere renders exactly as it did before these fields
-existed.
+export interface RadarAxisConfig {
+  format?: (value: number) => string;
+  key: string;
+  label: string;
+  max?: number;
+  min?: number;
+}
 
-## Pie, Donut, and Semi-circle Charts
+export type RadarSeriesConfig = Series>;
 
-All three variants use `createPieChart` with the `variant` field:
+export interface RadarGridConfig {
+  bands?: boolean;
+  labels?: boolean;
+  levels?: number;
+  shape?: 'circle' | 'polygon';
+}
 
-```ts
-import { createPieChart } from '@vielzeug/prism';
+export interface RadarAxisValue {
+  datum: Datum | undefined;
+  series: RadarSeriesConfig;
+}
 
-const chart = createPieChart(container, {
-  data: [
-    { label: 'Direct', value: 42, color: '#3b82f6' },
-    { label: 'Organic', value: 28, color: '#10b981' },
-    { label: 'Referral', value: 18, color: '#f59e0b' },
-    { label: 'Social', value: 12, color: '#8b5cf6' },
-  ],
-  variant: 'donut', // 'pie' | 'donut' | 'semi'
-  tooltip: true,
-  transition: { duration: 400, easing: 'ease-out' },
-});
-```
+export interface RadarEvent {
+  axis: RadarAxisConfig;
+  index: number;
+  originalEvent: Event;
+  values: RadarAxisValue[];
+}
 
-### Variants
+export interface RadarChartConfig extends Omit {
+  axes: RadarAxisConfig[];
+  curve?: 'linear' | 'rounded';
+  domain?: [number, number];
+  fill?: 'gradient' | 'none' | 'solid';
+  grid?: RadarGridConfig | boolean;
+  onClick?: (event: RadarEvent) => void;
+  onHover?: (event: RadarEvent | null) => void;
+  series: RadarSeriesConfig[];
+  showPoints?: boolean;
+  showValues?: boolean;
+  startAngle?: number;
+}
 
-| Value     | Shape                                                   |
-| --------- | ------------------------------------------------------- |
-| `'pie'`   | Full circle, no hole                                    |
-| `'donut'` | Full circle with inner hole (~55% of outer by default)  |
-| `'semi'`  | Top-half semicircle with inner hole: useful for gauges |
+export type SparklineVariant = 'area' | 'bar' | 'line' | 'stack';
 
-### Inner Radius
+export interface StackSegment {
+  color?: string;
+  label?: string;
+  value: number;
+}
 
-`innerRadius` overrides the automatic calculation:
+export interface SparklineEvent {
+  index: number;
+  originalEvent: Event;
+  value: number;
+}
 
-```ts
-createPieChart(container, {
-  data,
-  variant: 'donut',
-  innerRadius: 60, // explicit pixels
-});
+export interface SparklineConfig {
+  a11y?: ChartA11y;
+  color?: string;
+  cornerRadius?: number;
+  curve?: 'linear' | 'monotone' | 'step';
+  data: number[] | StackSegment[];
+  fillOpacity?: number;
+  onClick?: (event: SparklineEvent) => void;
+  onHover?: (event: SparklineEvent | null) => void;
+  padPixels?: number;
+  showEndPoint?: boolean;
+  strokeWidth?: number;
+  transition?: TransitionOption;
+  variant?: SparklineVariant;
+}
 ```
 
-### Slice Labels
+## Errors
 
-Set `label` on each `PieSliceConfig` to render text at the arc centroid. A label that does not fit inside its slice is not drawn; the value stays available through the tooltip, legend, and keyboard announcements:
+### `PrismError`
 
 ```ts
-{ value: 42, label: 'Direct' }
-```
-
-Style labels via CSS:
-
-```css
-:root {
-  --prism-pie-label-color: #fff;
-  --prism-pie-label-size: 11px;
+class PrismError extends Error {
+  constructor(message: string, opts?: ErrorOptions);
 }
 ```
 
-### Updating Data
-
-```ts
-const chart = createPieChart(container, {
-  data: [
-    { label: 'A', value: 40 },
-    { label: 'B', value: 60 },
-  ],
-  variant: 'donut',
-});
-
-chart.update([
-  { label: 'A', value: 55 },
-  { label: 'B', value: 45 },
-]);
-```
+Base class for Prism-originated errors. Its `name` is set to the concrete error class name, and it supports the standard `ErrorOptions` including `cause`.
 
-### Event Hooks
+### `PrismRenderError`
 
 ```ts
-createPieChart(container, {
-  data,
-  onHover: (event) => {
-    // event is PieEvent | null (null on mouseleave)
-    if (event) console.log(event.index, event.slice.label, event.slice.value);
-  },
-  onClick: (event) => {
-    console.log('clicked', event.index, event.slice.label);
-  },
-});
+class PrismRenderError extends PrismError {}
 ```
 
-`PieEvent` provides `index`, the hovered/clicked `slice` (`PieSliceConfig`), and the `originalEvent` (`MouseEvent` or `KeyboardEvent`).
+Thrown when a chart cannot be rendered because its container is not a DOM element, when initial rendering fails (the original error is available as `cause`), or when `update()` is called after disposal. Empty or malformed chart data may instead produce a development warning or an empty rendering, depending on the chart.
 
-## Radar Charts
+### Usage Guide
 
-`createRadarChart` compares several values on one shape, such as a hero's stats. Each series supplies values keyed by `axis.key`:
+## Basic Usage
+
+Create a host element with non-zero dimensions, then pass it to a chart factory. This example creates the host in JavaScript so the snippet can run as written.
 
 ```ts
-import { createRadarChart } from '@vielzeug/prism';
+import { createLineChart } from '@vielzeug/prism';
+import '@vielzeug/prism/theme.css';
 
-const axes = [
-  { key: 'str', label: 'Strength' },
-  { key: 'agi', label: 'Agility' },
-  { key: 'int', label: 'Intellect' },
-  { key: 'end', label: 'Endurance' },
-  { key: 'spd', label: 'Speed', max: 5 },
-];
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-const chart = createRadarChart(container, {
-  a11y: { ariaLabel: 'Hero stats' },
-  axes,
-  domain: [0, 10],
-  fill: 'gradient',
-  showValues: true,
+const chart = createLineChart(container, {
+  a11y: { ariaLabel: 'Revenue by month' },
   series: [
     {
-      name: 'Adam',
+      name: 'Revenue',
       data: [
-        { key: 'str', value: 8 },
-        { key: 'agi', value: 6 },
-        { key: 'int', value: 4 },
-        { key: 'end', value: 9 },
-        { key: 'spd', value: 3 },
+        { key: 1, value: 10 },
+        { key: 2, value: 16 },
       ],
     },
   ],
+  tooltip: true,
 });
+
+chart.dispose();
 ```
 
-### Scales
+Each factory appends an SVG to its container and returns a `ChartHandle`. Prism observes the container with `ResizeObserver`; if it has zero dimensions on creation, Prism uses a temporary `600 × 300` size and warns in development. Give the host its layout before creating the chart.
 
-Every axis shares `domain` (or a nice range around the data when omitted). Give an axis its own `min`/`max` when its stat uses a different range: above, Speed runs 0 to 5 while the rest run 0 to 10, so each still fills the chart.
+## Updating Data
 
-### Appearance
+Keep application state outside Prism and pass the next complete data value to `update()`. The update method replaces chart data synchronously; the default transition may animate the resulting SVG.
 
-| Option | Values | Use it for |
-| --- | --- | --- |
-| `fill` | `'solid'`, `'gradient'`, `'none'` | `gradient` for a single hero; `solid` or `none` when overlaying several |
-| `curve` | `'linear'`, `'rounded'` | Rounded reads softer; linear keeps exact vertices |
-| `grid.shape` | `'polygon'`, `'circle'` | Polygon matches the axes; circle suits many axes |
-| `grid.levels` / `grid.bands` | number / boolean | Ring count and alternate shading |
-| `grid.labels` | boolean | Level values; drawn only when every axis shares one domain |
-| `showValues` | boolean | Value beside each vertex, formatted by `axis.format` |
+```ts
+import { createLineChart } from '@vielzeug/prism';
 
-### Comparing Series
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-Pass several series with `legend: true`. Hovering one shape dims the others, and hovering an axis reports every series' value on it:
+let series = [{ data: [{ key: 1, value: 10 }], name: 'Live' }];
+const chart = createLineChart(container, { series });
 
-```ts
-createRadarChart(container, {
-  axes,
-  legend: true,
-  series: [adam, eve],
-  tooltip: true, // "Agility: Adam 6, Eve 9"
-  onHover: (event) => event && console.log(event.axis.label, event.values),
-});
+series = [{ data: [{ key: 1, value: 10 }, { key: 2, value: 20 }], name: 'Live' }];
+chart.update(series);
+chart.dispose();
 ```
 
-## Sparklines
+`update()` accepts the type shown by that factory's handle: a complete series array for line, area, scatter, bar, and radar charts; a slice array for pie charts; and a number or stack-segment array for sparklines. Chart options such as axes, variant, callbacks, and accessibility are set at creation. For example, radar axes and a pie chart's variant do not change through `update()`.
+
+## Line Charts
 
-Sparklines are minimal inline charts with no axes, no legend, and no margin: designed to live inline with text or inside table cells.
+Line and area series use number or `Date` keys. All series in one chart must use the same key kind. Use `curve` to choose interpolation, and enable markers with `showPoints`.
 
 ```ts
-import { createSparkline } from '@vielzeug/prism';
+import { createLineChart } from '@vielzeug/prism';
 
-const spark = createSparkline(container, {
-  data: [12, 18, 14, 22, 19, 28],
-  variant: 'line', // 'line' | 'area' | 'bar' | 'stack' (default: 'line')
-  color: '#3b82f6',
-  curve: 'monotone',
-  strokeWidth: 1.5,
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
+
+const chart = createLineChart(container, {
+  a11y: { ariaLabel: 'Revenue and expenses' },
+  series: [
+    {
+      curve: 'monotone',
+      data: [{ key: 1, value: 100 }, { key: 2, value: 150 }, { key: 3, value: 130 }],
+      name: 'Revenue',
+      showPoints: true,
+    },
+    {
+      color: '#c2410c',
+      data: [{ key: 1, value: 70 }, { key: 2, value: 95 }, { key: 3, value: 110 }],
+      name: 'Expenses',
+    },
+  ],
+  tooltip: true,
+  xAxis: { label: 'Month' },
+  yAxis: { grid: true, label: 'Dollars' },
 });
 
-spark.dispose();
+chart.dispose();
 ```
 
-### Variants
+### Independent Value Axes
 
-- **`line`**: simple polyline path (default)
-- **`area`**: gradient-filled area + line overlay
-- **`bar`**: vertical bar for each data point
-- **`stack`**: horizontal proportional segments; use `StackSegment[]` for `data` with per-segment colors
+Assign a line series to the right axis when it uses a different value range. Both axes share the x-scale; `rightYAxis` configures the second axis and cannot configure its position or grid.
 
-Line and area sparklines mark the latest value with a dot. Set `showEndPoint: false` to hide it.
+```ts
+import { createLineChart } from '@vielzeug/prism';
 
-### Updating Data
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-```ts
-const spark = createSparkline(container, {
-  data: [12, 18, 14, 22],
-  variant: 'area',
+const chart = createLineChart(container, {
+  a11y: { ariaLabel: 'Health and damage by level' },
+  rightYAxis: { label: 'Damage' },
+  series: [
+    { data: [{ key: 1, value: 30 }, { key: 2, value: 20 }], name: 'Health' },
+    { data: [{ key: 1, value: 100 }, { key: 2, value: 300 }], name: 'Damage', yAxis: 'right' },
+  ],
+  yAxis: { grid: true, label: 'Health' },
 });
 
-spark.update([12, 18, 14, 22, 30]);
+chart.dispose();
 ```
 
-### Event Hooks
+When any series uses the right axis, the primary value axis is placed on the left. Grid lines belong to the primary `yAxis`. The independent numeric scales mean that curve crossings do not imply equal values.
+
+### Time-Based X Axis
 
-Sparklines use simplified hooks: `SparklineEvent` rather than full `ChartEvent`. With a hook set, a marker follows the hovered value:
+Use `Date` values for every key when plotting time. Line and area charts use a time scale whose domain fits the data instead of rounding outward to tick boundaries.
 
 ```ts
-const spark = createSparkline(container, {
-  data: [10, 20, 30],
-  onHover: (event) => {
-    // event is SparklineEvent | null (null on mouseleave)
-    if (event) console.log(`Hovering point ${event.index}: ${event.value}`);
-  },
-  onClick: (event) => {
-    console.log(`Clicked point ${event.index}: ${event.value}`);
-  },
-});
-```
+import { createLineChart } from '@vielzeug/prism';
 
-`SparklineEvent` provides `index`, the hovered/clicked `value`, and the `originalEvent`.
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-> **Note:** Sparklines have no keyboard navigation. Label one with `a11y.ariaLabel` only when the trend carries meaning, and state the key value in surrounding text.
+const formatter = new Intl.DateTimeFormat(undefined, { month: 'short', day: 'numeric' });
+const chart = createLineChart(container, {
+  a11y: { ariaLabel: 'Signups over time' },
+  series: [{
+    data: [
+      { key: new Date('2026-09-01'), value: 50 },
+      { key: new Date('2026-09-08'), value: 80 },
+      { key: new Date('2026-09-15'), value: 120 },
+    ],
+    name: 'Signups',
+  }],
+  xAxis: { tickFormat: (value) => value instanceof Date ? formatter.format(value) : String(value) },
+});
 
-## Axes and Grid
+chart.dispose();
+```
 
-Both axes render by default: the value axis (y on vertical charts, x on horizontal ones) carries gridlines, the category axis does not. Set `xAxis: false` or `yAxis: false` to suppress one. An explicit config is used verbatim:
+`tickFormat` formats axis labels only. Tooltip content and accessibility announcements use the underlying keys and values. To render an exact set of ticks instead of scale-generated ones, pass `tickValues`; gridlines follow the same list. Values must match the axis's scale kind, and an off-scale value warns in development:
 
 ```ts
-{
-  xAxis: {
-    position: 'bottom',          // 'top' | 'bottom'
-    tickCount: 5,
-    tickFormat: (v) => `$${v}`,
-    label: 'Month',
-    grid: true,                  // or { color: '#ddd', dash: '4 2' }
-  },
-  yAxis: {
-    position: 'left',            // 'left' | 'right'
-    grid: { color: '#f0f0f0' },
-    label: 'Revenue ($)',
-  },
-}
+// Force a tick on the last month, which nice-stepped ticks can skip.
+const chart = createLineChart(container, {
+  series: [{ data: [{ key: 0, value: 90 }, { key: 11, value: 128 }], name: 'Costs' }],
+  xAxis: { tickValues: [0, 6, 11] },
+});
 ```
 
-Category axes show every label when the labels fit and thin them out only when they would overlap. Set `tickCount` to choose the density yourself.
+Numeric tick labels at a magnitude of `1e5` or above default to compact notation (`123K`, `1.23M`) so long numbers fit the default value-axis margin; pass `tickFormat: String` for raw labels. Supplying a partial value-axis config merges over its default, so `yAxis: { tickFormat }` alone keeps the default grid lines.
 
-## Tooltips
+## Bar Charts
 
-Enable with `tooltip: true`. On line, area, bar, and radar charts the default tooltip compares every series at the active key: a title, then a colour swatch, name, and value per series. Provide a custom `render` function to replace it. Strings are rendered as text. Return a DOM node for structured content:
+Bar chart keys are string categories. The default `grouped` variant puts series side by side; the horizontal variants put categories on the y-axis and values on the x-axis.
 
 ```ts
-{
-  tooltip: {
-    offset: 12,
-    render: (datum, series) => {
-      const content = document.createElement('strong');
-      content.textContent = `${series.name}: ${datum.value.toLocaleString()}`;
-      return content;
-    },
-  },
-}
+import { createBarChart } from '@vielzeug/prism';
+
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
+
+const chart = createBarChart(container, {
+  a11y: { ariaLabel: 'Sales by quarter' },
+  series: [{
+    data: [{ key: 'Q1', value: 200 }, { key: 'Q2', value: 350 }, { key: 'Q3', value: 280 }],
+    name: 'Sales',
+  }],
+  tooltip: true,
+});
+
+chart.dispose();
 ```
 
-Prism never injects tooltip strings as HTML, so custom rendering does not require a sanitizer.
+Choose `grouped`, `stacked`, `grouped-horizontal`, or `stacked-horizontal` in `variant`. Negative values in a stacked chart are clamped to zero and produce a development warning. Bars in stacked variants remain square; `borderRadius` applies to grouped bars.
 
-The tooltip element is scoped inside the chart container (not `document.body`) and is removed automatically on `dispose()`.
+Axes render by default, with grid lines on the value axis. For horizontal variants, `xAxis` is the value axis and `yAxis` is the category axis. Configure `grid` on the value axis.
 
-## Crosshair
+## Area Charts
 
-A vertical guide that snaps to the nearest data point:
+Area series use a gradient fill by default. Set `fill: 'solid'` for a flat fill, or set `fillOpacity` to override the theme opacity for that series.
 
 ```ts
-{
+import { createAreaChart } from '@vielzeug/prism';
+
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
+
+const chart = createAreaChart(container, {
+  a11y: { ariaLabel: 'Visitors over time' },
   crosshair: true,
-  // or configure:
-  crosshair: { vertical: true, horizontal: true, snap: true },
-}
+  series: [{
+    curve: 'monotone',
+    data: [{ key: 1, value: 12 }, { key: 2, value: 18 }, { key: 3, value: 15 }],
+    fill: 'solid',
+    fillOpacity: 0.2,
+    name: 'Visitors',
+    showLine: true,
+  }],
+});
+
+chart.dispose();
 ```
 
-## Legend
+## Scatter Charts
 
-Enable with `legend: true` (defaults to `bottom`) or configure position:
+Scatter charts treat every datum as an independent point: `key` is the numeric or `Date` x-value and `value` is the y-value. The scales fit the observed values rather than forcing the y-domain to include zero. Set `pointRadius` on a series to change its marker size (default `3`).
 
 ```ts
-{
-  legend: true,
-  // or:
-  legend: { position: 'top' },  // 'top' | 'bottom' | 'left' | 'right'
-}
-```
+import { createScatterChart } from '@vielzeug/prism';
 
-The legend renders as a `div` placed outside the SVG. Each item shows a color swatch and the series `name`. Customize via CSS:
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-```css
-:root {
-  --prism-legend-gap: 1rem;
-  --prism-legend-dot-size: 0.5rem;
-  --prism-legend-font-size: 0.75rem;
-}
+const chart = createScatterChart(container, {
+  a11y: { ariaLabel: 'Height against weight' },
+  series: [{
+    data: [{ key: 160, value: 55 }, { key: 175, value: 70 }, { key: 190, value: 88 }],
+    name: 'Cohort A',
+    pointRadius: 5,
+  }],
+  tooltip: true,
+});
+
+chart.dispose();
 ```
 
-## Event Hooks
+Scatter callbacks identify the nearest point in two dimensions and do not provide cross-series `values`, because points do not share a category key. Keyboard navigation visits every point across series in x order. With a tooltip, `titleFormat` formats the x-value and `valueFormat` the y-value, in both the visible row and the spoken summary.
+
+## Forecast and Emphasis Styling
 
-All charts expose `onClick` and `onHover` callbacks on the config:
+Add `dash` or `opacity` to individual `Datum` objects when one part of a series needs distinct styling. These fields do not change interaction, tooltip, or accessibility behavior.
 
 ```ts
+import { createLineChart } from '@vielzeug/prism';
+
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
+
+const values = [10, 13, 15, 18];
 const chart = createLineChart(container, {
-  series: [{ name: 'Revenue', data }],
-  onHover: (event) => {
-    // event is ChartEvent | null (null on mouseleave)
-    if (event) console.log(event.datum, event.series);
-  },
-  onClick: (event) => {
-    console.log('clicked', event.datum);
-  },
+  series: [{
+    data: values.map((value, index) => ({
+      key: index + 1,
+      value,
+      ...(index >= 2 ? { dash: '5 5', opacity: 0.4 } : {}),
+    })),
+    name: 'Forecast',
+    showPoints: true,
+  }],
 });
-```
 
-`ChartEvent` provides:
+chart.dispose();
+```
 
-- `datum`: the datum of the series nearest the pointer
-- `series`: the corresponding `Series` config
-- `values`: every series at the same key (line, area, and bar charts)
-- `originalEvent`: the raw `MouseEvent` or, for keyboard navigation, `KeyboardEvent`
+For line and area charts, each datum's `dash` styles the segment from that datum to the next; the final datum has no outgoing segment. Line opacity also fades the datum's marker. Area styling affects the top line, not the fill. Bar opacity and dashes apply to the individual bar; scatter opacity applies to its point and scatter dashes are ignored. Pie, radar, and sparkline ignore these two fields.
 
-> **Pie, radar, and sparkline events differ**: pie hooks receive a `PieEvent` (`index`, `slice`, `originalEvent`), sparkline hooks a `SparklineEvent` (`index`, `value`, `originalEvent`), and radar hooks a `RadarEvent` describing an axis. See [`PieChartConfig`](./api.md#chart-configurations) and [`createRadarChart()`](./api.md#createradarchart).
+## Pie, Donut, and Semi Charts
 
-## Animations
+Use `createPieChart()` for all three shapes. `variant` is fixed when the chart is created; `update()` replaces the slice data.
 
-Every chart animates by default: bars grow from the baseline, line and area
-series rise out of the plot, pie slices sweep in and then morph between values,
-radar polygons reshape, and sparklines tween. Motion runs through one
-`requestAnimationFrame` loop and is skipped when the user prefers reduced motion
-(`preference: 'system'`, the default).
+```ts
+import { createPieChart } from '@vielzeug/prism';
 
-Tune it with `transition`, or turn it off entirely:
+const container = document.createElement('div');
+container.style.cssText = 'width:320px;height:240px';
+document.body.append(container);
 
-```ts
-{
-  transition: {
-    duration: 400,
-    easing: 'ease-out',
-    stagger: 30,  // ms delay between bars (bar charts) or series (radar charts)
-  },
-}
-```
+const chart = createPieChart(container, {
+  a11y: { ariaLabel: 'Orders by channel' },
+  data: [
+    { label: 'Direct', value: 42 },
+    { label: 'Organic', value: 28 },
+    { label: 'Referral', value: 18 },
+    { label: 'Social', value: 12 },
+  ],
+  legend: true,
+  tooltip: true,
+  variant: 'donut',
+});
 
-```ts
-{ transition: false }  // every update renders synchronously
-{ transition: true }   // the defaults, stated explicitly
+chart.dispose();
 ```
 
-Named easings are `'linear'`, `'ease-in'`, `'ease-out'`, `'ease-in-out'`,
-`'expo-out'` (a hard decelerate), and `'back-out'` (a small overshoot); pass a
-`(t: number) => number` for anything else. `stagger` applies to bar-chart bars
-and radar-chart series and is ignored elsewhere — bar charts cap the total
-staggered delay near 400 ms so a long category axis still finishes promptly.
+The `pie` default has no inner radius. `donut` and `semi` default to an inner radius of 55% of the outer radius. `innerRadius` overrides that size in pixels. Slice labels are omitted when they do not fit; keep a tooltip or legend when small slices need identifying.
 
-## Theming
+## Radar Charts
 
-Import the default theme:
+Define at least three axes when creating a radar chart. Series data uses string keys that match `RadarAxisConfig.key`; `update()` replaces series but keeps axes and other configuration fixed.
 
 ```ts
-import '@vielzeug/prism/theme.css';
-```
-
-### Programmatic Theme with `setTheme`
-
-Call `setTheme` once at app startup to apply custom tokens programmatically:
+import { createRadarChart } from '@vielzeug/prism';
 
-```ts
-import { setTheme } from '@vielzeug/prism';
+const container = document.createElement('div');
+container.style.cssText = 'width:400px;height:320px';
+document.body.append(container);
 
-setTheme({
-  axisColor: '#94a3b8', // sets --prism-axis-color
-  colors: ['#6366f1', '#22d3ee', '#f59e0b', '#10b981'], // replaces --prism-color-1 through -4
-  fontFamily: 'Inter, system-ui, sans-serif', // sets --prism-font-family
-  gridColor: '#e2e8f0', // sets --prism-grid-color
-  gridOpacity: 0.6, // sets --prism-grid-opacity
-  textColor: '#0f172a', // sets --prism-text-color
-  tooltipBg: '#0f172a', // sets --prism-tooltip-bg
+const axes = [
+  { key: 'strength', label: 'Strength' },
+  { key: 'agility', label: 'Agility' },
+  { key: 'endurance', label: 'Endurance' },
+];
+const chart = createRadarChart(container, {
+  a11y: { ariaLabel: 'Hero stats' },
+  axes,
+  domain: [0, 10],
+  series: [{
+    data: [{ key: 'strength', value: 8 }, { key: 'agility', value: 6 }, { key: 'endurance', value: 9 }],
+    name: 'Adam',
+  }],
+  tooltip: true,
 });
-```
-
-`setTheme` writes inline custom properties, so it takes precedence over stylesheet defaults. Call `resetTheme()` to clear every custom property `setTheme` can set and restore the default theme: useful for a theme-switcher's "reset" action or test teardown:
 
-```ts
-import { resetTheme } from '@vielzeug/prism';
-
-resetTheme();
+chart.dispose();
 ```
 
-### Theming One Subtree (component libraries)
-
-Pass `scope` to write the tokens onto one element instead of `document.documentElement`. Charts render inside it, so their `var(--prism-*)` lookups resolve against the scoped values without touching `:root` — the hook for apps whose theme lives in a JS palette object (MUI, Chakra, Backstage):
+The default shared domain starts at zero and uses a nice maximum; set `domain` to compare series on a fixed range. Per-axis `min` and `max` override the chart domain for that axis. Grid rings, bands, curves, fills, vertex dots, and values are configurable; see `RadarChartConfig` and `RadarGridConfig` in the API reference.
 
-```tsx
-import { useEffect, useRef } from 'react';
-import { useTheme } from '@mui/material/styles';
-import { createBarChart, resetTheme, setTheme, type BarSeriesConfig } from '@vielzeug/prism';
-import '@vielzeug/prism/theme.css';
+## Sparklines
 
-function CostsChart({ series }: { series: BarSeriesConfig[] }) {
-  const theme = useTheme();
-  const containerRef = useRef(null);
+Sparklines omit axes, margins, and legends. Choose `line`, `area`, or `bar` for numeric arrays, and `stack` for an array of `StackSegment` objects.
 
-  useEffect(() => {
-    const scope = containerRef.current;
+```ts
+import { createSparkline } from '@vielzeug/prism';
 
-    if (!scope) return;
+const container = document.createElement('div');
+container.style.cssText = 'width:240px;height:48px';
+document.body.append(container);
 
-    // Scoped tokens win over :root inside this subtree and never leak out of it.
-    setTheme(
-      { axisColor: theme.palette.divider, textColor: theme.palette.text.primary },
-      { scope },
-    );
+const chart = createSparkline(container, {
+  a11y: { ariaLabel: 'Weekly orders' },
+  data: [10, 14, 12, 18, 22],
+  variant: 'area',
+});
 
-    const chart = createBarChart(scope, { series });
+chart.update([10, 14, 12, 18, 22, 25]);
+chart.dispose();
+```
 
-    return () => {
-      chart.dispose();
-      resetTheme({ scope });
-    };
-  }, [series, theme]);
+For a stacked sparkline, each segment can set `value`, `color`, and `label`. Sparklines do not offer keyboard navigation, a tooltip, or a live value announcer. Add a visible value or summary when the trend conveys important information.
 
-  return ;
-}
-```
+## Interaction
 
-A scoped call and a global call are independent: `resetTheme({ scope })` clears only what `setTheme({ scope })` wrote.
+Set `tooltip: true` to show Prism's default tooltip, or pass a `TooltipConfig` to format its content. `titleFormat` and `valueFormat` shape the default comparison tooltip on line, area, and bar charts—the title from the focused key and each row's value—without rebuilding its markup, and the same formatting is applied to the tooltip's spoken summary. A `render` callback receives the active `Datum` and `Series` and replaces the whole body, taking precedence over the formatters. Returned strings are inserted as text; return a DOM `Node` for structured content.
 
-### Custom Theme (CSS)
+```ts
+import { createLineChart } from '@vielzeug/prism';
 
-```css
-:root {
-  --prism-color-1: #6366f1;
-  --prism-color-2: #22c55e;
-  --prism-axis-color: #71717a;
-  --prism-grid-color: #f4f4f5;
-  --prism-text-color: #18181b;
-  --prism-tooltip-bg: #27272a;
-  --prism-font-family: 'Inter', system-ui, sans-serif;
-}
-```
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-### Scoped Themes
+const compact = new Intl.NumberFormat(undefined, { notation: 'compact' });
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 
-Apply tokens to a specific container:
+const chart = createLineChart(container, {
+  series: [{ data: [{ key: 11, value: 128000 }], name: 'EC2' }],
+  tooltip: {
+    titleFormat: (key) => months[Number(key)] ?? String(key),
+    valueFormat: (value) => compact.format(value),
+  },
+});
 
-```css
-.dark-dashboard {
-  --prism-axis-color: #64748b;
-  --prism-grid-color: #334155;
-  --prism-text-color: #e2e8f0;
-}
+chart.dispose();
 ```
 
-### Available Tokens
-
-| Token                     | Default                    | Description            |
-| ------------------------- | -------------------------- | ---------------------- |
-| `--prism-color-{1-8}`     | Colorblind-safe palette    | Series color palette   |
-| `--prism-bg`              | `transparent`              | Chart background       |
-| `--prism-axis-color`      | `hsl(215deg 16% 47%)`      | Axis lines and ticks   |
-| `--prism-grid-color`      | `hsl(220deg 10% 75%)`      | Grid lines             |
-| `--prism-text-color`      | `hsl(215deg 25% 27%)`      | Axis labels and text   |
-| `--prism-font-family`     | `system-ui`                | Chart font             |
-| `--prism-font-size`       | `0.75rem`                  | Label font size        |
-| `--prism-tooltip-bg`      | `hsl(222deg 47% 11%)`      | Tooltip background     |
-| `--prism-tooltip-color`   | `hsl(210deg 40% 98%)`      | Tooltip text           |
-| `--prism-tooltip-radius`  | `0.375rem`                 | Tooltip border radius  |
-| `--prism-crosshair-color` | `hsl(215deg 16% 47%)`      | Crosshair line         |
-| `--prism-crosshair-dash`  | `4 2`                      | Crosshair dash pattern |
-
-The palette follows Wong (2011) so adjacent series stay distinguishable under common color-vision deficiencies. Dark mode applies through `prefers-color-scheme`, an `html.dark` class, or `data-prism-theme="dark"` on the chart container or any ancestor — the last is the hook for apps that switch theme in JS without owning ``.
-
-Radar charts add their own tokens, each defaulting to a shared one:
-
-| Token | Default | Description |
-| --- | --- | --- |
-| `--prism-radar-grid-color` | `--prism-grid-color` | Rings |
-| `--prism-radar-grid-opacity` | `0.7` | Ring and spoke opacity |
-| `--prism-radar-band-fill` | `--prism-grid-color` | Alternate ring shading |
-| `--prism-radar-band-opacity` | `0.14` | Shading opacity |
-| `--prism-radar-spoke-color` | `--prism-radar-grid-color` | Spokes |
-| `--prism-radar-fill-opacity` | `--prism-area-opacity` | Solid shape fill |
-| `--prism-radar-stroke-width` | `--prism-line-width` | Shape outline |
-| `--prism-radar-point-radius` | `--prism-point-radius` | Vertex dots |
-| `--prism-radar-point-radius-active` | `--prism-point-radius-hover` | Dots on the active axis |
-| `--prism-radar-label-color` / `-size` | Secondary text tokens | Axis labels |
-| `--prism-radar-value-color` / `-size` | Text tokens | Vertex values |
-| `--prism-radar-dim-opacity` | `--prism-dim-opacity` | Other shapes while one is hovered |
-
-Shared interaction and chart tokens:
-
-| Token | Default | Description |
-| --- | --- | --- |
-| `--prism-dim-opacity` | `0.35` | Series or slices outside the active one |
-| `--prism-active-point-radius` | `--prism-point-radius-hover` | Points marked at the active key |
-| `--prism-point-ring` | `Canvas` | Ring separating active and end points from the line |
-| `--prism-focus-color` | `--prism-color-1` | Focus outline of a keyboard-focused chart |
-| `--prism-bar-radius` | `4px` | Bar corner radius (stacked bars stay square) |
-| `--prism-bar-band-fill` / `-opacity` | Grid colour / `0.18` | Shaded active category |
-| `--prism-bar-dim-opacity` | `0.55` | Bars outside the active category |
-| `--prism-area-gradient-start` / `-end` | `0.45` / `0.02` | Gradient fill opacity at the line and the baseline |
-| `--prism-spark-gradient-start` / `-end` | `0.35` / `0` | Sparkline gradient fill |
+`onHover` receives an event while a point, category, slice, or radar axis is active, then `null` when the interaction clears. `onClick` receives the selected event. For line, area, and bar charts, `ChartEvent.values` contains each series' datum at that shared key; a missing datum is `undefined`. Scatter events are `ChartEvent` objects without `values`; pie, radar, and sparkline use their chart-specific event types.
 
-Explicit config such as `strokeWidth`, `fillOpacity`, or `borderRadius` always wins over these tokens.
+`crosshair` is available on line, area, and scatter charts. By default it shows a vertical guide and snaps the line to the nearest datum. Set `horizontal: true` to add a horizontal guide or `vertical: false` to hide the vertical one. Set `snap: false` to make the guide follow the pointer; tooltip and callback data still come from the nearest datum.
 
-## Scales (Standalone)
+### Keyboard and Announcements
 
-Scales can be used independently for custom visualizations:
+Set `a11y: { ariaLabel }` on an informative chart. Prism gives the SVG `role="img"`, an accessible name, and keyboard focus. Arrow keys move among chart data; `Home` and `End` move to the first and last item where supported; `Enter` or `Space` activates an item when an `onClick` callback is configured; `Escape` clears the active selection. Sparklines do not support keyboard navigation.
 
-```ts
-import { linearScale, timeScale, bandScale } from '@vielzeug/prism';
+When `a11y` is omitted, or set to `{ decorative: true }`, the SVG is marked `aria-hidden="true"` and does not enter the keyboard tab order. Only mark charts decorative when their information is available elsewhere. Interactive cartesian and pie/radar charts use the tooltip as a polite live region when enabled; otherwise they announce active values in `.prism-live`. Sparklines have no live value announcements, so provide an equivalent visible value or summary.
 
-const y = linearScale({ domain: [0, 100], range: [300, 0] });
-y.map(50); // → 150
-y.invert(150); // → 50
-y.ticks(5); // → [0, 20, 40, 60, 80, 100]
+## Animation
 
-const x = bandScale({ domain: ['A', 'B', 'C'], range: [0, 300] });
-x.map('B'); // → pixel left edge of band B
-x.bandwidth(); // → width of each band
-```
+Chart motion is enabled by default, with a 300 ms duration per animated lane (radar uses 400 ms). Pass `transition: false` to render updates synchronously, or pass `true` to state the default explicitly.
 
-## Lifecycle and Cleanup
+```ts
+import { createBarChart } from '@vielzeug/prism';
 
-Every chart returns a `ChartHandle`. Always call `dispose()` when removing a chart:
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
 
-```ts
-const chart = createLineChart(container, config);
+const chart = createBarChart(container, {
+  series: [{ data: [{ key: 'A', value: 4 }, { key: 'B', value: 7 }], name: 'Count' }],
+  transition: { duration: 500, easing: 'ease-out', preference: 'system' },
+});
 
-// When done:
 chart.dispose();
-
-// Or with TC39 explicit resource management:
-{
-  using chart = createLineChart(container, config);
-  // auto-disposed at block end
-}
 ```
 
-Calling `dispose()`:
-
-- Cancels in-flight transitions
-- Disconnects the `ResizeObserver`
-- Removes the SVG element, tooltip, and legend from the DOM
-- Restores container styles changed for tooltip positioning
-- Is idempotent: safe to call multiple times
+Columns grow together from their baseline by default over 300 ms. Lines trace their final curve over 420 ms, uncovering point markers along the way without fading or shifting the series. Line data updates retain the default 300 ms geometry transition; an explicit `duration` overrides both timings.
 
-Call `update()` only while the handle is active. Updating a disposed chart throws `PrismRenderError`.
+`preference: 'system'` (the default) disables JavaScript motion when the user prefers reduced motion. Use `'always'` to ignore that preference or `'never'` to disable motion. `stagger` sets an optional delay between bars, entering scatter points (in x order), or radar series; bar and scatter charts cap the effective delay so many marks do not add unbounded time. Named easing values are `ease-in`, `ease-in-out`, `ease-out`, `back-out`, `expo-out`, and `linear`; you can also provide an easing function.
 
-## Responsive Behavior
+## Responsive Layout and Lifecycle
 
-Charts resize automatically when the container dimensions change. Prism uses `ResizeObserver` internally: no manual `resize()` call is needed.
+Size the host with CSS. Prism observes its content box and updates the SVG dimensions and chart layout when it changes. Bar, line, and scatter resize redraws apply immediately rather than animating between layout sizes; entrance animations and explicit data-update transitions remain enabled. The legend is rendered as container chrome outside the SVG and included in resize calculations.
 
-## Runtime Observation
+Call `dispose()` when the view no longer owns the chart. Disposal is idempotent: it removes the SVG, tooltip, legend, and resize observation, stops in-flight chart motion, and aborts `disposalSignal`. `chart[Symbol.dispose]()` calls the same cleanup method.
 
-Every handle exposes `tap()` to observe runtime behavior — resize and dispose — outside the render path. It reuses the chart's own `ResizeObserver`, so observing costs nothing extra, and handler errors are swallowed: observation never affects chart behavior.
+Use `tap()` when external code needs resize or dispose notifications rather than observing the chart DOM itself:
 
 ```ts
 import { createLineChart } from '@vielzeug/prism';
 
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
+
 const chart = createLineChart(container, {
   series: [{ data: [{ key: 1, value: 10 }], name: 'Revenue' }],
 });
-const controller = new AbortController();
-const unsubscribe = chart.tap(
-  (event) => {
-    if (event.type === 'resize') console.log('resized', event.width, event.height);
-    if (event.type === 'dispose') console.log('disposed');
-  },
-  { signal: controller.signal },
-);
+const stopObserving = chart.tap((event) => {
+  if (event.type === 'resize') console.log(event.width, event.height);
+  if (event.type === 'dispose') console.log('chart disposed');
+});
+
+stopObserving();
+chart.dispose();
 ```
 
-`tap()` returns an unsubscribe function; pass `options.signal` to detach automatically instead. The `resize` event carries the new `width`/`height` and fires after the chart re-laid-out; `dispose` fires once, before teardown completes. Tapping a disposed handle returns a no-op unsubscribe. This is separate from prism's internal validation warnings, which run automatically in development and are never part of the public API.
+`tap()` returns an unsubscribe function and accepts `{ signal }` for automatic unsubscription. A listener exception is swallowed by the observer so it cannot interrupt chart rendering.
 
-## Accessibility
+## Theming
 
-Label informative charts with `a11y: { ariaLabel }`. A labelled chart renders with `role="img"`, is focusable, and supports keyboard navigation. Charts without `a11y` are decorative and render with `aria-hidden="true"`.
+Import the stylesheet once to load Prism's structural styles, default tokens, dark-mode rules, and reduced-motion CSS. You can override any CSS custom property on an ancestor of the chart.
 
-```ts
-createLineChart(container, {
-  a11y: { ariaLabel: 'Revenue by month' },
-  series: [...],
-});
+```css
+.dashboard-chart {
+  --prism-color-1: #2563eb;
+  --prism-color-2: #16a34a;
+  --prism-grid-color: #94a3b8;
+  --prism-line-width: 3;
+  --prism-text-color: #172033;
+  --prism-tooltip-bg: #111827;
+}
 ```
 
-Mark a chart decorative explicitly when surrounding text already states its meaning:
+`setTheme()` provides a typed subset of theme properties. A scoped call writes inline values on the provided element; omit `scope` to write them to `document.documentElement`. Inline values override stylesheet tokens until reset.
 
 ```ts
-createSparkline(container, {
-  a11y: { decorative: true },
-  data: [...],
-});
+import { resetTheme, setTheme } from '@vielzeug/prism';
+
+const container = document.createElement('div');
+container.style.cssText = 'width:640px;height:320px';
+document.body.append(container);
+
+setTheme({ colors: ['#2563eb', '#16a34a'], fontFamily: 'Inter, sans-serif' }, { scope: container });
+// Call resetTheme({ scope: container }) when this scoped theme is no longer needed.
+resetTheme({ scope: container });
 ```
 
-### Keyboard and announcements
+### Available Tokens
 
-Every labelled chart except sparklines shares one keyboard model:
+The stylesheet defines defaults for the following token groups. Pie-label color and size are read with fallback values by the renderer but are not declared in the base token block. Set a token on the chart container or an ancestor to scope an override.
 
-| Chart | Arrow keys move between | `Home` / `End` | Announced |
-| --- | --- | --- | --- |
-| Line, area | x positions | First / last position | `1: Adam 3, Eve 6` |
-| Bar | categories | First / last category | `Str: Adam 8, Eve 5` |
-| Pie | slices | First / last slice | `Wins: 15 (75%)` |
-| Radar | axes (wrapping) | Not supported | `Agility: Adam 6, Eve 9` |
+| Group | CSS custom properties |
+| --- | --- |
+| Palette and surfaces | `--prism-color-1` through `--prism-color-8`, `--prism-bg`, `--prism-border-radius` |
+| Axes and grid | `--prism-axis-color`, `--prism-axis-width`, `--prism-grid-color`, `--prism-grid-width`, `--prism-grid-dash`, `--prism-grid-opacity` |
+| Text | `--prism-font-family`, `--prism-font-size`, `--prism-font-size-label`, `--prism-font-size-title`, `--prism-font-weight`, `--prism-font-weight-title`, `--prism-text-color`, `--prism-text-color-secondary` |
+| Tooltip | `--prism-tooltip-bg`, `--prism-tooltip-color`, `--prism-tooltip-border`, `--prism-tooltip-radius`, `--prism-tooltip-padding`, `--prism-tooltip-shadow`, `--prism-tooltip-font-size` |
+| Crosshair | `--prism-crosshair-color`, `--prism-crosshair-width`, `--prism-crosshair-dash`, `--prism-crosshair-opacity` |
+| Points | `--prism-point-radius`, `--prism-point-radius-hover`, `--prism-point-stroke-width`, `--prism-point-stroke` |
+| Bars | `--prism-bar-radius`, `--prism-bar-hover-opacity`, `--prism-bar-gap`, `--prism-bar-band-fill`, `--prism-bar-band-opacity`, `--prism-bar-dim-opacity` |
+| Areas and lines | `--prism-area-opacity`, `--prism-area-stroke-width`, `--prism-area-gradient-start`, `--prism-area-gradient-end`, `--prism-line-width`, `--prism-line-width-hover` |
+| Interaction | `--prism-dim-opacity`, `--prism-active-point-radius`, `--prism-point-ring`, `--prism-focus-color` |
+| Sparklines | `--prism-spark-fill-opacity`, `--prism-spark-gradient-start`, `--prism-spark-gradient-end` |
+| Radar | `--prism-radar-grid-color`, `--prism-radar-grid-opacity`, `--prism-radar-band-fill`, `--prism-radar-band-opacity`, `--prism-radar-spoke-color`, `--prism-radar-fill-opacity`, `--prism-radar-stroke-width`, `--prism-radar-point-radius`, `--prism-radar-point-radius-active`, `--prism-radar-label-color`, `--prism-radar-label-size`, `--prism-radar-value-color`, `--prism-radar-value-size`, `--prism-radar-dim-opacity` |
+| Motion | `--prism-duration-fast`, `--prism-duration`, `--prism-duration-slow`, `--prism-ease`, `--prism-ease-spring`, `--prism-transition`, `--prism-transition-fast` |
+| Legend and pie labels | `--prism-legend-gap`, `--prism-legend-dot-size`, `--prism-legend-font-size`, `--prism-pie-label-color`, `--prism-pie-label-size` |
+
+The default palette and structural colors adapt to `prefers-color-scheme: dark`, `html.dark`, or `[data-prism-theme='dark']` on an ancestor. Scoped inline values set with `setTheme()` take precedence in either mode. The stylesheet also provides `prefers-reduced-motion` overrides for CSS transitions.
 
-The first arrow press focuses the first item. `Enter` or `Space` fires `onClick` for the focused item, and `Escape` clears it. The tooltip speaks the text when one is enabled; otherwise the chart's own `role="status"` region (`.prism-live`) does, so each value is announced once.
+## Errors and Diagnostics
 
-### Hover feedback
+Prism throws `PrismRenderError` when the container is not a DOM element, when initial rendering fails, or when `update()` is called on a disposed chart. A wrapped initial-render error exposes its cause. Use `PrismError` to catch all Prism-originated errors.
 
-The active key is shown the same way on every chart. Line and area charts mark each series' point and dim the series farther from the pointer. Bar charts shade the category band and dim the other categories. Pie charts dim the other slices. Radar charts highlight the active spoke and its points, and dim the other shapes while one is hovered.
+Empty or malformed data is not always an exception. Depending on the chart, Prism may draw nothing or emit a development-only `console.warn`; examples include an unknown `bandScale` category, negative values in stacked bars, and radar axes with fewer than three entries or duplicate keys. Correct the input rather than relying on a warning for validation.
 
 ## Framework Integration
 
-Prism has no framework adapter. Connect the same three operations to your framework's lifecycle: create after mount, update when state changes, and dispose before unmount.
+Prism has no React, Vue, or Svelte adapter. In any framework, give Prism a host element after it is mounted, call `update()` when data changes, and call `dispose()` before the host is removed. This plain DOM pattern shows the ownership boundary without depending on a framework-specific lifecycle API:
 
 ```ts
-import { createLineChart, type ChartHandle, type ContinuousDatum, type LineSeriesConfig } from '@vielzeug/prism';
-
-let chart: ChartHandle | undefined;
-
-export function mountChart(container: HTMLElement, data: ContinuousDatum[]): void {
-  chart = createLineChart(container, { series: [{ data, name: 'Series' }] });
-}
+import { createLineChart, type LineSeriesConfig } from '@vielzeug/prism';
 
-export function updateChart(data: ContinuousDatum[]): void {
-  chart?.update([{ data, name: 'Series' }]);
-}
+function mountChart(host: HTMLElement, series: LineSeriesConfig[]) {
+  const chart = createLineChart(host, { a11y: { ariaLabel: 'Revenue' }, series });
 
-export function unmountChart(): void {
-  chart?.dispose();
-  chart = undefined;
+  return {
+    update(next: LineSeriesConfig[]) {
+      chart.update(next);
+    },
+    dispose() {
+      chart.dispose();
+    },
+  };
 }
-```
-
-## Working with Other Vielzeug Libraries
-
-### With Ripple
 
-Keep state ownership in Ripple and connect it to Prism through an explicit subscription.
-
-```ts
-import { createLineChart } from '@vielzeug/prism';
-import { signal } from '@vielzeug/ripple';
-
-const data = signal([{ key: 1, value: 10 }]);
-const toSeries = () => [{ data: data.value, name: 'Series' }];
-const chart = createLineChart(container, { series: toSeries() });
-const unsubscribe = data.subscribe(() => chart.update(toSeries()));
-
-// Cleanup both owners together.
-unsubscribe();
-chart.dispose();
+const host = document.createElement('div');
+host.style.cssText = 'width:640px;height:320px';
+document.body.append(host);
+const view = mountChart(host, [{ data: [{ key: 1, value: 10 }], name: 'Revenue' }]);
+view.update([{ data: [{ key: 1, value: 10 }, { key: 2, value: 15 }], name: 'Revenue' }]);
+view.dispose();
 ```
 
-### With Sourcerer
-
-Bind chart data to a Sourcerer remote source so charts update whenever the list refreshes.
+The application owns its state and host; Prism owns only the SVG, observer, and optional overlay elements it creates.
 
-```ts
-import { createBarChart } from '@vielzeug/prism';
-import { createPageSource } from '@vielzeug/sourcerer';
+## Working with Other Vielzeug Libraries
 
-const source = createPageSource({
-  load: async ({ page, pageSize, signal }) => {
-    const result = await api.stats.list({ page, pageSize }, { signal });
-    return { items: result.data, totalItems: result.total };
-  },
-});
-const toSeries = (state) => [
-  {
-    data: state.items.map((item) => ({ key: item.label, value: item.count })),
-    name: 'Series',
-  },
-];
-const chart = createBarChart(container, { series: toSeries(source.state) });
-const unsubscribe = source.subscribe((state) => chart.update(toSeries(state)));
-void source.reload().catch(() => undefined);
-```
+Use Refine components for dashboard controls and keep Prism in a sized host element. Map Refine theme tokens to Prism CSS custom properties or call `setTheme()` with a scoped element; Prism does not require a Refine adapter. Prism uses Orbit internally to place tooltips, so chart users do not need to create Orbit floating elements for the built-in tooltip.
 
 ## Best Practices
 
-- Ensure the container element has explicit dimensions before calling a chart factory: `ResizeObserver` needs a non-zero layout size to trigger the first render.
-- Call `chart.dispose()` in your framework's unmount/cleanup phase to cancel transitions, disconnect resize observation, and remove DOM nodes.
-- Call `chart.update(data)` from your application state boundary; Prism does not require or own a state library.
-- Set `a11y: { ariaLabel: '…' }` on every chart that conveys meaningful data: unlabelled charts are hidden from assistive technology and receive no keyboard navigation.
-- Observe lifecycle with `chart.tap(handler)` rather than polling `chart.disposed` or wrapping the container: it costs nothing when untapped and detaches via `signal`.
-- For SSR, skip chart creation server-side: Prism depends on DOM APIs and `ResizeObserver`. Render charts only after hydration in a `onMounted`/`useEffect` callback.
+- Give the host a non-zero size before creating a chart.
+- Set `a11y.ariaLabel` when a chart communicates information.
+- Use `Date` or number keys consistently across each line or area chart.
+- Pass the complete new data value to `update()`.
+- Keep chart options fixed after creation; recreate the chart to change them.
+- Dispose the handle when its host leaves the owning view.
+- Use `transition: false` for deterministic synchronous rendering.
+- Prefer CSS custom properties for reusable theme overrides.
 
 ### Examples
 
 - [Create a line chart](./examples/line-chart.md)
 - [Plot a time series](./examples/time-series.md)
+- [Plot a scatter chart](./examples/scatter-chart.md)
 - [Compare categories with a bar chart](./examples/bar-chart.md)
 - [Render compact charts](./examples/compact-charts.md)
 - [Compare hero stats with a radar chart](./examples/radar-chart.md)
@@ -19282,7 +20392,7 @@ Component registration happens through side-effect imports such as `@vielzeug/re
 
 **Feedback:** `ore-alert`, `ore-async`, `ore-badge`, `ore-chip`, `ore-cookie-banner`, `ore-password-strength`, `ore-progress`, `ore-skeleton`, `ore-toast`, `ore-typing-indicator`
 
-**Inputs:** `ore-button`, `ore-button-group`, `ore-calendar`, `ore-checkbox`, `ore-checkbox-group`, `ore-column`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-radio`, `ore-radio-group`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
+**Inputs:** `ore-button`, `ore-button-group`, `ore-calendar`, `ore-checkbox`, `ore-checkbox-group`, `ore-column`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-query-bar`, `ore-radio`, `ore-radio-group`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
 
 **Layout:** `ore-box`, `ore-grid`, `ore-grid-item`, `ore-navbar`, `ore-sidebar`
 
@@ -19388,7 +20498,7 @@ import type { OreButtonProps } from '@vielzeug/refine/button';
 | Content | `avatar`, `avatar-group`, `breadcrumb`, `card`, `carousel`, `chat-message`, `code-window`, `copy-command`, `icon`, `keyboard-key`, `list`, `list-item`, `marquee`, `pagination`, `separator`, `speech-player`, `stats`, `step`, `stepper`, `table`, `text` |
 | Disclosure | `accordion`, `accordion-item`, `tabs`, `tab-item`, `tab-panel` |
 | Feedback | `alert`, `async`, `badge`, `chip`, `cookie-banner`, `password-strength`, `progress`, `skeleton`, `toast`, `typing-indicator` |
-| Inputs | `button`, `button-group`, `calendar`, `checkbox`, `checkbox-group`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `radio`, `radio-group`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |
+| Inputs | `button`, `button-group`, `calendar`, `checkbox`, `checkbox-group`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `query-bar`, `radio`, `radio-group`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |
 | Layout | `box`, `grid`, `grid-item`, `navbar`, `sidebar` |
 | Overlays | `command-palette`, `dialog`, `drawer`, `menu`, `navigation-menu`, `popover`, `tooltip` |
 
@@ -29322,6 +30432,7 @@ useEffect(() => {
 ## Examples
 
 - [Sync a Vault Store](./examples/sync-a-vault-store.md)
+- [Make Store Commands Undoable](./examples/make-store-commands-undoable.md)
 - [Keep Deletions from Resurrecting](./examples/keep-deletions-from-resurrecting.md)
 - [Switch Accounts Safely](./examples/switch-accounts-safely.md)