@pithy-sh/core 0.1.1 → 0.1.3

package/dist/i18n/acceptLanguage.js

@@ -0,0 +1,55 @@
+import "./locale.js";
+//#region src/i18n/acceptLanguage.ts
+/**
+* The most `Accept-Language` entries this parser will read from one header.
+*
+* A browser sends a handful. A caller that sends ten thousand is not negotiating, and the matcher
+* walks every entry against every supported locale — so the bound is on the input, where it costs
+* nothing, rather than on the loop, where it would have to be argued about at each call site.
+*/
+const MAX_ACCEPT_LANGUAGE_ENTRIES = 32;
+/** The most characters this parser will read from one `Accept-Language` header, for the same reason. */
+const MAX_ACCEPT_LANGUAGE_LENGTH = 4096;
+/** Whether a q-weight parameter parses to a usable number. `q=` and `q=abc` are neither, and drop out. */
+function quality(parameter) {
+	const match = /^q=(\d(?:\.\d{0,3})?)$/.exec(parameter);
+	if (!match?.[1]) return null;
+	const value = Number.parseFloat(match[1]);
+	return Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+}
+/**
+* An `Accept-Language` header as q-weighted ranges, most-wanted first.
+*
+* **Tokenize, strip q-weights, then validate — in that order, and all of it before anything reaches
+* `Intl`.** The header is caller-supplied and its real-world contents include `*`, `en_US`, empty
+* tokens, and tags still carrying `;q=0.9`; `new Intl.Locale()` throws a `RangeError` on every one of
+* them. A header that cannot be read is an empty list, never a throw, so the resolver chain falls
+* through to its next link instead of 500-ing.
+*
+* The **full** weighted list is returned, not the first entry: `pt-PT;q=1.0, es;q=0.8, en;q=0.5` from a
+* reader who has no Portuguese is a request for Spanish, and reading only the head answers English.
+* Equal weights keep header order, which is what a browser means by listing them that way.
+*/
+function parseAcceptLanguage(header) {
+	if (!header || header.length > MAX_ACCEPT_LANGUAGE_LENGTH) return [];
+	const ranges = [];
+	for (const entry of header.split(",")) {
+		if (ranges.length >= MAX_ACCEPT_LANGUAGE_ENTRIES) break;
+		const [rawRange, ...parameters] = entry.split(";");
+		const range = rawRange?.trim().toLowerCase() ?? "";
+		if (range !== "*" && !/^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/.test(range)) continue;
+		if (range.length > 64) continue;
+		let weight = 1;
+		for (const parameter of parameters) {
+			const parsed = quality(parameter.trim().toLowerCase());
+			if (parsed !== null) weight = parsed;
+		}
+		if (weight > 0) ranges.push({
+			range,
+			quality: weight
+		});
+	}
+	return ranges.sort((left, right) => right.quality - left.quality);
+}
+//#endregion
+export { parseAcceptLanguage };

package/dist/i18n/catalog.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/** A catalog key — `<domain>/<path>`, where `<domain>` is the contributing capability's name. */
+export declare const MessageKey: z.ZodString;
+export type MessageKey = z.infer<typeof MessageKey>;
+/** The values a message may interpolate. Scalars only — a catalog renders text, never a structure. */
+export declare const MessageParams: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+export type MessageParams = z.infer<typeof MessageParams>;
+/** One locale's words: key → message. */
+export declare const MessageCatalog: z.ZodRecord<z.ZodString, z.ZodString>;
+export type MessageCatalog = z.infer<typeof MessageCatalog>;
+/** A set of catalogs, keyed by locale — what a capability contributes and what an adopter overrides with. */
+export declare const LocaleCatalogs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+export type LocaleCatalogs = z.infer<typeof LocaleCatalogs>;
+/** The domain of a catalog key — everything before the `/`. */
+export declare function messageDomain(key: string): string;
+/**
+ * `template` with every `{placeholder}` replaced by its parameter.
+ *
+ * A placeholder with no parameter is **left as written**, not blanked. A missing value is a bug in the
+ * call site or a typo in the catalog, and `Renews {date}.` on the screen says which; `Renews .` says
+ * nothing and reads like finished copy.
+ *
+ * Substitution is textual and performs no escaping, because the two consumers escape differently and
+ * both do it better than this could: React escapes what it renders, and the email engine precompiles
+ * `subject` and `text` with `noEscape` deliberately. A catalog value reaching an unescaped surface is
+ * therefore a fact about that surface — stated in `docs/I18N.md`, and the reason kit catalogs carry no
+ * markup.
+ */
+export declare function interpolate(template: string, params?: MessageParams): string;
+/**
+ * The first layer that has `key`, or `null` when none does.
+ *
+ * **Per key, never per catalog.** An adopter who translates one sentence passes one entry, and every
+ * key they did not mention keeps flowing from the package — which is what makes an override a merge
+ * rather than a fork. Layer order is the caller's: `@pithy-sh/i18n` walks adopter-locale, then
+ * adopter-default, then kit-locale, then kit-default.
+ */
+export declare function lookupMessage(layers: readonly (MessageCatalog | undefined)[], key: string): string | null;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/i18n/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/i18n/catalog.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,iGAAiG;AACjG,eAAO,MAAM,UAAU,aAI+D,CAAC;AACvF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,sGAAsG;AACtG,eAAO,MAAM,aAAa,yFAO8C,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,yCAAyC;AACzC,eAAO,MAAM,cAAc,uCAEsC,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,6GAA6G;AAC7G,eAAO,MAAM,cAAc,iEAEiF,CAAC;AAC7G,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,CAW5E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWzG"}

package/dist/i18n/catalog.js

@@ -0,0 +1,57 @@
+import { Locale } from "./locale.js";
+import { z } from "zod";
+/** A catalog key — `<domain>/<path>`, where `<domain>` is the contributing capability's name. */
+const MessageKey = z.string().max(129).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*\/[a-z0-9]+(?:_[a-z0-9]+)*(?:\.[a-z0-9]+(?:_[a-z0-9]+)*)*$/, { message: "A message key is `<domain>/<path>`, where the domain is a capability name." }).describe("A catalog key, `<domain>/<path>` — for an error, the error code itself.");
+/** The values a message may interpolate. Scalars only — a catalog renders text, never a structure. */
+const MessageParams = z.record(z.string().describe("The placeholder name, as written between braces in the message."), z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+]).describe("The value substituted for that placeholder. Scalar, so a message stays a sentence.")).describe("Values a message interpolates, keyed by placeholder name.");
+/** One locale's words: key → message. */
+const MessageCatalog = z.record(MessageKey.describe("The key this message answers."), z.string().describe("The message, in this locale.")).describe("One locale's messages, keyed by `<domain>/<path>`.");
+/** A set of catalogs, keyed by locale — what a capability contributes and what an adopter overrides with. */
+const LocaleCatalogs = z.record(Locale.describe("The locale these messages are written in."), MessageCatalog).describe("Catalogs keyed by locale — a capability's `messages` contribution, or an adopter's overrides.");
+/** The domain of a catalog key — everything before the `/`. */
+function messageDomain(key) {
+	const cut = key.indexOf("/");
+	return cut < 0 ? key : key.slice(0, cut);
+}
+/**
+* `template` with every `{placeholder}` replaced by its parameter.
+*
+* A placeholder with no parameter is **left as written**, not blanked. A missing value is a bug in the
+* call site or a typo in the catalog, and `Renews {date}.` on the screen says which; `Renews .` says
+* nothing and reads like finished copy.
+*
+* Substitution is textual and performs no escaping, because the two consumers escape differently and
+* both do it better than this could: React escapes what it renders, and the email engine precompiles
+* `subject` and `text` with `noEscape` deliberately. A catalog value reaching an unescaped surface is
+* therefore a fact about that surface — stated in `docs/I18N.md`, and the reason kit catalogs carry no
+* markup.
+*/
+function interpolate(template, params) {
+	if (!params) return template;
+	return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (whole, name) => {
+		if (!Object.hasOwn(params, name)) return whole;
+		const value = params[name];
+		return value === void 0 ? whole : String(value);
+	});
+}
+/**
+* The first layer that has `key`, or `null` when none does.
+*
+* **Per key, never per catalog.** An adopter who translates one sentence passes one entry, and every
+* key they did not mention keeps flowing from the package — which is what makes an override a merge
+* rather than a fork. Layer order is the caller's: `@pithy-sh/i18n` walks adopter-locale, then
+* adopter-default, then kit-locale, then kit-default.
+*/
+function lookupMessage(layers, key) {
+	for (const layer of layers) if (layer && Object.hasOwn(layer, key)) {
+		const message = layer[key];
+		if (message !== void 0) return message;
+	}
+	return null;
+}
+//#endregion
+export { LocaleCatalogs, MessageCatalog, MessageKey, MessageParams, interpolate, lookupMessage, messageDomain };

package/dist/i18n/locale.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+/**
+ * The longest language tag this kit accepts. RFC 5646's own grammar allows far more, but a tag that
+ * long is not a locale anyone serves — it is a header a caller filled with something else. The bound
+ * exists so a hostile `Accept-Language` cannot make the matcher walk a megabyte per request.
+ */
+export declare const MAX_LOCALE_TAG_LENGTH = 64;
+/**
+ * A BCP-47 language tag — the identity of a locale everywhere in the kit.
+ *
+ * One string, two jobs, and only one of them falls back: the tag that picks a **catalog** is the words
+ * we have written, and the tag that drives **formatting** is whatever the reader asked for. See
+ * {@link LocaleContext} for why collapsing them is the bug where an Argentine reads Spanish and sees
+ * `1,234.56`.
+ */
+export declare const Locale: z.ZodString;
+export type Locale = z.infer<typeof Locale>;
+/** Which way a locale's script runs. Drives the `dir` attribute on the document and the email shell. */
+export declare const TextDirection: z.ZodEnum<{
+    ltr: "ltr";
+    rtl: "rtl";
+}>;
+export type TextDirection = z.infer<typeof TextDirection>;
+/**
+ * The per-request locale seam, published on `c.var.locale` by `@pithy-sh/i18n` and `null` in a Worker
+ * that does not compose it. Core defines the shape; one capability populates it — the same split
+ * `AuthContext` uses, and for the same reason: `@pithy-sh/email` and the error module both need a
+ * locale and neither may import an i18n capability.
+ */
+export declare const LocaleContext: z.ZodObject<{
+    catalogLocale: z.ZodString;
+    formattingLocale: z.ZodString;
+    direction: z.ZodEnum<{
+        ltr: "ltr";
+        rtl: "rtl";
+    }>;
+}, z.core.$strip>;
+export type LocaleContext = z.infer<typeof LocaleContext>;
+/**
+ * `tag` as an `Intl.Locale`, or `null` when it is not one.
+ *
+ * **Every construction on header- or adopter-supplied input goes through this.** `new Intl.Locale()`
+ * throws `RangeError` on `*`, on `en_US`, on the empty string, and on any token still carrying
+ * `;q=0.9` — so a malformed `Accept-Language` is an uncaught 500 rather than a fallback, unless the
+ * throw is caught somewhere. It is caught here, once, and nowhere else.
+ */
+export declare function parseLocale(tag: string): Intl.Locale | null;
+/**
+ * The part of `tag` that may be handed to `Intl` as a **formatting** locale, or `null` when it is not a
+ * tag at all: language, script, region and variants, with every extension subtag stripped.
+ *
+ * **A `-u-` extension is not a locale, it is an instruction**, and the range a formatting locale is
+ * built from is caller-supplied. `?lang=en-u-nu-hanidec` truncates to `en`, matches a project that
+ * ships English, and — kept whole — reaches `Intl.NumberFormat` verbatim, where it renders `1,234` as
+ * `一,二三四`. `-u-ca-islamic` does the same to every date on the page. Nothing is disclosed and nothing
+ * persists, so it is spoofing rather than a breach; it is also a link somebody can send, and the whole
+ * point of resolving against `supportedLocales` is that a reader cannot pick a rendering the project
+ * did not offer.
+ *
+ * `baseName` is exactly the right cut, and is why this is a helper rather than a regex: `es-AR`,
+ * `zh-Hant-TW`, `es-419` and `de-DE-1996` all survive whole, because none of them is an extension.
+ */
+export declare function formattingLocaleOf(tag: string): string | null;
+/** Whether `tag` is a language tag `Intl` will accept — the predicate half of {@link parseLocale}. */
+export declare function isLocale(tag: string): tag is Locale;
+/**
+ * Which way `tag`'s script runs, feature-detected across both spellings and falling back to a small
+ * right-to-left language set when a runtime exposes neither.
+ *
+ * Total: an unparseable tag is `ltr`, because a document still needs a `dir` and guessing the other way
+ * mirrors a page nobody asked to mirror.
+ */
+export declare function localeDirection(tag: string): TextDirection;
+//# sourceMappingURL=locale.d.ts.map

package/dist/i18n/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/i18n/locale.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAaxC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,aAoBkF,CAAC;AACtG,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE5C,wGAAwG;AACxG,eAAO,MAAM,aAAa;;;EAEyD,CAAC;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;iBAM8E,CAAC;AACzG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAO3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED,sGAAsG;AACtG,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,MAAM,CAEnD;AAuBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAQ1D"}

package/dist/i18n/locale.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+//#region src/i18n/locale.ts
+/**
+* The longest language tag this kit accepts. RFC 5646's own grammar allows far more, but a tag that
+* long is not a locale anyone serves — it is a header a caller filled with something else. The bound
+* exists so a hostile `Accept-Language` cannot make the matcher walk a megabyte per request.
+*/
+const MAX_LOCALE_TAG_LENGTH = 64;
+/**
+* The shape of a well-formed language tag, checked before `Intl.Locale` ever sees it.
+*
+* Deliberately looser than RFC 5646 and deliberately stricter than "any string". Looser, because the
+* authority on whether `es-419` or `zh-Hans-CN` is meaningful is ICU, not a regular expression we would
+* have to keep in step with it. Stricter, because {@link https://tc39.es/ecma402 `Intl.Locale`} throws a
+* `RangeError` rather than returning a signal, and the four things it throws on — `*`, `en_US`, the empty
+* string, and a token still carrying `;q=0.9` — all appear in real `Accept-Language` headers.
+*/
+const LANGUAGE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
+/**
+* A BCP-47 language tag — the identity of a locale everywhere in the kit.
+*
+* One string, two jobs, and only one of them falls back: the tag that picks a **catalog** is the words
+* we have written, and the tag that drives **formatting** is whatever the reader asked for. See
+* {@link LocaleContext} for why collapsing them is the bug where an Argentine reads Spanish and sees
+* `1,234.56`.
+*/
+const Locale = z.string().min(2).max(64).regex(LANGUAGE_TAG, { message: "A locale is a BCP-47 tag like `en`, `es`, or `es-AR`." }).refine((tag) => parseLocale(tag) !== null, { message: "That is not a language tag `Intl` accepts. `en-x` and `en-a-bbb-a-ccc` are the usual shapes that miss." }).describe("A BCP-47 language tag (`en`, `es`, `es-AR`) — the identity of a locale across the kit.");
+/** Which way a locale's script runs. Drives the `dir` attribute on the document and the email shell. */
+const TextDirection = z.enum(["ltr", "rtl"]).describe("Which way a locale's script runs — the value of the `dir` attribute.");
+/**
+* The per-request locale seam, published on `c.var.locale` by `@pithy-sh/i18n` and `null` in a Worker
+* that does not compose it. Core defines the shape; one capability populates it — the same split
+* `AuthContext` uses, and for the same reason: `@pithy-sh/email` and the error module both need a
+* locale and neither may import an i18n capability.
+*/
+const LocaleContext = z.object({
+	catalogLocale: Locale.describe("The locale whose catalog answers `t()` — the words the kit actually has."),
+	formattingLocale: Locale.describe("The locale handed to `Intl` — what the reader asked for, region and all."),
+	direction: TextDirection.describe("The catalog locale's text direction, for `lang`/`dir` on the document.")
+}).describe("Per-request resolved locale; the seam capabilities read instead of negotiating their own.");
+/**
+* `tag` as an `Intl.Locale`, or `null` when it is not one.
+*
+* **Every construction on header- or adopter-supplied input goes through this.** `new Intl.Locale()`
+* throws `RangeError` on `*`, on `en_US`, on the empty string, and on any token still carrying
+* `;q=0.9` — so a malformed `Accept-Language` is an uncaught 500 rather than a fallback, unless the
+* throw is caught somewhere. It is caught here, once, and nowhere else.
+*/
+function parseLocale(tag) {
+	if (!LANGUAGE_TAG.test(tag) || tag.length > 64) return null;
+	try {
+		return new Intl.Locale(tag);
+	} catch {
+		return null;
+	}
+}
+/**
+* The part of `tag` that may be handed to `Intl` as a **formatting** locale, or `null` when it is not a
+* tag at all: language, script, region and variants, with every extension subtag stripped.
+*
+* **A `-u-` extension is not a locale, it is an instruction**, and the range a formatting locale is
+* built from is caller-supplied. `?lang=en-u-nu-hanidec` truncates to `en`, matches a project that
+* ships English, and — kept whole — reaches `Intl.NumberFormat` verbatim, where it renders `1,234` as
+* `一,二三四`. `-u-ca-islamic` does the same to every date on the page. Nothing is disclosed and nothing
+* persists, so it is spoofing rather than a breach; it is also a link somebody can send, and the whole
+* point of resolving against `supportedLocales` is that a reader cannot pick a rendering the project
+* did not offer.
+*
+* `baseName` is exactly the right cut, and is why this is a helper rather than a regex: `es-AR`,
+* `zh-Hant-TW`, `es-419` and `de-DE-1996` all survive whole, because none of them is an extension.
+*/
+function formattingLocaleOf(tag) {
+	return parseLocale(tag)?.baseName ?? null;
+}
+/** Whether `tag` is a language tag `Intl` will accept — the predicate half of {@link parseLocale}. */
+function isLocale(tag) {
+	return parseLocale(tag) !== null;
+}
+/**
+* The languages written right-to-left, for the runtimes that expose neither text-info accessor.
+*
+* A last resort, not the answer: `getTextInfo()` knows about scripts this list cannot name, and it is
+* asked first. The five here are the ones a fallback has to get right.
+*/
+const RTL_LANGUAGES = /* @__PURE__ */ new Set([
+	"ar",
+	"he",
+	"fa",
+	"ur",
+	"ps"
+]);
+/**
+* Which way `tag`'s script runs, feature-detected across both spellings and falling back to a small
+* right-to-left language set when a runtime exposes neither.
+*
+* Total: an unparseable tag is `ltr`, because a document still needs a `dir` and guessing the other way
+* mirrors a page nobody asked to mirror.
+*/
+function localeDirection(tag) {
+	const locale = parseLocale(tag);
+	if (!locale) return "ltr";
+	const withTextInfo = locale;
+	const info = typeof withTextInfo.getTextInfo === "function" ? withTextInfo.getTextInfo() : withTextInfo.textInfo;
+	if (info?.direction === "rtl") return "rtl";
+	if (info?.direction === "ltr") return "ltr";
+	return RTL_LANGUAGES.has(locale.language) ? "rtl" : "ltr";
+}
+//#endregion
+export { Locale, LocaleContext, MAX_LOCALE_TAG_LENGTH, TextDirection, formattingLocaleOf, isLocale, localeDirection, parseLocale };

package/dist/i18n/localeMarker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The locale tag this source declares in its head, or `null` if it declares none.
+ *
+ * `null` is the ordinary answer: almost every file in a tree declares nothing, and a file that does is saying
+ * something about its own values, not asking to be skipped. See this module's docblock for what a caller owes
+ * the answer — in particular that `en` comes back like any other tag and exempts nothing.
+ */
+export declare function localeDeclared(source: string): string | null;
+/**
+ * Every span on one line whose quoted content is a value rather than prose — as `[open, close)` offsets.
+ *
+ * `open` is the first character inside the quote and `close` is the closing quote, so a match at or after
+ * `open` and ending at or before `close` sits inside a value. Left to right, in whichever of the three quote
+ * characters opened it.
+ *
+ * By default a run holding whitespace is a sentence, not a value, and **a span that turns out to hold one is
+ * passed over rather than skipped**: the scan keeps reading inside it, which is how a backticked token inside
+ * a prose string literal still counts — this repository names wire values that way in a `.describe()`.
+ *
+ * `everyQuoted` widens that to include the sentences, for one case and one only: a line in a file that has
+ * declared itself written in another language, where the quoted runs are the translation. It is the mechanism
+ * the marker drives, and it is why the marker exempts a file's values without exempting the file.
+ *
+ * A run is one line's worth. A quote that never closes on its line opens no value, so the inner lines of a
+ * multi-line template literal are read as prose — deliberately, since that is where a long English argument
+ * would otherwise hide.
+ */
+export declare function valueSpans(line: string, everyQuoted?: boolean): [number, number][];
+//# sourceMappingURL=localeMarker.d.ts.map

package/dist/i18n/localeMarker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localeMarker.d.ts","sourceRoot":"","sources":["../../src/i18n/localeMarker.ts"],"names":[],"mappings":"AAmEA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAchF"}

package/dist/i18n/localeMarker.js

@@ -0,0 +1,112 @@
+//#region src/i18n/localeMarker.ts
+/**
+* Reading the locale a source file declares in its head — the reader for the marker `docs/I18N.md` publishes.
+*
+* A prose census reads every committed file as text and refuses the spellings a project does not write. This
+* repository runs one (`packages/cli/src/ci/americanEnglish.test.ts`: the words this project writes are
+* American), and any project that ships translated copy eventually needs the same thing, because a catalog
+* written in Spanish is prose that is *supposed* not to be English. A path list would answer that and is
+* exactly what a census must not grow — a list is right on the day it is written, wrong afterwards, and the
+* way it goes wrong is that the gate keeps passing. So the file says what it is instead, in one marker, in
+* its head, where a reader meets it: the **locale** it is written in, and that the copy is an **unreviewed
+* first pass**. Both facts are load-bearing and neither is checkable from the outside.
+*
+* ## The half that is easy to get backwards
+*
+* **The marker exempts the file's quoted values, not the file.** A catalog is not written in Spanish — its
+* *values* are. Everything around them is a docblock, an import and an identifier: the project's own English
+* prose, and exactly as subject to the rule as any other file's. So a declaring file widens what counts as a
+* value — every quoted run, whole sentences included, rather than only the whitespace-free tokens exempt
+* everywhere else — and every character outside those quotes is censused as it would be anywhere.
+*
+* Reading the marker as *skip this file* is the port that goes wrong, and it goes wrong quietly. It made this
+* repository's own `es/errors.ts` a place where a twenty-seven-line English argument went unread, which is a
+* gate that cannot fail on most of what it is looking at, and it costs an adopter the docblocks of every
+* translated catalog they ever add.
+*
+* **`en` and `en-*` are a declaration and never an exemption**, which is why {@link localeDeclared} hands back
+* the tag rather than a yes or a no. The words a project writes *in English* are the ones a census is about,
+* and a marker cannot become a way to opt English prose out of it. The caller decides what a tag means;
+* treating `en` as translated is the same mistake as treating `es` as skippable.
+*
+* ## Why it lives in `core/src/i18n`
+*
+* The folder is the import path, so it is named for the caller. The marker is a locale declaration — the same
+* thing `./locale` and `./catalog` are about, one artifact earlier — and an adopter reaching for it is asking
+* a question about translated copy, not about linting. It is deliberately not in the CLI: the CLI is a
+* development tool an adopter's own test suite has no reason to depend on, and this is the kit's precedent for
+* a pure textual scanner that a repository's tests want back (`../entitlement/gateScan`, which exports
+* `withoutComments` for the same reason). No `node:` import, no filesystem: the caller brings the text,
+* whether from a walked directory or from `import.meta.glob(…, "?raw")` inside a Workers-typed program.
+*
+* The census that owns the rest of the rule stays where it is. What ships here is the pair a port gets wrong.
+*/
+/**
+* What a file written in a language other than English declares in its head.
+*
+* The exact spelling is published in `docs/I18N.md` — `LOCALE <tag>`, an em dash, and the unreviewed-first-pass
+* sentence — and `packages/cli/src/ci/americanEnglish.test.ts` reads the line out of that document and holds it
+* to this pattern, so an adopter copying the published marker cannot copy one that matches nothing. The tag is
+* captured, never merely detected, because the caller's decision turns on which language it names.
+*/
+const LOCALE_DECLARED = /\bLOCALE ([a-z]{2,8}(?:-[A-Za-z0-9]{1,8})*) — an unreviewed first pass\./;
+/**
+* How far into a file the marker has to be, so a file mentioning it in prose is still read.
+*
+* A documented number rather than a tuning knob: `docs/I18N.md` publishes this window to adopters, and
+* `packages/cli/src/ci/americanEnglish.test.ts` holds the count that document states to where this reader
+* actually stops — so moving the number here fails the build until the document moves with it. This module's
+* own test pins both sides of the boundary. It is an implementation detail of {@link localeDeclared} and is
+* not exported — a caller hands over a whole source and gets an answer.
+*/
+const HEAD_LINES = 25;
+/**
+* The locale tag this source declares in its head, or `null` if it declares none.
+*
+* `null` is the ordinary answer: almost every file in a tree declares nothing, and a file that does is saying
+* something about its own values, not asking to be skipped. See this module's docblock for what a caller owes
+* the answer — in particular that `en` comes back like any other tag and exempts nothing.
+*/
+function localeDeclared(source) {
+	for (const line of source.split("\n").slice(0, HEAD_LINES)) {
+		const found = LOCALE_DECLARED.exec(line);
+		if (found !== null) return found[1];
+	}
+	return null;
+}
+/**
+* Every span on one line whose quoted content is a value rather than prose — as `[open, close)` offsets.
+*
+* `open` is the first character inside the quote and `close` is the closing quote, so a match at or after
+* `open` and ending at or before `close` sits inside a value. Left to right, in whichever of the three quote
+* characters opened it.
+*
+* By default a run holding whitespace is a sentence, not a value, and **a span that turns out to hold one is
+* passed over rather than skipped**: the scan keeps reading inside it, which is how a backticked token inside
+* a prose string literal still counts — this repository names wire values that way in a `.describe()`.
+*
+* `everyQuoted` widens that to include the sentences, for one case and one only: a line in a file that has
+* declared itself written in another language, where the quoted runs are the translation. It is the mechanism
+* the marker drives, and it is why the marker exempts a file's values without exempting the file.
+*
+* A run is one line's worth. A quote that never closes on its line opens no value, so the inner lines of a
+* multi-line template literal are read as prose — deliberately, since that is where a long English argument
+* would otherwise hide.
+*/
+function valueSpans(line, everyQuoted = false) {
+	const spans = [];
+	for (let index = 0; index < line.length; index += 1) {
+		const quote = line[index];
+		if (quote !== "\"" && quote !== "'" && quote !== "`") continue;
+		const close = line.indexOf(quote, index + 1);
+		if (close === -1) continue;
+		const inner = line.slice(index + 1, close);
+		if (inner.length === 0) continue;
+		if (!everyQuoted && /\s/.test(inner)) continue;
+		spans.push([index + 1, close]);
+		index = close;
+	}
+	return spans;
+}
+//#endregion
+export { localeDeclared, valueSpans };

package/dist/i18n/match.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A declared exception map: a language range the truncation walk would miss, and the supported locale
+ * it means. `{ nb: "no", tl: "fil" }` — the pairs no algorithm derives, because they are historical
+ * rather than structural.
+ */
+export type LocaleExceptions = Readonly<Record<string, string>>;
+/** How a match was reached, so a caller can tell an answer from a default. */
+export interface LocaleMatch {
+    /** The supported locale that answered, exactly as the caller spelled it in `supported`. */
+    readonly locale: string;
+    /** The range that matched it, lower-cased — `*` when a wildcard took the first supported locale. */
+    readonly range: string;
+}
+/**
+ * The first supported locale any of `desired` asks for, most-wanted first, or `null` when none does.
+ *
+ * `desired` is already in preference order — {@link parseAcceptLanguage} sorts by q-weight, and a
+ * browser resolver chain builds it from the reader's explicit choice downward. A `*` range takes the
+ * first supported locale, which is what "anything you have" means; it is checked in place rather than
+ * up front, so a reader who wrote `de, *` is answered in German when German ships.
+ *
+ * Total, and never throws: every `Intl` construction on the way through is guarded, so a header full
+ * of `en_US` and `;q=0.9` fragments falls through to `null` and the caller's default.
+ */
+export declare function matchLocale(desired: readonly string[], supported: readonly string[], exceptions?: LocaleExceptions): LocaleMatch | null;
+//# sourceMappingURL=match.d.ts.map

package/dist/i18n/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/i18n/match.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhE,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AA+DD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,UAAU,GAAE,gBAAqB,GAChC,WAAW,GAAG,IAAI,CAcpB"}

package/dist/i18n/match.js

@@ -0,0 +1,88 @@
+import { parseLocale } from "./locale.js";
+//#region src/i18n/match.ts
+/** Lower-cased index of the supported list, so matching is case-insensitive without lower-casing answers. */
+function index(supported) {
+	const map = /* @__PURE__ */ new Map();
+	for (const locale of supported) {
+		const key = locale.toLowerCase();
+		if (!map.has(key)) map.set(key, locale);
+	}
+	return map;
+}
+/**
+* RFC 4647 §3.4 lookup: `tag`, then `tag` with its right-most subtag removed, and so on.
+*
+* A trailing single-character subtag is removed with the one before it, as the RFC requires —
+* `en-a-bbb` truncates to `en`, never to the meaningless `en-a`.
+*/
+function truncationWalk(tag, supported) {
+	let candidate = tag.toLowerCase();
+	while (candidate.length > 0) {
+		const hit = supported.get(candidate);
+		if (hit) return hit;
+		const cut = candidate.lastIndexOf("-");
+		if (cut < 0) return null;
+		candidate = candidate.slice(0, cut);
+		const tail = candidate.lastIndexOf("-");
+		if (tail >= 0 && candidate.length - tail === 2) candidate = candidate.slice(0, tail);
+	}
+	return null;
+}
+/**
+* The supported locale that best answers one range, or `null`.
+*
+* Three passes, in the order that makes each one earn its place: the declared exception map first,
+* because it exists to override what follows; then the truncation walk on the range as written, which
+* answers `es-AR` with `es`; then the walk again over the **maximized** form, which answers `zh-TW`
+* with `zh-Hant` by way of `zh-Hant-TW`.
+*
+* **Maximizing is the third step, not the first.** `Intl.Locale` throws on input the first step handles
+* fine, and maximizing a range before trying it as written turns `es` into `es-Latn-ES` and then walks
+* back down to `es` — the same answer, three constructions later, and a `RangeError` away from a 500.
+*/
+function lookupRange(range, supported, exceptions) {
+	const key = range.toLowerCase();
+	const declared = Object.hasOwn(exceptions, key) ? exceptions[key] : void 0;
+	if (declared) {
+		const hit = supported.get(declared.toLowerCase());
+		if (hit) return hit;
+	}
+	const direct = truncationWalk(range, supported);
+	if (direct) return direct;
+	const maximized = parseLocale(range)?.maximize().toString();
+	return maximized ? truncationWalk(maximized, supported) : null;
+}
+/**
+* The first supported locale any of `desired` asks for, most-wanted first, or `null` when none does.
+*
+* `desired` is already in preference order — {@link parseAcceptLanguage} sorts by q-weight, and a
+* browser resolver chain builds it from the reader's explicit choice downward. A `*` range takes the
+* first supported locale, which is what "anything you have" means; it is checked in place rather than
+* up front, so a reader who wrote `de, *` is answered in German when German ships.
+*
+* Total, and never throws: every `Intl` construction on the way through is guarded, so a header full
+* of `en_US` and `;q=0.9` fragments falls through to `null` and the caller's default.
+*/
+function matchLocale(desired, supported, exceptions = {}) {
+	if (supported.length === 0) return null;
+	const lookup = index(supported);
+	for (const range of desired) {
+		const normalized = range.trim().toLowerCase();
+		if (normalized.length === 0) continue;
+		if (normalized === "*") {
+			const first = supported[0];
+			return first ? {
+				locale: first,
+				range: normalized
+			} : null;
+		}
+		const hit = lookupRange(normalized, lookup, exceptions);
+		if (hit) return {
+			locale: hit,
+			range: normalized
+		};
+	}
+	return null;
+}
+//#endregion
+export { matchLocale };

package/dist/i18n/registry.d.ts

@@ -0,0 +1,25 @@
+import type { Capability } from "../capability/capability";
+import { type LocaleCatalogs, type MessageCatalog } from "./catalog";
+/**
+ * Every composed capability's `messages`, merged into one set of catalogs keyed by locale.
+ *
+ * **A capability may only declare keys under its own domain**, and the merge refuses anything else.
+ * That is the same rule as `pithy_<capability>_<table>` and `auth/invalid_token`, enforced for the same
+ * reason: the domain segment is what makes two capabilities' contributions incapable of colliding, so
+ * merge order stops being a thing anyone has to reason about. It applies to the adopter's own `app`
+ * capability exactly as it applies to a kit package — `board/nav.settings` is theirs to declare, and
+ * `auth/sign_in.title` is not.
+ *
+ * Library-before-app, like the migration registry: capabilities are merged in composition order, so a
+ * later contribution wins a key an earlier one wrote. With the domain rule in force that can only
+ * happen between two capabilities sharing a name, which `createBackend` already refuses.
+ */
+export declare function composeMessages(capabilities: readonly Capability[]): LocaleCatalogs;
+/**
+ * The catalog for `locale`, or the default locale's, or an empty one.
+ *
+ * The fallback that makes the seam optional: a Worker composing no i18n capability reads the baked
+ * English and behaves byte for byte as it did before any of this landed.
+ */
+export declare function catalogFor(catalogs: LocaleCatalogs, locale: string): MessageCatalog;
+//# sourceMappingURL=registry.d.ts.map

package/dist/i18n/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/i18n/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAiB,MAAM,WAAW,CAAC;AAWpF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,cAAc,CAqCnF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAEnF"}