@voltro/i18n 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -39,6 +39,166 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.51.0] — 2026-08-24
+
+### ⚠ BREAKING
+
+- **@voltro/data-transfer, @voltro/cli** — The asset counts reported references as if they were blobs. `_voltro_storage_refs` holds one row per reference and several rows legitimately name one key, so a capture of 57 rows over 16 keys wrote `count: 57` into the stamp beside an `assets/` directory holding 16 files, and the restore reported "57 blob(s) restored" while 16 objects appeared. Nothing was lost; what was lost is the ability to check. Anyone answering "are all the blobs there?" after a restore compared the stamp's number against one they counted and found a 3.5x gap that was not one.
+
+  A key named by several references is now fetched once rather than downloaded, hashed and discarded once per row, and the three numbers are stated separately: `references` (rows enumerated), `count` (distinct keys), `objects` (distinct sha256 bodies), with `totalBytes` and `objectBytes` beside them. The stamp's existing fields keep their names and now mean what a reader always took them for; the new ones are optional, so a stamp written before them still parses.
+
+  **Breaking on one export.** `restoreAssetsFromCas` returns `{ count, objects }` instead of a bare `number` — one number could not answer both questions, which is the defect. `count` is what the old value was, so the migration that changes nothing is `.count`.
+
+  **`voltro update` carries you across this** — codemod `0.51.0/03_restore-assets-returns-counts`. 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.51.0).
+- **@voltro/i18n** — `<I18nProvider>` takes `timeZone` as its own prop, and `intlConfig` no longer accepts one.
+
+  `intlConfig` exists to forward props to react-intl UNMODIFIED, and for every other member of `IntlConfig` that is the right shape. `timeZone` is the one member this package's own formatters read — and they did not read it: `useFormatDate` built `Intl.DateTimeFormat` itself and took only the locale from the provider. So a zone passed through `intlConfig` configured `<T>`'s ICU dates and NOT the `useFormatDate()` beside them. Measured under one provider, one instant (`2026-08-24T23:30:00Z`), `locale: 'de'`, `intlConfig: { timeZone: 'Europe/Berlin' }`, process zone UTC: react-intl rendered `25.08.26, 01:30` and the hook rendered `24.08.26, 23:30`. A different hour, and a different day.
+
+  The zone has to be a prop this package can see. It is validated once at the provider (an unusable zone — a stale cookie, a typo, a runtime with a trimmed ICU — is dropped, because `Intl` THROWS on an unknown zone and `useFormatDate` catches, which would degrade every timestamp in the app to a raw `Date` string). It is what the new `useTimeZone()` reports. And it is what the framework fills per request.
+
+  **Migration:** `intlConfig={{ timeZone: 'Europe/Berlin' }}` → `timeZone="Europe/Berlin"`. The codemod does it, including the case where the zone was the bag's only member. An `intlConfig` naming a variable is reported by file and line rather than guessed at — the property would otherwise stop being read with nothing red anywhere.
+- **@voltro/cli** — A native restore whose bookkeeping store would not open ran anyway, with no in-progress marker and no word about it. `nativeBookkeeping` was `try { … } catch { return undefined }`, and that `undefined` guarded every branch below — including the refusal for a marker that could not be written. So the failure removed the precaution AND the sentence that would have reported it missing, and `markerState` was never computed, defaulting to "held".
+
+  What it produced was worse than silence: a failed restore printed "This database is now in an unknown state and the next boot will REFUSE, by design" over a database with zero marker rows. The next boot did not refuse, and `voltro data clear-replace-marker` had nothing to clear. The trigger is not exotic — wrong credentials, an unreachable database, a missing env var, no `app.config.ts` from here — and a restore is the operation you run against a target that is already unwell, so the guard fell away exactly when it was needed.
+
+  The reason now travels instead of being caught and dropped. A restore that cannot write the marker REFUSES and names which of the two reasons it was (the store would not open, or the table is not there); those were two separate refusals and are now one, because they are one decision for the operator. `--no-marker` is the deliberate way past it and warns every time. And the `recorded:` line no longer reports a local failure as a property of the target — it says where the failure was.
+
+  **This changes an exit code.** A restore that could not write the marker used to exit 0; it now exits 1. Two invocations are affected — the bookkeeping store will not open, or there is no `app.config.ts` from the working directory — and the second surprises people, because `restore` reads its target from the environment and so looks like it needs no project. It does not, for the dump; it needs one for the marker. `--no-marker` is the deliberate way through and warns every time. The note ships under `reach: 'beyond-source'` because the affected invocations live in cron entries, CI jobs and runbooks rather than in TypeScript.
+
+  **`voltro update` carries you across this** — codemod `0.51.0/02_restore-refuses-without-marker`. 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.51.0).
+
+### Added
+
+- **@voltro/i18n, @voltro/cli, @voltro/voltro** — `timeZone` in the web `app.config.ts` — the zone every date/time formatter renders in, resolved per request and published so the client agrees.
+
+  A formatter is deterministic given the value, the locale, the zone and the clock. The locale already came from the provider and was already agreed across the hydration boundary — the server publishes it as `<html lang>` and the client reads that attribute rather than `navigator.languages`, precisely because the browser's own answer can differ from what the server saw. The zone had no such source. `Intl` fell back to the zone of whichever runtime was formatting: the pod on the server (UTC on a container with no `TZ`), the viewer's machine in the browser. Every server-rendered timestamp was therefore a hydration mismatch waiting for a wide enough offset, and across midnight it was a different calendar day.
+
+  timeZone: 'Europe/Berlin' // one zone for every viewer timeZone: 'viewer' // per request, from the `voltro:tz` cookie defaultTimeZone: 'UTC' // before the viewer's zone is known
+
+  Whatever it resolves to is stamped on the document as `<html data-voltro-tz>`, and the generated client entry reads that attribute. Both sides then format against one value — which is the property that removes the mismatch, whether or not the value is the viewer's true zone: being wrong together is repairable after mount, being different is not.
+
+  Under `'viewer'` the framework injects a script that seeds `voltro:tz` from the browser when the cookie is absent, so the server renders in the viewer's zone from the second request with no login. It never overwrites an existing value — the APP is the authoritative writer, at login, from the zone it holds for the signed-in user (`TIMEZONE_COOKIE` and `isSupportedTimeZone` are exported for that). Unset, nothing changes: each runtime keeps using its own zone, and `useTimeZone()` returns `undefined` to say so.
+
+  This is the RENDER zone. The server-side compute zone — what `startOfDay` resolves against inside a handler — is still `@voltro/datetime/context`'s seam, unwired.
+
+  **`apiSurface: compatible`** covers the two golden lines that moved, and they are the same change twice: `makeSsgWrap`'s returned wrapper, and the `wraps` record on the SSG shell input, each gained an OPTIONAL second parameter (the per-request zone + render instant; the wrapper is built once per locale, so they cannot live in the factory). A function with an optional extra parameter is assignable wherever the one-parameter type was expected, so no call site that compiled stops compiling — and both are the framework's SSG bridge, documented as never imported by app code. Everything else this release adds to these packages is a pure addition; the one genuine break in `@voltro/i18n` is the `timeZone` prop, which has its own entry and its own codemod.
+
+### Changed
+
+- **@voltro/cli** — A `BREAKING` entry's changelog footer now tells a reader who pins versions by hand how to print the codemod's note without upgrading anything:
+
+  voltro update --codemods-only --from <your current version> --dry-run
+
+  The footer used to stop at the codemod's id, which is enough for anyone who runs `voltro update` and nothing at all for anyone who does not. A deployment said so plainly: they pin every `@voltro/*` version from their own container scripts, have never run the command, and `CHANGELOG.md` out of the tarball is the only channel anything reaches them through. So a note deliberately filed under an unreached version — our one mechanism for correcting guidance that can no longer be corrected in place — reached that population not at all, and the id told them a fix existed without telling them what it was.
+
+  No new surface: every flag in that invocation is already parsed, which is what lets `check-message-apis.mjs` verify the line rather than trust it.
+- **@voltro/cli** — Two fingerprint labels now say what they compare.
+
+  The restore's skew warning said the backup's schema "differs from what this code declares". It does not: the value it compares against is the TARGET database's live schema, read by introspection at restore time. Bringing a target to the backup's shape makes the warning disappear while the declared fingerprint is a third value entirely, which is how the mislabel was caught. The comparison is the useful one and is unchanged; the sentence sent readers looking for a code change where a database differed.
+
+  `voltro db plan` prints `fingerprint: live … · declared …` instead of `from … → to …`, plus a line saying the two are not meant to match. A hash of a live database never equals the hash of the declaration it came from — introspection cannot recover generated expressions, `maxLength` or sensitivity markers — which is why `db drift` keeps a separate live baseline. Printed as `from → to`, `0 operations` under two differing hashes read as a contradiction.
+
+### Fixed
+
+- **@voltro/cli** — `voltro check` reported a reactivity CHANNEL as a missing table, at `error` severity — so it set the exit code:
+
+  ✗ error reference/dangling-source query(presence.list) reads table 'channel:presence' which does not exist fix: declare a 'channel:presence.entity.ts' table or fix the query's source
+
+  A `source:` entry is a table name OR a channel's routing key (`channel:<name>`), and every rule resolved entries against the table set. The advice cannot be followed — a channel exists precisely because no table is meant — and because it is an error rather than a warning, `voltro check` could not be a CI gate for any app that uses a channel. That includes an app whose only channel comes from `@voltro/plugin-presence`, whose own `presence.list` declares one: a first-party feature meeting a rule that did not know about it, inside a first-party plugin.
+
+  Channels are filtered in the ONE helper every table rule reads, rather than at each rule, because a per-rule filter is how the next rule joins without one. The same cause was live one rule over: `observed/declared-but-unobserved` reported "declares source 'channel:presence' but never read it while running" for every exercised procedure that declares a channel. Both are covered, each with a negative control — a filter that dropped the whole source list would have silenced the rules instead of narrowing them.
+- **@voltro/data-transfer** — A native dump no longer carries `_voltro_data_transfers`, for the same reason it stopped carrying the in-progress marker one release ago. The restore opens its own run row there BEFORE the tool runs; the dump then dropped the table mid-flight, and the update recording the outcome wrote into a table that no longer held the row. Measured downstream: after a deliberately failed native restore, `voltro data transfers` showed no restore at all — only the `backup` row the dump had carried over from the SOURCE database. The command that answers "did the restore finish" could not see the run asking the question.
+
+  Exactly two tables are excluded and the line is deliberate: a native restore into the same deployment should bring the migration ledger, the stored plans, the CDC offsets and the schedule claims, because they describe the data being restored. These two describe the RESTORE, and a record of an operation must not be overwritten by the operation it records. Covered per dialect against real servers and real vendor tools, including a non-vacuity check that a table which SHOULD travel still does.
+- **@voltro/i18n, @voltro/cli** — `useRelativeTime` used `Date.now()` as its base, which under SSR is two different numbers. The server rendered at T and wrote "3 minutes ago" into the HTML; the browser hydrated at T+Δ and rendered "4 minutes ago" whenever a unit boundary fell in the gap. The gap is network latency, so it reproduced on a slow connection and never on the developer's machine, and it had nothing to do with timezones — a correctly zoned app hit it just the same.
+
+  The server states its render instant (`<html data-voltro-now>`, `renderedAt` on the provider), the first client render uses that same number, and the clock goes live once hydration commits. Server markup and hydration markup are therefore identical BY CONSTRUCTION — the property `await.tsx` and `deferred.ts` already hold, rather than `suppressHydrationWarning`, which would hide a real mismatch along with this one. An explicit `{ now }` still wins.
+
+  The mount state lives in the provider, not in the hook: a table of ten thousand rows would otherwise pay a state hook and a passive effect each to learn one fact that is true for the whole document. An app that never renders on the server publishes no stamp and takes no second render pass.
+- **@voltro/cli** — `closeNativeRun` writes the transfer row BACK when the restore's own artefact dropped the table it lives in, instead of issuing an `UPDATE` that matches nothing and returning happily. Excluding `_voltro_data_transfers` from our own dumps shortens that window; it does nothing for a dump taken before that change, for a hand-made one, or for mssql and sqlite, whose restores have no per-table exclusion at all. The write-back covers every dialect and every artefact, which is why it is the rule and the exclusion is the optimisation.
+
+  The row is read back rather than trusted — an update that matched nothing is indistinguishable from one that matched — and a read that itself fails writes nothing, because a duplicate row invented on a guess is its own defect in a history somebody reads under pressure.
+- **@voltro/cli** — A prerendered page shipped the shell's baked `lang="en"` whatever locale it was rendered in.
+
+  `voltro dev` and `voltro start` both set `<html lang>` per request; the prerender never did. So a `/de/...` artefact — rendered with the German catalog, handed `locale: 'de'` in its `meta` — served `<html lang="en">`. That attribute is what a screen reader pronounces in, what Chrome offers to translate FROM, and what hyphenation uses, so the failure was silent to whoever shipped it and loud only to the people it excluded. The same shape as the 0.30.0 cookie-name drift, one document path over.
+
+  It surfaced while giving the zone somewhere to travel: `<html lang>` was set by four hand-written copies of one `.replace(/<html…/)` and by nothing in the prerender, and adding a second attribute to that arrangement is how the next one reaches three paths out of five. There is one `applyDocumentAttrs` now, and the prerender is one of its callers — which fixes the locale as a side effect of having somewhere to put the zone.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — `voltro data backup --assets` / `restore --assets` are now driven against a REAL S3 API (MinIO in the test stack), over the network, with a real backup and a real restore into a second bucket and the bytes compared.
+
+  The asset half rests on one field: a provider must map "there is no object at that key" to `status === 404`, and nothing looser — a 403 from a rotated credential is also non-transient, and calling that "the object is gone" turns a recoverable outage into a backup that quietly contains nothing. That mapping was measured against memory, filesystem and database live, and against the s3/azure SDK error SHAPES constructed. A constructed shape is a claim about an SDK, not about a round trip: nothing in it exercises signing, path-style addressing, or what the SDK actually raises when a server answers `NoSuchKey`. Two deployments listed exactly this as the gap they could not close either.
+
+  Both directions are covered against the real server: a dangling reference is stepped over and reported, and a bad credential fails the capture rather than being read as a missing object.
+
+  The native dialect lane also stops being silent about mssql. It was absent from the array entirely — an absent lane and a covered one look identical from the outside — and it is now listed with a written reason for why it does not register here (`sqlpackage` is a separate Microsoft download on a .NET runtime, absent from `mcr.microsoft.com/mssql-tools`). It is registered rather than skipped-forever, because a skip present on every healthy run teaches readers to ignore skip lines; and an assertion fails if any lane drops out WITHOUT a written reason, or if a reason names a lane that is in fact running.
+- **@voltro/cli, @voltro/plugin-storage** — Coverage for the data commands, at the level the defects actually live.
+
+  `dataDirectFlags.e2e.test.ts` drives every DIRECT-target flag of `voltro data export` / `import` through the real binary against a real sqlite database, and carries the same `DATA_FLAGS`-driven self-check the native suite has: a new direct flag has to be driven there or the file goes red. The api-only flags are listed explicitly with the reason they are not here, and that list is asserted against `DATA_FLAGS` so it cannot become a place to hide an untested flag.
+
+  `missingObjectIs404.test.ts` pins the contract the dangling-reference skip rests on: every provider maps "no object at that key" to `status === 404`, and nothing looser. Five providers, three of them live, s3 and azure through their SDK's real error shapes — which read DIFFERENT fields (`$metadata.httpStatusCode` vs a bare `statusCode`), so a mapping copied from one to the other would turn dangling references back into hard capture failures on that backend alone.
+
+  `codegenFeatureTables.integration.test.ts` measures the count a report was about: `voltro codegen` must carry the tables a `*.cron.tsx` contributes, which the entity walk cannot see. The structural guards beside it were TRUE while that count was wrong. `frameworkSourceTypo.integration.test.ts` measures what catches a misspelled `_voltro_*` source given that the type deliberately does not — `voltro check` reports it as a dangling source and exits 1, with a negative control so the check is not merely flagging every framework name.
+
+---
+
+## [0.50.1] — 2026-08-24
+
+### Added
+
+- **@voltro/cli** — A `0.51.0` upgrade note for the case 0.45.0's typed-`source:` note left open: a source that is COMPUTED but whose names are all known — a generic reader that takes its table from `input` or a registry. Both remedies the original offered are wrong there. There is no misspelled name to fix, and widening to `ReactivitySourceValue` (or casting) compiles instantly while taking that entire set of tables permanently out of the check the narrowing exists to provide.
+
+  The note carries the recipe that keeps the names — `as const satisfies`, with the key set recovered separately — and the trap under it: an ANNOTATION widens the keys back even when the literal carries `as const`, because it is checked against the literal and then replaces its type. Filed under an unreached version because codemod selection is `from < version <= to`: 0.45.0's note can never fire again for anyone already past it. Documented on the subscriptions page in both languages.
+
+### Changed
+
+- **@voltro/data-transfer** — The `mariadb-dump`-not-on-PATH hint now also warns that a MariaDB 12.x client requires TLS by default, so running it BY HAND against a server without TLS fails with `TLS/SSL error: SSL is required` (2026) and needs `--skip-ssl`. Our own invocation is unaffected. It is said here because this hint is what sends people to install that client package, and the next thing many of them do is run the tool by hand — where the failure reads like a broken install of the thing we just told them to install.
+
+### Fixed
+
+- **@voltro/cli, @voltro/mcp** — `voltro check`'s `rbac/unguarded-mutation` no longer fires on `internal: true` procedures. Those are in no rpc group and on no route, so the finding's own sentence — "any caller who can reach the rpc surface can invoke it" — named a surface that does not exist, and neither remedy it offered was available: a guard protects nothing there, and `openAccess` is refused outright on an internal descriptor. An app with 990 internal mutations got 990 warnings and a `FAILED` exit from the same tree on which `voltro doctor` reported zero procedures without an access decision, which made `check` unusable as the CI gate it exists to be.
+
+  The capability manifest now carries `internal: true` per procedure (present only when true), and the rule reads it through `isWireReachable` — the same predicate the boot access gate and all three rpc-group assemblies use, rather than a fourth spelling of the same flag. A manifest that does not carry the field is read as REACHABLE, so the rule stays loud on an api older than the field rather than going quiet on it.
+- **@voltro/data-transfer, @voltro/cli** — `--assets` aborted the whole capture at the first blob reference the storage provider could not resolve. A dangling reference is a fact about the source data — a row pointing at an object that was deleted, or that never arrived because an earlier import ran without the flag — and no backup can put back bytes that are not there. Aborting made the flag unusable for exactly the deployment that needed it: 178 references, one resolvable, and the run stopped at the second.
+
+  The phase now records the key, steps over it, and the run reports how many were skipped. Only a genuine not-found (`status === 404`) is treated this way; a 403 from a rotated credential or a 5xx from a backend outage still fails the capture, because calling those "the object is gone" turns a recoverable outage into a backup that quietly contains nothing.
+
+  The same abort also cost the artefact its provenance: `voltro-backup-stamp.json` was written after the asset phase, so a backup taken WITH `--assets` had no stamp at all, and `restore` then greeted an artefact this tool had written minutes earlier as "an older/handmade backup. Cannot verify dialect or schema version." The stamp is now written on every path — it describes the dump, and the dump is on disk and correct by the time the assets run.
+- **@voltro/cli** — `voltro doctor`'s eager-loaded-relation rule resolves nested relations against their PARENT's target table instead of against the query's roots, so every level is reported in one pass. It flattened the `.with({ … })` tree before resolving, which meant a level-2 relation stayed invisible until level 1's table had been added to `source:` — each fix revealed the next level, and a clean run after the first fix meant nothing. One app ran `doctor → fix → doctor` twice before the output stopped producing new findings.
+
+  The one case that is still genuinely under-reported is now stated instead of being silent: when the executor's base table is neither declared nor textually readable, nothing resolves, and doctor prints which relation names it could not check rather than reporting clean.
+- **@voltro/data-transfer** — A native restore whose client exited before consuming its input took the whole CLI down with an unhandled `EPIPE`. `createReadStream(dump).pipe(child.stdin)` had no `error` listener, so Node threw on a write to a pipe with no reader:
+
+  Error: write EPIPE Emitted 'error' event on Socket instance at: at Socket.onerror (node:internal/streams/readable:1045:14)
+
+  What that cost is the point. The crash landed before `close`, so the step never resumed: the client's stderr — the one place the reason was written down — was discarded, the transfer row was never closed, the in-progress marker was never re-asserted, and the operator got a raw Node stack trace over a database that was now half replaced. A deployment met it on a 64 MB restore and could not diagnose it at all, because the only diagnosis had been thrown away.
+
+  Every stream in the step now carries a handler. `EPIPE` on the child's stdin is deliberately swallowed — a child closes the pipe by dying, and its exit code and stderr are the actual failure — while any other stream error is carried and reported. The failure line now always includes the tool's stderr (and says so explicitly when the tool printed none), plus how many bytes of the artefact had been fed before it stopped. A source error also ends the child's stdin, which turns a restore that used to hang forever on a vanished dump into one that fails, and a clean exit over a broken input stream is reported as a failure rather than as a truncated success.
+- **@voltro/cli** — `voltro check`'s observed-vs-declared findings advised an op that does not exist. The recorder reports what the store did, and `store.upsert` is one call; a `target:` is `InsertTarget | UpdateTarget | DeleteTarget` and has no `upsert` member. So `observed/undeclared-write` said to add `{ table: '…', op: 'upsert' }` — a `TS2322`, from a line whose whole purpose is to be pasted. It now advises both halves, and the observed → declarable mapping is typed `Record<ObservedWriteOp, ReadonlyArray<TargetSpec['op']>>` so a new recorder op cannot ship without a declarable answer.
+
+  The remedy no longer produces a finding of its own either: declared targets are now collected per table as a SET. `new Map(targets.map(t => [t.table, t.op]))` kept only the last op, so the correct two-entry declaration read as "declares update" and the insert half came back as a `wrong-op`.
+- **@voltro/data-transfer, @voltro/cli** — The in-progress restore marker did not survive a native restore, on the exact dialects that were documented as safe. The claim — postgres and the mysql family drop only the objects the dump names, so the marker row survives — had a correct argument and a wrong premise: a native dump names the WHOLE database, `_voltro_replace_in_progress` included, and a mysql-family restore writes `DROP TABLE IF EXISTS` in front of each table. The table sorts early, so the guard was removed near the START of the window it exists to cover. Measured downstream as one row before and zero after, twice, once by hand and once through the command — and then a restore died and left a database with a schema, some of its tables, no users and no blobs, with nothing to stop the next boot.
+
+  Two changes, covering different dumps. `voltro data backup` now excludes the marker table (`--exclude-table` / `--ignore-table`), so an artefact we produce cannot carry the thing that erases the guard on the way back in. And `restore` re-asserts the marker after the tool exits, on the failing path as well as the succeeding one, which covers dumps taken before this change and dumps made by hand: rewritten is a warning, and unwritable is an error, because the guard is then off for that run.
+- **@voltro/plugin-storage, @voltro/cli** — `--assets` could not be refused when no storage was configured, and resolved the wrong backend when it was.
+
+  `resolveStorageProvider({})` is total: its final `default:` arm returns an in-process `memoryProvider`. So the three `if (!provider)` refusals in `voltro data backup` / `export` / `restore` — whose entire job is to refuse a flag the app cannot honour — were checking a condition that cannot hold. What they let through is worse than an unchecked flag: with no storage configured, `backup --assets` captured from a fresh memory provider, found nothing in it, and wrote an artefact stamped `assets: { count: 0 }` — a rollback story that says the blobs are in there.
+
+  It also ignored the provider the app REGISTERED. An app on `storagePlugin({ provider: s3(…) })` had its export/import/backup read and write the env-derived default instead, which surfaces later as "no object at key" — the exact drift `appStorageProvider()` exists to prevent, in call sites that never adopted it.
+
+  `configuredStorageProvider()` is the honest predicate: the app's registered provider, else the env-named one, else `undefined`. A memory provider nobody asked for is not a decision. The CLI now loads the app config BEFORE resolving — `storagePlugin(...)` registers at construction, so asking first answered with the default no matter what the app had configured.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — `voltro data backup` / `restore` / `clear-replace-marker` are now driven end to end, one case per declared option and one per refusal, as real CLI subprocesses against a real database.
+
+  Every defect this command has shipped lived in the SEQUENCE rather than in a function — an unhandled `EPIPE` that discarded the client's stderr before `close` fired, a marker erased by the restore's own artefact, an asset abort that skipped the provenance stamp, a refusal that could not fire — so none of them was reachable by testing a part. `nativeBackupRestore.e2e.test.ts` covers the whole surface against sqlite (a file copy: no vendor binary, runs anywhere) and `nativeBackupRestoreDialects.integration.test.ts` runs the vendor-tool half against postgres, mariadb and mysql, skipping BY NAME when the server or the client binary is absent — including when the client is present but too old for the server, which a "is it on PATH" check reports as ready.
+
+  The suite checks itself against `DATA_FLAGS`, the command's own declared option list, so an option cannot be added without a case that drives it.
+
+---
+
 ## [0.50.0] — 2026-08-23
 
 ### ⚠ BREAKING

package/dist/cookieNames-CqdYWVpp.js

@@ -0,0 +1,11 @@
+//#region src/timeZone.ts
+var e = "viewer", t = "UTC", n = (e) => {
+	if (!e) return !1;
+	try {
+		return new Intl.DateTimeFormat("en-US", { timeZone: e }), !0;
+	} catch {
+		return !1;
+	}
+}, r = "voltro:locale", i = "voltro:theme", a = "voltro:tz";
+//#endregion
+export { e as a, t as i, i as n, n as o, a as r, r as t };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ComponentProps } from 'react';
+import { Context } from 'react';
 import { FormattedMessage } from 'react-intl';
 import { IntlConfig } from 'react-intl';
 import { ReactNode } from 'react';
@@ -61,6 +62,10 @@ export declare const createTypedMessages: <C extends MessageCatalog>() => TypedM
 
 export declare type DateInput = Date | number | string;
 
+/** The zone used when nothing else resolves. Always valid, never surprising —
+ *  and, unlike the process zone, the SAME on the server and in the browser. */
+export declare const DEFAULT_TIME_ZONE = "UTC";
+
 /**
  * Identity function with type narrowing. Wrap your BASE catalog in
  * this so other locales can `extends` its key set.
@@ -105,7 +110,7 @@ export declare interface I18nInstanceReport {
  *  never loaded the package (reports zeroes). */
 export declare const i18nInstanceReport: () => I18nInstanceReport;
 
-export declare const I18nProvider: ({ locale, messages, defaultLocale, silenceMissingTranslations, intlConfig, children, }: I18nProviderProps) => ReactNode;
+export declare const I18nProvider: ({ locale, messages, defaultLocale, silenceMissingTranslations, timeZone, renderedAt, intlConfig, children, }: I18nProviderProps) => ReactNode;
 
 declare interface I18nProviderProps {
     readonly locale: string;
@@ -119,9 +124,41 @@ declare interface I18nProviderProps {
      *  rollout missing strings will fall back to the source-of-truth
      *  locale, no need to flood the console. */
     readonly silenceMissingTranslations?: boolean;
-    /** Forward any other IntlProvider prop unmodified (timeZone,
-     *  formats, textComponent, …). */
-    readonly intlConfig?: Partial<Omit<IntlConfig, 'locale' | 'messages' | 'defaultLocale' | 'onError'>>;
+    /**
+     * The IANA zone every date/time formatter under this provider renders in.
+     *
+     * **Under SSR this is not a preference, it is the correctness knob.** Omit it
+     * and each side falls back to the zone of the runtime it happens to be in —
+     * the pod for the server (UTC on a container with no `TZ`), the viewer's
+     * machine for the browser. The two then disagree by an offset, the day can
+     * differ across midnight, and React reports it as a hydration mismatch.
+     *
+     * The framework resolves and passes this per request when the web app sets
+     * `timeZone` in `app.config.ts`; it also publishes the same value as
+     * `<html data-voltro-tz>` so the client's first render agrees by
+     * construction. Hand-built providers pass it themselves.
+     *
+     * An unusable zone (a stale cookie, a typo'd config, a runtime with a trimmed
+     * ICU) is DROPPED rather than forwarded — otherwise `Intl.DateTimeFormat`
+     * throws and every timestamp in the app degrades to a raw `Date` string.
+     */
+    readonly timeZone?: string;
+    /**
+     * The instant this render reasons about, in epoch milliseconds — the server's
+     * render time, so that a relative formatter ("3 minutes ago") produces the
+     * SAME string on the server and in the hydration pass.
+     *
+     * Live again as soon as hydration commits, so a mounted page does not sit
+     * frozen at the server's clock. Omit it outside SSR: with no stamp the clock
+     * is simply live, which is what a client-only app wants and costs it no
+     * second render pass.
+     */
+    readonly renderedAt?: number;
+    /** Forward any other IntlProvider prop unmodified (formats,
+     *  textComponent, …). `timeZone` has its own prop above — it is
+     *  read by this package's formatters as well as by react-intl, so
+     *  it cannot be an opaque passthrough. */
+    readonly intlConfig?: Partial<Omit<IntlConfig, 'locale' | 'messages' | 'defaultLocale' | 'onError' | 'timeZone'>>;
     readonly children: ReactNode;
 }
 
@@ -143,6 +180,16 @@ export declare type ICUVars<S extends string> = string extends S ? never : S ext
  *  a plural/select BRANCH's text (`"# days total duration"`) is rejected. */
 declare type IsICUIdentifier<S extends string> = S extends '' ? false : S extends `${infer C}${infer Rest}` ? C extends ICUIdentChar ? Rest extends '' ? true : IsICUIdentifier<Rest> : false : false;
 
+/**
+ * Is `name` an IANA zone THIS runtime can format in?
+ *
+ * Runtime-scoped on purpose: the question that matters is not whether the name
+ * is in the tzdata spec but whether `Intl.DateTimeFormat` here accepts it. A
+ * Node built with a trimmed ICU answers differently from a browser, and the
+ * one that has to render is the one that gets asked.
+ */
+export declare const isSupportedTimeZone: (name: string | null | undefined) => name is string;
+
 export declare interface LazyCatalogs<L extends string = string> {
     /** Locales this app declares, in declaration order. */
     readonly locales: ReadonlyArray<L>;
@@ -206,21 +253,7 @@ export declare const LOCALE_COOKIE = "voltro:locale";
  */
 export declare type LooseTFunction = (id: string, values?: Readonly<Record<string, MessageValue>>) => string;
 
-/**
- * Build a children-to-tree wrapper that mounts `<I18nProvider>` with
- * the supplied locale + catalog. The framework's SSG pipeline calls
- * this once per build and passes the returned function as
- * `renderPageToHtml({ outerWrap })`.
- *
- * For a multi-locale build the SSG emits per-locale HTML variants:
- * `voltro build` calls this once per locale and, for each rendered
- * page, picks `localeWraps.get(renderLocale)` — a `[locale]/…` route
- * renders under its own `locale` param, a bare-path route under the
- * `defaultLocale`. The client still swaps to the user's locale on
- * hydration via the runtime's provider in `.framework/app.tsx`, but the
- * emitted HTML is already locale-correct (right catalog + `meta({ locale })`).
- */
-export declare const makeSsgWrap: (locale: string, messages: MessageCatalog, defaultLocale: string) => ((children: ReactNode) => ReactNode);
+export declare const makeSsgWrap: (locale: string, messages: MessageCatalog, defaultLocale: string) => ((children: ReactNode, request?: SsgWrapRequest) => ReactNode);
 
 /**
  * The positional `values` a message key requires: none for a plain message, a
@@ -278,6 +311,42 @@ export declare type PluralForms = {
     readonly other: string;
 };
 
+/**
+ * The instant the CURRENT render is reasoning about, in epoch milliseconds —
+ * or `undefined` for "the clock is live, read it yourself".
+ *
+ * `undefined` is the steady state. A number appears only between the server's
+ * render and the client's hydration commit, which is exactly the window in
+ * which the two sides must agree.
+ */
+export declare const RenderClockContext: Context<number | undefined>;
+
+/**
+ * Build a children-to-tree wrapper that mounts `<I18nProvider>` with
+ * the supplied locale + catalog. The framework's SSG pipeline calls
+ * this once per build and passes the returned function as
+ * `renderPageToHtml({ outerWrap })`.
+ *
+ * For a multi-locale build the SSG emits per-locale HTML variants:
+ * `voltro build` calls this once per locale and, for each rendered
+ * page, picks `localeWraps.get(renderLocale)` — a `[locale]/…` route
+ * renders under its own `locale` param, a bare-path route under the
+ * `defaultLocale`. The client still swaps to the user's locale on
+ * hydration via the runtime's provider in `.framework/app.tsx`, but the
+ * emitted HTML is already locale-correct (right catalog + `meta({ locale })`).
+ */
+/**
+ * Per-request facts the wrapper stamps onto the provider. Both vary per REQUEST
+ * while the wrapper itself is built once per LOCALE, which is why they arrive
+ * at call time rather than in the factory above.
+ */
+export declare interface SsgWrapRequest {
+    /** The IANA zone this request renders in — see `I18nProvider`'s `timeZone`. */
+    readonly timeZone?: string | undefined;
+    /** The server's render instant, so relative times survive hydration. */
+    readonly renderedAt?: number | undefined;
+}
+
 export declare const T: ({ id, ...rest }: TProps) => ReactNode;
 
 /**
@@ -290,6 +359,28 @@ export declare const T: ({ id, ...rest }: TProps) => ReactNode;
  */
 export declare const THEME_COOKIE = "voltro:theme";
 
+/**
+ * The cookie carrying the IANA timezone to render in (`Europe/Berlin`).
+ *
+ * Read by `resolveTimeZone` when the app configures `timeZone: 'viewer'`, and
+ * therefore by every SSR path — it is what lets the SERVER render in the
+ * viewer's zone instead of the pod's. Two writers are expected and both are
+ * correct:
+ *
+ *   - the framework's pre-paint script, which seeds it from
+ *     `Intl.DateTimeFormat().resolvedOptions().timeZone` when it is absent, so
+ *     the zone is known from the second request onward with no login; and
+ *   - the APP, at login, overwriting it with the zone it holds for the signed-in
+ *     user (a profile field, an identity provider's `timeZone` claim). That is
+ *     the authoritative one — a user travelling with a laptop keeps the zone
+ *     their account says, not the airport's.
+ *
+ * Absent means "no answer yet", never "UTC": the resolver falls through to the
+ * app's `defaultTimeZone` so the two sides still agree on a value neither of
+ * them guessed.
+ */
+export declare const TIMEZONE_COOKIE = "voltro:tz";
+
 declare type TProps = Omit<ComponentProps<typeof FormattedMessage>, 'id'> & {
     readonly id: string;
 };
@@ -328,11 +419,20 @@ export declare type TypedTProps<C extends MessageCatalog> = Omit<ComponentProps<
 export declare const useFormatCurrency: (currency: string) => ((value: number, options?: Intl.NumberFormatOptions) => string);
 
 /**
- * Locale-aware date/time formatting bound to the active locale.
+ * Locale-aware date/time formatting bound to the active locale AND the active
+ * zone.
  *
- * Pass a `timeZone` in the options to render in a fixed zone (what an app pins
- * globally today) — omit it and the viewer's own zone is used, which is what a
- * multi-timezone app wants.
+ * The zone comes from the provider (`useTimeZone`), which the framework fills
+ * from `app.config.ts`'s `timeZone` — either a fixed IANA name for everyone, or
+ * `'viewer'` to resolve each request against the signed-in user's own zone.
+ * Passing `timeZone` in the options overrides it for one call, which is what a
+ * value that genuinely belongs to a fixed zone wants (a store's opening hours,
+ * a scheduled broadcast).
+ *
+ * **With no zone pinned anywhere, each runtime uses its own** — the pod's on the
+ * server, the viewer's in the browser. That is fine for a client-rendered page
+ * and is a hydration mismatch under SSR, because the two are not the same zone
+ * and across midnight not even the same day.
  */
 export declare const useFormatDate: () => ((value: DateInput, options?: Intl.DateTimeFormatOptions) => string);
 
@@ -342,6 +442,9 @@ export declare const useFormatNumber: () => ((value: number, options?: Intl.Numb
 /** All formatters at once, for components that need several. */
 export declare const useFormatters: () => {
     readonly locale: string;
+    /** The pinned IANA zone, or `undefined` when the ambient runtime zone is in
+     *  use — see `useTimeZone`. */
+    readonly timeZone: string | undefined;
     readonly formatDate: ReturnType<typeof useFormatDate>;
     readonly relativeTime: ReturnType<typeof useRelativeTime>;
     readonly formatNumber: ReturnType<typeof useFormatNumber>;
@@ -369,11 +472,26 @@ export declare const usePlural: () => ((count: number, forms: PluralForms, optio
  * Picks the largest unit that fits, so a 90-minute delta reads "1 hour ago", not
  * "90 minutes ago". Anything under a second is "now" (via the `second` unit at
  * 0), which avoids the "0 seconds ago" flicker hand-rolled versions produce.
+ *
+ * **Hydration-safe by construction.** The base instant is the server's render
+ * time for the server render and the hydration pass that has to match it, then
+ * the live clock once hydration commits — so the string cannot change between
+ * the HTML and the first client render, and does not stay frozen afterwards.
+ * Pass `{ now }` to state the base yourself; that always wins.
  */
 export declare const useRelativeTime: () => ((value: DateInput, options?: Intl.RelativeTimeFormatOptions & {
     readonly now?: DateInput;
 }) => string);
 
+/**
+ * The pinned render instant, or `undefined` when the clock is live.
+ *
+ * Call sites treat `undefined` as "use `Date.now()`" rather than defaulting to
+ * one, so a component outside any provider behaves exactly as it did before
+ * this context existed.
+ */
+export declare const useRenderClock: () => number | undefined;
+
 export declare const useT: (id: string, values?: Record<string, string | number | boolean | Date | null | undefined>) => string;
 
 /**
@@ -392,10 +510,24 @@ export declare const useT: (id: string, values?: Record<string, string | number
  */
 export declare const useTFn: () => (id: string, values?: Record<string, string | number | boolean | Date | null | undefined>) => string;
 
+/**
+ * The IANA zone the active provider renders in, or `undefined` when none is
+ * pinned and the ambient runtime zone is in use.
+ *
+ * `undefined` is a real answer and worth branching on: it means the server and
+ * the browser are each using their OWN zone, so a server-rendered timestamp is
+ * not guaranteed to survive hydration. Set `timeZone` in the web
+ * `app.config.ts` to make it a value.
+ */
+export declare const useTimeZone: () => string | undefined;
+
 /** A validated ICU arg name, or `never` when the candidate isn't a real
  *  identifier. This is the guard that keeps the type-level parse from emitting a
  *  plural/select branch's TEXT as a phantom required var — an ICU arg name can't
  *  contain spaces/`#`/`—`, so anything that does is dropped. */
 declare type ValidICUName<S extends string> = IsICUIdentifier<S> extends true ? S : never;
 
+/** The `app.config.ts` sentinel meaning "resolve per request from the viewer". */
+export declare const VIEWER_TIME_ZONE = "viewer";
+
 export { }

package/dist/index.js

@@ -1,14 +1,14 @@
-import { n as e, t } from "./cookieNames-BlfAjNqu.js";
-import { FormattedMessage as n, IntlProvider as r, useIntl as i } from "react-intl";
-import { jsx as a } from "react/jsx-runtime";
-import { createElement as o, useCallback as s, useEffect as c, useMemo as l, useState as u } from "react";
+import { a as e, i as t, n, o as r, r as i, t as a } from "./cookieNames-CqdYWVpp.js";
+import { createContext as o, createElement as s, useCallback as c, useContext as l, useEffect as u, useMemo as d, useState as f } from "react";
+import { FormattedMessage as p, IntlProvider as m, useIntl as h } from "react-intl";
+import { jsx as g } from "react/jsx-runtime";
 //#region src/instanceRegistry.ts
-var d = "__voltro_i18n_instances__", f = () => {
-	let e = globalThis, t = e[d];
+var _ = "__voltro_i18n_instances__", v = () => {
+	let e = globalThis, t = e[_];
 	if (t !== void 0) return t;
 	let n = { records: [] };
-	return e[d] = n, n;
-}, p = () => {
+	return e[_] = n, n;
+}, y = () => {
 	try {
 		let e = String((/* @__PURE__ */ Error()).stack ?? "").split("\n");
 		for (let t of e.slice(3)) {
@@ -17,60 +17,71 @@ var d = "__voltro_i18n_instances__", f = () => {
 		}
 	} catch {}
 	return "unknown";
-}, m = (e) => {
-	f().records.push({
-		file: p(),
+}, b = (e) => {
+	v().records.push({
+		file: y(),
 		intlProvider: e
 	});
-}, h = () => {
-	let e = globalThis[d]?.records ?? [];
+}, x = () => {
+	let e = globalThis[_]?.records ?? [];
 	return {
 		instances: e.length,
 		reactIntlCopies: new Set(e.map((e) => e.intlProvider)).size,
 		files: [...new Set(e.map((e) => e.file))]
 	};
-};
+}, S = o(void 0), C = () => l(S);
 //#endregion
 //#region src/provider.tsx
-m(r);
-var g = ({ locale: e, messages: t, defaultLocale: n, silenceMissingTranslations: i = !0, intlConfig: o, children: s }) => {
-	let c = i ? (e) => {
+b(m);
+var w = ({ locale: e, messages: t, defaultLocale: n, silenceMissingTranslations: i = !0, timeZone: a, renderedAt: o, intlConfig: s, children: c }) => {
+	let l = i ? (e) => {
 		e.code !== "MISSING_TRANSLATION" && console.error(e);
-	} : void 0;
-	return /* @__PURE__ */ a(r, {
+	} : void 0, [d, p] = f(!1);
+	u(() => {
+		o !== void 0 && p(!0);
+	}, [o]);
+	let h = d ? void 0 : o, _ = r(a) ? a : void 0;
+	return /* @__PURE__ */ g(m, {
 		locale: e,
 		defaultLocale: n,
 		messages: t,
-		...c ? { onError: c } : {},
-		...o,
-		children: s
+		...l ? { onError: l } : {},
+		..._ ? { timeZone: _ } : {},
+		...s,
+		children: /* @__PURE__ */ g(S.Provider, {
+			value: h,
+			children: c
+		})
 	});
-}, _ = ({ id: e, ...t }) => /* @__PURE__ */ a(n, {
+}, T = ({ id: e, ...t }) => /* @__PURE__ */ g(p, {
 	id: e,
 	...t
-}), v = (e, t) => i().formatMessage({ id: e }, t), y = () => i().locale, b = () => i().messages, x = () => {
-	let e = i();
-	return s((t, n) => e.formatMessage({ id: t }, n), [e]);
-}, S = (e, t, n, r) => {
+}), E = (e, t) => h().formatMessage({ id: e }, t), D = () => h().locale, O = () => h().messages, k = () => {
+	let e = h();
+	return c((t, n) => e.formatMessage({ id: t }, n), [e]);
+}, A = (e, t, n, r) => {
 	if (t === 0 && n.zero !== void 0) return n.zero.replace(/\{count\}/g, String(t));
 	let i = "other";
 	try {
 		i = new Intl.PluralRules(e, r).select(t);
 	} catch {}
 	return (n[i] ?? n.other).replace(/\{count\}/g, String(t));
-}, C = () => {
-	let e = y();
-	return s((t, n, r) => S(e, t, n, r), [e]);
-}, w = (e) => e instanceof Date ? e : new Date(e), T = () => {
-	let e = y();
-	return s((t, n) => {
+}, j = () => {
+	let e = D();
+	return c((t, n, r) => A(e, t, n, r), [e]);
+}, M = (e) => e instanceof Date ? e : new Date(e), N = () => h().timeZone, P = () => {
+	let e = D(), t = N();
+	return c((n, r) => {
 		try {
-			return new Intl.DateTimeFormat(e, n).format(w(t));
+			return new Intl.DateTimeFormat(e, {
+				...t ? { timeZone: t } : {},
+				...r
+			}).format(M(n));
 		} catch {
-			return String(t);
+			return String(n);
 		}
-	}, [e]);
-}, E = [
+	}, [e, t]);
+}, F = [
 	["year", 31536e6],
 	["month", 2592e6],
 	["week", 6048e5],
@@ -78,67 +89,69 @@ var g = ({ locale: e, messages: t, defaultLocale: n, silenceMissingTranslations:
 	["hour", 36e5],
 	["minute", 6e4],
 	["second", 1e3]
-], D = () => {
-	let e = y();
-	return s((t, n) => {
-		let { now: r, ...i } = n ?? {}, a = w(t).getTime() - (r === void 0 ? Date.now() : w(r).getTime());
+], I = () => {
+	let e = D(), t = C();
+	return c((n, r) => {
+		let { now: i, ...a } = r ?? {}, o = M(n).getTime() - (i === void 0 ? t ?? Date.now() : M(i).getTime());
 		try {
 			let t = new Intl.RelativeTimeFormat(e, {
 				numeric: "auto",
-				...i
+				...a
 			});
-			for (let [e, n] of E) if (Math.abs(a) >= n || e === "second") return t.format(Math.round(a / n), e);
+			for (let [e, n] of F) if (Math.abs(o) >= n || e === "second") return t.format(Math.round(o / n), e);
 			return t.format(0, "second");
 		} catch {
-			return String(t);
+			return String(n);
 		}
-	}, [e]);
-}, O = () => {
-	let e = y();
-	return s((t, n) => {
+	}, [e, t]);
+}, L = () => {
+	let e = D();
+	return c((t, n) => {
 		try {
 			return new Intl.NumberFormat(e, n).format(t);
 		} catch {
 			return String(t);
 		}
 	}, [e]);
-}, k = (e) => {
-	let t = O();
-	return s((n, r) => t(n, {
+}, R = (e) => {
+	let t = L();
+	return c((n, r) => t(n, {
 		style: "currency",
 		currency: e,
 		...r
 	}), [t, e]);
-}, A = () => {
-	let e = y(), t = T(), n = D(), r = O(), i = C();
-	return l(() => ({
+}, z = () => {
+	let e = D(), t = N(), n = P(), r = I(), i = L(), a = j();
+	return d(() => ({
 		locale: e,
-		formatDate: t,
-		relativeTime: n,
-		formatNumber: r,
-		plural: i
+		timeZone: t,
+		formatDate: n,
+		relativeTime: r,
+		formatNumber: i,
+		plural: a
 	}), [
 		e,
 		t,
 		n,
 		r,
-		i
+		i,
+		a
 	]);
-}, j = (e) => e, M = () => (e) => e, N = (e, t, n) => e[t ?? n] ?? e[n], P = /\{\s*([A-Za-z0-9_]+)/g, F = (e) => {
+}, B = (e) => e, V = () => (e) => e, H = (e, t, n) => e[t ?? n] ?? e[n], U = /\{\s*([A-Za-z0-9_]+)/g, W = (e) => {
 	let t = /* @__PURE__ */ new Set();
-	for (let n of e.matchAll(P)) t.add(n[1]);
+	for (let n of e.matchAll(U)) t.add(n[1]);
 	return t;
-}, I = (e, t) => {
+}, G = (e, t) => {
 	let n = Object.keys(e);
 	if (n.length < 2) return;
 	let r = t?.baseLocale ?? n[0], i = e[r] ?? {}, a = [];
 	for (let [t, o] of Object.entries(i)) {
-		let i = F(o);
+		let i = W(o);
 		for (let o of n) {
 			if (o === r) continue;
 			let n = e[o]?.[t];
 			if (n === void 0) continue;
-			let s = F(n), c = [...i].filter((e) => !s.has(e)), l = [...s].filter((e) => !i.has(e));
+			let s = W(n), c = [...i].filter((e) => !s.has(e)), l = [...s].filter((e) => !i.has(e));
 			if (c.length > 0 || l.length > 0) {
 				let e = [c.length > 0 ? `missing {${c.join("}, {")}}` : "", l.length > 0 ? `unexpected {${l.join("}, {")}}` : ""].filter(Boolean);
 				a.push(`${o} '${t}': ${e.join("; ")} (base ${r} has {${[...i].join("}, {")}})`);
@@ -152,21 +165,21 @@ var g = ({ locale: e, messages: t, defaultLocale: n, silenceMissingTranslations:
 		return;
 	}
 	throw Error(o);
-}, L = (e) => {
+}, K = (e) => {
 	let t = e;
 	return t.dynamic === void 0 && (t.dynamic = (t, n) => e(t, n)), t;
-}, R = () => ({
-	useT: L((e, t) => v(e, t)),
-	useTFn: (() => L(x())),
-	T: _
-}), z = (e) => "default" in e && typeof e.default == "object" ? e.default : e, B = (e, t) => {
+}, q = () => ({
+	useT: K((e, t) => E(e, t)),
+	useTFn: (() => K(k())),
+	T
+}), J = (e) => "default" in e && typeof e.default == "object" ? e.default : e, Y = (e, t) => {
 	let n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map(), i = (n) => n && n in e ? n : t, a = (t) => {
 		let a = i(t), o = n.get(a);
 		if (o) return Promise.resolve(o);
 		let s = r.get(a);
 		if (s) return s;
 		let c = e[a], l = c().then((e) => {
-			let t = z(e);
+			let t = J(e);
 			return n.set(a, t), r.delete(a), t;
 		}).catch((e) => {
 			throw r.delete(a), e;
@@ -182,33 +195,35 @@ var g = ({ locale: e, messages: t, defaultLocale: n, silenceMissingTranslations:
 			a(e).catch(() => {});
 		}
 	};
-}, V = ({ catalogs: e, locale: t, fallback: n = null, silenceMissingTranslations: r, children: i }) => {
-	let [o, s] = u(() => e.peek(t));
-	return c(() => {
+}, X = ({ catalogs: e, locale: t, fallback: n = null, silenceMissingTranslations: r, children: i }) => {
+	let [a, o] = f(() => e.peek(t));
+	return u(() => {
 		let n = e.peek(t);
 		if (n) {
-			s(n);
+			o(n);
 			return;
 		}
 		let r = !0;
-		return s(void 0), e.load(t).then((e) => {
-			r && s(e);
+		return o(void 0), e.load(t).then((e) => {
+			r && o(e);
 		}), () => {
 			r = !1;
 		};
-	}, [e, t]), o ? /* @__PURE__ */ a(g, {
+	}, [e, t]), a ? /* @__PURE__ */ g(w, {
 		locale: t,
-		messages: o,
+		messages: a,
 		defaultLocale: e.defaultLocale,
 		...r === void 0 ? {} : { silenceMissingTranslations: r },
 		children: i
 	}) : n;
-}, H = (e, t, n) => (r) => o(g, {
+}, Z = (e, t, n) => (r, i) => s(w, {
 	locale: e,
 	messages: t,
 	defaultLocale: n,
 	silenceMissingTranslations: !0,
+	...i?.timeZone === void 0 ? {} : { timeZone: i.timeZone },
+	...i?.renderedAt === void 0 ? {} : { renderedAt: i.renderedAt },
 	children: r
 });
 //#endregion
-export { g as I18nProvider, t as LOCALE_COOKIE, V as LazyI18nProvider, _ as T, e as THEME_COOKIE, I as assertCatalogParity, R as createTypedMessages, j as defineCatalog, B as defineCatalogs, M as defineLocale, h as i18nInstanceReport, H as makeSsgWrap, N as pickCatalog, S as plural, k as useFormatCurrency, T as useFormatDate, O as useFormatNumber, A as useFormatters, y as useLocale, b as useMessages, C as usePlural, D as useRelativeTime, v as useT, x as useTFn };
+export { t as DEFAULT_TIME_ZONE, w as I18nProvider, a as LOCALE_COOKIE, X as LazyI18nProvider, S as RenderClockContext, T, n as THEME_COOKIE, i as TIMEZONE_COOKIE, e as VIEWER_TIME_ZONE, G as assertCatalogParity, q as createTypedMessages, B as defineCatalog, Y as defineCatalogs, V as defineLocale, x as i18nInstanceReport, r as isSupportedTimeZone, Z as makeSsgWrap, H as pickCatalog, A as plural, R as useFormatCurrency, P as useFormatDate, L as useFormatNumber, z as useFormatters, D as useLocale, O as useMessages, j as usePlural, I as useRelativeTime, C as useRenderClock, E as useT, k as useTFn, N as useTimeZone };

package/dist/server.d.ts

@@ -1,3 +1,17 @@
+/** The zone used when nothing else resolves. Always valid, never surprising —
+ *  and, unlike the process zone, the SAME on the server and in the browser. */
+export declare const DEFAULT_TIME_ZONE = "UTC";
+
+/**
+ * Is `name` an IANA zone THIS runtime can format in?
+ *
+ * Runtime-scoped on purpose: the question that matters is not whether the name
+ * is in the tzdata spec but whether `Intl.DateTimeFormat` here accepts it. A
+ * Node built with a trimmed ICU answers differently from a browser, and the
+ * one that has to render is the one that gets asked.
+ */
+export declare const isSupportedTimeZone: (name: string | null | undefined) => name is string;
+
 /**
  * Build the per-request resolver: cookie > Accept-Language > default, then the
  * matching wrapper.
@@ -11,6 +25,13 @@ export declare const makeSsrI18nResolver: (args: SsrI18nResolverArgs) => ((cooki
 /** What a renderer needs to render one request in the right locale. */
 export declare interface ResolvedSsrI18n {
     readonly locale: string;
+    /**
+     * The IANA zone this request renders in, or `undefined` when the app pins
+     * none. The renderer PUBLISHES it (`<html data-voltro-tz>`) so the client's
+     * first render formats against the same value the server did — the same
+     * contract `<html lang>` has for the locale.
+     */
+    readonly timeZone: string | undefined;
     /** Mounts `<I18nProvider>` around the tree — `renderPageToHtml`'s `outerWrap`. */
     readonly outerWrap: (children: unknown) => unknown;
 }
@@ -32,13 +53,67 @@ export declare interface ResolveLocaleArgs {
     readonly defaultLocale: string;
 }
 
+/**
+ * Resolve the IANA zone this request renders in, or `undefined` when the app
+ * pins none.
+ *
+ * Every candidate is validated before it is returned, so an unusable value
+ * (stale cookie naming a zone this runtime's ICU does not carry, a typo in
+ * `app.config.ts`) falls THROUGH to the next signal rather than reaching
+ * `Intl.DateTimeFormat` — which would throw and degrade every date in the app
+ * to a raw `Date` string. Same treatment `resolveLocale` gives a cookie naming
+ * a locale we no longer ship.
+ */
+export declare const resolveTimeZone: (args: ResolveTimeZoneArgs) => string | undefined;
+
+export declare interface ResolveTimeZoneArgs {
+    /** Raw `Cookie:` request header, or null/undefined when absent. */
+    readonly cookieHeader?: string | null;
+    /**
+     * The web app's `timeZone` setting: an IANA name to pin one zone for every
+     * viewer, or `'viewer'` to resolve per request from the `voltro:tz` cookie.
+     * Absent means the app has not opted in — the result is `undefined` and each
+     * runtime keeps using its own zone, which is the pre-existing behaviour.
+     */
+    readonly configured?: string | null;
+    /**
+     * The answer when `'viewer'` yields nothing: the very first request of a
+     * session (no cookie yet) and every prerendered page (one document, all
+     * viewers). Defaults to `UTC` — arbitrary, but identical on both sides, which
+     * is the property that matters.
+     */
+    readonly defaultTimeZone?: string | null;
+}
+
 export declare interface SsrI18nResolverArgs {
-    /** Per-locale `<I18nProvider>` wrappers, built by the caller with `makeSsgWrap`. */
-    readonly wraps: Readonly<Record<string, (children: unknown) => unknown>>;
+    /**
+     * Per-locale `<I18nProvider>` wrappers, built by the caller with
+     * `makeSsgWrap`. The second parameter carries the per-REQUEST facts (zone,
+     * render instant); the wrapper itself is built once per LOCALE, which is why
+     * they cannot live in the factory.
+     */
+    readonly wraps: Readonly<Record<string, (children: unknown, request?: {
+        readonly timeZone?: string | undefined;
+        readonly renderedAt?: number | undefined;
+    }) => unknown>>;
     /** Locale codes the app ships catalogs for. */
     readonly supported: ReadonlyArray<string>;
     /** MUST be in `supported`. */
     readonly defaultLocale: string;
+    /** The app's `timeZone` setting — an IANA name, or `'viewer'`. See
+     *  `resolveTimeZone`. */
+    readonly timeZone?: string | null;
+    /** Fallback when `'viewer'` yields nothing. See `resolveTimeZone`. */
+    readonly defaultTimeZone?: string | null;
+    /**
+     * The render instant, injected for tests. Production leaves it unset and each
+     * request stamps its own `Date.now()` — the point of the stamp is that the
+     * CLIENT reuses the server's number, not that the number is fixed.
+     */
+    readonly now?: () => number;
 }
 
+/** The `app.config.ts` sentinel meaning "resolve per request from the viewer". */
+export declare const VIEWER_TIME_ZONE = "viewer";
+
 export { }

package/dist/server.js

@@ -1,10 +1,10 @@
-import { t as e } from "./cookieNames-BlfAjNqu.js";
+import { a as e, i as t, o as n, r, t as i } from "./cookieNames-CqdYWVpp.js";
 //#region src/server.ts
-var t = e, n = (e) => RegExp(`(?:^|;\\s*)${e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=([^;]*)`), r = (e, t) => {
+var a = i, o = (e) => RegExp(`(?:^|;\\s*)${e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=([^;]*)`), s = (e, t) => {
 	if (!e) return;
-	let r = e.match(n(t));
-	return r ? decodeURIComponent(r[1]) : void 0;
-}, i = (e, t) => {
+	let n = e.match(o(t));
+	return n ? decodeURIComponent(n[1]) : void 0;
+}, c = (e, t) => {
 	let n = e.toLowerCase();
 	for (; n.length > 0;) {
 		let e = t.find((e) => e.toLowerCase() === n);
@@ -13,7 +13,7 @@ var t = e, n = (e) => RegExp(`(?:^|;\\s*)${e.replace(/[.*+?^${}()|[\]\\]/g, "\\$
 		if (r < 0) return;
 		n = n.slice(0, r);
 	}
-}, a = (e) => e ? e.split(",").map((e) => {
+}, l = (e) => e ? e.split(",").map((e) => {
 	let [t, ...n] = e.split(";").map((e) => e.trim());
 	if (!t || t === "*") return null;
 	let r = 1;
@@ -28,31 +28,45 @@ var t = e, n = (e) => RegExp(`(?:^|;\\s*)${e.replace(/[.*+?^${}()|[\]\\]/g, "\\$
 		tag: t,
 		q: r
 	};
-}).filter((e) => e !== null).sort((e, t) => t.q - e.q) : [], o = (e) => {
-	let { cookieHeader: n, acceptLanguageHeader: o, supported: s, defaultLocale: c } = e, l = r(n, t);
-	if (l) {
-		let e = i(l, s);
+}).filter((e) => e !== null).sort((e, t) => t.q - e.q) : [], u = (e) => {
+	let { cookieHeader: t, acceptLanguageHeader: n, supported: r, defaultLocale: i } = e, o = s(t, a);
+	if (o) {
+		let e = c(o, r);
 		if (e) return e;
 	}
-	for (let e of a(o)) {
-		let t = i(e.tag, s);
+	for (let e of l(n)) {
+		let t = c(e.tag, r);
 		if (t) return t;
 	}
-	return c;
-}, s = (e) => {
+	return i;
+}, d = (e) => {
+	let { cookieHeader: t, configured: i, defaultTimeZone: a } = e;
+	if (!i) return;
+	if (i !== "viewer") return n(i) ? i : n(a) ? a : "UTC";
+	let o = s(t, r);
+	return n(o) ? o : n(a) ? a : "UTC";
+}, f = (e) => {
 	let { wraps: t, supported: n, defaultLocale: r } = e;
-	return Object.keys(t).length === 0 ? () => void 0 : (e, i) => {
-		let a = o({
-			cookieHeader: e ?? null,
-			acceptLanguageHeader: i ?? null,
+	return Object.keys(t).length === 0 ? () => void 0 : (i, a) => {
+		let o = u({
+			cookieHeader: i ?? null,
+			acceptLanguageHeader: a ?? null,
 			supported: n,
 			defaultLocale: r
-		}), s = t[a] ?? t[r];
-		return s === void 0 ? void 0 : {
-			locale: a,
-			outerWrap: s
+		}), s = d({
+			cookieHeader: i ?? null,
+			configured: e.timeZone ?? null,
+			defaultTimeZone: e.defaultTimeZone ?? null
+		}), c = (e.now ?? Date.now)(), l = t[o] ?? t[r];
+		if (l !== void 0) return {
+			locale: o,
+			timeZone: s,
+			outerWrap: (e) => l(e, {
+				timeZone: s,
+				renderedAt: c
+			})
 		};
 	};
 };
 //#endregion
-export { s as makeSsrI18nResolver, o as resolveLocale };
+export { t as DEFAULT_TIME_ZONE, e as VIEWER_TIME_ZONE, n as isSupportedTimeZone, f as makeSsrI18nResolver, u as resolveLocale, d as resolveTimeZone };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/i18n",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Voltro's i18n layer — thin opinionated wrap over react-intl. Provides the framework's locale-resolution conventions (voltro:locale cookie + Accept-Language fallback), a typed message-catalog helper, and a slim provider component. Power users can import directly from react-intl for advanced APIs.",
   "keywords": [
     "voltro",

package/dist/cookieNames-BlfAjNqu.js

@@ -1,4 +0,0 @@
-//#region src/cookieNames.ts
-var e = "voltro:locale", t = "voltro:theme";
-//#endregion
-export { t as n, e as t };