@voltro/cli 0.51.0 → 0.52.0

package/templates/agent-docs/plugins/{versioning.md → row-history.md}

@@ -1,27 +1,27 @@
-# Row versioning
+# Row history
 
-> Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.
+> Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.
 
 
 
 ---
 
-<!-- source: en/plugins/versioning.md -->
-## Row versioning
+<!-- source: en/plugins/row-history.md -->
+## Row history
 
-_Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries._
+_Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries._
 
-`@voltro/plugin-versioning` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, versioning records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
+`@voltro/plugin-row-history` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, row-history records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
 
 ## Wiring
 
 ```ts
 // app.config.ts
-import { versioningPlugin } from '@voltro/plugin-versioning'
+import { rowHistoryPlugin } from '@voltro/plugin-row-history'
 
 export default {
   type: 'api' as const, name: 'api',
-  plugins: [versioningPlugin({})],
+  plugins: [rowHistoryPlugin({})],
 }
 ```
 
@@ -30,14 +30,14 @@ Every committed change to a listed table appends a row to `_voltro_row_history`
 The history row's own `id` is **derived** from `(tableName, rowId, version)` and has a fixed width — it is a surrogate, and every part of it is already a column beside it, so do not parse or construct it. That width is the point: an `id()` column is `VARCHAR(64)` on mysql/mariadb and `NVARCHAR(64)` on mssql, so a key built by concatenating those parts grew with your **table name** and stopped fitting past 22 characters — which failed every write to that table, not merely an import.
 
 
-### What gets versioned — opt OUT, not in
+### What gets recorded — opt OUT, not in
 
-`versioningPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
+`rowHistoryPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
 
 ```ts
-versioningPlugin({})                              // every app table
-versioningPlugin({ exclude: [domainEvents] })     // opt one out
-versioningPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
+rowHistoryPlugin({})                              // every app table
+rowHistoryPlugin({ exclude: [domainEvents] })     // opt one out
+rowHistoryPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
 ```
 
 Both take table **values**, not names — a misspelling is a compile error at the call site, exactly as with `reference(() => table)`.
@@ -51,18 +51,18 @@ A table named in both `include` and `exclude` throws at construction — only yo
 **Check the boot line once after upgrading.** It prints the RESOLVED count, not the configured one:
 
 ```txt
-versioning active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
+row-history active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
 ```
 
 If 41 surprises you, `exclude` is the knob. The retention sweep (`VOLTRO_ROW_HISTORY_TTL_HOURS`) still bounds age.
 
 ## What this is NOT — the grain
 
-Versioning records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
+Row history records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
 
 The distinction is worth reading before you plan a migration onto it. A migration off hundreds of hand-written audit calls onto this tap runs into the same wall a few hours in: the grain is different. A table-keyed tap does not produce an aggregate-keyed trail with better coverage, it produces a *different artifact*. The two compose:
 
-- **versioning** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
+- **row history** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
 - an **aggregate trail** (the [audit sink](/docs/plugins/audit), one row per mutation invocation) answers "what business operation happened, to which entity, and did it succeed";
 - `traceId` joins them, so one request reads as one story.
 
@@ -95,10 +95,10 @@ migration — with the same meaning as an absent `traceId`.
 
 ## The correlation bridge — joining *what changed* to *who called*
 
-`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: versioning knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
+`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: row-history knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
 
 ```ts
-import { historyByTrace, historyBySubject } from '@voltro/plugin-versioning'
+import { historyByTrace, historyBySubject } from '@voltro/plugin-row-history'
 
 // What did this call change? (`byTrace`)
 const touched = await historyByTrace(ctx.store, traceId, ctx.request.subject.tenantId)
@@ -118,7 +118,7 @@ Both questions were previously unanswerable at any speed — `byRow` is the only
 ## `timing` — when the history row is written
 
 ```ts
-versioningPlugin({ timing: 'in-transaction' })
+rowHistoryPlugin({ timing: 'in-transaction' })
 ```
 
 | | `'post-commit'` (default) | `'in-transaction'` |
@@ -175,7 +175,7 @@ That is the correct order, not a race to engineer around: the change is durable,
 { "id": "sess_1", "secret": "enc:v1:a56iziEV9THLhzmJ:Vk0ux+0bECleTLBJkCa0Rg==:3AtMwP" }
 ```
 
-So versioning a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
+So keeping history for a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
 
 **`.serverOnly()` columns ARE withheld**, and for a sharper reason than "a second copy": `crud.*` strips those columns from every row it returns, and a snapshot would smuggle the value back past that stripping inside a `json()` blob, where no column-level rule applies. A marker meaning *never serialize this to a client* cannot survive being re-exported through a different column's contents.
 
@@ -189,7 +189,7 @@ The withheld names are listed under `data._omitted`, so a reader can tell *"this
 ## Querying the timeline
 
 ```ts
-import { rowHistory, rowAsOf } from '@voltro/plugin-versioning'
+import { rowHistory, rowAsOf } from '@voltro/plugin-row-history'
 
 // Every version of a row, oldest → newest — TENANT-SCOPED to the caller:
 const history = await rowHistory(ctx.store, 'posts', postId, ctx.request.subject.tenantId)
@@ -204,7 +204,7 @@ Pass the caller's `tenantId` — reads are **tenant-scoped**: a row's value time
 ## Restore & diff
 
 ```ts
-import { restoreAsOf, diffVersions } from '@voltro/plugin-versioning'
+import { restoreAsOf, diffVersions } from '@voltro/plugin-row-history'
 
 // Roll the LIVE row back to its state at a past instant (tenant-scoped like
 // rowAsOf — no visible state then ⇒ null, nothing written). The restore goes

package/templates/agent-docs/plugins/storage.md

@@ -1,6 +1,6 @@
 # Storage
 
-> File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser.
+> File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/storage.md -->
 ## Storage
 
-_File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser._
+_File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser._
 
 `@voltro/plugin-storage` is file storage behind one `StorageService`. Wire a
 provider in `app.config.ts`; consume it in handlers and actions via

package/templates/agent-docs/plugins.md

@@ -27,7 +27,7 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-billing](/docs/plugins/billing) — subscriptions, plans, entitlements + usage metering (Stripe + mock provider); seat-based billing on Stripe's own proration, retries, tax and checkout; money as integer minor units
 - [plugin-licensing](/docs/plugins/licensing) — offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; plan entitlements + pricing decided server-side, never baked into a published version
 - [plugin-mail](/docs/plugins/mail) — transactional email (Resend / Postmark / SendGrid / SES / Mailgun / SMTP, templates, suppression, scheduling, batch, idempotency)
-- [plugin-storage](/docs/plugins/storage) — file storage: public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem
+- [plugin-storage](/docs/plugins/storage) — file storage: public (CDN-direct) + private (access policy + per-object grants), S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem
 - [plugin-ai-flows](/docs/plugins/ai-flows) — durable multi-step AI pipelines (deterministic + agentic) with human-in-the-loop, chaining, and cadence; code-first `defineFlow` or data-driven rows
 - [plugin-postgis](/docs/plugins/postgis) — postgres-native `geography` / `geometry` columns + spatial operators
 - [plugin-broadcast](/docs/plugins/broadcast) — cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects
@@ -42,10 +42,10 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-logship](/docs/plugins/logship) — ship structured logs to Better Stack / Axiom / Loki / any HTTP sink; batched, redacted, fail-soft
 - [plugin-moderation](/docs/plugins/moderation) — moderate user content before commit: keyword or AI provider, block / flag via interceptor + in-handler redact
 - [plugin-search](/docs/plugins/search) — keep an external index (Typesense / Meilisearch / Algolia) in sync via the ChangeEvent tap; tenant-scoped `search.query` + hook
-- [plugin-cdc-out](/docs/plugins/cdc-out) — declarative reverse-ETL: mirror table changes outward to a webhook / Kafka / Snowflake / BigQuery sink through a durable outbox; ordered per pipe, at-least-once from enqueue, dead-lettered
+- [plugin-cdc-out](/docs/plugins/cdc-out) — declarative reverse-ETL: mirror table changes outward to a webhook sink (or any custom `CdcSink`) through a durable outbox; ordered per pipe, at-least-once from enqueue, dead-lettered
 - [plugin-governance](/docs/plugins/governance) — data governance: retention TTL sweep, GDPR export + erasure, consent ledger, field encryption
 - [plugin-openapi](/docs/plugins/openapi) — OpenAPI 3.1 spec + Swagger-UI docs generated from your `defineRestRoute` descriptors and (opt-in) rpc procedures
-- [plugin-versioning](/docs/plugins/versioning) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
+- [plugin-row-history](/docs/plugins/row-history) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
 - [plugin-presence](/docs/plugins/presence) — ephemeral realtime presence: heartbeat roster per channel + `usePresence` / `useTyping` hooks, held in memory; cross-instance with [plugin-broadcast](/docs/plugins/broadcast)
 - [plugin-auth-social](/docs/plugins/auth-social) — first-party Sign in with Google / GitHub / Apple: mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, sessions issued through plugin-auth
 - [plugin-scim](/docs/plugins/scim) — SCIM 2.0 provisioning (Users + Groups at `/scim/v2`) so an enterprise IdP can create/deactivate users
@@ -70,7 +70,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-licensing` | ✓ | Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; plan entitlements + pricing decided server-side, never baked into a published version. [→ details](/docs/plugins/licensing) |
 | `@voltro/plugin-ai-flows` | ✓ | Durable multi-step AI pipelines — deterministic or agentic, with human-in-the-loop, chaining and cadence; author flows in code (`defineFlow`) or as data (visual-editor rows), one engine runs both. [→ details](/docs/plugins/ai-flows) |
 | `@voltro/plugin-mail` | ✓ | Transactional email — Resend / Postmark / SendGrid / SES / Mailgun / SMTP, *.email.tsx templates, per-tenant suppression, send-time scheduling, bulk/batch send, per-send idempotency, durable via workflows |
-| `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
+| `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
 | `@voltro/plugin-broadcast` | ✓ | Cross-replica reactivity — fans out app-mutation change events to every replica over a pub/sub bus (Redis / NATS). Closes the single-instance gap for every non-postgres dialect. [→ details](/docs/plugins/broadcast) |
 | `@voltro/plugin-webhooks` | ✓ | Incoming + outgoing webhooks — `defineIncomingWebhook` (signature verify + idempotency, Stripe/GitHub/Slack presets) and `defineEvent` (durable delivery workflow, HMAC signing, retries, filters). [→ details](/docs/plugins/webhooks) |
@@ -91,10 +91,10 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-logship` | ✓ | Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — rides the log-sink hook, batched + redacted + fail-soft, trace-correlated. [→ details](/docs/plugins/logship) |
 | `@voltro/plugin-moderation` | ✓ | Content moderation — keyword denylist or AI provider (fails open), block (typed `ContentRejected`) / flag via rpc interceptor + in-handler `moderate()` redact helper. [→ details](/docs/plugins/moderation) |
 | `@voltro/plugin-search` | ✓ | External search index sync — rides the ChangeEvent tap to mirror tables into Typesense / Meilisearch / Algolia (memory default), tenant-scoped `search.query` action (facets · highlighting · fuzziness · range/negation filters · engine-param passthrough) + `useSearch` hook + `backfillIndex` + durable cross-replica sync stats. [→ details](/docs/plugins/search) |
-| `@voltro/plugin-cdc-out` | ◐ | Declarative reverse-ETL — mirror table changes outward to external sinks (webhook / Kafka / Snowflake / BigQuery) through a durable outbox; ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. Engine + memory/webhook sinks shipped; warehouse connectors implement the `CdcSink` interface. |
+| `@voltro/plugin-cdc-out` | ◐ | Declarative reverse-ETL — mirror table changes outward to external sinks (webhook, plus a `CdcSink` interface for custom sinks) through a durable outbox; ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. Engine + memory/webhook sinks shipped; anything else implements the `CdcSink` interface. |
 | `@voltro/plugin-governance` | ✓ | Data governance — retention TTL sweep (delete / anonymise), GDPR subject export + erasure (admin-gated routes + `GovernanceService`), consent ledger, field encryption. [→ details](/docs/plugins/governance) |
 | `@voltro/plugin-openapi` | ✓ | OpenAPI 3.1 spec (`GET /openapi.json`) + Swagger-UI (`GET /docs`) generated from `defineRestRoute` descriptors AND (opt-in) rpc procedures (queries/mutations/actions/streams → `POST /rpc/<name>`) — input/output/error Schemas via `JSONSchema.make`. [→ details](/docs/plugins/openapi) |
-| `@voltro/plugin-versioning` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete on listed tables into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/versioning) |
+| `@voltro/plugin-row-history` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete (every table by default; narrow with include/exclude) into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/row-history) |
 | `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator. Held **in memory**, owner-partitioned — no table is written; cross-instance requires [`@voltro/plugin-broadcast`](/docs/plugins/broadcast), and without a broker each replica sees only its own clients. [→ details](/docs/plugins/presence) |
 | `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `_voltro_scim_users`/`_voltro_scim_groups`. [→ details](/docs/plugins/scim) |
 | `@voltro/plugin-sso-saml` | ✓ | Enterprise SAML 2.0 SSO — SP-initiated login + Single Logout (both directions) + ACS + SP metadata under `/saml`; IdP-metadata-URL auto cert rotation, encrypted assertions, clock-skew, SP request signing. Signature verify via `@node-saml/node-saml` (optional+lazy), mints a framework session. [→ details](/docs/plugins/sso-saml) |
@@ -746,7 +746,7 @@ A package can ship BOTH a schema mixin AND a runtime plugin (`@voltro/plugin-aud
 
 ## More extension surfaces
 
-The plugin contract carries eight additional surfaces beyond the
+The plugin contract carries the additional surfaces below, beyond the
 interceptors + lifecycle + manifest fields covered above:
 
 ### `inspectEndpoints: PluginInspectEndpoint[]` — plugin-mounted HTTP endpoints
@@ -874,6 +874,17 @@ plugin-provided template is scaffolded exactly like a built-in one —
 `scaffoldFromTemplate` copies the declared tree and substitutes the
 `{{…}}` tokens in both file content AND file/directory names.
 
+### `httpRoutes: PluginHttpRoute[]` — raw HTTP endpoints on the framework listener
+
+A plugin can mount plain HTTP routes beside the rpc surface (`@voltro/plugin-storage`'s upload/download routes, an IdP callback). The request/response shape is transport-honest, and four properties are worth pinning:
+
+- **The full method union is first-class.** `method` is `'*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'`. **HEAD is admitted wherever GET is** (RFC 9110) — the GET handler runs and the transport drops the body; you never mount a second route for it. A wrong method stays a precise `405` with an `Allow:` header, including when several routes share one path.
+- **The body read is capped** — 8 MiB by default, the same cap as every other surface (`http.maxBodyBytes` in `app.config.ts`, env `VOLTRO_MAX_BODY_BYTES`), and the read is binary-clean. A route that takes more declares its own `maxBodyBytes`; routes **sharing a path share one body read**, so the widest override in the group applies to the group. Oversize answers `413` for both `Content-Length` and chunked requests.
+- **Binary streaming responses** return `byteStream` on the `PluginHttpRouteResult` — a `ReadableStream<Uint8Array>` (or lazy thunk) with optional `contentLength` / `contentDisposition`, piped without buffering and never compressed. It is the plugin-route spelling of the REST surface's [`bytes()`](/docs/data/rest-routes#binary-downloads--bytes).
+- **Buffered responses are compression-negotiated** (brotli/gzip, compressible types only) by the listener — nothing to declare; see [Security → compression](/docs/security/overview).
+
+A state-changing plugin route is origin-checked unless it declares `originGuard: 'exempt'`, and `req.remoteAddr` is the trusted-proxy-resolved client address — both covered with examples in [Security](/docs/security/overview#routes-that-a-third-party-legitimately-posts-to).
+
 ### `onHttpRequest: HttpRequestInterceptor` — pre-auth HTTP-pipeline hook
 
 Fires at the **very top** of every HTTP request — BEFORE auth resolution,
@@ -937,6 +948,17 @@ is deliberate: `GET /internal/liveness` and `GET /internal/readiness` are
 answered before the interceptor, so a rate-limit or geo-block plugin cannot 503
 a Kubernetes probe and take the replica out of rotation.
 
+**The chain is FAIL-CLOSED.** An interceptor that throws is a `500` plus a log
+line — the request does NOT continue. It used to: the failure was swallowed and
+the request flowed on, which meant a crashed security gate was an open one.
+That polarity puts a decision on every interceptor author: if your hook is a
+GATE (geo-block, bot detection), let a failure propagate — refusing is the
+correct degraded behaviour. If it is protection with a DEPENDENCY (a rate-limit
+counter in Redis), catch your own failure inside the hook and **degrade
+loudly** — `@voltro/plugin-ratelimit`'s `httpShield` does exactly that: a Redis
+outage means unlimited-with-a-warning, never a self-inflicted API outage.
+What no interceptor gets to do anymore is fail silently and stay in the chain.
+
 ### `extendSchema: { tables, migrations }` — contribute schema + migrations
 
 A plugin contributes BOTH declarative table descriptors AND custom SQL

package/templates/agent-docs/reference.md

@@ -581,6 +581,7 @@ Returns a function `(to: string, options?) => void`.
 |---|---|
 | `replace: true` | Replace the history entry (no back-button entry). |
 | `scroll: false` | Don't scroll to top after navigation. |
+| `transition: true / false` | Run (or suppress) this navigation's swap through `document.startViewTransition`, overriding the app-wide `router.viewTransitions` default. `<Link transition>` is the declarative mirror. See [View transitions](/docs/routing/navigation#view-transitions). |
 
 `navigate` takes a path string only — there is no numeric history overload. For back / forward, reach for the browser API:
 
@@ -607,12 +608,22 @@ Pass `true`/`false` or a predicate `({ to, opts }) => boolean` (to allow some de
 
 ## `useSearchParams()` + `useSetSearchParams()`
 
-Read the query string as a `URLSearchParams` (SSR-aware — the request URL on the server, `window.location.search` on the client):
+Read the query string. Two overloads, both SSR-aware (the request URL on the server, `window.location.search` on the client):
+
+- `useSearchParams()` — the raw `URLSearchParams`, for routes without a schema.
+- `useSearchParams(searchParams)` — pass the page's own `searchParams` schema export to get the decoded, typed shape. Defaults applied; an invalid query falls back to the defaults instead of crashing.
 
 ```tsx
+import { Schema } from 'effect'
 import { useSearchParams } from '@voltro/web'
 
-const tab = useSearchParams().get('tab') ?? 'overview'
+export const searchParams = Schema.Struct({
+  tab:  Schema.optionalWith(Schema.String, { default: () => 'overview' }),
+  page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+})
+
+const { tab, page } = useSearchParams(searchParams)   // tab: string · page: number
+const raw = useSearchParams()                         // URLSearchParams (schema-less routes)
 ```
 
 Write it with `useSetSearchParams()` — the setter updates the query via `navigate`, so readers re-render immediately:
@@ -628,6 +639,28 @@ setParams({ page: '2' }, { push: true })             // distinct history entry
 
 Writes default to a history replace; pass `{ push: true }` for a Back entry or `{ scroll: false }` to keep scroll. See [Navigation](/docs/routing/navigation#reading--writing-search-params).
 
+`useSetSearchParams(searchParams)` — pass the schema to get the **typed** setter. Object form replaces the query (a left-out field decodes to its default on the next read); the updater form receives the current **decoded** params, so a merge is an explicit spread:
+
+```tsx
+const setTyped = useSetSearchParams(searchParams)
+setTyped({ page: 2 })                          // replaces → ?page=2
+setTyped((p) => ({ ...p, page: p.page + 1 }))  // keeps every other param — typed merge
+```
+
+## Typed `withQuery()`
+
+Not a hook, but the link-side half of the same contract: for a route whose page exports a `searchParams` schema, the generated `routes` builder brands the URL with the schema's shape (through a type-only import — no page code enters the routes module), and `withQuery` type-checks the params against it — a misspelt key or a wrong value type is a compile error:
+
+```tsx
+import { withQuery } from '@voltro/web'
+import { routes } from './.framework/routes'
+
+withQuery(routes['/notes'](), { page: 2 })     // OK — typed against the schema
+// withQuery(routes['/notes'](), { pgae: 2 })  // compile error (unknown key)
+```
+
+The encode is canonical: strings pass through, numbers/booleans via `String()`, arrays as repeated keys, `undefined` omitted; a `Date` (or any object) is refused loudly — declare the field as a string/number transform in the schema instead. See [Navigation → typed `withQuery`](/docs/routing/navigation#typed-withquery).
+
 ## `usePrefetch()`
 
 Trigger loader-data prefetch on hover / focus. Wired automatically by `<Link prefetch />`; export only useful for custom triggers.
@@ -821,6 +854,10 @@ export default function SearchPage() {
 that must react to router-pushed query changes without a reload re-render through the router
 (`useNavigate`/`useLocation`); the hook then re-resolves on that render.
 
+Prefer the typed form where the page declares a `searchParams` schema export —
+`useSearchParams(searchParams)` returns the decoded shape instead of a raw
+`URLSearchParams`. See [Routing hooks](/docs/reference/hooks-routing#usesearchparams--usesetsearchparams).
+
 ## Reading cookies
 
 ```ts