@voltro/ui-shadcn 0.67.0 → 0.68.0

package/CHANGELOG.md

@@ -39,6 +39,221 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.68.0] — 2026-09-09
+
+### ⚠ BREAKING
+
+- **@voltro/devtools-ui, @voltro/cli, @voltro/plugin-queue** — The shared inspect pages now show reverse-ETL dead letters and replica handoff health, flag kill-switch history, and governance subject-graph limitations. Migration: provide `CdcOutPage.useDeadLetter`, `FlagsPage.useAudit`, and `GovernancePage.useSubjectGraph` as typed data-source hooks; preserve the complete CDC outbox/handoff response and handle `MetricRow.kind: 'plugin'`. Metrics accept both API invocation windows and web registry snapshots. Both dashboards share task navigation and add plugin inventory, data expectations, compute budgets, experiments, invariant checks, and agent-tool inventory. Production now exposes the same standing registries as development with process-scoped observation metadata. Schedules add bounded backfill with explicit confirmation and preserve HTTP 409 outcomes; hosts must supply `SchedulesPage.useBackfill`. Workflow run details support resuming from a recorded step, and the Flow view validates queued payloads and confirms intent retry/discard. Optional hooks are `WorkflowsPage.useResumeFromStep`, `useIntentValidation`, and `useOperateIntent`; both shipped hosts wire them. The shared dev/serve inspect router now reaches step resume, redrive, discard and synchronous update instead of returning 404.
+
+  The Data explorer row detail now offers last-write audit evidence through optional `DataViewerPage.useProvenance`, with separate missing-row, unattributed and unavailable states. Shared workflow controls fit narrow viewports and use theme-aware status text.
+
+  App metrics now include the full process metric registry with label/type filters and distribution details via `/_voltro/inspect/metrics/registry`. Hosts can supply `MetricsPage.useRegistry`; both dashboards do. Nonfinite histogram and summary readings remain explicit in JSON. Scope notices retain process identity even for a complete single-process answer, and row detail uses a keyboard-accessible native dialog with readable values for read-only columns.
+
+  Both dashboards add the transactional outbox queue, retained delivery attempts and a confirmed one-attempt resend with a required reason. Custom capability bags must provide `canResendOutbox`; privileged history reads use `canViewAuditLog`. The shared dev/serve routes enforce read and write credentials and omit payload/response bodies.
+
+  Mail preview now requires `Capabilities.canPreviewMail`; custom hosts must derive it from operator access and the app's inspect write credential. Mail views retain process/declaration scope, show failed reads explicitly and discard a preview that completes after its template or props changed.
+
+  Storage access writes now require `Capabilities.canManageStorage`. Derive it from operator authorization and the app's inspect write credential; read-only users can inspect grants but cannot create or revoke them. Plugin panels choose effective instances and clear previous selections' read/action state.
+
+  Queue inspection replaces `connected` with `producerSelected`: whether the selected instance owns the app-wide outbox/CDC producer slot. It is not a broker-health probe. Custom `QueueData` producers must provide `producerSelected` and remove `connected`.
+
+  Both dashboards compare remote SQL schemas through the real planner, with immediate results and explicit fetch failures. Dev and production wire the same comparison service; results are bounded to 20 per process. Custom hosts must provide `canCompareMigrationEnvironments` and return `CrossEnvDiffSnapshot` from `MigrationsPage.useCompareCrossEnv` and `InspectManifestApi.compareCrossEnv`. Cloud admins may compare with both inspect credentials; schema mutations remain owner-restricted.
+
+  Plugin snapshots include `httpRoutes` (method and path only). Custom inventory producers must provide this array. Pass `PluginsPage.appUrl` to link literal GET routes under the inspected app, including configured OpenAPI and Swagger mounts. Links never contain inspect credentials.
+
+  Data row pages preserve empty-page counts, upstream observation scope and connection state. `DataRowsPage.syncState` optionally reports `live` or `reconnecting`; disconnected views refresh snapshots every 15 seconds and reconcile after reconnect. Cloud commits page rows and status atomically and invalidates credential or organization changes. Local streams send the per-app bearer as an Authorization header on every handshake; the SSE proxy no longer accepts a shared stream cookie.
+
+  Cloud inspect schemas retain upstream scope, origin, completeness and capture time, including array-shaped web metrics. `DataSource.observation` optionally carries this envelope alongside a payload; `MetricsPage` supports it. The five standing-inspection pages display the sampled process and scope rather than only their collection timestamp.
+
+  Cloud RPCs preserve observation envelopes, optional log scopes and event delivery declarations. Cluster inspection maps actual scheduler claim IDs and owners. Local reads serialize refreshes and clear app/credential-stale snapshots; fleet responses require assembly evidence and retain departed replicas. Web metric arrays use the same JSON-safe nonfinite readings as the registry; custom hosts must accept `MetricReading` in metric values and histogram boundaries. Cloud and local operating surfaces use compact headings, responsive log/cluster rows and unobstructed mobile controls.
+
+  The inspector combines snapshot refresh and access guidance in a compact toolbar; expand the read-only notice to configure credentials. Log filters retain associated visible labels after entry. Cache hit rate stays unmeasured until the first request, while hit/miss counters remain zero. Cluster warnings reuse the shared callout icon.
+
+  **`voltro update` carries you across this** — codemod `0.68.0/01_dashboard-inspection-evidence`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.68.0).
+- **@voltro/runtime, @voltro/voltro** — Outbox resends record an independent request timestamp, so manual attempts without an actor ID remain manual. Re-arming uses a conditional store update to refuse concurrent worker claims or competing requests. Migration: custom `makeOutboxFacade` store adapters must provide `updateMany` instead of `update`; the framework DataStore already does. Boot or `db apply` reconciles the nullable `resendRequestedAt` queue column.
+
+  **`voltro update` carries you across this** — codemod `0.68.0/01_dashboard-inspection-evidence`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.68.0).
+
+### Added
+
+- **@voltro/ui-shadcn** — `Dialog` accepts a typed native dialog ref for `showModal()` and `close()`. Its props retain all `DialogHTMLAttributes<HTMLDialogElement>` and add React's native element ref; no existing attribute is removed or narrowed.
+- Inspect declared rate-limit rules, RPC and HTTP decisions, SQL binding and fail-open observations in both dashboards, with explicit plugin-instance selection and process scope. Custom rate-limit stores can report unchecked requests using `RateLimitDecision.failOpenReason` (`unbound` or `store-error`).
+- **@voltro/protocol, @voltro/runtime, @voltro/client, @voltro/web, @voltro/cli** — `voltro dev` tells you when the api client a page loaded is not the one the server binds, naming the procedures that disagree.
+
+  Every other freshness mechanism here predicts staleness from source bytes: hash what the browser's client is built from, re-bundle when it moves. Those have twice hashed a set smaller than what the browser actually loads, and the symptom each time was silence — a client decoding against an older schema drops the fields it does not know, and an unknown field is not a decode error, it is simply absent. This asks the question from the other end. The server publishes per-rpc-tag digests of the schemas it bound, the client computes the same over the group it loaded, and a disagreement is one console warning plus a `runtime.surface-mismatch` diagnostic. A gap in an import walk, an optimizer that did not re-run, a service worker and a stale cache all look the same from there: different schemas.
+
+  The digest is a STRUCTURAL walk of the schema AST, and the obvious implementation would have been useless. `String(schema.ast)` on a `Schema.TaggedError` renders the declared name, so two fields added to a typed error leave it identical — a check built on it would have passed cleanly through the incident it exists to catch. Tests pin that a field added to a tagged error, a tagged class, a nested struct, a union, a tuple and a record each move the digest, so an Effect version that breaks the walk fails loudly rather than going quiet.
+
+  Two limits stated rather than hidden. A recursive schema (`Schema.suspend`) renders opaque: following it would not terminate, so a field added inside one is invisible, though everything around it still counts. And a procedure only the CLIENT has is never reported — a browser group legitimately omits server-only routes, and a check that cries wolf about the normal case is one people switch off.
+
+  Dev only, by an asymmetry that is deliberate: `voltro serve` ships a built bundle where this staleness cannot arise from a dep optimizer, and a rolling deploy would make a transient mismatch normal.
+
+  `apiSurface: compatible` — the only replaced golden lines in `@voltro/client` and `@voltro/web` are one member added to the `ClientDiagnosticKind` union (`runtime.surface-mismatch`). Every existing member is unchanged, the framework is the only producer, and a reader that does not know the new kind sees one more event it can ignore. Only a switch exhaustive over the vocabulary needs an arm. `@voltro/web` is listed because it re-exports that type and its golden carries the same line.
+- **@voltro/ui-shadcn** — Shared Signal opener classes unify responsive headlines, sublines and CTA rows across the Framework landing, Cloud landing and Docs index, including secondary-link and primary-button interactions.
+- **@voltro/testing** — `ctx.asSubject(subject)` and `ctx.asTenant(tenantId)` return a re-scoped test context instead of passing one to a block — for a test with two actors alive at once.
+
+  `withSubject` nests, which reads well for "write as A, then assert B cannot see it" and badly for a conflict: two editors on one row, a lock contest, an undo the other person's write must refuse. Those want two named contexts and interleaved calls, and a block per alternation buries the sequence under test. Both forms call the same builder, so a context held side by side cannot differ from one handed to a callback: one store, one event bus, one cache, one clock.
+
+  The `store` option's documentation now says the seed is COPIED. Passing one seed to two `makeTestContext` calls reads like sharing a store and does not share one — each context builds its own from the rows, which is what keeps two tests in a file independent.
+
+  A test pins the trap that made this worth adding: spreading the context to replace `request.subject` moves the field you read and nothing that decides a write. `ctx.store` was wrapped for the original subject, so tenant scoping, row filters and the `audit()` stamp keep resolving to the first identity, and a write made that way lands with the wrong `updatedBy` — letting a test assert that one person touched a row while the row records another.
+
+### Fixed
+
+- **@voltro/cli** — Server bundles no longer wrap every closure in an `Object.defineProperty`.
+
+  They were built with `minify: true, keepNames: true`. esbuild implements `keepNames` by emitting `__name(fn, "original")`, and `__name` is an `Object.defineProperty` on the function object. For a function DEFINITION that runs once; for a function EXPRESSION created inside a hot path it runs on every instance, and defining a property that way moves the instance's own properties out of its in-object slots into a separate `PropertyArray`.
+
+  Measured on the memory fixture with 200 open subscriptions, `heapUsed` after a forced GC:
+
+  minify + keepNames 168.0 KB/subscription, idle 49319 KB identifiers unmangled, no keepNames 135.4 KB/subscription, idle 44767 KB
+
+  A heap-snapshot diff of the same pair carries the fingerprint of the mechanism in its object counts — +28 200 `closure` nodes against +25 982 `array (object properties)` nodes, for the same 200 subscriptions.
+
+  The reason `keepNames` was there is unchanged and still correct: Effect's tags, error `name`s and the boot-refusal marker are read as STRINGS across the bundle boundary, and a mangled class name turns a precise refusal into an anonymous one. What was wrong was the estimate written beside it — "it costs a few percent of the saving" — which measured BYTES while the bill was paid in HEAP, once per live subscription, for as long as the subscription lives.
+
+  So the names are kept by NOT mangling identifiers, which is what created the need for a wrapper in the first place. Whitespace and syntax minification still apply, so the parse-time property these bundles exist for survives: the serve bundle grows 6184 KB → 8388 KB on disk while the cold-boot `modules` phase moves 139 ms → 137 ms, inside the noise. The idle-heap saving alone exceeds the bytes added, before a single subscription exists.
+
+  It applies to the api SERVE bundle and nothing else, because the bill scales with how many closures a process holds ALIVE. The web start bundle and the middleware bundle serve per-request closures that are collected, not live subscriptions, so the swap bought them nothing — and applying it there overran the start-bundle byte budget by 45 %, which is how the scope was found. They keep `keepNames`, as does the browser bundle, where download bytes over a user's connection dominate.
+
+  `serverBundleMinify.test.ts` asserts that each exemption is still real — an exemption list that describes nothing reads like a considered decision — and that `apiBuild.ts` being exempted for its precompiled-entry bag does not quietly exempt the serve bundle in the same file.
+
+  `serveBundleBytes` is re-pinned 6.58 → 9.42 MB, and it is the only artefact budget that moves. What the budget protects is unchanged: the cold-boot `modules` phase measured 139 → 137 ms, inside the noise, on the very number minification was bought for. Bytes are the proxy there; parse time is the property.
+- **@voltro/cli** — `voltro build` on a web app now generates the rpc groups of the apis it imports.
+
+  `rpcGroup.generated.ts` is gitignored, so a clean clone has none — and only `voltro dev` and `voltro codegen` ever wrote it. The api branch of `voltro build` already self-healed its own, with the right reason recorded beside it: "a production build from a clean CI checkout is the exact case that never ran `voltro dev`". A WEB app imports that file from the API's package, where nothing was healing it, and the note two hundred lines up said so — "unlike the web case this file usually EXISTS, which is worse: a missing import fails the build" — while leaving the worse case alone.
+
+  What a user got instead was the bundler's:
+
+  Rolldown failed to resolve import "<pkg>/rpcGroup" from "<app>/.framework/main.tsx" If you do want to externalize this module explicitly add it to `build.rolldownOptions.external`
+
+  An internal path they did not write, and advice that is exactly wrong.
+
+  Only WORKSPACE apis: an external api is a URL with no local package, and `resolveApis` deliberately admits those.
+
+  Resolving the api's directory needs care, and the first attempt got it wrong in the quietest possible way. `${pkg}/package.json` is NOT resolvable when the package declares an `exports` map that omits it — which every voltro api does, because its map exists to expose `./rpcGroup`. That attempt caught the throw and continued, so the whole helper was a no-op that looked like it worked. It now resolves the subpath the bundler itself will use, and falls back to the workspace link (verifying the manifest's `name`) for the case this exists for: the file is not there yet, so every resolution into that package fails.
+- **@voltro/cli** — `voltro dev` re-bundles the browser's api client when a shared file a descriptor IMPORTS changes, not only when a descriptor file itself does.
+
+  The dev server pre-bundles the generated rpc group's whole import graph, and Vite never re-optimizes a pre-bundled dependency on a content change — so the framework fingerprints that graph itself. It fingerprinted the descriptor files alone. A descriptor declaring `error: [SomeTypedError]` whose class lives in a shared `lib/` file therefore left the fingerprint untouched when the class gained a field, and the browser kept decoding the failure against the older class, dropping the new fields with nothing reported anywhere: an unknown field decodes as absent, not as an error, so there is no exception, no warning, and no request in the api log to find.
+
+  Three mechanisms carried that blind spot — the stamp codegen embeds in the generated file, the across-boot force, and the in-session watcher — so the fix is one shared definition rather than a third patch. `valueImportGraph.ts` now owns what an import is and where a specifier leads; `browserSafetyGuard` reads the same resolver instead of its own copy. The in-session watcher watches the closure it hashes, since hashing the right set and watching a smaller one leaves the same gap.
+
+  Type-only imports stay out (they are erased), executor halves stay out (the browser never loads them, and including them would re-bundle on every handler edit), and `@voltro/*` stays out — in an install those are built JavaScript that stops the walk anyway.
+
+  `descriptorSourceFingerprint` is deliberately unchanged. It answers whether the generated FILE is stale, which the descriptor set settles: an edit inside a shared `lib/` file changes no import line and no rpc tag, so the group it would regenerate is byte-identical.
+- **@voltro/client** — `useConnectionStatus` no longer causes a React hydration mismatch on an SSR page.
+
+  It passed `getSnapshot` as `useSyncExternalStore`'s SERVER reader as well as its client one, so the server rendered whatever the live recovery coordinator held at that instant while the browser's hydration render read a coordinator that had already moved. React discards the server markup for that subtree and re-renders it on the client — the SSR benefit gone — and reports it only as a console error in a browser.
+
+  Both readers now agree on a frozen boot snapshot (`INITIAL_RECOVERY_SNAPSHOT`, exported from `@voltro/client`), and React swaps to the live value on the first commit after hydration, so nothing is lost but the mismatch. `navigator.onLine` went through the same door for the same reason.
+- **@voltro/cli** — Three things `voltro dev` did silently.
+
+  **The dashboard auto-launch skipped without a word.** The launch was `if (resolveDashboardAppPath(root)) { … }` with no `else`, so a project that has never installed `@voltro/dashboard` — a separate package — watched the documented auto-launch not happen and learned nothing, while the same absence reached through `voltro dashboard` printed the exact install line. The boot prints that same sentence once now, from one constant both callers read, and stays quiet when `VOLTRO_DASHBOARD=off` or `--disable-dashboard` says the developer has already declined.
+
+  The launcher can also decline for five reasons of its OWN — each carrying a `reason`, all five dropped — so "it is installed and it did not come up" had no answer either, on the console or in the log file. A non-TTY stdout (a process manager, a piped run, CI) skips the launch by design, and by design is not the same as unexplained. The reason is logged at `debug`: three of the five are the developer's own decision or a peer process already doing the work, so a console line would be noise, but the log file answers the question when it is asked.
+
+  **A web app got no inspect token at all.** The mint ran on the api boot path only, so in a project with both, the api had a token and demanded it while the web app was fail-closed shut: `/_voltro/inspect/{app,routes,metrics}` all refused, its runtime-registry entry carried no token, and the dashboard listed the web app and could read nothing from it — the route list, the render modes and the web process's own metrics being exactly what only that half has. The web boot mints before it registers, so the entry carries the token.
+
+  It mints the INSPECT pair only. The framework's mintable set is split by what owns it now: a web dev boot has no store, so minting a field-encryption key there would write a real AES key into a `.env.local` that nothing can use. An api boot still mints all three.
+
+  The messages that described the token as minted "per project" said the wrong thing in four places; it is per APP, and an api and a web app each publish their own on their own registry entry.
+
+  **Orphaned registry temp files were never swept.** The atomic write is `writeFile` then `rename`, with a `catch` that unlinks its own tmp — and that catch cannot run when the process dies between the two, which is what Ctrl-C on a `voltro dev` does. Measured independently on two machines: 270 each, oldest a month old, 188 of them zero bytes, in the same directory the dashboard reads its app list from. A successful write now sweeps its own pattern, once per process, for files older than an hour — old enough that a live writer's tmp, which exists for microseconds, can never be reached.
+- **@voltro/cli** — `voltro db …` now honours the `store` an app declares.
+
+  `dev.ts` states the rule for the whole framework — "env `$DB_DIALECT` → config.store → 'memory'" — and the db subcommands implemented `$DB_DIALECT` → `'postgres'`. The middle step was missing and the fallback was the wrong one, so an app declaring `store: 'sqlite'` (or mysql, mssql, turso) had every `voltro db` subcommand build a POSTGRES layer against a database that was not there.
+
+  What that looked like, in a project with no migration files at all:
+
+  db apply: a file-based migration FAILED — the schema diff was NOT run failed: SqlError: PgClient: Failed to connect
+
+  Two wrong statements in one message: the project has no file migrations, and the failure is not about migrations. The command was simply pointed at the wrong engine.
+
+  `$DB_DIALECT` still wins, because an operator acting on a running deployment outranks what the project declared. A declared `memory` store is deliberately not recorded: it is not a dialect these subcommands can operate on, and recording it would make the resolver refuse with a message naming `DB_DIALECT=memory` to someone who never set that variable.
+
+  The declared store is read once per command run rather than threaded through the resolver's twenty-one synchronous call sites; `resetDeclaredStore` exists so a suite can prove the value does not leak between runs.
+- **@voltro/runtime** — The fleet view no longer reports a LIVE replica as departed.
+
+  `mergeFleetObservations` classified any observation row whose replica the local roster did not list as departed — a process that is gone. But a membership view is per process: replicas sharing a database and no broadcast bus each hold a roster of one, so two live replicas reported each other as departed while quoting an age of under two seconds, which is the same answer saying the process was alive moments ago.
+
+  Departure now needs age as well as roster-absence: a row is departed only when it is unrostered AND older than the freshness window, because a departed process cannot have written inside it. A fresh unrostered row is a responder whose existence the roster does not know about, which is what it always was.
+
+  The behaviour this replaces is kept: a row from a long-gone process is still old and still unrostered, so it still lands in `departed` rather than inflating `responded` or splitting the framework-version count.
+- **@voltro/cli** — A 403 on the no-JS `/form/*` path now leaves a record saying which of the three refusal reasons fired.
+
+  `/form/*` and `POST /rpc` are two surfaces of ONE origin decision. The rpc listener has logged `refused cross-site request` under `voltro:security` with the reason and the offending origin since the guard shipped; the form path answered a terse `origin not allowed` to the browser, wrote nothing anywhere, and dropped the `decision.reason` it had just computed. So a refusal on the surface a user reaches WITHOUT JavaScript — the one where there is no console to inspect and no network panel to open — was the one with no diagnosis on either side.
+
+  The form path now logs the same message under the same scope, so an operator greps one scope for both surfaces. The response body is deliberately unchanged and still identical for every reason: the client learns it was refused, not which allowlist entry to guess at.
+
+  `host` is logged beside `origin` because it is part of the decision rather than context. Both `sameAuthority` and `bothLoopback` compare against the Host header and both return false when it is absent, so a request whose Origin reads as perfectly same-origin is refused the moment Host does not arrive — a case that, in a record carrying the origin alone, is indistinguishable from a genuine cross-site POST.
+- **@voltro/cli** — The dashboard proxy sent its OWN inspect token to every app it opened.
+
+  Three sites forwarded `process.env.VOLTRO_INSPECT_TOKEN` — the token of whichever process was doing the forwarding — as the bearer for an arbitrary target: the dashboard proxy on the api boot path, the same proxy on the web boot path, and the in-page overlay's proxy to its api. `inspectFetch.ts` has resolved per registry entry all along, which is why `voltro logs` works from any directory; the three readers that forward on someone else's behalf never learned it.
+
+  That was invisible for exactly as long as every app on a machine shared one token. It stops being true the moment tokens are minted per app, and then the proxy opens precisely one app and is refused by every other — 401, `missing Authorization header`, against a registry entry carrying a perfectly good token of its own. In a project with an api and a web app, the half that answers is whichever one happens to own the forwarding process.
+
+  `inspectTokenForTarget` / `inspectTokenForTargetSync` resolve the bearer from the target's ORIGIN against the runtime registry, falling back to this process's token when the target is not registered — an operator-configured remote target has nothing else to offer, and a single-app machine has always used exactly that. A malformed target or an unreadable registry degrades to the same fallback rather than throwing, which matters for the sync form, used on a request path with no error boundary above it.
+
+  The write credential stays env-only and deliberately unpublished: the registry file is a per-app READ capability, and putting an action-authorising token in it would widen every entry into something worth stealing.
+
+  Three sites were wrong at once, so the guard is over the SET rather than over the line that was reported — a fourth forwarder is one paste away, and the paste looks locally correct, `process.env.VOLTRO_INSPECT_TOKEN` being, after all, this process's token.
+- **@voltro/cli, @voltro/ui-shadcn** — The local dashboard JSON proxy forwards the separate inspect write credential on action requests in both development and production. Explicit read credentials are never upgraded with the proxy's local write token; runtime dashboard app configuration accepts an optional `writeToken`. The shared `Dialog` now accepts its native React ref so access forms can open with `showModal()` and retain native focus containment.
+- **@voltro/cli** — `voltro e2e` reported a spec whose process was KILLED as passed.
+
+  Node gives a signal-killed child `code: null`, and the runner coerced that with `code ?? 0` — so an out-of-memory runner, a CI cancel or a harness timeout turned "this spec never finished" into "this spec succeeded", with nothing else in the run saying otherwise. A killed spec is a failure now, and the line names the signal, because `exit 1` for a SIGKILL sends the reader looking for an assertion that never ran.
+
+  `voltro typecheck` and the deploy command runner already failed closed on the same null; what they could not say is WHY. A typecheck failure with no diagnostics above it reads as a tsc bug rather than as a machine that ran out of memory, so both print the signal now.
+
+  The same discard sat in nine spawn helpers across the test suite, where it made a killed child fail as `expected null to be 1` — a message describing a behaviour defect that had not happened, on a rule that was working. All nine carry the signal into what the assertion prints, and `spawnedChildSignals.test.ts` keeps the tenth copy from being written: the one site where an exit code alone is provably enough is exempted BY NAME with its reason, and an exemption that stops matching fails the run.
+- **@voltro/plugin-mail** — Mail inspection declares recent-send buffers as process-local and template lists as declarations, so dashboards retain replica identity and completeness instead of presenting them as a complete delivery history.
+- **@voltro/web** — Closing an intercepting-route overlay returns focus to whatever opened it.
+
+  The overlay is a native `<dialog>` opened with `showModal()`, and the code relied on the platform for focus restoration — reasonably, because that is what the spec says `close()` does. The spec also says it only happens while the dialog is still in a document, and React deletes a subtree by detaching its topmost host node before walking the children to run their effect cleanups. So when the overlay is unmounted as part of a route change, its `close()` can land on an element that is already detached, and the restoration step silently does nothing.
+
+  Measured in a real chromium against `voltro start`: the trigger was focused (`activeElement=open-2`), `showModal()` moved focus into the dialog (`activeElement=DIALOG`), and after Back the dialog was gone with `document.activeElement` on `BODY`. The trigger itself was untouched — same node, still connected — so this was not a re-render replacing it. For anyone navigating by keyboard, Back dropped them at the top of the document.
+
+  The overlay now records what was focused before it opened and restores it on close. It FILLS THE GAP rather than fighting the platform: when `close()` restored focus itself this is a no-op on the same element, and a focus the app moved somewhere real while the overlay was open is left alone — only a focus that has fallen to nothing gets put back.
+
+  `e2e-fixtures/web-intercept` driven through a real browser goes from one failure to none, and both halves are pinned in jsdom, which has no `showModal` at all and is therefore the right harness for the explicit path.
+- **@voltro/cli, @voltro/protocol** — Production now mounts plugin inspect endpoints through the same authenticated dispatcher as development. Plugin JSON GET endpoints can declare process, shared-store or declaration scope to retain origin and completeness at effective and aliased mounts. Plugin writes reject non-loopback browser origins in the shared dispatcher.
+- Keep plugin operation targets, permissions and failures explicit in both dashboards. Confirm retention, subject erasure, search reindex/repair and moderation decisions; bind subject results to the selected subject and reject already-reviewed moderation items with HTTP 409. Report process/declaration/store scope without treating missing data as an empty or healthy state.
+- Resolve dashboard plugin reads and writes against the selected effective instance. Distinguish failed reads from empty lists, show bounded storage and notification samples honestly, and retain declaration/process scope for billing configuration and queue counters.
+- **@voltro/runtime** — The default `Referrer-Policy` made the framework refuse its own no-JS forms.
+
+  `no-referrer` was the shipped default, and under it a browser sends `Origin: null` on a same-origin state-changing request — the Fetch specification serialises the origin as `null` when the referrer policy is `no-referrer`. The origin guard refuses an opaque origin, correctly and by design. So every no-JS `<form method="post">` in every app answered **403**, on `voltro dev` and `voltro start` alike, for every user. Two security defaults, each defensible alone, cancelling each other: we asked the browser to withhold provenance and then refused the request for lacking it.
+
+  The same request also arrived without a `Referer`, which `/form/*` reads to choose the PRG redirect target and the 422 re-render's return path.
+
+  The default is now `strict-origin-when-cross-origin`. It withholds the path cross-origin — the privacy property `no-referrer` was chosen for — while leaving the `Origin` intact, and nulls it only on an https→http downgrade, which is the one case where withholding it is the point. It is also what a browser does with no header at all. `same-origin` would also fix the form path but nulls the `Origin` on a legitimate cross-origin post to an allowlisted api, which is exactly what a split deployment's `VOLTRO_ALLOWED_ORIGINS` exists to permit.
+
+  Measured in a real headless chromium against a bare `node:http` server, one header changed between rows:
+
+  (none) → Origin: http://127.0.0.1:45412 no-referrer → Origin: null ← and no Referer strict-origin-when-cross-origin → Origin: http://127.0.0.1:45412 same-origin → Origin: http://127.0.0.1:45412
+
+  An app that set `referrerPolicy: 'no-referrer'` explicitly keeps it and keeps the 403; `preservesSameOriginHeader` is exported so the incompatibility can be asserted rather than rediscovered.
+- **@voltro/ui-shadcn** — The shared token stylesheet now supplies light/dark success, warning and info colors and their Tailwind utilities, so Callout status treatments render consistently in every consuming app without local token definitions.
+- **@voltro/ui-shadcn** — Signal header actions use the navigation's resting border contrast, 16px icon size and text line height so equally sized controls also align visually.
+- **@voltro/cli** — `voltro --help` stopped advertising a subcommand that was removed on purpose, and `voltro support --help` answers as help.
+
+  `voltro support sentry <eventId>` went away in 0.67.0 — sentry-cli 3 dropped `sourcemaps explain` — with a codemod carrying users across it. What outlived the removal was the command table's own summary, which went on listing `Subcommands: collect, sentry` while the implementation answered `unknown subcommand 'sentry'` with exit 2. The summary names the removal and where to look instead, so a reader arriving from an older help output or a runbook learns why rather than meeting a refusal.
+
+  `voltro support --help` also came back as `unknown subcommand '--help'` with exit 2. The command declares `handlesHelp`, so the flag arrives as the first argument and hit the subcommand check — an error for the one request that is never one, on the command somebody reaches for BECAUSE they do not yet know the subcommands. `--help`, `-h` and `help` all print usage and exit 0.
+- **@voltro/cli** — `voltro test` no longer turns a TYPE-ONLY `tsconfig` `paths` mapping into a runtime alias. An app that maps `"react": ["./node_modules/@types/react"]` — the usual trick so `tsc` resolves ambient types in a hoisted monorepo — could not run a single test that imported React: vitest resolved the real `import 'react'` to a package of declarations and every such file died with `"." is not exported under the conditions ["node","development","import"] from @types/react`.
+
+  `voltro build` and `voltro dev` already skipped these mappings; the test runner and `voltro doctor` used a second alias reader that did not. The rule now has one definition (`isTypeOnlyPathTarget`) that all three import, and the two readers are pinned against each other in a test — the codemod path is deliberately excluded, since it hands `paths` back to a TypeScript compiler, which is who a type-only mapping is written for.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — `scripts/browser-surface-mismatch.mjs` drives the schema cross-check in a real Chromium — a real `fetch` to the derived capabilities URL, a real console, the real `buildApiRuntime`.
+
+  The unit tests reach everything except the environment the check actually runs in, and this one's whole value is that it SAYS something where the alternative is silence: a version that had quietly stopped firing would look, from outside, exactly like a client that is always fresh. Three cases, and the last two are what keep the first honest — a disagreeing surface warns and names the procedure, an agreeing one is silent, and a server publishing no surface at all is silent too. Falsified by disconnecting the reporter: four cases go red, the two silence cases stay green.
+
+  It joins `browser-checks.mjs` by existing; the runner discovers `browser-*.mjs` by name.
+- **@voltro/cli** — Synchronize the published dashboard-inspection codemod manifest and the development inspect-door regression with shared routing. Measure Redis delivery only after broker subscription readiness, establish file-watcher readiness in every workspace root, and run these real-process, watcher and Redis suites in the serial integration group.
+- **@voltro/client** — `documentHidden` in the subscription cache reads `document` through `globalThis` with a local structural type, the way `formBinding` already does, instead of `typeof document !== 'undefined' && document.visibilityState`. Same value in every environment. The spelling mattered only to a program that compiles `@voltro/client` without the DOM lib: `@voltro/cli`'s test tsconfig does, and its `lint` reported TS2584 twice on that line while the client's own `lint` — DOM lib present — was green. A cross-package view of a file is its own check, and this one runs only in CI's Lint job.
+
+---
+
 ## [0.67.0] — 2026-09-07
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -3,9 +3,9 @@ import { ClassProp } from 'class-variance-authority/types';
 import { ClassValue } from 'clsx';
 import { ComponentProps } from 'react';
 import { ComponentPropsWithoutRef } from 'react';
+import { ComponentPropsWithRef } from 'react';
 import { ComponentType } from 'react';
 import { CSSProperties } from 'react';
-import { DialogHTMLAttributes } from 'react';
 import { FC } from 'react';
 import { FormHTMLAttributes } from 'react';
 import { ForwardRefExoticComponent } from 'react';
@@ -241,7 +241,7 @@ export declare const DatabaseIcon: (p: DocIconProps) => ReactNode;
  *  writes `document.cookie` in the browser, returns the header string. */
 export declare const deleteCookie: (name: string, path?: string) => string;
 
-export declare const Dialog: ({ className, children, ...props }: DialogHTMLAttributes<HTMLDialogElement>) => ReactNode;
+export declare const Dialog: ({ className, children, ...props }: ComponentPropsWithRef<"dialog">) => ReactNode;
 
 export declare const DialogDescription: ({ className, ...props }: HTMLAttributes<HTMLParagraphElement>) => ReactNode;
 

package/dist/signal.css

@@ -103,6 +103,46 @@
 
 .signal-stage .signal-atmosphere { mask-image: linear-gradient(#000 0%, #000 85%, transparent 100%); }
 .signal-shell { width: min(100% - 88px, 1536px); margin-inline: auto; }
+/* One opening rhythm for Framework, Cloud and the documentation index. */
+.signal-opener { padding-top: 50px; }
+.signal-opener-title { margin: 0; position: relative; z-index: 1; font-size: clamp(48px, 6.15vw, 96px); font-weight: 700; line-height: 1.06; letter-spacing: -.04em; }
+.signal-opener-title > span { display: block; }
+.signal-opener-accent { color: var(--signal-light); margin-top: 9px; }
+.signal-opener-description { position: relative; z-index: 1; max-width: 75ch; margin: 27px 0 0; font-size: clamp(18px, 1.64vw, 25px); line-height: 1.48; letter-spacing: -.023em; color: var(--signal-ink); }
+.signal-opener-description > span { display: block; }
+.signal-opener-actions { position: relative; z-index: 2; display: flex; flex-wrap: wrap; align-items: center; gap: 16px 39px; width: fit-content; margin-top: 29px; }
+.signal-opener-secondary { display: inline-flex; align-items: center; gap: 12px; min-height: 44px; font-size: 15px; color: var(--signal-ink); }
+.signal-opener-secondary > span { position: relative; padding-block: 7px; }
+.signal-opener-secondary > span::after { content: ''; position: absolute; left: 0; right: 0; bottom: 1px; height: 1px; background: var(--signal-light); transform-origin: left; transform: scaleX(.22); transition: transform 220ms var(--signal-ease); }
+.signal-opener-actions .signal-opener-secondary svg { width: 16px; height: 16px; color: var(--signal-light); transition: transform 200ms var(--signal-ease); }
+.signal-opener-secondary:hover > span::after, .signal-opener-secondary:focus-visible > span::after { transform: scaleX(1); }
+.signal-opener-secondary:hover svg, .signal-opener-secondary:focus-visible svg { transform: translate(2px, -2px); }
+.signal-opener-actions .signal-primary { position: relative; isolation: isolate; }
+.signal-opener-actions .signal-arrow svg { width: 22px; height: 22px; }
+.signal-opener-actions .signal-primary::after { content: ''; position: absolute; height: 2px; bottom: 0; left: 0; right: 0; background: #d5beff; transform: scaleX(0); transform-origin: left; transition: transform 280ms var(--signal-ease); }
+.signal-opener-actions .signal-primary:hover::after, .signal-opener-actions .signal-primary:focus-visible::after { transform: scaleX(1); }
+.signal-opener-actions .signal-primary:active svg { transform: translateX(2px); }
+@media (min-width: 1600px) { .signal-opener { padding-top: 70px; } }
+@media (max-width: 1150px) {
+  .signal-opener { padding-top: 40px; }
+  .signal-opener-title { font-size: clamp(48px, 6.1vw, 75px); }
+}
+@media (max-width: 760px) {
+  .signal-opener { padding-top: 29px; }
+  .signal-opener-title { font-size: clamp(37px, 7.5vw, 57px); line-height: 1.1; letter-spacing: -.035em; }
+  .signal-opener-accent { margin-top: 5px; }
+  .signal-opener-description { max-width: 40ch; margin-top: 22px; font-size: 16px; line-height: 1.5; }
+  .signal-opener-description > span { display: inline; }
+  .signal-opener-description > span + span::before { content: ' '; }
+  .signal-opener-actions { width: 100%; gap: 12px 22px; margin-top: 24px; }
+  .signal-opener-secondary { gap: 5px; font-size: 13px; }
+  .signal-opener-actions .signal-opener-secondary svg { width: 14px; height: 14px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .signal-opener-secondary > span::after, .signal-opener-actions .signal-primary::after { transition: none; }
+  .signal-opener-actions svg { transition: none; }
+  .signal-opener-actions a:hover svg, .signal-opener-actions a:focus-visible svg, .signal-opener-actions a:active svg { transform: none; }
+}
 .signal-primary {
   display: inline-flex; align-items: stretch; min-height: 54px; width: fit-content;
   background: #7c3aed linear-gradient(115deg, #6d28d9, #7c3aed 48%, #8a49ed);
@@ -164,8 +204,8 @@
 .signal-control:hover, .signal-control[data-state=open] { border-color: var(--input); background: var(--secondary); }
 .signal-preferences { padding-inline: 12px; border-color: transparent; background: transparent; color: var(--muted-foreground); font-size: 12px; }
 .signal-preferences:hover, .signal-preferences[data-state=open] { color: var(--foreground); }
-.signal-header-action { border-color: var(--input); }
-.signal-header-action > svg { color: var(--signal-accent-ink); transition: transform 180ms var(--signal-ease); }
+.signal-header-action { line-height: 1.5; }
+.signal-header-action > svg { width: 16px; height: 16px; color: var(--signal-accent-ink); transition: transform 180ms var(--signal-ease); }
 .signal-header-action:hover > svg { transform: translateX(3px); }
 .signal-search { width: 224px; justify-content: flex-start; color: var(--muted-foreground); font-weight: 400; }
 .signal-search kbd { margin-left: auto; padding: 2px 5px; border: 1px solid var(--border); border-radius: 3px; font-family: inherit; font-size: 11px; line-height: 1.4; }

package/dist/tokens.css

@@ -51,6 +51,9 @@
   --accent-foreground: oklch(0 0 0);
   --destructive: oklch(0.63 0.19 23.03);
   --destructive-foreground: oklch(1 0 0);
+  --success: #167252;
+  --warning: #805e00;
+  --info: #2563b4;
   --border: oklch(0.92 0 0);
   --input: oklch(0.94 0 0);
   --ring: oklch(0 0 0);
@@ -111,6 +114,9 @@
   --accent-foreground: oklch(1 0 0);
   --destructive: oklch(0.69 0.2 23.91);
   --destructive-foreground: oklch(0 0 0);
+  --success: #62cda1;
+  --warning: #e4ba65;
+  --info: #86b7f2;
   --border: oklch(0.26 0 0);
   --input: oklch(0.32 0 0);
   --ring: oklch(0.72 0 0);
@@ -173,6 +179,9 @@
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-info: var(--info);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/ui-shadcn",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Voltro's first-party shadcn/ui kit: Tailwind v4 design tokens (light + dark), 30+ primitives, layout compositions, styled widgets for the @voltro/ui seam, and the canonical theme/language preference-cookie helpers.",
   "keywords": [
     "voltro",
@@ -52,7 +52,7 @@
     "@radix-ui/react-toggle-group": "^1.1.19",
     "@shikijs/langs": "^4.4.3",
     "@shikijs/themes": "^4.4.3",
-    "@voltro/ui": "0.67.0",
+    "@voltro/ui": "0.68.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "shiki": "^4.4.3",

package/src/primitives/dialog.tsx

@@ -7,10 +7,10 @@
 // imperative API (`dialogRef.current?.showModal()`) is the native
 // path; we surface it as a uncontrolled wrapper for now.
 
-import type { DialogHTMLAttributes, HTMLAttributes, ReactNode } from 'react'
+import type { ComponentPropsWithRef, HTMLAttributes, ReactNode } from 'react'
 import { cn } from '../cn'
 
-export const Dialog = ({ className, children, ...props }: DialogHTMLAttributes<HTMLDialogElement>): ReactNode => (
+export const Dialog = ({ className, children, ...props }: ComponentPropsWithRef<'dialog'>): ReactNode => (
   <dialog
     data-slot="dialog"
     className={cn(

package/src/signal.css

@@ -103,6 +103,46 @@
 
 .signal-stage .signal-atmosphere { mask-image: linear-gradient(#000 0%, #000 85%, transparent 100%); }
 .signal-shell { width: min(100% - 88px, 1536px); margin-inline: auto; }
+/* One opening rhythm for Framework, Cloud and the documentation index. */
+.signal-opener { padding-top: 50px; }
+.signal-opener-title { margin: 0; position: relative; z-index: 1; font-size: clamp(48px, 6.15vw, 96px); font-weight: 700; line-height: 1.06; letter-spacing: -.04em; }
+.signal-opener-title > span { display: block; }
+.signal-opener-accent { color: var(--signal-light); margin-top: 9px; }
+.signal-opener-description { position: relative; z-index: 1; max-width: 75ch; margin: 27px 0 0; font-size: clamp(18px, 1.64vw, 25px); line-height: 1.48; letter-spacing: -.023em; color: var(--signal-ink); }
+.signal-opener-description > span { display: block; }
+.signal-opener-actions { position: relative; z-index: 2; display: flex; flex-wrap: wrap; align-items: center; gap: 16px 39px; width: fit-content; margin-top: 29px; }
+.signal-opener-secondary { display: inline-flex; align-items: center; gap: 12px; min-height: 44px; font-size: 15px; color: var(--signal-ink); }
+.signal-opener-secondary > span { position: relative; padding-block: 7px; }
+.signal-opener-secondary > span::after { content: ''; position: absolute; left: 0; right: 0; bottom: 1px; height: 1px; background: var(--signal-light); transform-origin: left; transform: scaleX(.22); transition: transform 220ms var(--signal-ease); }
+.signal-opener-actions .signal-opener-secondary svg { width: 16px; height: 16px; color: var(--signal-light); transition: transform 200ms var(--signal-ease); }
+.signal-opener-secondary:hover > span::after, .signal-opener-secondary:focus-visible > span::after { transform: scaleX(1); }
+.signal-opener-secondary:hover svg, .signal-opener-secondary:focus-visible svg { transform: translate(2px, -2px); }
+.signal-opener-actions .signal-primary { position: relative; isolation: isolate; }
+.signal-opener-actions .signal-arrow svg { width: 22px; height: 22px; }
+.signal-opener-actions .signal-primary::after { content: ''; position: absolute; height: 2px; bottom: 0; left: 0; right: 0; background: #d5beff; transform: scaleX(0); transform-origin: left; transition: transform 280ms var(--signal-ease); }
+.signal-opener-actions .signal-primary:hover::after, .signal-opener-actions .signal-primary:focus-visible::after { transform: scaleX(1); }
+.signal-opener-actions .signal-primary:active svg { transform: translateX(2px); }
+@media (min-width: 1600px) { .signal-opener { padding-top: 70px; } }
+@media (max-width: 1150px) {
+  .signal-opener { padding-top: 40px; }
+  .signal-opener-title { font-size: clamp(48px, 6.1vw, 75px); }
+}
+@media (max-width: 760px) {
+  .signal-opener { padding-top: 29px; }
+  .signal-opener-title { font-size: clamp(37px, 7.5vw, 57px); line-height: 1.1; letter-spacing: -.035em; }
+  .signal-opener-accent { margin-top: 5px; }
+  .signal-opener-description { max-width: 40ch; margin-top: 22px; font-size: 16px; line-height: 1.5; }
+  .signal-opener-description > span { display: inline; }
+  .signal-opener-description > span + span::before { content: ' '; }
+  .signal-opener-actions { width: 100%; gap: 12px 22px; margin-top: 24px; }
+  .signal-opener-secondary { gap: 5px; font-size: 13px; }
+  .signal-opener-actions .signal-opener-secondary svg { width: 14px; height: 14px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .signal-opener-secondary > span::after, .signal-opener-actions .signal-primary::after { transition: none; }
+  .signal-opener-actions svg { transition: none; }
+  .signal-opener-actions a:hover svg, .signal-opener-actions a:focus-visible svg, .signal-opener-actions a:active svg { transform: none; }
+}
 .signal-primary {
   display: inline-flex; align-items: stretch; min-height: 54px; width: fit-content;
   background: #7c3aed linear-gradient(115deg, #6d28d9, #7c3aed 48%, #8a49ed);
@@ -164,8 +204,8 @@
 .signal-control:hover, .signal-control[data-state=open] { border-color: var(--input); background: var(--secondary); }
 .signal-preferences { padding-inline: 12px; border-color: transparent; background: transparent; color: var(--muted-foreground); font-size: 12px; }
 .signal-preferences:hover, .signal-preferences[data-state=open] { color: var(--foreground); }
-.signal-header-action { border-color: var(--input); }
-.signal-header-action > svg { color: var(--signal-accent-ink); transition: transform 180ms var(--signal-ease); }
+.signal-header-action { line-height: 1.5; }
+.signal-header-action > svg { width: 16px; height: 16px; color: var(--signal-accent-ink); transition: transform 180ms var(--signal-ease); }
 .signal-header-action:hover > svg { transform: translateX(3px); }
 .signal-search { width: 224px; justify-content: flex-start; color: var(--muted-foreground); font-weight: 400; }
 .signal-search kbd { margin-left: auto; padding: 2px 5px; border: 1px solid var(--border); border-radius: 3px; font-family: inherit; font-size: 11px; line-height: 1.4; }

package/src/tokens.css

@@ -51,6 +51,9 @@
   --accent-foreground: oklch(0 0 0);
   --destructive: oklch(0.63 0.19 23.03);
   --destructive-foreground: oklch(1 0 0);
+  --success: #167252;
+  --warning: #805e00;
+  --info: #2563b4;
   --border: oklch(0.92 0 0);
   --input: oklch(0.94 0 0);
   --ring: oklch(0 0 0);
@@ -111,6 +114,9 @@
   --accent-foreground: oklch(1 0 0);
   --destructive: oklch(0.69 0.2 23.91);
   --destructive-foreground: oklch(0 0 0);
+  --success: #62cda1;
+  --warning: #e4ba65;
+  --info: #86b7f2;
   --border: oklch(0.26 0 0);
   --input: oklch(0.32 0 0);
   --ring: oklch(0.72 0 0);
@@ -173,6 +179,9 @@
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-info: var(--info);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);