@voltro/client 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -39,6 +39,133 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.52.0] — 2026-08-25
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/web, @voltro/plugin-storage, @voltro/plugin-ratelimit** — The HTTP surface is complete — seven gaps closed, each proven against the real listener.
+
+  **Binary byte streams.** REST handlers return `bytes(stream, { contentType, contentLength?, contentDisposition? })` (lazy thunk form defers opening the source); plugin routes return `byteStream`. Piped, never buffered (a 256 MiB export streams with bounded heap), never compressed. Idempotency × stream is DECIDED: `streaming: true` on an idempotent method with an idempotency binding is a mount error (a stream cannot cache a replayable body — retries would 409 until the TTL); an undeclared stream releases its claim at return. Storage's full-object download rides the generic path now.
+
+  **Negotiated compression + conditional GET.** brotli/gzip negotiated with a compressible-type allowlist, 1 KiB threshold, `Vary: Accept-Encoding` always on compressible types — on the api's buffered responses AND `voltro start`'s HTML (`http.compression.{enabled,minBytes}`). The BREACH position is structural: `POST /rpc` responses are NEVER compressed. ISR keeps ONE uncompressed entry and compresses per hit. `voltro start` answers `If-None-Match` with 304 (weak md5 tags over the uncompressed body); REST routes can declare `etag: true` (GET, weak SHA-1 content tag).
+
+  **Raw WebSocket gateways.** `defineWebSocket({ path, auth, onConnection })` in a `*.ws.ts` file — for FOREIGN protocols (a Yjs provider, a device fleet); app realtime stays the subscription protocol. `auth` is required with no default: `'subject'` runs the same chain as rpc/SSR BEFORE the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code 4001); `'public'` is a written-down decision. Every gateway path joins the upgrade origin guard (cross-site WebSocket hijacking → 403). Teardown at construction; plain GET → 426; duplicate paths refuse the boot.
+
+  **Body caps everywhere.** The 8 MiB cap used to guard only `/rpc`; plugin routes read uncapped and webhooks read uncapped AND UTF-8-round-tripped (corrupting binary bodies — fixed, proven byte-for-byte). `http.maxBodyBytes` (env `VOLTRO_MAX_BODY_BYTES`), per-route overrides on `defineRestRoute` and webhook handlers; a shared path takes its group's widest override. 413 for both request shapes.
+
+  **Full method unions.** PATCH/HEAD/OPTIONS are first-class on plugin and REST routes; HEAD is admitted wherever GET is (RFC 9110) with the transport dropping the body.
+
+  **BREAKING — the interceptor chain is fail-closed.** A throwing `onHttpRequest` interceptor is a 500 + a log line now; it used to be swallowed, which let a crashed security gate silently stop guarding. The manual codemod tells interceptor authors where the decision lives: propagate (a gate) or catch-and-degrade-loudly (protection with a dependency) — plugin-ratelimit's httpShield now does the latter, so a Redis outage cannot become a self-inflicted API outage. No app-authored call sites change shape, hence `apiSurface: compatible` — the break is the error POLARITY of one plugin-author hook, carried by the manual note.
+
+  **Middleware response headers + CSP nonce.** `middleware.ts` can return `responseHeaders` (applied on every render response shape, both boot paths; prerendered static files are the documented proxy-side limit) and `cspNonce` — the framework stamps every script tag of that render (React's own included) while the policy header stays the middleware's. `isr` + `cspNonce` is refused loudly: a cached nonce is a lie the browser enforces.
+
+  Deliberate limits: no multipart parser on REST/webhook routes (the storage upload routes are the sanctioned file path); static-file response headers belong at the proxy.
+- **@voltro/plugin-row-history, @voltro/cli** — `@voltro/plugin-versioning` is renamed to `@voltro/plugin-row-history` — the name now says what it does.
+
+  The old name collided head-on with API versioning (versioned REST routes, `/v1` → `/v2`, sunset flow), which `defineRestRoute` now supports as a first-class `version:` field. What this plugin does is row history + time travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions` over `_voltro_row_history`); every comparison table that filed it under API versioning was reading the name, not the feature.
+
+  Renamed with it: the factory (`versioningPlugin` → `rowHistoryPlugin`), the options type (`VersioningPluginOptions` → `RowHistoryPluginOptions`), and the default instance alias (`versioning` → `row-history` — the inspect endpoint path and boot-log lines; an explicit `alias:` you passed is untouched). The table name (`_voltro_row_history`) and `VOLTRO_ROW_HISTORY_TTL_HOURS` already carried the new name: no data movement, no env change, no migration.
+
+  The codemod rewrites imports, the factory call sites and the options-type references, and prints the one step it cannot do — swapping the dependency in package.json.
+
+### Added
+
+- **@voltro/cli** — `voltro doctor` now reports every declared `@voltro/*` dependency with no import site — the residue a migration off a framework package leaves in `package.json`, where it keeps getting installed, walked by `voltro update`, and read as evidence the package is in use, its breaking-change notes included.
+
+  Scoped to `@voltro/*` deliberately (third-party packages have too many legitimate no-import shapes), and three states are distinguished and printed: exempt by name with a reason (`@voltro/cli` is the binary, `@voltro/devtools` is mounted by `voltro dev`, `@voltro/sql-*` drivers are loaded from config); not-measurable-yet for `@voltro/client`/`@voltro/web` on a tree where codegen has never run (a missing measurement, not a dead dependency); and unimported — advisory, never fatal. A mention in a comment or an error string does not count as an import, and a commented-out import counts least of all: it is the artefact the rule exists to see past. Also in `voltro doctor --json` under `unimportedDeps`, `null` when no `package.json` could be read.
+- **@voltro/web, @voltro/cli** — Islands now save real bytes — every `interactive: 'islands'` page gets its OWN browser entry.
+
+  Measured on the reference fixture (pinned in `bundle-budget.json`, 2026-08-25): an islands page's first load is **59.6 KB gz** against **181.9 KB gz** for a fully hydrated page — react + the island runtime + that page's islands, no router, no Effect runtime, no subscription cache. The bundle-budget gate pins a hard <70 KB bound AND the ratio (<50 % of a full page), so a regression that re-couples the entries fails loudly.
+
+  - **`@voltro/web/islands`** is the new react-only subpath — `island()` and the hydration runtime import only react + react-dom/client. Importing the `@voltro/web` BARREL (or `@voltro/i18n`) anywhere in an island's import graph is now a BUILD error naming file and specifier: an island hydrates provider-less, router hooks and `useT()` throw there anyway, and the barrel would pull the Effect runtime into the slim entry. - **The build finds each page's islands** through its relative import graph (transitively, through components in between) and emits one shell + entry per islands page. `interactive` must be a source LITERAL to select the slim entry — a computed value ships the full entry as before, and the build says so. - **All three paths**: `voltro build` (SSG renders into the per-page shell, main-shell stylesheets folded in), `voltro start` (ssr/isr islands routes serve their shell), `voltro dev` (same mechanism on demand — violations fire in dev, not first in CI). Fixed on the way: a STATIC islands page fell through dev's render gate to the SPA fallback and loaded the full app entry — dev now server-renders it like production. - **Framework islands**: an island importing `@voltro/client` (`useSubscription`, …) is detected — that page's entry boots the rpc client and wraps each island root in `VoltroRuntimeProvider`, so the island receives live data. Presentational pages never pay for the client core. - **`hydrate: 'only'`** (Astro's `client:only`): the server renders an empty placeholder — a browser-only lib touching `window` in render no longer crashes the SSR pass — and the client mounts fresh with `createRoot`. - **Island props are declared lossy where they are**: props cross an HTML attribute as JSON, so a `Date` arrives as an ISO string and `Map`/`Set`/ functions do not arrive at all — dev warns naming the island and prop. - The per-island `manualChunks` rule is gone: with per-page entries as additional rollup inputs it MERGED the shared react modules into the island group (a second-React-instance shape); per-island chunks were also redundant — the entry already scopes to the page's islands, and they were statically preloaded anyway.
+
+  Limits: an islands page reached via SPA navigation from a full page runs in the already-loaded app bundle (the saving applies to hard loads of the islands page); a page's islands share one entry (hydrate strategies control WHEN each hydrates, not when it downloads).
+
+  Why the golden churn is compatible: `hydrate: 'only'` widens a union, `hydrateIslandsOnPage` gains an optional options argument, and the subpath is a new export.
+- **@voltro/ui, @voltro/client, @voltro/web, @voltro/cli** — Forms without JavaScript — `<AutoForm>` on a server-rendered page now works with JS disabled, end to end.
+
+  The form always renders `action="/form/<mutationTag>"` + `method="post"`; with JS alive, `onSubmit` intercepts exactly as before (optimistic rpc path unchanged). The `/form/*` endpoint is mounted by the WEB listener on BOTH boot paths (`voltro dev` and `voltro start`, one shared builder):
+
+  - **Origin-checked at the door** with the same `classifyRequestOrigin` the api's rpc listener runs — a cross-origin form POST is a 403 before a byte of the body is parsed. (The server-side forward reaches the api as a no-browser-origin request, so the web listener's check is the one that guards this surface.) - **One validation path.** The urlencoded body maps through the schema-driven `formDataToInput` (checkbox present/absent → true/false, `''` on number/date omits the field — never a silent 0 —, repeated keys → arrays, non-numeric strings pass through RAW so the decode fails honestly instead of minting NaN, unknown keys dropped) and validates with the SAME `validateFields` the client-side submit runs — byte-identical field errors. - **PRG on success**: 303 back to the submitting page, or to `<AutoForm redirectTo>` (same-origin relative paths only — anything else is refused, a hidden field must not become an open redirect). Reloading the redirected-to page cannot resubmit. - **422 re-render on validation failure**: the referring page renders in the same response with field errors + submitted values in the SAME error UI (`role="alert"`, aria unchanged), `cache-control: no-store`, bypassing the ISR cache in both directions. An rpc refusal after valid input (guard, server error) renders as a form-level error. The flash also embeds as a JSON script, so a page whose bundle arrives late hydrates to the identical state. - **Valid submits forward server-side over `POST /rpc`** with the request's cookie — auth middleware, guards and the rpc interceptor chain run identically to every other mutation.
+
+  New `<AutoForm>` props: `formKey` (several forms per page — the 422 re-render re-fills only the submitted one), `redirectTo`, and `action={false}` for purely static deploys where `/form/*` does not exist. Headless: `useFormBinding` gains `flash` + `formError`, `@voltro/web` gains `useFormFlash(formKey)`.
+
+  Also fixed on the way: a required `Schema.Boolean` field with no default used to block the JS submit as "missing" while its checkbox rendered visibly unchecked — boolean fields now seed `false`, agreeing with what the user sees (and with the no-JS mapping).
+
+  Deliberate limits: the no-JS error re-render needs an `ssr`/`isr` page (a static page cannot be re-rendered with request state; a minimal error page is the fallback); a purely static deploy has no `/form/*` endpoint (use `action={false}`); file uploads stay JS-only (multipart → 415). On an ssr page pass `schema` explicitly — descriptor resolution is a client-runtime feature and the SSR render would otherwise show no fields.
+
+  Bundle note: the `serverContext` chunk group is renamed `serverRequest` by the context's move to @voltro/client — identical 190 B gz, re-pinned in `bundle-budget.json` (fresh full measurement 2026-08-25: firstLoad 185,494 B gz, was 185,309 — +185 B from the form-flash read in the request context).
+
+  Why the golden churn is compatible: every addition is a new export or an optional prop; `FormBinding.formError` is a new member of the hook's RETURN type (nothing in the public API accepts a caller-built `FormBinding`), and `ServerRequestContextValue.formFlash` is optional.
+- **@voltro/runtime, @voltro/cli, @voltro/cms, @voltro/plugin-broadcast** — On-demand ISR revalidation — the third invalidation axis next to time (`revalidate`) and CDC (`cacheInvalidatesOn`). Server code in the api process calls `revalidatePath('/blog/[slug]')` / `revalidateTable('posts')` / `revalidateTag('pricing')` (exported from `@voltro/runtime`; callable from mutations, actions, webhook receivers and REST routes) and the matching ISR cache entries fall on EVERY `voltro start` replica — including on dialects with no CDC at all, which is the case this exists for.
+
+  Transport is dialect-shaped, either or both: on postgres a `pg_notify` rides the SAME LISTEN connection the CDC invalidator already holds (no broker needed); everywhere else the broadcast broker carries it (`BROADCAST_URL` on both deployments; channel namespaced by `VOLTRO_BROADCAST_NAMESPACE` — deliberately env-derived, because this channel pairs an api with its WEB app and no shared name is derivable). A web process with isr routes and neither transport warns loudly at boot; under `voltro dev` the calls are documented debug-logged no-ops. Tags share ONE mechanism with tables — `cacheInvalidatesOn` accepts free strings, so `revalidateTag` is the same sink under another name.
+
+  Correctness edges built in: `revalidatePath` against a `static` route is a NAMED error on the web process (never a silent no-op); a purge landing while an SWR refresh or miss fill renders is guarded by a per-key generation counter on BOTH cache backends — the pre-purge page cannot be written back with a full TTL, and a refused write also suppresses the postgres backend's fire-and-forget upsert so no replica resurrects a deleted row. A content type declares `revalidate: { paths, tags }` and `publish()`/`unpublish()` fire them after commit.
+
+  Proven end-to-end (`scripts/revalidate-e2e.mjs`): 1 api + 2 `voltro start` replicas behind Redis (warm → purge → both fresh, with a negative control), the sqlite dialect leg, and a broker-less postgres leg where the NOTIFY line alone carries the purge to a LISTEN-only replica.
+
+  `apiSurface: compatible` — additive only: the new `@voltro/runtime` revalidation exports, an optional `revalidate` on `ContentTypeSpec`, the optional `onRevalidate`/`revalidateChannel` on the CDC invalidator options, a widened `BroadcastChannelKind`, and `IsrCache.set`'s new optional generation guard (plus `generation()`).
+- **@voltro/protocol, @voltro/plugin-openapi** — `defineRestRoute` takes an opt-in `version:` — versioned REST APIs with a sunset flow.
+
+  `version: 'v2'` + `path: '/customers'` mounts the route at `/v2/customers`, the same `/vN/` convention the `publicApi:` projection and the built-in `/v1/api-keys` surface already use. The path is normalised ONCE at definition time, so every consumer — the mount, path-param matching, the idempotency scope, tracing spans, the OpenAPI generator — sees the mounted path and none can disagree.
+
+  Deliberate edges:
+
+  - **Opt-in, no auto-prefix.** A route without `version:` keeps its literal path untouched — an automatic prefix would silently move every deployed route. A path that already starts with `/vN/` AND declares `version:` is refused loudly at definition (both spellings at once is never what the author meant). - **Two versions are two descriptors.** The old version is ordinary code — visible, testable, deletable — carrying `deprecated:` (the replacement pointer) and `sunset:` (the date it starts answering `410 Gone`; the 410 body now also names which `version` died). - **One OpenAPI document for every version.** The `/vN/` prefix already separates the paths; each versioned operation is grouped under a version tag and carries `x-voltro-api-version` for tooling. No `?version=` filtered spec — a second document shape for information the paths already state. - The rpc socket stays outside URL versioning on purpose: the generated client is versioned with the server it was generated from. A stale browser tab runs the previous client until reload — that skew window exists and is documented, not solved by URLs.
+- **@voltro/web, @voltro/cli** — Opt-in View Transitions for SPA navigations. `router.viewTransitions: true` in a web `app.config.ts` runs every route swap — `<Link>` clicks, `navigate(...)`, back/forward — through `document.startViewTransition`; individual navigations override the default in either direction with `navigate(to, { transition })` / `<Link transition>`.
+
+  The visual swap is the router's deferred-navigation commit, flushed synchronously inside the transition callback — by that point the target's lazy chunk and loaders have settled, so the flushed tree renders with data in hand. Three deliberate behaviors: `defer()` fields (and an explicit `Pending` skeleton's settled content) resolve AFTER the transition as ordinary updates, never a second animation; navigating while a transition is animating skips the running one (last navigation wins, nothing queues); overlay/dialog state changes never trigger one — a root snapshot would cross-fade the whole viewport for a one-layer change.
+
+  Fallback is exact: a browser without the API, and any user with `prefers-reduced-motion: reduce`, gets today's untransitioned swap — same timing, nothing to feature-detect. Styling is plain `::view-transition-*` CSS (no animation DSL); cross-document transitions for static/MPA pages are a one-line `@view-transition` CSS opt-in with no framework involvement.
+
+  Proven in a real chromium (`scripts/browser-view-transitions.mjs`): called on navigation, silent under reduced-motion, harmless with the API deleted, one transition across a `defer()` commit, rapid double-navigation lands on the last target — plus the jsdom wiring suite and the generated-entry flag check shared by all three web boot paths.
+
+  `apiSurface: compatible` — additive only: a new optional `viewTransitions` on `RouterProps`, optional `transition` on `NavigateOptions`/`LinkProps`, and the optional `router` block on the web app config.
+- **@voltro/web, @voltro/cli** — Schema-typed search params — the query-string half of the URL is now part of the type graph.
+
+  A page declares its contract once:
+
+  ```ts
+  export const searchParams = Schema.Struct({
+    q:    Schema.optionalWith(Schema.String, { default: () => '' }),
+    page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+  })
+  ```
+
+  and gets, end to end:
+
+  - **Typed reads** — `useSearchParams(searchParams)` returns the decoded, defaulted shape, SSR-aware; the zero-arg call keeps returning the raw `URLSearchParams`. Decoding is TOTAL: an invalid query falls back to the schema's defaults instead of crashing a render; only a schema that cannot even decode `{}` (a required field with no default) throws, naming the fix. - **Typed links** — the generated `routes` builder brands the route's URL with the schema's shape through a TYPE-ONLY page import (zero value edges: code-splitting is untouched, pinned by test), and `withQuery` type-checks against it — a misspelt key or wrong value type is a compile error. The link-side encode is canonical and schema-free (strings/numbers/booleans, arrays as repeated keys); a roundtrip test pins that it produces exactly what the schema's decode accepts. Deliberately ONE generic signature rather than overloads: with overloads, a wrong key would silently fall through to the permissive untyped form and the compile error would never fire. - **Typed writes** — `useSetSearchParams(searchParams)` returns the typed setter: its object form replaces the query (same semantics as the untyped form), and its updater form receives the CURRENT decoded params, so keeping `?filter` across a page flip is one explicit spread — `setParams((p) => ({ ...p, page: p.page + 1 }))` — instead of a hand-rolled merge. - **A fail-closed isr gate** — `renderMode: 'isr'` plus a `searchParams` export is refused at boot: the isr cache is keyed by path (+tenant+locale), not query, so the first variant would be cached for every query — and the gate catches the re-exported spelling (`export { searchParams } from …`, the mirror-route pattern) too, not only the local declaration. - **A doctor rule** — a page that exports the schema but keeps reading the query with zero-arg `useSearchParams()` is flagged with the typed spelling.
+
+  Deliberate limits: array fields decode a single occurrence as a one-element array (link shape stays stable); `siblingApps` routes stay untyped (their schemas live in a foreign compile graph); `static` pages see the defaults at build time and decode live on the client.
+
+  Why the golden churn is compatible: `VoltroRouteUrl` gains a type parameter with a DEFAULT (`<TSearch = unknown>`), so every existing bare `VoltroRouteUrl` spelling still compiles, and the new brand member is an OPTIONAL phantom property of type `unknown` — assignability in both directions is unchanged. `withQuery`'s parameter for the untyped case is strictly WIDER than before (adds `boolean` and array values); no call that compiled stops compiling.
+
+### Fixed
+
+- **@voltro/cli** — `voltro agents-md`'s copied `agent-docs/` mirror no longer keeps orphaned modules across a re-seed.
+
+  The copy fallback (projects where `@voltro/cli` isn't resolvable) merged into an existing `agent-docs/` directory: when a module was renamed upstream (`plugins/versioning.md` → `plugins/row-history.md`), a `--force` re-seed brought the new file and left the old one sitting beside it — a stale generated doc teaching a package name that no longer exists, which is exactly the claim≠code drift the guide exists to prevent. The mirror is wholly framework-owned, so a re-seed now replaces it (the generator prunes its own output dir the same way).
+- **@voltro/cli** — `voltro check`'s observed-diff footer now accounts for every declared procedure, and no result line states a verdict without the count it is a verdict about.
+
+  Two defects, both found by readers doing arithmetic on the output:
+
+  - The diff computes TWO kinds of blindness — a procedure that never ran, and one that ran with no table access recorded — and the printer named only the first. The printed counts came out short of the total, with no way to tell an unshown category from a defect in `check` itself. The buckets are now derived from the result type, so a third one cannot be added without the label map failing to compile, and a partition that does not close prints as such instead of quietly under-counting. - `no declared/observed mismatches` was a bare verdict sitting under its denominator, and was quotable — and quoted — without it, as a clean bill of health for a surface where almost nothing had been exercised. Every result line now carries its scope (`no declared/observed mismatch among the 12 that ran`), and at zero coverage the section reports the ABSENCE of a comparison (`nothing was compared — a declaration is only checked against a procedure that RAN`) rather than the absence of findings. The two are different facts and only one of them is evidence.
+- **@voltro/cli** — An `isr` render no longer sees the requesting visitor's credentials — in `voltro dev` and `voltro start` alike.
+
+  An isr page's HTML is cached under tenant+locale and served to every visitor inside the revalidate window, but the render itself ran with the FULL request: loaders received the session cookie, and `ctx.query` was bound to it. A loader that read subject-scoped data on an isr page therefore cached the first visitor's data and served it to everyone — cache poisoning by construction.
+
+  The render boundary is fail-closed now: before an isr render runs, the cookie jar (except `voltro:locale`), the `authorization` header and every `x-voltro-*` header are stripped, for the loaders, `ctx.query` AND the `useServerRequest()` snapshot. What survives is exactly what the cache key and locale resolution read: `x-tenant`, `accept-language`, and the locale cookie — so a `de` visitor's fill still lands under the `de` key. One shared helper (`isrCredentialStrip.ts`), called by both boot paths, so dev renders isr anonymously exactly as production does — a page can no longer look personalised in dev and silently serve shared HTML in production.
+
+  Behavioural consequence, on purpose: a subject-reading loader on an isr page now gets the anonymous answer. A page whose loader needs the signed-in subject belongs on `renderMode: 'ssr'`.
+- **@voltro/cli, @voltro/runtime** — **`voltro serve` registers plugin rpc routes again — every plugin-contributed procedure answered `Unknown request tag` in production while `voltro dev` registered all of them.** The serve path mirrored dev's plugin-route block by hand and mirrored exactly half of it: the collision check ran (so nothing warned) and the returned routes were discarded as a bare expression statement, never reaching the buckets the rpc registry is built from. Every plugin route was indistinguishable from a tag that never existed — `useUpload`'s storage tags, presence, every inspect-less plugin rpc — while the app's own procedures answered normally, so the registry looked alive.
+
+  Three changes, each aimed at the way this stayed invisible:
+
+  - Both boot paths now call ONE shared builder (`mergePluginRoutesInto`) whose buckets are required parameters — a returned list can be discarded by a statement that typechecks; a function you cannot call without handing it the sinks cannot have its effect dropped. A reachability test drives a real socket with a plugin tag and an invented-tag control, and a source pin keeps the helper pair from being reassembled by hand in either path. - The boot line `plugin routes registered` prints WHENEVER plugins are installed, count included — zero is a finding, and silence is how this shipped. `voltro check` against a running server now also diffs source-declared tags against the live registry (`declared vs live:`), and its offline manifest includes plugin routes, which it previously did not. - Every `Defect` frame the server sends is now also a server log line (`rpc defect sent to client`, ws and http rpc). The defect string used to exist only inside the WebSocket frame — visible in whoever's browser console, invisible to the operator whose server produced it.
+
+---
+
 ## [0.51.0] — 2026-08-24
 
 ### ⚠ BREAKING

package/dist/form.d.ts

@@ -0,0 +1,127 @@
+import { Schema } from 'effect';
+
+export declare interface FieldDescriptor {
+    /** Property name on the input object. */
+    readonly name: string;
+    /** Human label — the Schema `title` annotation, else the humanised name. */
+    readonly label: string;
+    /** The default widget kind. `'custom'` ⇒ supply a render-prop. */
+    readonly widget: WidgetKind;
+    /** True when the property must be present (in JSON-Schema `required`). */
+    readonly required: boolean;
+    /** True when the value may be `null` (e.g. `Schema.NullOr`). */
+    readonly nullable: boolean;
+    /** Present for closed value sets (a `Schema.Literal` union → `select`). */
+    readonly options?: ReadonlyArray<FieldOption>;
+    /** The resolved JSON-Schema node — carries `maxLength` / `pattern` /
+     *  `minimum` / `format` / `description` for widgets + validation hints. */
+    readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+
+export declare interface FieldErrors {
+    readonly [field: string]: string;
+}
+
+export declare interface FieldOption {
+    readonly value: string;
+    readonly label: string;
+}
+
+/** DOM id of the JSON script the 422 re-render embeds (survives the
+ *  `interactive:'none'` strip — it is neither `type="module"` nor `src`). */
+export declare const FORM_FLASH_SCRIPT_ID = "__voltro_form_flash__";
+
+/** Hidden field carrying the form's instance key (multi-form pages). */
+export declare const FORM_KEY_FIELD = "__voltro_form";
+
+/** URL prefix the web listener mounts the no-JS endpoint under. */
+export declare const FORM_PATH_PREFIX = "/form/";
+
+/** Hidden field carrying the declared success-redirect path. */
+export declare const FORM_REDIRECT_FIELD = "__voltro_redirect";
+
+/** The path a native `<AutoForm>` POST goes to. */
+export declare const formActionPath: (mutationTag: string) => string;
+
+/**
+ * Convert posted form entries into the input object the mutation's schema
+ * decodes — the shape `validateFields` (and the RPC payload) expects.
+ *
+ * Mapping rules (the documented contract):
+ * - **checkbox/switch**: present → `true`, absent → `false`. A native POST
+ *   omits an unchecked checkbox entirely, so absence is data, not a gap.
+ * - **number**: `Number(raw)`; `''` → the field is omitted (`undefined`), so
+ *   an optional number stays absent and a required one reports "missing"
+ *   instead of silently becoming `0`.
+ * - **date/datetime**: the string passes through (the schema's encoded side);
+ *   `''` → omitted, same reasoning as number.
+ * - **arrays** (multi-select): `getAll` semantics — every entry under the key,
+ *   items converted per the array's item type (number items → `Number`).
+ * - **unknown keys are dropped**: only names the schema declares are mapped,
+ *   so protocol fields (`__voltro_form`, …) never reach the input object —
+ *   the server rejects undeclared fields, and a hidden bookkeeping field must
+ *   not turn every no-JS submit into a validation error.
+ */
+export declare const formDataToInput: (schema: Schema.Schema.Any, entries: Iterable<FormEntry>) => Record<string, unknown>;
+
+/** One posted entry. File entries must be filtered out by the caller —
+ *  uploads are a declared limit of the no-JS path. */
+export declare type FormEntry = readonly [name: string, value: string];
+
+/**
+ * The error/values payload a failed no-JS form POST carries back into the
+ * 422 re-render. Keyed by `formKey` so a page with several forms re-fills
+ * only the one that was submitted. The SSR render passes it through the
+ * server-request context; the client reads the same payload back off the
+ * `#__voltro_form_flash__` JSON script, so a late-hydrating page shows the
+ * identical state (no mismatch, no vanished errors).
+ */
+export declare interface FormFlashPayload {
+    /** The submitted form's key — `<AutoForm formKey>` or its mutation tag. */
+    readonly formKey: string;
+    /** The mapped input values as posted (pre-decode), to re-fill the fields. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** First error per field — the `validateFields` shape. */
+    readonly errors: Readonly<Record<string, string>>;
+    /** A non-field error (the RPC refused after valid input: guard, server). */
+    readonly formError?: string;
+}
+
+/**
+ * Derive table COLUMNS from a query's output `Schema` — an
+ * `Schema.Array(Schema.Struct({...}))`. Drills into the array's element and maps
+ * its properties (same descriptor shape as `schemaToFields`, reused for
+ * `<DataTable>` cells). Returns `[]` if the output isn't an array of objects.
+ */
+export declare const schemaToColumns: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
+
+/**
+ * Derive the ordered field list for a `Schema.Struct` input. Returns `[]` for a
+ * schema with no object properties (a scalar, `Schema.Void`, or anything
+ * `JSONSchema.make` cannot represent).
+ */
+export declare const schemaToFields: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
+
+/**
+ * Validate `values` against an input `schema`, returning the first error per
+ * top-level field (`{ [field]: message }`) — the shape `<AutoForm>` and custom
+ * widgets render inline. Uses the same `decodeUnknownEither` + `ArrayFormatter`
+ * path the store's `.validate(...)` uses, so client and server speak ONE
+ * schema. `{ errors: 'all' }` collects every field's error in one pass.
+ *
+ * Client-side validation is non-authoritative UX — the server re-validates the
+ * same schema on the mutation; this just gives instant inline feedback.
+ */
+export declare const validateFields: (schema: Schema.Schema.Any, values: unknown) => ValidationResult;
+
+export declare interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: FieldErrors;
+}
+
+/** The default widget kinds the framework can render from a schema. `'custom'`
+ *  means "no default widget" — the field needs a render-prop (a nested object,
+ *  an array of objects, or a multi-branch union). Mirrors innovation/01's set. */
+export declare type WidgetKind = 'text' | 'textarea' | 'number' | 'checkbox' | 'switch' | 'select' | 'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' | 'file' | 'hidden' | 'custom';
+
+export { }

package/dist/form.js

@@ -0,0 +1,2 @@
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "./formData-Bw07C0wr.js";
+export { c as FORM_FLASH_SCRIPT_ID, i as FORM_KEY_FIELD, o as FORM_PATH_PREFIX, n as FORM_REDIRECT_FIELD, e as formActionPath, a as formDataToInput, t as schemaToColumns, r as schemaToFields, s as validateFields };

package/dist/formData-Bw07C0wr.js

@@ -0,0 +1,155 @@
+import { JSONSchema as e, Schema as t } from "effect";
+import { ArrayFormatter as n } from "effect/ParseResult";
+//#region src/schemaFields.ts
+var r = "#/$defs/", i = (e) => e.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/\s+/g, " ").trim().replace(/^./, (e) => e.toUpperCase()), a = (e, t) => {
+	let n = e;
+	for (let e = 0; e < 8; e += 1) {
+		let e = n.$ref;
+		if (typeof e != "string" || !e.startsWith(r)) return n;
+		let i = t[e.slice(8)];
+		if (!i || typeof i != "object") return n;
+		n = i;
+	}
+	return n;
+}, o = (e) => {
+	if (!e || typeof e != "object") return !1;
+	let t = e;
+	if (t.type === "null" || t.const === null) return !0;
+	let n = t.enum;
+	return Array.isArray(n) && n.length === 1 && n[0] === null;
+}, s = (e, t) => {
+	let n = e.type;
+	if (Array.isArray(n) && n.includes("null")) {
+		let t = n.filter((e) => e !== "null");
+		return {
+			node: {
+				...e,
+				type: t.length === 1 ? t[0] : t
+			},
+			nullable: !0
+		};
+	}
+	for (let n of ["anyOf", "oneOf"]) {
+		let r = e[n];
+		if (!Array.isArray(r)) continue;
+		let i = r.filter((e) => !o(e));
+		if (i.length !== r.length) return i.length === 1 ? {
+			node: a(i[0], t),
+			nullable: !0
+		} : {
+			node: {
+				...e,
+				[n]: i
+			},
+			nullable: !0
+		};
+	}
+	return {
+		node: e,
+		nullable: !1
+	};
+}, c = (e) => e.map((e) => ({
+	value: String(e),
+	label: i(String(e))
+})), l = (e) => {
+	let t = e.enum;
+	if (Array.isArray(t) && t.length > 0) return {
+		widget: "select",
+		options: c(t)
+	};
+	let n = e.type, r = Array.isArray(n) ? n.find((e) => e !== "null") : n, i = e.format;
+	switch (r) {
+		case "string": return i === "date" ? { widget: "date" } : i === "date-time" ? { widget: "datetime" } : { widget: "text" };
+		case "integer":
+		case "number": return { widget: "number" };
+		case "boolean": return { widget: "checkbox" };
+		case "array": return { widget: "multi-select" };
+		default: return { widget: "custom" };
+	}
+}, u = (e, t, n) => Object.entries(e).map(([e, r]) => {
+	let { node: o, nullable: c } = s(a(r, n), n), u = a(o, n), { widget: d, options: f } = l(u);
+	return {
+		name: e,
+		label: i(e),
+		widget: d,
+		required: t.has(e),
+		nullable: c,
+		...f ? { options: f } : {},
+		jsonSchema: u
+	};
+}), d = (t) => {
+	try {
+		return e.make(t);
+	} catch {
+		return;
+	}
+}, f = (e) => {
+	let t = d(e);
+	if (t === void 0) return [];
+	let n = t.$defs ?? {}, r = a(t, n), i = r.properties;
+	return i ? u(i, new Set(Array.isArray(r.required) ? r.required : []), n) : [];
+}, p = (e) => {
+	let t = d(e);
+	if (t === void 0) return [];
+	let n = t.$defs ?? {}, r = a(t, n);
+	if (r.type !== "array") return [];
+	let i = r.items;
+	if (!i || typeof i != "object") return [];
+	let o = a(i, n), s = o.properties;
+	return s ? u(s, new Set(Array.isArray(o.required) ? o.required : []), n) : [];
+}, m = (e, r) => {
+	let i = t.decodeUnknownEither(e, { errors: "all" })(r);
+	if (i._tag === "Right") return {
+		valid: !0,
+		errors: {}
+	};
+	let a = {};
+	for (let e of n.formatErrorSync(i.left)) {
+		let t = e.path.length === 0 ? "" : String(e.path[0]);
+		t !== "" && !(t in a) && (a[t] = e.message);
+	}
+	return {
+		valid: !1,
+		errors: a
+	};
+}, h = "__voltro_form_flash__", g = "/form/", _ = (e) => `${g}${encodeURIComponent(e)}`, v = "__voltro_form", y = "__voltro_redirect", b = (e) => {
+	let t = Number(e);
+	return Number.isNaN(t) ? e : t;
+}, x = (e) => {
+	let t = e.jsonSchema.items;
+	if (!t || typeof t != "object") return;
+	let n = t.type;
+	return typeof n == "string" ? n : void 0;
+}, S = (e, t) => {
+	switch (e.widget) {
+		case "number": return t === "" ? void 0 : b(t);
+		case "date":
+		case "datetime": return t === "" ? void 0 : t;
+		default: return t;
+	}
+}, C = (e, t) => {
+	let n = /* @__PURE__ */ new Map();
+	for (let [e, r] of t) {
+		let t = n.get(e);
+		t === void 0 ? n.set(e, [r]) : t.push(r);
+	}
+	let r = {};
+	for (let t of f(e)) {
+		let e = n.get(t.name);
+		if (t.widget === "checkbox" || t.widget === "switch") {
+			r[t.name] = e !== void 0;
+			continue;
+		}
+		if (t.widget === "multi-select") {
+			let n = x(t), i = e ?? [];
+			r[t.name] = n === "number" || n === "integer" ? i.filter((e) => e !== "").map(b) : i.filter((e) => e !== "");
+			continue;
+		}
+		if (e === void 0) continue;
+		let i = S(t, e[0]);
+		i !== void 0 && (r[t.name] = i);
+	}
+	return r;
+};
+//#endregion
+export { _ as a, p as c, y as i, f as l, v as n, C as o, g as r, m as s, h as t };

package/dist/index.d.ts

@@ -961,6 +961,22 @@ export declare type FilterKind = 'text' | 'select' | 'multi-select' | 'number-ra
  *  input field → one FilterDescriptor. Pure. */
 export declare const filtersFromSchema: (schema: Schema.Schema.Any) => ReadonlyArray<FilterDescriptor>;
 
+/** DOM id of the JSON script the 422 re-render embeds (survives the
+ *  `interactive:'none'` strip — it is neither `type="module"` nor `src`). */
+export declare const FORM_FLASH_SCRIPT_ID = "__voltro_form_flash__";
+
+/** Hidden field carrying the form's instance key (multi-form pages). */
+export declare const FORM_KEY_FIELD = "__voltro_form";
+
+/** URL prefix the web listener mounts the no-JS endpoint under. */
+export declare const FORM_PATH_PREFIX = "/form/";
+
+/** Hidden field carrying the declared success-redirect path. */
+export declare const FORM_REDIRECT_FIELD = "__voltro_redirect";
+
+/** The path a native `<AutoForm>` POST goes to. */
+export declare const formActionPath: (mutationTag: string) => string;
+
 export declare interface FormBinding<Input, Output> {
     /** Ordered, render-agnostic field list derived from the input schema. */
     readonly fields: ReadonlyArray<FieldDescriptor>;
@@ -972,6 +988,9 @@ export declare interface FormBinding<Input, Output> {
     readonly pending: boolean;
     /** The mutation's typed failure, if the last submit threw. */
     readonly submitError: unknown | undefined;
+    /** A form-level (non-field) error carried in from a failed no-JS POST —
+     *  the RPC refused after valid input. Cleared by the next submit/reset. */
+    readonly formError: string | undefined;
     readonly data: Output | undefined;
     readonly setValue: (name: string, value: unknown) => void;
     readonly setValues: (patch: Partial<Input>) => void;
@@ -981,6 +1000,50 @@ export declare interface FormBinding<Input, Output> {
     readonly submit: () => Promise<Output | undefined>;
 }
 
+/**
+ * Convert posted form entries into the input object the mutation's schema
+ * decodes — the shape `validateFields` (and the RPC payload) expects.
+ *
+ * Mapping rules (the documented contract):
+ * - **checkbox/switch**: present → `true`, absent → `false`. A native POST
+ *   omits an unchecked checkbox entirely, so absence is data, not a gap.
+ * - **number**: `Number(raw)`; `''` → the field is omitted (`undefined`), so
+ *   an optional number stays absent and a required one reports "missing"
+ *   instead of silently becoming `0`.
+ * - **date/datetime**: the string passes through (the schema's encoded side);
+ *   `''` → omitted, same reasoning as number.
+ * - **arrays** (multi-select): `getAll` semantics — every entry under the key,
+ *   items converted per the array's item type (number items → `Number`).
+ * - **unknown keys are dropped**: only names the schema declares are mapped,
+ *   so protocol fields (`__voltro_form`, …) never reach the input object —
+ *   the server rejects undeclared fields, and a hidden bookkeeping field must
+ *   not turn every no-JS submit into a validation error.
+ */
+export declare const formDataToInput: (schema: Schema.Schema.Any, entries: Iterable<FormEntry>) => Record<string, unknown>;
+
+/** One posted entry. File entries must be filtered out by the caller —
+ *  uploads are a declared limit of the no-JS path. */
+export declare type FormEntry = readonly [name: string, value: string];
+
+/**
+ * The error/values payload a failed no-JS form POST carries back into the
+ * 422 re-render. Keyed by `formKey` so a page with several forms re-fills
+ * only the one that was submitted. The SSR render passes it through the
+ * server-request context; the client reads the same payload back off the
+ * `#__voltro_form_flash__` JSON script, so a late-hydrating page shows the
+ * identical state (no mismatch, no vanished errors).
+ */
+export declare interface FormFlashPayload {
+    /** The submitted form's key — `<AutoForm formKey>` or its mutation tag. */
+    readonly formKey: string;
+    /** The mapped input values as posted (pre-decode), to re-fill the fields. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** First error per field — the `validateFields` shape. */
+    readonly errors: Readonly<Record<string, string>>;
+    /** A non-field error (the RPC refused after valid input: guard, server). */
+    readonly formError?: string;
+}
+
 export declare interface FrameworkRuntimes {
     /** Look up an api handle (runtime + cache) by name. Throws if no such api was mounted. */
     readonly get: (name: string) => ApiHandle;
@@ -1010,6 +1073,32 @@ export declare const getMutationNotifier: () => MutationNotifier | undefined;
 /** Read the current feed. Newest-first; up to MAX_MUTATIONS entries. */
 export declare const getMutations: () => ReadonlyArray<MutationEvent>;
 
+/**
+ * A process-wide singleton React context, pinned on the global symbol registry.
+ *
+ * WHY this exists: the SSG prerender (`voltro build`) loads the framework
+ * through TWO separate module instances — the renderer comes in via Vite's
+ * `ssrLoadModule('@voltro/web/ssr')` (Vite-transformed) while a page's own
+ * framework import is externalised to Node — so a plain `createContext()`
+ * in a shared module is evaluated twice and yields two DISTINCT context
+ * objects. The `<Router>` provider then holds one while the page's
+ * `useLocation()` reads the other, which throws "Router hooks must be used
+ * inside <Router>." The same duplicate-instance hazard shows up wherever a
+ * deployment ends up with two copies of a package (the classic dual-package
+ * hazard, monorepo hoisting quirks, separate SSR vs client bundles).
+ *
+ * Resolving every context through `Symbol.for(...)` on `globalThis` makes all
+ * module copies share ONE instance, so provider and consumer can never diverge.
+ * A duplicated copy of THIS helper is harmless — both copies hit the same
+ * global registry entry.
+ *
+ * Lives in @voltro/client (the lowest React-carrying package) so both
+ * @voltro/web and @voltro/ui reach it without a cycle; the key prefix keeps
+ * its historical spelling on purpose — a mixed dist/src world must resolve
+ * to the same registry entries.
+ */
+export declare const globalContext: <T>(key: string, initial: T) => Context<T>;
+
 /** Is this the framework's `Unauthenticated`? Matched on `_tag`, the wire
  *  contract, rather than on an instance — the error crosses a package boundary
  *  and may be re-created by the decoder. */
@@ -1832,6 +1921,29 @@ export declare type SequenceResult<Ctx> = {
     }>;
 };
 
+export declare const ServerRequestContext: Context<ServerRequestContextValue | null>;
+
+export declare interface ServerRequestContextValue {
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Raw request URL as it came off the wire (path + query). Useful
+     *  for SSR pages that need to read `?q=…` style search params
+     *  without touching anything client-only. Empty string for build-
+     *  time SSG renders where there is no incoming request. */
+    readonly url: string;
+    /** Present ONLY on the 422 re-render of a failed no-JS form POST:
+     *  the submitted values + field errors, keyed by formKey. Travels on
+     *  the EXISTING request context deliberately — a dedicated provider
+     *  would add a fiber fork the client boot does not have, and every
+     *  ancestor arity difference shifts every useId in the app. */
+    readonly formFlash?: FormFlashPayload;
+}
+
+export declare const ServerRequestProvider: ({ value, children, }: {
+    readonly value: ServerRequestContextValue;
+    readonly children: ReactNode;
+}) => ReactNode;
+
 /** Register (or clear) the app-wide notifier that `notify:` routes to. Call once
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
@@ -3048,8 +3160,27 @@ export declare interface UseFormBindingOptions<Input> {
     readonly schema?: Schema.Schema.Any;
     /** Initial field values. */
     readonly defaults?: Partial<Input>;
+    /** The failed no-JS POST's payload for THIS form (`useFormFlash` from
+     *  @voltro/web resolves it, SSR and client alike). When present it seeds
+     *  the initial values + field errors, so the 422 re-render shows the
+     *  submitted state server-side and hydrates to the identical state. */
+    readonly flash?: FormFlashPayload | undefined;
 }
 
+/**
+ * The failed-no-JS-POST payload for ONE form, or `undefined`.
+ *
+ * On the server (the 422 re-render) it comes off the request context; on the
+ * client it is read back from the `#__voltro_form_flash__` JSON script the
+ * same response embedded. Both carry the SAME payload, so a page that loads
+ * its bundle after a native submit hydrates to exactly the server-rendered
+ * state — errors visible, values filled, no mismatch.
+ *
+ * Keyed: only the form whose `formKey` was submitted receives the payload —
+ * two `<AutoForm>`s on one page re-fill only the one that POSTed.
+ */
+export declare const useFormFlash: (formKey: string) => FormFlashPayload | undefined;
+
 /** The field shape a `<AutoForm mutation=…>` will render — from the mutation's
  *  input Schema. Use it to render a matching skeleton while anything the form
  *  depends on is still loading. */
@@ -3198,6 +3329,8 @@ export declare interface UseSequenceResult {
     readonly failedStep: string | undefined;
 }
 
+export declare const useServerRequest: () => ServerRequestContextValue | null;
+
 export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input: Readonly<Record<string, unknown>>, options: SubscriptionOptions<T> & {
     readonly initialSnapshot: T;
 }): SubscriptionStateWithFallback<T>;