@pithy-sh/i18n 0.1.2 → 0.1.3

package/dist/config/config.js

@@ -0,0 +1,103 @@
+import { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { Locale } from "@pithy-sh/core/src/i18n/locale";
+import { z } from "zod";
+//#region src/config/config.ts
+/**
+* One link of the **server** resolver chain — the order a Worker asks "what language is this request in?".
+*
+* Split from the browser chain because `localStorage` does not exist in a Worker and
+* `navigator.language` inside workerd is the constant `"en"`, carrying no request information at all.
+* Two chains over one contract is honest; one chain with half its links inert is not.
+*/
+const ServerResolver = z.enum([
+	"param",
+	"user",
+	"cookie",
+	"header",
+	"default"
+]).describe("A link of the server resolver chain: an explicit param, the account, a cookie, the header, the default.");
+/**
+* One link of the **browser** resolver chain.
+*
+* `account` sits above `storage` deliberately: `pithy_auth_users.locale` is where a person's locale
+* lives, so a signed-in reader's choice must not silently diverge per device. See `docs/I18N.md`.
+*/
+const BrowserResolver = z.enum([
+	"query",
+	"account",
+	"storage",
+	"navigator",
+	"server",
+	"default"
+]).describe("A link of the browser resolver chain: `?lang=`, the account, local storage, the browser's own languages, the server, the default.");
+/** The server chain's default order — explicit param, account, cookie, `Accept-Language`, project default. */
+const DEFAULT_SERVER_RESOLVERS = [
+	"param",
+	"user",
+	"cookie",
+	"header",
+	"default"
+];
+/** The browser chain's default order — `?lang=`, account, local storage, the server's answer, default. */
+/**
+* The browser chain's default order — `?lang=`, account, this device's memory, the reader's own
+* browser languages, what the server declared, the project default.
+*
+* **`navigator` sits above `server`, and that ordering is the whole reason the link exists.** The
+* `server` link reads `document.documentElement.lang`, and a scaffolded SPA is served from a static
+* `index.html` that says `lang="en"` with no substitution token — so without a browser link, a
+* first-time Spanish visitor to a project shipping `es` resolved to the default and read English on
+* every screen. Automatic negotiation worked on the server and nowhere else.
+*
+* Placing it above `server` costs a genuinely server-rendered app nothing: if that server negotiated,
+* it negotiated from `Accept-Language`, which is the same preference `navigator.languages` reports —
+* and anything it knew that the browser does not, the reader's account, is already ranked higher.
+*/
+const DEFAULT_BROWSER_RESOLVERS = [
+	"query",
+	"account",
+	"storage",
+	"navigator",
+	"server",
+	"default"
+];
+/** The locale the kit writes in, and what every unconfigured project falls back to. */
+const DEFAULT_LOCALE = "en";
+/**
+* The i18n capability's configuration.
+*
+* Everything an adopter decides about language lives here, including their own catalogs — **a config
+* object passed to the capability, never files discovered on disk.** Two reasons, and both are hard
+* constraints rather than preferences. `configEntrypoints.test.ts` imports every capability's config
+* entry point in a plain Node process, so a catalog loader doing `readFileSync` at module scope breaks
+* `pithy upgrade`, `migrate` and `deploy` for every project composing it. And a catalog file copied
+* into an adopter's repository is a fork on the day they scaffold: a typo fix or a new locale could
+* never reach them again.
+*/
+const I18nConfig = z.object({
+	supportedLocales: z.array(Locale).min(1).default([DEFAULT_LOCALE]).describe("Every locale this project serves. Ship the least specific tag that is true — `es`, not `es-ES`."),
+	defaultLocale: Locale.default(DEFAULT_LOCALE).describe("The locale served when nothing else answers. Must be one of `supportedLocales`."),
+	messages: LocaleCatalogs.default({}).describe("This project's own catalogs. Overriding one kit key is one entry; everything unmentioned keeps flowing from the package."),
+	exceptions: z.record(z.string().describe("The language range a reader sends that no truncation of it would match."), Locale.describe("The supported locale it means.")).default({}).transform((exceptions) => Object.fromEntries(Object.entries(exceptions).map(([range, locale]) => [range.toLowerCase(), locale]))).describe("Language ranges the matcher cannot derive — historical pairs like `nb` meaning `no`."),
+	cookie: z.string().min(1).default("pithy_locale").describe("The cookie the server chain's `cookie` link reads a chosen locale from."),
+	queryParam: z.string().min(1).default("lang").describe("The query parameter an explicit choice arrives on, on both the server and the browser."),
+	storageKey: z.string().min(1).default("pithy.locale").describe("The `localStorage` key the browser chain's `storage` link reads and writes."),
+	serverResolvers: z.array(ServerResolver).min(1).default([...DEFAULT_SERVER_RESOLVERS]).describe("The server chain, in the order it is asked. Reorder or shorten it; `default` is the last resort."),
+	browserResolvers: z.array(BrowserResolver).min(1).default([...DEFAULT_BROWSER_RESOLVERS]).describe("The browser chain, in the order it is asked.")
+}).check((ctx) => {
+	const { supportedLocales, defaultLocale } = ctx.value;
+	if (!supportedLocales.includes(defaultLocale)) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["defaultLocale"],
+		message: `\`${defaultLocale}\` is the default locale and is not in \`supportedLocales\`, so nothing would answer when negotiation fails.`
+	});
+	for (const locale of Object.keys(ctx.value.messages)) if (!supportedLocales.includes(locale)) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["messages", locale],
+		message: `\`${locale}\` carries messages and is not in \`supportedLocales\`, so nothing would ever read them.`
+	});
+}).describe("How this project negotiates and renders language, and the catalogs it adds of its own.");
+//#endregion
+export { BrowserResolver, I18nConfig, ServerResolver };

package/dist/http/middleware.d.ts

@@ -0,0 +1,36 @@
+import type { PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import type { I18nConfig } from "../config/config";
+/** How a request's locale is looked up, given the locale that won. Supplied by the capability. */
+export type LayersFor = (locale: string) => readonly (MessageCatalog | undefined)[];
+/**
+ * The one middleware this capability contributes: resolve the request's locale, and put a real
+ * translator on it.
+ *
+ * It **replaces** `c.var.t` rather than filling a null. Core seeds a translator over the baked English
+ * for every request whether or not this capability is composed, which is what lets every capability
+ * call `c.var.t(...)` with no null check, and what makes a project that never opts in behave byte for
+ * byte as it did before.
+ *
+ * A fresh translator per request, never a cached one. A Worker isolate is reused across requests from
+ * different readers, so anything holding a locale across that boundary applies request A's language to
+ * request B. It is the same hazard `z.config()` is banned repo-wide for, and it is why the `Intl`
+ * formatters are held on the translator — which lives and dies with one request — rather than in a
+ * module-level cache.
+ *
+ * ## Why the query string is read off the URL here, and not through `zValidator`
+ *
+ * §HTTP's rule is that a route declares its request contract on the route line and a handler reads
+ * `c.req.valid(target)`; `plugins/no-raw-request-input.grit` enforces it by making the raw accessors
+ * unreadable under every capability's `src/http/` tree. This is a **global middleware over every route**, so there
+ * is no route line to declare a validator on and no handler to hand a typed value to — the rule's
+ * replacement does not exist at this position.
+ *
+ * What the rule is *for* still holds, and it holds structurally rather than by care: the value is one
+ * language range among four sources, every one of them is matched against `config.supportedLocales`
+ * before anything is done with it, and a range that matches nothing falls through to the next link.
+ * Nothing downstream ever sees a string this middleware did not already find in the project's own
+ * configured set. A reader who sends `?lang=<script>` gets the default locale.
+ */
+export declare function i18nMiddleware(config: I18nConfig, layersFor: LayersFor): PithyMiddleware;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/http/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/http/middleware.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,GAAG,eAAe,CAwExF"}

package/dist/http/middleware.js

@@ -0,0 +1,93 @@
+import { resolveServerLocale } from "../resolve/server.js";
+import { createTranslator } from "@pithy-sh/core/src/i18n/translator";
+import { getCookie } from "hono/cookie";
+//#region src/http/middleware.ts
+/**
+* The one middleware this capability contributes: resolve the request's locale, and put a real
+* translator on it.
+*
+* It **replaces** `c.var.t` rather than filling a null. Core seeds a translator over the baked English
+* for every request whether or not this capability is composed, which is what lets every capability
+* call `c.var.t(...)` with no null check, and what makes a project that never opts in behave byte for
+* byte as it did before.
+*
+* A fresh translator per request, never a cached one. A Worker isolate is reused across requests from
+* different readers, so anything holding a locale across that boundary applies request A's language to
+* request B. It is the same hazard `z.config()` is banned repo-wide for, and it is why the `Intl`
+* formatters are held on the translator — which lives and dies with one request — rather than in a
+* module-level cache.
+*
+* ## Why the query string is read off the URL here, and not through `zValidator`
+*
+* §HTTP's rule is that a route declares its request contract on the route line and a handler reads
+* `c.req.valid(target)`; `plugins/no-raw-request-input.grit` enforces it by making the raw accessors
+* unreadable under every capability's `src/http/` tree. This is a **global middleware over every route**, so there
+* is no route line to declare a validator on and no handler to hand a typed value to — the rule's
+* replacement does not exist at this position.
+*
+* What the rule is *for* still holds, and it holds structurally rather than by care: the value is one
+* language range among four sources, every one of them is matched against `config.supportedLocales`
+* before anything is done with it, and a range that matches nothing falls through to the next link.
+* Nothing downstream ever sees a string this middleware did not already find in the project's own
+* configured set. A reader who sends `?lang=<script>` gets the default locale.
+*/
+function i18nMiddleware(config, layersFor) {
+	return (app) => {
+		app.use("*", async (c, next) => {
+			let resolved;
+			const locale = () => resolved ??= resolveServerLocale({
+				param: queryParam(c.req.url, config.queryParam),
+				user: c.var.auth?.locale ?? null,
+				cookie: getCookie(c, config.cookie) ?? null,
+				header: c.req.header("accept-language") ?? null
+			}, config);
+			let translator;
+			const t = () => translator ??= createTranslator({
+				catalogLocale: locale().catalogLocale,
+				formattingLocale: locale().formattingLocale,
+				layers: layersFor(locale().catalogLocale)
+			});
+			c.set("locale", {
+				get catalogLocale() {
+					return locale().catalogLocale;
+				},
+				get formattingLocale() {
+					return locale().formattingLocale;
+				},
+				get direction() {
+					return locale().direction;
+				}
+			});
+			c.set("t", {
+				get catalogLocale() {
+					return t().catalogLocale;
+				},
+				get formattingLocale() {
+					return t().formattingLocale;
+				},
+				get direction() {
+					return t().direction;
+				},
+				t: (key, params) => t().t(key, params),
+				maybe: (key, params) => t().maybe(key, params),
+				plural: (key, count, params) => t().plural(key, count, params),
+				formatNumber: (value, options) => t().formatNumber(value, options),
+				formatCurrency: (value, currency, options) => t().formatCurrency(value, currency, options),
+				formatDate: (value, options) => t().formatDate(value, options),
+				formatList: (values, options) => t().formatList(values, options),
+				formatRelativeTime: (value, unit, options) => t().formatRelativeTime(value, unit, options)
+			});
+			await next();
+		});
+	};
+}
+/** One query parameter off a request URL, or `null` — total, so a URL Hono accepted cannot throw here. */
+function queryParam(url, name) {
+	try {
+		return new URL(url).searchParams.get(name);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { i18nMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The package entrypoint — the surface `pithy add i18n` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory plus the config types an app declares.
+ *
+ * The React bindings are a first-class public API of this package and are imported by deep path
+ * (`@pithy-sh/i18n/src/react/translator`) at the component that mounts them — the documented contract,
+ * not a barrel over the package, and what keeps `react` off the Worker program's import graph. The
+ * adapters (`@pithy-sh/i18n/src/adapters/*`) and the browser helpers
+ * (`@pithy-sh/i18n/src/browser/signals`) are reached the same way.
+ *
+ * `Translator` itself lives in `@pithy-sh/core/src/i18n/translator` and is importable **without
+ * composing this capability**, so an adopter's own module can type against the seam whether or not
+ * they ever opt in.
+ */
+export { type I18nCapability, i18n, isI18nCapability } from "./capability";
+export { BrowserResolver, type I18nConfig, type I18nConfigInput, ServerResolver } from "./config/config";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+import { BrowserResolver, ServerResolver } from "./config/config.js";
+import { i18n, isI18nCapability } from "./capability.js";
+export { BrowserResolver, ServerResolver, i18n, isI18nCapability };

package/dist/react/translator.d.ts

@@ -0,0 +1,73 @@
+import { type MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import { type ReactNode } from "react";
+/**
+ * The React bindings — **a first-class public API of this package**, not something the kit's own
+ * templates happen to import.
+ *
+ * An adopter rendering entirely their own screens has to be able to consume the seam without ever
+ * touching a kit template, and after the first day most of them are: the screens are *copied*, so
+ * `pithy ui add` reaches a project scaffolded after this landed and no command retrofits one that was
+ * not. The seam is what an already-scaffolded adopter consumes. So this is the deliverable, and the
+ * templates are one of its consumers.
+ */
+/**
+ * What the provider carries: the two locales, and the catalog layers to walk.
+ *
+ * **The pieces, not a finished `Translator`.** A screen supplies the English it was scaffolded with as
+ * a final fallback layer, and that layer can only be appended if the layers are still a list. Handing
+ * the context a built translator would make a screen's own English unreachable — which is the one
+ * thing that has to keep working, because it is the only catalog that survives being copied.
+ */
+export interface TranslatorSource {
+    /** The locale whose catalog answers `t()`. */
+    readonly catalogLocale: string;
+    /** The locale handed to `Intl`. May be more specific than the catalog locale — `es-AR` over `es`. */
+    readonly formattingLocale: string;
+    /** The catalogs to walk, most-specific first: the adopter's, then the kit's translation. */
+    readonly layers: readonly (MessageCatalog | undefined)[];
+}
+/**
+ * What a provider may be given: the pieces, or a translator somebody else already built.
+ *
+ * The second arm is what makes the adapters reachable. `fromI18next`, `fromIntl` and `fromLingui`
+ * return a `Translator` — an adopter's whole message layer, already resolved — and with only the
+ * pieces arm they had nowhere to go: an adapted translator could be passed screen by screen as a `t`
+ * prop, and `useTranslator()` in the adopter's *own* components would never see it. A stack you plug
+ * in that only half the tree can read is not plugged in.
+ */
+export type TranslatorValue = TranslatorSource | Translator;
+/** Mount a resolved locale over a subtree. Everything under it reads the same translator. */
+export declare function TranslatorProvider({ value, children }: {
+    value: TranslatorValue;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The translator for this subtree, with `fallback` as its last layer.
+ *
+ * **Never throws when there is no provider**, and that is deliberate rather than lenient. A screen
+ * copied into an adopter's repository renders in a project that may not compose `i18n` at all, and in
+ * that project it must render the English it was scaffolded with, byte for byte. With no provider this
+ * is exactly a `bakedTranslator` over `fallback` — no negotiation, no merge, no config.
+ *
+ * With a provider, `fallback` goes **last**: the adopter's own catalog, then the kit's translation,
+ * then the screen's baked English. So a key nobody translated still renders a sentence.
+ *
+ * That holds for a provider given a finished `Translator` too — an adapted i18next, FormatJS or Lingui
+ * instance answers first and the screen's own English is behind it, so plugging your stack in never
+ * costs you the sentences the kit already wrote.
+ */
+export declare function useTranslator(fallback?: MessageCatalog): Translator;
+/**
+ * The prop every screen that renders copy takes.
+ *
+ * Optional, and injected the same way `fetch` and `redirect` already are on the kit's screens: a
+ * rendered fact no assertion about source text can reach is what earns a prop there, and a
+ * locale-dependent render is exactly that. A screen with no `t` passed reads the context, and with no
+ * context reads its own English.
+ */
+export interface TranslatorProp {
+    /** The translator this screen renders through. Defaults to the context, then to the baked English. */
+    t?: Translator;
+}
+//# sourceMappingURL=translator.d.ts.map

package/dist/react/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../../src/react/translator.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAErE,OAAO,EAAiB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAE3E;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,qGAAqG;IACrG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,CAAC;CAC1D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,UAAU,CAAC;AA2C5D,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAEtG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,UAAU,CAWnE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,sGAAsG;IACtG,CAAC,CAAC,EAAE,UAAU,CAAC;CAChB"}

package/dist/react/translator.js

@@ -0,0 +1,81 @@
+import { bakedTranslator, createTranslator } from "@pithy-sh/core/src/i18n/translator";
+import { interpolate } from "@pithy-sh/core/src/i18n/catalog";
+import { createContext, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/translator.tsx
+const TranslatorContext = createContext(null);
+/** Whether a provider was handed the pieces rather than a finished translator. */
+function isSource(value) {
+	return "layers" in value;
+}
+/**
+* `primary` first, then `fallback` — the screen's own English behind somebody else's message layer.
+*
+* Built by delegation rather than by spreading `primary`, because a `Translator` may carry getters
+* (the request-scoped one does) and spreading would evaluate them once, here, freezing the answer.
+*
+* `t` and `maybe` consult the fallback because `maybe` is exactly the miss signal they need. `plural`
+* has a weaker one — it answers the key on a miss, which is the documented contract — so it falls back
+* only when it sees that, and an adapter whose library selects plurals itself (i18next does) keeps
+* answering for every key it knows.
+*/
+function overlay(primary, fallback) {
+	const own = (key, params) => Object.hasOwn(fallback, key) ? interpolate(fallback[key], params) : null;
+	return {
+		catalogLocale: primary.catalogLocale,
+		formattingLocale: primary.formattingLocale,
+		direction: primary.direction,
+		t: (key, params) => primary.maybe(key, params) ?? own(key, params) ?? key,
+		maybe: (key, params) => primary.maybe(key, params) ?? own(key, params),
+		plural: (key, count, params) => {
+			const answered = primary.plural(key, count, params);
+			if (answered !== key) return answered;
+			const withCount = {
+				count,
+				...params
+			};
+			return own(`${key}.other`, withCount) ?? own(key, withCount) ?? key;
+		},
+		formatNumber: (value, options) => primary.formatNumber(value, options),
+		formatCurrency: (value, currency, options) => primary.formatCurrency(value, currency, options),
+		formatDate: (value, options) => primary.formatDate(value, options),
+		formatList: (values, options) => primary.formatList(values, options),
+		formatRelativeTime: (value, unit, options) => primary.formatRelativeTime(value, unit, options)
+	};
+}
+/** Mount a resolved locale over a subtree. Everything under it reads the same translator. */
+function TranslatorProvider({ value, children }) {
+	return /* @__PURE__ */ jsx(TranslatorContext.Provider, {
+		value,
+		children
+	});
+}
+/**
+* The translator for this subtree, with `fallback` as its last layer.
+*
+* **Never throws when there is no provider**, and that is deliberate rather than lenient. A screen
+* copied into an adopter's repository renders in a project that may not compose `i18n` at all, and in
+* that project it must render the English it was scaffolded with, byte for byte. With no provider this
+* is exactly a `bakedTranslator` over `fallback` — no negotiation, no merge, no config.
+*
+* With a provider, `fallback` goes **last**: the adopter's own catalog, then the kit's translation,
+* then the screen's baked English. So a key nobody translated still renders a sentence.
+*
+* That holds for a provider given a finished `Translator` too — an adapted i18next, FormatJS or Lingui
+* instance answers first and the screen's own English is behind it, so plugging your stack in never
+* costs you the sentences the kit already wrote.
+*/
+function useTranslator(fallback) {
+	const source = useContext(TranslatorContext);
+	return useMemo(() => {
+		if (!source) return bakedTranslator(fallback ?? {});
+		if (!isSource(source)) return fallback ? overlay(source, fallback) : source;
+		return createTranslator({
+			catalogLocale: source.catalogLocale,
+			formattingLocale: source.formattingLocale,
+			layers: fallback ? [...source.layers, fallback] : source.layers
+		});
+	}, [source, fallback]);
+}
+//#endregion
+export { TranslatorProvider, useTranslator };

package/dist/react/useNegotiatedLocale.d.ts

@@ -0,0 +1,67 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import type { I18nClientProjection } from "../client/projection";
+import type { TranslatorSource } from "./translator";
+/** What the hook hands back: what to mount, what was chosen, and how to choose again. */
+export interface NegotiatedLocale {
+    /**
+     * Pass this straight to `TranslatorProvider`. `null` until the locale's catalog has loaded — and
+     * permanently `null` for a project with no `i18n` composed, which is the same branch and needs no
+     * second one: render the children untouched and every screen keeps its baked English.
+     */
+    readonly source: TranslatorSource | null;
+    /** The catalog locale in force — the words the app has. */
+    readonly locale: string;
+    /** Choose a language. Remembers it on this device and puts `lang`/`dir` on the document. */
+    readonly choose: (locale: string) => void;
+}
+/** What the caller knows that the browser cannot work out for itself. */
+export interface NegotiatedLocaleOptions {
+    /** The signed-in reader's stored locale, when the app knows it. Outranks this device's memory. */
+    readonly account?: string | null;
+    /** The adopter's own catalogs, keyed by locale — the top layer, above the kit's translation. */
+    readonly messages?: Readonly<Record<string, MessageCatalog | undefined>>;
+    /**
+     * Write a signed-in reader's choice through to their account. Omit it and a choice is remembered on
+     * this device only.
+     *
+     * **A seam rather than something this package does for you, because it cannot.** `pithy_auth_users.locale`
+     * is written through `updateUser` (`@pithy-sh/auth/src/client/api`) — a call `@pithy-sh/auth` owns and
+     * this package never imports. What it can do is call you at the moment the choice is made.
+     *
+     * It matters more than a convenience: `account` outranks `storage` in the browser chain precisely so
+     * a reader who picks Spanish on their phone is not reading French on their laptop. Without the
+     * write-through, that ordering describes a value nothing updates, and the second device keeps
+     * answering from its own older memory forever. Pass this whenever a reader is signed in.
+     *
+     * **Failures are yours to handle, inside this function.** It is called and not awaited, and a
+     * rejection is caught rather than reported: the reader already has the language they asked for and
+     * the device already remembers it, so a failed preference write must not become an unhandled
+     * rejection in their console or an error in your Worker. If a dropped write is worth knowing about,
+     * catch it here where you know what your API meant.
+     */
+    readonly persist?: (locale: string) => void | Promise<void>;
+}
+/**
+ * Negotiate the reader's locale in the browser, load that locale's catalog, and keep the document in
+ * step.
+ *
+ * **It takes what a browser holds.** `projection` is `virtual:pithy/i18n` — locale metadata and nothing
+ * else — so a screen reads the chain order **this project** configured rather than one the front end
+ * assumed, and no page is asked for the catalogs, the cookie name or the server chain that only a
+ * Worker has. Your own catalogs reach it through `options.messages`, above the kit's translation.
+ *
+ * The catalog arrives by dynamic import, one Vite chunk per locale, so a reader downloads only their
+ * own language. Until it lands, `source` is `null` and every screen renders the English it was
+ * scaffolded with — which is the right thing to show for the handful of milliseconds involved, and is
+ * also exactly what a reader in the default locale sees permanently.
+ *
+ * **`{ enabled: false }` is an answer, not an error, and it costs the caller no branch of its own.** A
+ * project that never composed `i18n` projects it, and the hook then negotiates nothing, downloads no
+ * chunk, writes nothing to `localStorage`, and leaves the `lang` `index.html` declared exactly where it
+ * is: `source` stays `null` permanently, `locale` is `en`, and `choose` does nothing. `source === null`
+ * is the same null a caller already renders through while a catalog is in flight — so the screen shows
+ * the English it was scaffolded with, byte for byte as it did before any of this landed, and removing
+ * the capability puts the app back where it started.
+ */
+export declare function useNegotiatedLocale(projection: I18nClientProjection, options?: NegotiatedLocaleOptions): NegotiatedLocale;
+//# sourceMappingURL=useNegotiatedLocale.d.ts.map

package/dist/react/useNegotiatedLocale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNegotiatedLocale.d.ts","sourceRoot":"","sources":["../../src/react/useNegotiatedLocale.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAKtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC;IACzE;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAWD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CA6GlB"}

package/dist/react/useNegotiatedLocale.js

@@ -0,0 +1,108 @@
+import { resolveBrowserLocale } from "../resolve/browser.js";
+import { applyDocumentLocale, readBrowserSignals, rememberBrowserLocale } from "../browser/signals.js";
+import { loadKitCatalog } from "../catalogs/browser.js";
+import { localeDirection } from "@pithy-sh/core/src/i18n/locale";
+import { useCallback, useEffect, useMemo, useState } from "react";
+//#region src/react/useNegotiatedLocale.ts
+/**
+* What `locale` answers, and what nothing writes to the document, when the capability is not composed.
+*
+* The kit writes in English and a scaffolded `templates/index.html` ships `lang="en"` as static text —
+* so this is both the language on screen and the tag already on the document. Nothing negotiated it,
+* which is exactly why the document is left alone rather than restamped with it.
+*/
+const UNNEGOTIATED_LOCALE = "en";
+/**
+* Negotiate the reader's locale in the browser, load that locale's catalog, and keep the document in
+* step.
+*
+* **It takes what a browser holds.** `projection` is `virtual:pithy/i18n` — locale metadata and nothing
+* else — so a screen reads the chain order **this project** configured rather than one the front end
+* assumed, and no page is asked for the catalogs, the cookie name or the server chain that only a
+* Worker has. Your own catalogs reach it through `options.messages`, above the kit's translation.
+*
+* The catalog arrives by dynamic import, one Vite chunk per locale, so a reader downloads only their
+* own language. Until it lands, `source` is `null` and every screen renders the English it was
+* scaffolded with — which is the right thing to show for the handful of milliseconds involved, and is
+* also exactly what a reader in the default locale sees permanently.
+*
+* **`{ enabled: false }` is an answer, not an error, and it costs the caller no branch of its own.** A
+* project that never composed `i18n` projects it, and the hook then negotiates nothing, downloads no
+* chunk, writes nothing to `localStorage`, and leaves the `lang` `index.html` declared exactly where it
+* is: `source` stays `null` permanently, `locale` is `en`, and `choose` does nothing. `source === null`
+* is the same null a caller already renders through while a catalog is in flight — so the screen shows
+* the English it was scaffolded with, byte for byte as it did before any of this landed, and removing
+* the capability puts the app back where it started.
+*/
+function useNegotiatedLocale(projection, options = {}) {
+	const config = projection.enabled ? projection : null;
+	const enabled = projection.enabled;
+	const resolved = useMemo(() => config === null ? null : resolveBrowserLocale({
+		...readBrowserSignals(config),
+		account: options.account
+	}, config), [config, options.account]);
+	const [chosen, setChosen] = useState(null);
+	const [kit, setKit] = useState(null);
+	const locale = chosen ?? resolved?.catalogLocale ?? UNNEGOTIATED_LOCALE;
+	const formattingLocale = chosen ?? resolved?.formattingLocale ?? UNNEGOTIATED_LOCALE;
+	const defaultLocale = config?.defaultLocale ?? UNNEGOTIATED_LOCALE;
+	useEffect(() => {
+		if (!enabled) return;
+		let live = true;
+		loadKitCatalog(locale).then((catalog) => {
+			if (live) setKit({
+				locale,
+				catalog
+			});
+		}).catch(() => {
+			if (live) setKit({
+				locale,
+				catalog: {}
+			});
+		});
+		return () => {
+			live = false;
+		};
+	}, [enabled, locale]);
+	const direction = localeDirection(locale);
+	useEffect(() => {
+		if (!enabled) return;
+		applyDocumentLocale(locale, direction);
+	}, [
+		enabled,
+		locale,
+		direction
+	]);
+	const persist = options.persist;
+	const choose = useCallback((next) => {
+		if (config === null) return;
+		if (!config.supportedLocales.includes(next)) return;
+		rememberBrowserLocale(next, config);
+		setChosen(next);
+		Promise.resolve(persist?.(next)).catch(() => void 0);
+	}, [config, persist]);
+	return {
+		source: useMemo(() => {
+			if (kit?.locale !== locale) return null;
+			return {
+				catalogLocale: locale,
+				formattingLocale,
+				layers: [
+					options.messages?.[locale],
+					options.messages?.[defaultLocale],
+					kit.catalog
+				]
+			};
+		}, [
+			kit,
+			locale,
+			formattingLocale,
+			options.messages,
+			defaultLocale
+		]),
+		locale,
+		choose
+	};
+}
+//#endregion
+export { useNegotiatedLocale };