saykit 0.11.0 → 0.12.0

package/README.md

@@ -4,9 +4,9 @@
 
 [![Coverage](https://codecov.io/gh/k0d13/saykit/graph/badge.svg?flag=integration)](https://codecov.io/gh/k0d13/saykit?flags%5B0%5D=integration)
 
-The core runtime for [SayKit](https://saykit.js.org). Exports `createCatalogue`, which holds your locales and where each one's messages come from, `createView`, which binds one locale and formats messages using ICU MessageFormat, and `createStore`, which holds the current view and swaps it when you switch locale.
+The core runtime for [SayKit](https://saykit.js.org). Exports `createCatalogue`, which holds your locales and where each one's messages come from, `createView`, which binds one locale and formats its compiled messages, and `createStore`, which holds the current view and swaps it when you switch locale.
 
-You author messages with the `` say`...` `` tagged template (and `say.plural`, `say.ordinal`, `say.select`), and format numbers, dates and times for the locale with `say.number`, `say.date` and `say.time`; a SayKit build-tool plugin rewrites them at build time into small runtime calls.
+You author messages with the `` say`...` `` tagged template (and `say.plural`, `say.ordinal`, `say.select`), and format numbers, dates and times for the locale with `say.number`, `say.date` and `say.time`; a SayKit build-tool plugin rewrites them at build time into small runtime calls, and `saykit compile` turns each catalogue into a `.js` module of data that you import.
 
 ## Install
 
@@ -20,8 +20,8 @@ You will normally also want [`@saykit/config`](https://github.com/k0d13/saykit/t
 
 ```ts
 import { createCatalogue } from 'saykit';
-import en from './locales/en.po';
-import fr from './locales/fr.po';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
 
 const catalogue = createCatalogue({ en, fr });
 

package/dist/index.d.mts

@@ -1,14 +1,63 @@
-//#region src/types.d.ts
-type Tuple = [any, ...any[]];
-type Disallow<T, K extends PropertyKey> = T & Partial<Record<K, never>>;
-type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * What each node in a compiled message is, by the number it starts with.
+ *
+ * The numbers are the format, so a kind is only ever appended, never renumbered or reused.
+ */
+export declare const Kind: {
+  readonly Value: 0;
+  readonly Number: 1;
+  readonly DateTime: 2;
+  readonly Plural: 3;
+  readonly Ordinal: 4;
+  readonly Select: 5;
+  readonly Hash: 6;
+};
+export type Kind = (typeof Kind)[keyof typeof Kind];
+/**
+ * A compiled message.
+ *
+ * The CLI compiles a catalogue to this: strings and arrays, with styles already resolved to
+ * `Intl` options. It is plain JSON, so it can cross a server/client boundary.
+ *
+ * A node is an array starting with its {@link Kind}; an array starting with anything else is a
+ * concatenation. Operands are descriptor keys, never nodes. A message with no placeholders is its
+ * own string.
+ */
+type Message = string | Message[] | [typeof Kind.Value, string] | [typeof Kind.Number, string, Intl.NumberFormatOptions?, number?] | [typeof Kind.DateTime, string, Intl.DateTimeFormatOptions?] | [typeof Kind.Plural, string, Message.Cases, number?] | [typeof Kind.Ordinal, string, Message.Cases, number?] | [typeof Kind.Select, string, Message.Cases] | [typeof Kind.Hash];
+declare namespace Message {
+  /**
+   * A plural's or a select's branches, by key. A plural's keys are CLDR
+   * categories or an exact `=n`, and `other` is the fallback for both.
+   */
+  type Cases = {
+    [key: string]: Message;
+  };
+  /** What a compiled message is called with: the descriptor the transform built. */
+  type Values = Record<string, unknown>;
+}
+/**
+ * Compile one message into the function that formats it.
+ *
+ * Called once per message per locale; a view memoises the result.
+ *
+ * @param message The compiled message, as the CLI emitted it
+ * @param locale The locale to format in
+ * @param options Whether written values are wrapped in bidi isolation marks
+ * @returns A function from a descriptor to the formatted string
+ */
+export declare function compileMessage(message: Message, locale: string, options?: {
+  bidiIsolation?: 'default' | 'none';
+}): (values: Message.Values) => string;
+export type Tuple = [any, ...any[]];
+export type Disallow<T, K extends PropertyKey> = T & Partial<Record<K, never>>;
+export type Awaitable<T> = T | PromiseLike<T>;
 /**
  * A value wrapped in the name its ICU placeholder should take, written inline
  * as a single-key object: `` say`Total: ${{ cartTotal: getTotal() }}` ``. The
  * transform reads the key at build time and compiles only the value, so this
  * is never a real object at runtime.
  */
-type Named<T> = {
+export type Named<T> = {
   [name: string]: T;
 };
 /**
@@ -17,7 +66,7 @@ type Named<T> = {
  * `Branch` is what a case may be written as: text everywhere the message is
  * text, widening in JSX, where a case showing the number has to be a fragment.
  */
-interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLPluralRule, Branch>>, 'other'> {
+export interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLPluralRule, Branch>>, 'other'> {
   other: Branch;
   [digit: number]: Branch;
   /**
@@ -26,7 +75,7 @@ interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLP
    */
   offset?: number;
 }
-interface SelectOptions<Branch = string> {
+export interface SelectOptions<Branch = string> {
   other: Branch;
   [match: string | number]: Branch;
 }
@@ -38,38 +87,55 @@ interface SelectOptions<Branch = string> {
  * A skeleton is where the formats the named styles have no word for live:
  * currency, compact notation, a year and month with no day.
  */
-type Skeleton = `::${string}`;
+export type Skeleton = `::${string}`;
 /**
  * Formatting for a `{arg, number}` placeholder.
  *
  * A literal `NumberFormat` pattern such as `#,##0.00` is also accepted, for the
  * cases neither the named styles nor a skeleton spell more clearly.
  */
-interface NumberOptions {
+export interface NumberOptions {
   style?: 'integer' | 'percent' | Skeleton | (string & {});
 }
 /** Formatting for a `{arg, date}` or `{arg, time}` placeholder. */
-interface DateTimeOptions {
+export interface DateTimeOptions {
   style?: 'short' | 'medium' | 'long' | 'full' | Skeleton;
 }
-//#endregion
-//#region src/view.d.ts
 declare namespace View {
+  /**
+   * One locale's messages, compiled.
+   *
+   * Each is a {@link Message} the CLI compiled from the catalogue. They are plain data, so a
+   * server can hand them to a client tree.
+   */
   type Messages = {
-    [key: string]: string;
+    [key: string]: Message;
   };
   /**
-   * What the transform compiles a message down to: the id it was extracted
-   * under, or the ICU message itself when there was nothing to extract, with
-   * its values behind one underscore each.
+   * What the transform compiles a message down to: its extracted id, or the compiled message
+   * itself when there was nothing to extract. Values sit behind one underscore each.
    */
   type Descriptor = ({
     id: string;
   } | {
-    message: string;
+    message: Message;
   }) & {
     [match: string | number]: unknown;
   };
+  interface Options {
+    /**
+     * Whether a substituted value is wrapped in Unicode bidi isolation marks,
+     * U+2068 and U+2069, so right-to-left text cannot reorder the sentence
+     * around it.
+     *
+     * `'none'` leaves values byte-for-byte as given, for output that is parsed
+     * after it is formatted: a Discord mention such as `<#123>` stops being
+     * one once the id inside it is isolated.
+     *
+     * @default 'default'
+     */
+    bidiIsolation?: 'default' | 'none';
+  }
 }
 /**
  * One locale, bound to the messages it formats against.
@@ -115,12 +181,16 @@ interface View<Locale extends string = string> {
   readonly locale: Locale;
   /** The messages this view formats against. */
   readonly messages: Readonly<View.Messages>;
+  /**
+   * How this view formats its messages. Plain data, so it can cross a
+   * server/client boundary alongside {@link locale} and {@link messages}.
+   */
+  readonly options: Readonly<View.Options>;
   /**
    * Format the message a descriptor names, or the message it carries.
    *
-   * A message with nothing to translate, a lone `say.date(x)` with no text
-   * around it, is never extracted: the transform writes the ICU into the call
-   * instead of an id.
+   * A message with nothing to translate, such as a lone `say.date(x)`, is never extracted:
+   * the transform writes the compiled message into the call instead of an id.
    *
    * @param descriptor Descriptor to format
    * @returns The formatted message
@@ -246,17 +316,14 @@ interface View<Locale extends string = string> {
  * Create a view over one locale and the messages it formats against.
  *
  * A catalogue memoises one per locale, which is how application code usually
- * reaches one; a single-locale app can build one directly. The format cache
- * belongs to the view, so a view built over one set of messages can never be
- * served a format compiled from another.
+ * reaches one; a single-locale app can build one directly.
  *
  * @param locale The locale to bind to
  * @param messages The messages this view formats against
+ * @param options How this view formats its messages
  * @returns The view
  */
-declare function createView<Locale extends string>(locale: Locale, messages: View.Messages): View<Locale>;
-//#endregion
-//#region src/catalogue.d.ts
+export declare function createView<Locale extends string>(locale: Locale, messages: View.Messages, options?: View.Options): View<Locale>;
 declare namespace Catalogue {
   /**
    * One guess at a locale, or several. Guesses are read from cookies, headers
@@ -281,6 +348,8 @@ declare namespace Catalogue {
   type Produced = View.Messages | {
     default: View.Messages;
   };
+  /** How every view the catalogue hands back formats its messages. */
+  type Options = View.Options;
 }
 /**
  * Everything an application knows how to say: its locales and where their
@@ -365,11 +434,11 @@ interface Catalogue<Locale extends string = string> {
  * @param messages Where each locale's messages come from, keyed by locale. The
  *   keys are the catalogue's locales, in the order they are written, and the
  *   first of them is the default locale
+ * @param options How every view the catalogue hands back formats its
+ *   messages, such as `{ bidiIsolation: 'none' }`
  * @returns The catalogue
  */
-declare function createCatalogue<const Locale extends string = string>(messages: Record<Locale, Catalogue.Source>): Catalogue<Locale>;
-//#endregion
-//#region src/store.d.ts
+export declare function createCatalogue<const Locale extends string = string>(messages: Record<Locale, Catalogue.Source>, options?: Catalogue.Options): Catalogue<Locale>;
 declare namespace Store {
   /** Called after a successful switch, with the view that is now current. */
   type Listener<Locale extends string> = (view: View<Locale>) => void;
@@ -450,9 +519,7 @@ interface Store<Locale extends string = string> {
  * @returns The store
  * @throws If the starting locale has no messages loaded
  */
-declare function createStore<Locale extends string>(catalogue: Catalogue<Locale>, locale?: Locale): Store<Locale>;
-//#endregion
-//#region src/scope.d.ts
+export declare function createStore<Locale extends string>(catalogue: Catalogue<Locale>, locale?: Locale): Store<Locale>;
 declare namespace Scope {
   /**
    * Where a scope holds the view a piece of work is running under.
@@ -561,6 +628,5 @@ interface Scope {
  *   browser wants
  * @returns The scope
  */
-declare function createScope(storage?: Scope.Storage): Scope;
-//#endregion
-export { Awaitable, type Catalogue, DateTimeOptions, Disallow, Named, NumberOptions, NumeralOptions, type Scope, SelectOptions, Skeleton, type Store, Tuple, type View, createCatalogue, createScope, createStore, createView };
+export declare function createScope(storage?: Scope.Storage): Scope;
+export type { Catalogue, Message, Scope, Store, View };

package/dist/index.mjs

@@ -1,448 +1,205 @@
-import { parse } from "@messageformat/parser";
-import { MessageFormat } from "messageformat";
-import { getDateTimeFormatOptions, parseDateTokens } from "@messageformat/date-skeleton";
-import { getNumberFormatOptions, parseNumberPattern, parseNumberSkeleton } from "@messageformat/number-skeleton";
-import { getLocaleDir } from "messageformat/functions";
-//#region src/messageformat/options.ts
-const literal = (value) => ({
-	type: "literal",
-	value
-});
-function options(value) {
-	return typeof value === "object" && value !== null ? value : {};
+// src/runtime.ts
+const formatters = /* @__PURE__ */ new Map();
+function memoise(key, make) {
+	let formatter = formatters.get(key);
+	if (formatter === void 0) formatters.set(key, formatter = make());
+	return formatter;
 }
-//#endregion
-//#region src/messageformat/styles.ts
-var StyleError = class extends Error {};
-const DATE_STYLES = {
-	short: {
-		year: "numeric",
-		month: "numeric",
-		day: "numeric"
-	},
-	medium: {
-		year: "numeric",
-		month: "short",
-		day: "numeric"
-	},
-	long: {
-		year: "numeric",
-		month: "long",
-		day: "numeric"
-	},
-	full: {
-		year: "numeric",
-		month: "long",
-		day: "numeric",
-		weekday: "long"
-	}
-};
-const TIME_STYLES = {
-	short: {
-		hour: "numeric",
-		minute: "numeric"
-	},
-	medium: {
-		hour: "numeric",
-		minute: "numeric",
-		second: "numeric"
-	},
-	long: {
-		hour: "numeric",
-		minute: "numeric",
-		second: "numeric",
-		timeZoneName: "short"
-	},
-	full: {
-		hour: "numeric",
-		minute: "numeric",
-		second: "numeric",
-		timeZoneName: "long"
-	}
-};
-function dateTimeStyle(kind, style) {
-	const named = kind === "date" ? DATE_STYLES : TIME_STYLES;
-	if (style.startsWith("::")) {
-		const errors = [];
-		const opt = getDateTimeFormatOptions(parseDateTokens(style.slice(2)), (_type, message) => errors.push(message));
-		if (errors.length > 0) throw new StyleError(errors[0]);
-		if (Object.keys(opt).length === 0) throw new StyleError(`Empty skeleton ${style}`);
-		return opt;
-	}
-	if (style === "") return named.medium;
-	if (Object.hasOwn(named, style)) return named[style];
-	throw new StyleError(`Unsupported ${kind} style ${style}`);
+function numberFormat(locale, options) {
+	return memoise(`n${locale}${JSON.stringify(options ?? null)}`, () => new Intl.NumberFormat(locale, options));
 }
-function numberStyle(style) {
-	if (style === "") return {};
-	if (style === "integer") return { maximumFractionDigits: 0 };
-	if (style === "percent") return { style: "percent" };
-	const errors = [];
-	const onError = (error) => errors.push(String(error));
-	const skeleton = style.startsWith("::") ? parseNumberSkeleton(style.slice(2), onError) : parseNumberPattern(style, "XXX", onError);
-	let scale;
-	const opt = getNumberFormatOptions(skeleton, (stem, option) => {
-		if (stem === "scale") scale = Number(option);
-		else errors.push(`Unsupported number stem ${stem}`);
-	});
-	if (errors.length > 0) throw new StyleError(errors[0]);
-	return scale === void 0 ? opt : {
-		...opt,
-		scale
-	};
+function dateTimeFormat(locale, options) {
+	return memoise(`d${locale}${JSON.stringify(options ?? null)}`, () => new Intl.DateTimeFormat(locale, options));
 }
-//#endregion
-//#region src/messageformat/convert.ts
-const isSelect = (token) => token.type === "plural" || token.type === "select" || token.type === "selectordinal";
-const asKey = (key) => /^=\d+$/.test(key) ? Number(key.slice(1)) : key;
-function functionRef(token) {
-	let style = "";
-	for (const part of token.param ?? []) {
-		if (part.type !== "content") throw new Error(`Unsupported style part: ${part.type}`);
-		style += part.value;
-	}
-	style = style.trim();
-	const ref = (name, value) => ({
-		type: "function",
-		name,
-		...value === void 0 ? {} : { options: { options: literal(value) } }
-	});
-	try {
-		switch (token.key) {
-			case "date":
-			case "time": return ref("say:datetime", dateTimeStyle(token.key, style));
-			case "number": return ref("say:number", numberStyle(style));
-			case "duration": return ref("say:duration");
-			default: throw new StyleError(`Unsupported argument type ${token.key}`);
-		}
-	} catch (error) {
-		/* v8 ignore next */
-		if (!(error instanceof StyleError)) throw error;
-		switch (token.key) {
-			case "date":
-			case "time": return ref("say:datetime", dateTimeStyle(token.key, ""));
-			case "number": return ref("say:number", {});
-			default: return ref("say:string");
-		}
-	}
+function pluralRules(locale, type) {
+	return memoise(`p${locale}${type}`, () => new Intl.PluralRules(locale, { type }));
 }
-function toPart(token, plural) {
-	switch (token.type) {
-		case "content": return token.value;
-		case "argument": return {
-			type: "expression",
-			arg: {
-				type: "variable",
-				name: token.arg
-			}
-		};
-		case "function": return {
-			type: "expression",
-			arg: {
-				type: "variable",
-				name: token.arg
-			},
-			functionRef: functionRef(token)
-		};
-		case "octothorpe":
- /* v8 ignore next */
-		return plural ? {
-			type: "expression",
-			arg: {
-				type: "variable",
-				name: plural
-			}
-		} : "#";
-		/* v8 ignore next 2 -- the token union has no other members */
-		default: throw new Error(`Unsupported token type: ${token.type}`);
-	}
-}
-const sameSelector = (a) => (b) => a.arg === b.arg && a.type === b.type && a.offset === b.offset;
-function findSelectors(tokens) {
-	const selectors = [];
-	const add = (selector) => {
-		const existing = selectors.find(sameSelector(selector));
-		if (existing) {
-			existing.keys.push(...selector.keys);
-			return;
-		}
-		const taken = selectors.filter((s) => s.arg === selector.arg).length;
-		const name = taken === 0 ? selector.arg : `${selector.arg}#${taken}`;
-		selectors.push({
-			...selector,
-			name
-		});
-	};
-	for (const token of tokens) {
-		if (!isSelect(token)) continue;
-		add({
-			arg: token.arg,
-			type: token.type,
-			offset: token.pluralOffset ?? 0,
-			keys: token.cases.map((c) => token.type === "select" ? c.key : asKey(c.key))
-		});
-		for (const c of token.cases) for (const inner of findSelectors(c.tokens)) add(inner);
-	}
-	return selectors;
-}
-function declaration({ arg, name, type, offset }) {
-	const functionRef = type === "select" ? {
-		type: "function",
-		name: "say:string"
-	} : {
-		type: "function",
-		name: "say:plural",
-		options: { options: literal({
-			offset,
-			ordinal: type === "selectordinal"
-		}) }
-	};
-	const value = {
-		type: "expression",
-		arg: {
-			type: "variable",
-			name: arg
-		},
-		functionRef
-	};
-	return name === arg ? {
-		type: "input",
-		name,
-		value
-	} : {
-		type: "local",
-		name,
-		value
-	};
+function toNumeric(value) {
+	const raw = typeof value === "object" && value !== null ? value.valueOf() : value;
+	if (typeof raw === "bigint") return raw;
+	if (raw === null || raw === "") return void 0;
+	const number = Number(raw);
+	return Number.isNaN(number) ? void 0 : number;
 }
-function sortKeys(keys) {
-	const rank = (key) => typeof key === "number" ? 0 : key === "other" ? 2 : 1;
-	return Array.from(new Set(keys)).sort((a, b) => rank(a) - rank(b));
+function toDate(value) {
+	let raw = value;
+	if (typeof raw === "object" && raw !== null && !(raw instanceof Date)) raw = raw.valueOf();
+	if (typeof raw === "number" || typeof raw === "string") raw = new Date(raw);
+	return raw instanceof Date && !Number.isNaN(raw.getTime()) ? raw : void 0;
 }
-function toMessage(ast) {
-	const selectors = findSelectors(ast);
-	if (selectors.length === 0) return {
-		type: "message",
-		declarations: [],
-		pattern: ast.map((t) => toPart(t, null))
-	};
-	let tuples = [[]];
-	for (const selector of selectors) {
-		const keys = sortKeys(selector.keys);
-		tuples = tuples.flatMap((tuple) => keys.map((key) => [...tuple, key]));
-	}
-	const variants = tuples.map((tuple) => ({
-		keys: tuple.map((key) => key === "other" ? { type: "*" } : {
-			type: "literal",
-			quoted: false,
-			value: String(key)
-		}),
-		value: []
-	}));
-	function fill(tokens, plural, filter) {
-		for (const token of tokens) {
-			if (isSelect(token)) {
-				const index = selectors.findIndex(sameSelector({
-					arg: token.arg,
-					type: token.type,
-					offset: token.pluralOffset ?? 0
-				}));
-				const inner = token.type === "select" ? plural : selectors[index].name;
-				for (const c of token.cases) {
-					const key = token.type === "select" ? c.key : asKey(c.key);
-					fill(c.tokens, inner, [...filter, {
-						index,
-						key
-					}]);
-				}
-				continue;
-			}
-			for (const variant of variants) {
-				if (!filter.every(({ index, key }) => {
-					const vk = variant.keys[index];
-					return vk.type === "*" ? key === "other" : String(key) === vk.value;
-				})) continue;
-				const part = toPart(token, plural);
-				const last = variant.value.length - 1;
-				if (typeof part === "string" && typeof variant.value[last] === "string") variant.value[last] += part;
-				else variant.value.push(part);
-			}
-		}
-	}
-	fill(ast, null, []);
-	return {
-		type: "select",
-		declarations: selectors.map(declaration),
-		selectors: selectors.map((s) => ({
-			type: "variable",
-			name: s.name
-		})),
-		variants
-	};
+// src/message.ts
+const Kind = {
+	Value: 0,
+	Number: 1,
+	DateTime: 2,
+	Plural: 3,
+	Ordinal: 4,
+	Select: 5,
+	Hash: 6
+};
+const FSI = String.fromCharCode(8296);
+const RLI = String.fromCharCode(8295);
+const PDI = String.fromCharCode(8297);
+const RTL = /* @__PURE__ */ new Set([
+	"Adlm",
+	"Arab",
+	"Hebr",
+	"Mand",
+	"Nkoo",
+	"Rohg",
+	"Syrc",
+	"Thaa"
+]);
+function localeDir(locale) {
+	try {
+		const script = new Intl.Locale(locale).maximize().script;
+		if (script) return RTL.has(script) ? "rtl" : "ltr";
+	} catch {}
+	return "auto";
 }
-//#endregion
-//#region src/messageformat/values.ts
-function part(type, locale, parts) {
-	const dir = getLocaleDir(locale);
-	/* v8 ignore next 3 */
-	return dir === "ltr" || dir === "rtl" ? {
-		type,
-		dir,
-		locale,
-		parts
-	} : {
-		type,
-		locale,
-		parts
-	};
+function isolate(ctx, written, localised) {
+	if (!ctx.dir) return written;
+	if (!localised) return FSI + written + PDI;
+	if (ctx.dir === "ltr") return written;
+	return (ctx.dir === "rtl" ? RLI : FSI) + written + PDI;
 }
-function numeric(operand) {
-	const value = typeof operand === "object" && operand !== null ? operand.valueOf() : operand;
-	if (typeof value === "bigint") return value;
-	const number = Number(value);
-	if (Number.isNaN(number) && value !== void 0) throw new Error("Input is not numeric");
-	return number;
+function unformattable(kind, value, error) {
+	console.warn(`saykit: cannot format ${String(value)} as a ${kind}`, ...error ? [error] : []);
+	return String(value);
 }
-function temporal(operand) {
-	let value = operand;
-	if (typeof value === "object" && value !== null && !(value instanceof Date)) value = value.valueOf();
-	if (typeof value === "number" || typeof value === "string") value = new Date(value);
-	if (!(value instanceof Date) || Number.isNaN(value.getTime())) throw new Error("Input is not a valid date");
-	return value;
+function prepare(kind, make) {
+	try {
+		return make();
+	} catch (error) {
+		console.warn(`saykit: cannot build a ${kind} formatter`, error);
+		return;
+	}
 }
-function number(locales, value, opt) {
-	let nf;
-	let locale;
-	const format = () => nf ??= new Intl.NumberFormat(locales, opt);
-	const resolved = () => locale ??= format().resolvedOptions().locale;
-	return {
-		type: "number",
-		get dir() {
-			return getLocaleDir(resolved());
-		},
-		get options() {
-			return { ...opt };
-		},
-		toParts: () => [part("number", resolved(), format().formatToParts(value))],
-		toString: () => format().format(value),
-		valueOf: () => value
+function formatNumber(ctx, value, out, options, scale) {
+	const format = prepare("number", () => numberFormat(ctx.locale, options));
+	return (values) => {
+		const raw = value(values);
+		if (raw === void 0) return void 0;
+		const number = toNumeric(raw);
+		if (number === void 0 || !format) return unformattable("number", raw);
+		let scaled = number;
+		if (scale !== void 0) scaled = typeof number === "bigint" && Number.isInteger(scale) ? number * BigInt(scale) : Number(number) * scale;
+		return out ? isolate(ctx, format.format(scaled), true) : format.format(scaled);
 	};
 }
-function datetime(locales, value, opt) {
-	let dtf;
-	let locale;
-	const format = () => dtf ??= new Intl.DateTimeFormat(locales, opt);
-	const resolved = () => locale ??= format().resolvedOptions().locale;
+function arms(cases, ctx, out) {
+	const built = /* @__PURE__ */ new Map();
+	for (const [key, node] of Object.entries(cases)) built.set(key, build(node, ctx, out));
 	return {
-		type: "datetime",
-		get dir() {
-			return getLocaleDir(resolved());
-		},
-		get options() {
-			return { ...opt };
-		},
-		toParts: () => [part("datetime", resolved(), format().formatToParts(value))],
-		toString: () => format().format(value),
-		valueOf: () => value
+		built,
+		other: built.get("other")
 	};
 }
-function duration(seconds) {
-	if (!Number.isFinite(seconds)) return String(seconds);
-	const sign = seconds < 0 ? "-" : "";
-	const total = Math.round(Math.abs(seconds) * 1e3) / 1e3;
-	const secs = total % 60;
-	const minutes = Math.floor(total / 60);
-	const hours = Math.floor(minutes / 60);
-	const written = Math.round(secs) === secs ? String(secs) : secs.toFixed(3);
-	const parts = hours > 0 ? [
-		hours,
-		minutes % 60,
-		written
-	] : [minutes, written];
-	const first = parts.shift();
-	const pad = (n) => Number(n) < 10 ? `0${n}` : String(n);
-	return sign + [first, ...parts.map(pad)].join(":");
-}
-//#endregion
-//#region src/messageformat/functions.ts
-const functions = {
-	"say:number": (ctx, opt, operand) => {
-		const { scale, ...nf } = options(opt.options);
-		const value = numeric(operand);
-		return number(ctx.locales, scale ? Number(value) * scale : value, nf);
-	},
-	"say:datetime": (ctx, opt, operand) => datetime(ctx.locales, temporal(operand), options(opt.options)),
-	"say:duration": (_ctx, _opt, operand) => {
-		const value = Number(numeric(operand));
-		const str = duration(value);
-		return {
-			type: "say:duration",
-			toParts: () => [{
-				type: "say:duration",
-				value: str
-			}],
-			toString: () => str,
-			valueOf: () => value
-		};
-	},
-	"say:plural": (ctx, opt, operand) => {
-		const { offset = 0, ordinal = false } = options(opt.options);
-		const value = numeric(operand);
-		const shifted = typeof value === "bigint" ? value - BigInt(offset) : value - offset;
-		const result = number(ctx.locales, shifted, {});
-		result.valueOf = () => value;
-		let rules;
-		result.selectKey = (keys) => {
-			const exact = String(value);
-			if (keys.has(exact)) return exact;
-			rules ??= new Intl.PluralRules(ctx.locales, {
-				localeMatcher: ctx.localeMatcher,
-				type: ordinal ? "ordinal" : "cardinal"
-			});
-			const category = rules.select(Number(shifted));
-			return keys.has(category) ? category : null;
-		};
-		return result;
-	},
-	"say:string": (_ctx, _opt, operand) => {
-		const str = operand === void 0 ? "" : String(operand);
-		return {
-			type: "string",
-			selectKey: (keys) => keys.has(str) ? str : null,
-			toParts: () => [{
-				type: "string",
-				value: str
-			}],
-			toString: () => str,
-			valueOf: () => str
+function build(node, ctx, out) {
+	if (typeof node === "string") return () => node;
+	if (typeof node[0] !== "number") {
+		const parts = node.map((part) => build(part, ctx, out));
+		return (values) => {
+			let written = "";
+			for (const part of parts) written += part(values) ?? "";
+			return written;
 		};
 	}
-};
-//#endregion
-//#region src/messageformat/index.ts
-function compile(locale, source) {
-	return new MessageFormat(locale, toMessage(parse(source)), { functions });
+	const read = (key) => (values) => values[key];
+	switch (node[0]) {
+		case Kind.Value: {
+			const key = node[1];
+			if (!out) return read(key);
+			return (values) => {
+				const value = values[key];
+				return value === void 0 ? value : isolate(ctx, String(value), false);
+			};
+		}
+		case Kind.Number: return formatNumber(ctx, read(node[1]), out, node[2], node[3]);
+		case Kind.DateTime: {
+			const value = read(node[1]);
+			const format = prepare("date", () => dateTimeFormat(ctx.locale, node[2]));
+			return (values) => {
+				const raw = value(values);
+				if (raw === void 0) return void 0;
+				const date = toDate(raw);
+				if (!date || !format) return unformattable("date", raw);
+				return out ? isolate(ctx, format.format(date), true) : format.format(date);
+			};
+		}
+		case Kind.Plural:
+		case Kind.Ordinal: {
+			const value = read(node[1]);
+			const offset = node[3] ?? 0;
+			const rules = pluralRules(ctx.locale, node[0] === Kind.Ordinal ? "ordinal" : "cardinal");
+			const shift = (number) => offset === 0 ? number : typeof number === "bigint" ? number - BigInt(offset) : number - offset;
+			const hash = (values) => {
+				const number = toNumeric(value(values));
+				return number === void 0 ? void 0 : shift(number);
+			};
+			const { built, other } = arms(node[2], {
+				...ctx,
+				hash
+			}, out);
+			return (values) => {
+				const number = toNumeric(value(values));
+				let arm;
+				if (number !== void 0) {
+					arm = built.get(`=${String(number)}`);
+					arm ??= built.get(rules.select(Number(shift(number))));
+				}
+				return (arm ?? other)?.(values);
+			};
+		}
+		case Kind.Select: {
+			const value = read(node[1]);
+			const { built, other } = arms(node[2], ctx, out);
+			return (values) => {
+				const raw = value(values);
+				return ((raw === void 0 ? void 0 : built.get(String(raw))) ?? other)?.(values);
+			};
+		}
+		default:
+			if (!ctx.hash) return () => "#";
+			return formatNumber(ctx, ctx.hash, out);
+	}
 }
-//#endregion
-//#region src/view.ts
-function resolveDescriptorValues(descriptor) {
-	return Object.fromEntries(Object.entries(descriptor).filter(([key]) => key !== "id" && key !== "message").map(([key, value]) => [key.startsWith("_") ? key.slice(1) : key, value]));
+function compileMessage(message, locale, options = {}) {
+	if (typeof message === "string") return () => message;
+	const formatter = build(message, {
+		locale,
+		dir: options.bidiIsolation === "none" ? void 0 : localeDir(locale),
+		hash: void 0
+	}, true);
+	return (values) => String(formatter(values) ?? "");
 }
+// src/view.ts
 function macro(name) {
 	throw new Error(`'say.${name}' is a macro and must be used with the relevant saykit plugin`);
 }
-function createView(locale, messages) {
-	const own = Object.freeze({ ...messages });
-	const formats = /* @__PURE__ */ new Map();
+function snapshot(value) {
+	if (typeof value !== "object" || value === null) return value;
+	if (Array.isArray(value)) return Object.freeze(value.map(snapshot));
+	return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, node]) => [key, snapshot(node)])));
+}
+function createView(locale, messages, options = {}) {
+	const { bidiIsolation } = options;
+	const ownOptions = Object.freeze(bidiIsolation ? { bidiIsolation } : {});
+	const own = snapshot(messages);
 	const say = (() => {
 		throw new Error("'say' is a macro and must be used with the relevant saykit plugin");
 	});
+	const compiled = /* @__PURE__ */ new Map();
 	function call(descriptor) {
-		const { id, message = own[id] } = descriptor;
-		if (typeof message !== "string") throw new Error(`Message for ${id} is not a string`);
-		let format = formats.get(message);
-		if (!format) formats.set(message, format = compile(locale, message));
-		return String(format.format(resolveDescriptorValues(descriptor)));
+		const { id, message } = descriptor;
+		if (message !== void 0) return compileMessage(message, locale, ownOptions)(descriptor);
+		let format = compiled.get(id);
+		if (!format) {
+			const message = Object.hasOwn(own, id) ? own[id] : void 0;
+			if (message === void 0) throw new Error(`No message for ${id} in locale '${locale}'`);
+			compiled.set(id, format = compileMessage(message, locale, ownOptions));
+		}
+		return format(descriptor);
 	}
 	return Object.freeze(Object.defineProperties(say, {
 		locale: {
@@ -453,6 +210,10 @@ function createView(locale, messages) {
 			value: own,
 			enumerable: true
 		},
+		options: {
+			value: ownOptions,
+			enumerable: true
+		},
 		call: { value: call },
 		plural: { value: () => macro("plural") },
 		ordinal: { value: () => macro("ordinal") },
@@ -463,9 +224,9 @@ function createView(locale, messages) {
 		[Symbol.for("nodejs.util.inspect.custom")]: { value: (_depth, context, inspect) => `View<${inspect(locale, context)}> {}` }
 	}));
 }
-//#endregion
-//#region src/catalogue.ts
-function createCatalogue(messages) {
+// src/catalogue.ts
+function createCatalogue(messages, options = {}) {
+	const { bidiIsolation } = options;
 	const sources = Object.assign(Object.create(null), messages);
 	const keys = Object.freeze(Object.keys(sources));
 	if (keys.length === 0) throw new Error("A catalogue needs at least one locale, none were given");
@@ -474,7 +235,8 @@ function createCatalogue(messages) {
 	const views = /* @__PURE__ */ new Map();
 	const loading = /* @__PURE__ */ new Map();
 	function fill(locale, produced) {
-		const messages = typeof produced.default === "object" ? produced.default : produced;
+		const { default: inner } = produced;
+		const messages = typeof inner === "object" && !Array.isArray(inner) ? inner : produced;
 		if (!store.has(locale)) store.set(locale, messages);
 		return catalogue.locale(locale);
 	}
@@ -484,7 +246,7 @@ function createCatalogue(messages) {
 			const messages = store.get(locale);
 			if (!messages) throw new Error(typeof sources[locale] === "function" ? `Messages for locale '${locale}' have not been loaded yet` : `No messages for locale '${locale}'`);
 			let view = views.get(locale);
-			if (!view) views.set(locale, view = createView(locale, messages));
+			if (!view) views.set(locale, view = createView(locale, messages, { bidiIsolation }));
 			return view;
 		},
 		loaded(locale) {
@@ -530,8 +292,7 @@ function createCatalogue(messages) {
 	}
 	return Object.freeze(catalogue);
 }
-//#endregion
-//#region src/scope.ts
+// src/scope.ts
 const NO_VIEW = "No view is in scope for 'say'. Run the work inside 'scope.run(view, callback)', or establish one with 'scope.use(store)'.";
 function createVariableStorage() {
 	let running;
@@ -602,8 +363,7 @@ function createScope(storage = createVariableStorage()) {
 		return `Scope<${view ? inspect(view.locale, context) : "unset"}> {}`;
 	} } }));
 }
-//#endregion
-//#region src/store.ts
+// src/store.ts
 function createStore(catalogue, locale = catalogue.locales[0]) {
 	let current = catalogue.locale(locale);
 	const listeners = /* @__PURE__ */ new Set();
@@ -656,5 +416,4 @@ function createStore(catalogue, locale = catalogue.locales[0]) {
 		}
 	}, { [Symbol.for("nodejs.util.inspect.custom")]: { value: (_depth, context, inspect) => `Store<${inspect(current.locale, context)}> {}` } }));
 }
-//#endregion
-export { createCatalogue, createScope, createStore, createView };
+export { Kind, compileMessage, createCatalogue, createScope, createStore, createView };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saykit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Type-safe i18n library with compile-time macro transforms",
   "keywords": [
     "i18n",
@@ -22,7 +22,8 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "skills"
   ],
   "type": "module",
   "sideEffects": false,
@@ -36,12 +37,6 @@
     "access": "public",
     "provenance": true
   },
-  "dependencies": {
-    "@messageformat/date-skeleton": "2.0.0-0",
-    "@messageformat/number-skeleton": "2.0.0-0",
-    "@messageformat/parser": "^5.1.1",
-    "messageformat": "^4.0.0"
-  },
   "scripts": {
     "check": "tsc --noEmit",
     "build": "tsdown"

package/skills/saykit/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: saykit
+description: Use when adding, changing, or debugging internationalisation with SayKit (the `saykit`, `@saykit/*`, `unplugin-saykit`, or `babel-plugin-saykit` packages), or when a project has a saykit.config.ts. Covers setup, the say and <Say> macros, plurals and formatting, catalogues, views and stores, React client and server usage, extraction, and the mistakes agents make most.
+---
+
+# SayKit
+
+Compile-time i18n. Messages are written inline, `` say`Hello, ${name}!` `` or `<Say>Hello, {name}!</Say>`. The CLI extracts them to translation files and compiles each locale into a `.js` module of data; a build plugin rewrites each macro to `say.call({ id, ... })`. Nothing parses ICU at runtime, a small evaluator formats the compiled data with `Intl`.
+
+Docs: https://saykit.js.org. Source and end-to-end examples (`examples/*`): https://github.com/k0d13/saykit.
+
+All SayKit packages are released together and must share one version. Pre-1.0, so APIs still move between minors.
+
+## Packages
+
+| Package                 | Purpose                                                                 | When                                                         |
+| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `saykit`                | Runtime: `createCatalogue`, `createStore`, the `say` macros, formatting | Always, a runtime dependency                                 |
+| `@saykit/config`        | `defineConfig` and the `saykit` CLI (`extract`, `compile`, `clean`)     | Always, dev dependency                                       |
+| `@saykit/transform-js`  | Extracts and rewrites `say` macros in `.js`/`.ts`                       | Always                                                       |
+| `@saykit/transform-jsx` | Same for `<Say>` in `.jsx`/`.tsx`                                       | Any JSX                                                      |
+| `@saykit/format-po`     | Gettext PO catalogues                                                   | Default choice, translators and TMSes know it                |
+| `@saykit/format-json`   | JSON catalogues; `arb` and `webextension` dialects                      | Flutter-style ARB, browser extension `_locales/`, plain JSON |
+| `unplugin-saykit`       | Bundler plugin                                                          | Vite, Rollup, Rolldown, Webpack, Rspack, esbuild, Farm, Bun  |
+| `babel-plugin-saykit`   | Babel plugin                                                            | Next.js, Expo, React Native, any Babel pipeline              |
+| `@saykit/react`         | `<Say>`, `SayProvider`, `useSay`, `withSay`, `getSay`                   | React                                                        |
+| `@saykit/carbon`        | `SayPlugin`, `withSay`, `interaction.say`, `guild.say`                  | Carbon Discord bots                                          |
+
+A project needs the runtime, config, one formatter, the transformers for its file types, and one plugin. Use the project's own package manager.
+
+## Setup
+
+### `saykit.config.ts`
+
+At the project root. A TypeScript config needs Node 22.18+, or Bun, Deno or tsx.
+
+```ts
+import { defineConfig } from '@saykit/config';
+import po from '@saykit/format-po';
+import js from '@saykit/transform-js';
+import jsx from '@saykit/transform-jsx';
+
+export default defineConfig({
+  // The first locale is the source locale: the language the code is written
+  // in, the only one extraction writes, and the final fallback for every other
+  locales: ['en', 'en-GB', 'en-NZ', 'fr'],
+  // Optional chains between a locale and the source, most specific first.
+  // Every key and value must also appear in `locales`
+  fallbackLocales: { 'en-NZ': ['en-GB'] },
+  buckets: [
+    {
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: ['src/**/*.d.*.ts'],
+      // Must contain {locale} and end in .{extension}
+      output: 'src/locales/{locale}.{extension}',
+      formatter: po(),
+      transformer: [js(), jsx()],
+      // Optional: strings with no call site (a manifest, a store listing), keyed by id
+      messages: { extensionName: 'Reading Time' },
+    },
+  ],
+});
+```
+
+A bucket is "these files in, this catalogue out". One bucket is the norm, including for a Next.js app where server and client components share a catalogue. Add more only when two areas genuinely want separate files, such as transactional emails beside a UI.
+
+### Bundler
+
+Vite, and every other bundler `unplugin` supports (change only the import path: `/rollup`, `/rolldown`, `/webpack`, `/rspack`, `/esbuild`, `/farm`, `/bun`):
+
+```ts title="vite.config.ts"
+import react from '@vitejs/plugin-react';
+import saykit from 'unplugin-saykit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [saykit(), react()],
+});
+```
+
+Next.js, Expo, React Native and plain Babel. Adding a `.babelrc` switches Next from SWC to Babel; there is no SWC plugin:
+
+```json title=".babelrc"
+{
+  "presets": ["next/babel"],
+  "plugins": ["saykit"]
+}
+```
+
+```js title="babel.config.js"
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['saykit'],
+  };
+};
+```
+
+A plugin only rewrites macros. Catalogues are never loaded through it: no `next.config` or `metro.config` wrapper, no loader options.
+
+### Compiled locale modules
+
+`saykit compile` writes a `{locale}.js` beside each catalogue (`src/locales/fr.po` → `src/locales/fr.js`), with the `fallbackLocales` chain already merged in, plus a `{locale}.d.ts` declaring `Record<string, Message>`. `saykit extract` compiles too, and `extract --watch` recompiles when a catalogue changes. Gitignore the `.js` modules and commit the `.d.ts`, which never changes, so `tsc` passes on a fresh clone. Since the modules are not committed, run compile before anything that imports a locale:
+
+```json title="package.json"
+{
+  "scripts": {
+    "predev": "saykit compile",
+    "prebuild": "saykit compile",
+    "pretest": "saykit compile"
+  }
+}
+```
+
+A formatter whose extension is `.js` cannot be used: its module would overwrite the catalogue.
+
+## Writing messages
+
+### TypeScript
+
+```ts
+say`Hello, ${name}!`; // Hello, {name}!
+say`Total: ${{ cartTotal: getTotal() }}`; // Total: {cartTotal}
+say`Hello, ${user.name}`; // Hello, {0}   (not an identifier, so numbered)
+
+say.plural(count, { 0: 'No items', one: '1 item', other: `${count} items` });
+say.ordinal(n, { one: `${n}st`, two: `${n}nd`, few: `${n}rd`, other: `${n}th` });
+say.select(status, { active: 'Active', archived: 'Archived', other: 'Unknown' });
+```
+
+A placeholder is named after the variable when the expression is a bare identifier. Anything else is numbered, which tells a translator nothing; name it with a single-key object, `${{ name: user.name }}`, or lift it into a local first. Keep a sentence in one message: ``say`Hello, ` + name`` gives a translator half a sentence.
+
+`plural`, `ordinal` and `select` need `other`. Exact-number branches are plain digits. Interpolating the selector inside a branch extracts as ICU `#`. Branch keys are ICU keys, identifiers with no hyphens or spaces: `'sold-out'` fails the build, and the fix is to rename the discriminant at its source to `soldOut`, since `select` compares literal strings and a renamed branch would never match.
+
+### Context and comments
+
+Identical strings that mean different things get a `context`, which gives them separate catalogue entries and shows the translator which is which. A custom `id` gives an optional readable key
+
+```ts
+say({ context: 'noun' })`Post`;
+say({ context: 'verb' })`Post`;
+say({ id: 'checkout.review' })`Review your order`;
+say({ id: 'nav.right', context: 'direction' })`Right`;
+```
+
+A comment starting with `TRANSLATORS:` directly above a message is extracted alongside it; use it for tone, length limits and anything a translator could not infer. Other comments stay in code.
+
+```ts
+// TRANSLATORS: Button text, keep under 20 characters
+say`Continue`;
+```
+
+### Numbers, dates and times
+
+```ts
+say`Published ${say.date(post.at, { style: 'long' })}`; // Published {0, date, long}
+say`Total ${say.number(total, { style: '::currency/EUR' })}`; // Total {0, number, ::currency/EUR}
+say.number(1234.5); // "1,234.5" in en, "1 234,5" in fr
+say.time(opensAt, { style: 'short' });
+```
+
+Inside a message the format lands in the catalogue, so a locale can move the number. Alone, the value is formatted for the view's locale but nothing is extracted, there is nothing to translate. `number` styles: `integer`, `percent`, a skeleton (`::currency/EUR`, `::compact-short`), or a pattern (`#,##0.00`). `date` and `time` styles: `short`, `medium`, `long`, `full`, or a skeleton (`::yMMMM`, `::Hm`). There is no `currency` style, only the skeleton. Unknown styles fail the build.
+
+### JSX
+
+```tsx
+import { Say } from '@saykit/react';
+
+<Say>Hello, {name}!</Say>
+<Say>Hello, {{ name: user.name }}!</Say>
+<Say context="noun">Post</Say>
+<Say id="checkout.review">Review your order</Say>
+
+{/* TRANSLATORS: Shown on an empty board */}
+<Say>Nothing here yet.</Say>
+
+// Elements become tags a translator can move: "Read the <0>docs</0>".
+// say-tag names one: "Read the <link>docs</link>". Name it after what it does to the text.
+<Say>Read the <a href="/docs" say-tag="link">docs</a></Say>
+
+<Say.Plural _={count} _0="Nothing here" one={<>{count} item</>} other={<>{count} items</>} />
+<Say.Ordinal _={n} one={<>{n}st</>} two={<>{n}nd</>} few={<>{n}rd</>} other={<>{n}th</>} />
+<Say.Select _={status} active="Active" archived="Archived" other="Unknown" />
+
+<Say>Due <Say.Date _={dueAt} style="medium" /></Say>
+<Say.Number _={row.total} style="::currency/EUR" />
+```
+
+`_` is the selector. Exact-number branches are `_0`, `_1` because a prop cannot start with a digit; extraction strips the underscore. A branch that shows the number must be a fragment, not a string. `{' '}` inside `<Say>` folds into the text. `whitespace` defaults to `true`; pass `whitespace={false}` in React Native when `<Text>` elements sit next to each other, otherwise a bare string outside `<Text>` throws.
+
+## Runtime
+
+Three objects. A **catalogue** holds locales and where their messages come from. A **view** is one locale bound to its messages: callable, immutable, and what application code holds. A **store** holds the current view and swaps it, which is what switching locale in a browser is.
+
+```ts title="src/i18n.ts"
+import { createCatalogue, createStore } from 'saykit';
+import en from './locales/en.js';
+
+export const catalogue = createCatalogue({
+  en, // inline
+  fr: () => import('./locales/fr.js'), // lazy: one chunk, fetched on first load
+});
+
+// No Locale type is exported; derive it
+export type Locale = (typeof catalogue.locales)[number];
+```
+
+`createCatalogue` takes a record whose keys are the locales; the first is the fallback `match` resolves to. Never write the messages by hand: keys are content hashes the transform chose, and values are compiled trees, so a hand-written `{ greeting: 'Hello' }` matches nothing. Import the compiled module. A second argument sets view options: `{ bidiIsolation: 'none' }` turns off the FSI/PDI marks written around interpolated values (on by default, as in MessageFormat 2).
+
+```ts
+catalogue.locales; // ['en', 'fr']
+catalogue.match(navigator.languages, cookieLocale); // exact, then language prefix, then locales[0]; nullish guesses are skipped
+catalogue.loaded('fr'); // false until loaded
+const say = await catalogue.load('fr'); // calls the thunk once; synchronous when already loaded
+catalogue.locale('fr'); // synchronous; throws if a lazy locale has not been loaded
+for (const [locale, say] of catalogue) {
+} // every locale's view
+
+say.locale; // 'fr'
+say`Hello`; // formats against fr
+```
+
+`fallbackLocales` and `match` are different fallbacks. `fallbackLocales` is build time, it decides which files are merged into a locale's catalogue so an untranslated key resolves to another locale's string. `match` is runtime, it decides which key of the catalogue a guess maps to, and never resolves to a locale that is not a key.
+
+Browser, where the locale changes:
+
+```ts
+const initial = catalogue.match(navigator.languages);
+await catalogue.load(initial); // no-op for an eager locale; required when `initial` is lazy
+export const store = createStore(catalogue, initial);
+
+store.say`Hello`; // read per call; identity changes on switch
+store.subscribe((say) => {
+  document.documentElement.lang = say.locale;
+});
+await store.set('fr'); // loads if needed; last switch wins; a failed load keeps the current view
+```
+
+A store exposes `say`, `set` and `subscribe` only; keep the catalogue for `locales`. Do not hold `const say = store.say` across a switch. `createStore` throws when its initial locale is lazy and unloaded, so `await catalogue.load(initial)` before building the store whenever any locale is lazy, including a mixed catalogue.
+
+Server: no store. Look a view up per request with `catalogue.load(catalogue.match(guesses))`, splitting an `Accept-Language` header into its tags first (`header.split(',').map((s) => s.split(';')[0].trim())`), since `match` compares whole strings; views are safe to share between requests. For code that cannot be handed a view, `createScope(new AsyncLocalStorage())` from `saykit` gives a `scope.say` resolving to whatever `scope.run(view, fn)` established.
+
+## React
+
+### Client
+
+```tsx title="src/main.tsx"
+import { SayProvider } from '@saykit/react/client';
+import { store } from './i18n';
+
+<SayProvider store={store}>
+  <App />
+</SayProvider>;
+```
+
+```tsx title="src/locale-picker.tsx"
+import { useSay } from '@saykit/react/client';
+import { catalogue, store, type Locale } from './i18n';
+
+export function LocalePicker() {
+  const say = useSay(); // the current View; re-renders on switch
+  return (
+    <select value={say.locale} onChange={(event) => store.set(event.target.value as Locale)}>
+      {catalogue.locales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+There is no store hook; the store is a module value, import it. `<SayProvider locale={locale} messages={messages}>` is the single-locale form a server hands across the boundary; it cannot switch.
+
+### Server components
+
+```ts title="src/i18n.ts"
+import { createWithSay } from '@saykit/react/server';
+import { createCatalogue } from 'saykit';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
+
+export const catalogue = createCatalogue({ en, fr });
+export const withSay = createWithSay(catalogue);
+```
+
+```tsx title="app/[locale]/layout.tsx"
+import { SayProvider } from '@saykit/react/client';
+import { getSay } from '@saykit/react/server';
+import { withSay } from '../../i18n';
+
+function Layout({ children }: LayoutProps<'/[locale]'>) {
+  return (
+    <html lang={getSay().locale}>
+      <body>
+        <SayProvider>{children}</SayProvider>
+      </body>
+    </html>
+  );
+}
+
+export default withSay(Layout, (p) => p.params.then((p) => p.locale));
+```
+
+`withSay(Component, getLocale)` runs `getLocale` (returns a string, array, or nullish, sync or async), passes it through `catalogue.match`, loads the view and establishes it in React's per-request `cache()` before rendering. Wrap **every** layout and page that renders messages, not only the root: Next renders a page before its layout, so an unwrapped page's `getSay()` throws `'getSay' must be called below a 'withSay'`. `<SayProvider>` written in a server component takes no props; the `react-server` build hands the established locale and messages, plain data, to the client. `getSay()` is the server `useSay()`, for the locale as data or a string in a handler. `setSay(view)` establishes a view you resolved yourself. One view per request: a second locale replaces the first for everything rendered after it.
+
+## Carbon
+
+```ts
+import { Client, Command, type CommandInteraction } from '@buape/carbon';
+import { createWithSay, SayPlugin } from '@saykit/carbon';
+
+export const withSay = createWithSay(catalogue);
+
+class Ping extends withSay(Command) {
+  constructor() {
+    super((say) => ({ name: say`ping`, description: say`Ping the bot!` }));
+  }
+
+  async run(interaction: CommandInteraction) {
+    await interaction.reply({ content: interaction.say`Pong!` });
+  }
+}
+
+new Client(options, { commands: [new Ping()] }, [new SayPlugin(catalogue)]);
+```
+
+`withSay` builds command metadata once per locale. `interaction.say` is the interaction locale's view, `guild.say` the guild's.
+
+## Workflow
+
+1. Write or change a message.
+2. `saykit extract` (or `saykit extract --watch`). Only the source locale file is written; other locales are created header-only and never touched afterwards. Every locale is then compiled.
+3. Translate the other locales by hand or through a TMS. A locale file needs only the entries actually translated; the rest fall back through `fallbackLocales` to the source string at compile time. After pulling translations, `saykit compile`.
+4. `saykit clean` when source strings were removed or reworded: it drops orphaned and empty entries from non-source locales and never adds anything.
+
+Commit the catalogues and `.d.ts` files, not the compiled `.js`. CI check that extraction was run:
+
+```yaml
+- run: pnpm saykit extract
+- run: git diff --exit-code -- 'src/locales/*.po'
+```
+
+Macros throw without the plugin, so a test runner needs it too; Vitest picks it up from `vite.config.ts`.
+
+Custom formats: a `Formatter` is `{ extension: '.yaml', parse(content) => Message[], stringify(messages, meta) => string }` and a `Transformer` is `{ match(id) => boolean, extract(code, id) => Message[], transform(code, id) => string }`, where `Message` (from `@saykit/config`, not the runtime type) is `{ message, translation?, id?, context?, comments, references }`. See `examples/custom-formatter`.
+
+## Errors
+
+| Symptom                                                             | Cause and fix                                                                                                       |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `'say' is a macro and must be used with the relevant saykit plugin` | The file was not transformed. Check the bucket `include` glob and that the plugin is in the bundler and test config |
+| `No message for <id> in locale 'x'`                                 | Stale or hand-written module. Run `saykit extract`; import the compiled file, never declare messages                |
+| `Cannot find module './locales/en.js'`                              | Not compiled yet. `saykit compile`, and add it as a `pre` script                                                    |
+| `Messages for locale 'x' have not been loaded yet`                  | `catalogue.locale('x')` on a lazy locale. `await catalogue.load('x')` or `store.set('x')` first                     |
+| `No messages for locale 'x'`                                        | `x` is not a key of the catalogue. Run guesses through `match` first                                                |
+| `'getSay' must be called below a 'withSay'`                         | This segment is not wrapped. Wrap every layout and page, not only the root                                          |
+| Edited a `.po`, dev server shows old strings                        | The module was not recompiled. Run `saykit extract --watch` alongside the dev server, or `saykit compile`           |
+| Translator sees `{0}`                                               | Placeholder is not an identifier. Name it: `${{ name: value }}`                                                     |
+| Build fails on a branch key such as `sold-out`                      | ICU keys are identifiers. Rename the discriminant at its source                                                     |
+| `Text strings must be rendered within a <Text> component`           | React Native. `<Say whitespace={false}>`                                                                            |