@k8ordo/i18n 0.1.0 → 1.0.0

package/README.md

@@ -8,8 +8,10 @@ function — `message({ ja: 'ホーム', en: 'Home' })` — that reads the local
 where it is called: the request on the server, the URL in the browser. So the
 same line renders in a Server Component and in a Client Component, there is
 no provider and no hook, and a bundler keeps only the messages a client module
-names. No message grammar: interpolation is a template literal and plurals are
-`Intl.PluralRules`.
+names. No message grammar: interpolation is a template literal, and plurals,
+dates and numbers are `Intl`, drawn for the current locale by the set
+(`locales.pluralRules()`, `locales.dateTimeFormat()`, …) — a date always in
+that locale's time zone, so the server's HTML and the browser agree.
 
 Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
 Components, uses only what has reached Baseline newly available, and ships no
@@ -28,27 +30,45 @@ pnpm add @k8ordo/i18n
 
 ## Peer Dependencies
 
-| Package      | Version | Needed for                    |
-| ------------ | ------- | ----------------------------- |
-| `typescript` | ≥7.0.2  | the shipped type declarations |
+<!-- peers -->
+
+| Package      | Version | Required | Needed for                    |
+| ------------ | ------- | -------- | ----------------------------- |
+| `typescript` | ≥7.0.0  | optional | the shipped type declarations |
+
+<!-- /peers -->
 
 No React import and no schema library: a message is a plain function, and a
 locale set is a list that checks membership itself. `locales.paramsSchema`
-speaks Standard Schema, which is what `@k8ordo/static` and `@k8ordo/server`
-run for a route's params. On a server the current locale rides on
-`AsyncLocalStorage` (Node ≥ 24).
+speaks Standard Schema, which is what `@k8ordo/framework` runs for a
+route's params. On a server the current locale rides on
+`AsyncLocalStorage`, reached through `process.getBuiltinModule`, so a server
+runtime has to provide that API; Node 24, which the framework modes require,
+does.
 
 ## Quick Start
 
-The locale set in its own module, registered once so every message is held
-to it:
+The locale set in its own module — each locale with the time zone its dates
+are shown in and the direction its text runs in:
 
 ```ts
-// i18n.ts
+// src/i18n.ts
 import { defineLocales } from '@k8ordo/i18n';
-import type { LocaleOf } from '@k8ordo/i18n';
 
-export const locales = defineLocales(['ja', 'en']);
+export const locales = defineLocales({
+  ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
+  en: { timeZone: 'UTC', dir: 'ltr' },
+});
+```
+
+Every message is held to the set through `Register`. Under
+`@k8ordo/framework` that is generated from the `locales` export of
+`src/i18n.ts`, and there is nothing to write. Anywhere else, register it
+once, beside the set:
+
+```ts
+// src/i18n.ts, outside @k8ordo/framework
+import type { LocaleOf } from '@k8ordo/i18n';
 
 declare module '@k8ordo/i18n' {
   interface Register {
@@ -60,7 +80,7 @@ declare module '@k8ordo/i18n' {
 Each message is one export, with its text in every locale:
 
 ```ts
-// messages/nav.ts
+// src/messages/nav.ts
 import { message } from '@k8ordo/i18n';
 
 export const home = message({ ja: 'ホーム', en: 'Home' });
@@ -74,30 +94,30 @@ The `[locale]` route's layout declares the schema; accepting a locale makes it
 the locale of that render:
 
 ```tsx
-// routes/[locale]/layout.tsx
+// src/routes/[locale]/layout.tsx
 import { locales } from '../../i18n';
 
-export const paramsSchema = locales.paramsSchema; // /fr/… is a 404
+export const { paramsSchema } = locales; // /fr/… is a 404
 ```
 
 And a message is called the same way everywhere:
 
 ```tsx
-// routes/[locale]/page.tsx — a Server Component
-import * as nav from '../../messages/nav';
+// src/routes/[locale]/page.tsx — a Server Component
+import { home } from '../../messages/nav';
 
 export default function Page() {
-  return <h1>{nav.home()}</h1>;
+  return <h1>{home()}</h1>;
 }
 ```
 
 ```tsx
-// components/toolbar.tsx — a Client Component, the same line
+// src/components/toolbar.tsx — a Client Component, the same line
 'use client';
-import * as nav from '../messages/nav';
+import { greeting } from '../messages/nav';
 
 export function Toolbar() {
-  return <button>{nav.greeting('k8o')}</button>;
+  return <button>{greeting('k8o')}</button>;
 }
 ```
 
@@ -105,16 +125,41 @@ Where a Server Component hands text to a Client Component as a prop, it calls
 the message and passes the string: a function does not cross that boundary.
 
 `/` negotiates and redirects; `<html lang>` and a language switcher read
-`locales.getLocale()`; a static build expands `[locale]` from `locales.all`.
+`locales.getLocale()`, and `<html dir>` its `locales.definitions[…].dir`; a static build passes `paths: locales.paths`. Links
+stay the router's: `bindParams(() => ({ locale: locales.getLocale() }))`
+(imported from `@k8ordo/framework` in a framework application) gives an `href` that spells `/:locale/…` patterns without the locale.
 
 ## AI Agent Documentation
 
-This package ships its documentation so an AI coding assistant reads the exact
-installed version:
+The docs ship **inside the package**, so an agent always reads the exact
+version you installed — there is no snapshot to copy or re-sync on upgrade.
+
+Point your agent at them once by pasting this into your project's `CLAUDE.md` /
+`AGENTS.md`:
+
+```markdown
+Use `@k8ordo/i18n` for locales and translated text. Before adding a message
+or touching a `[locale]` route, read `node_modules/@k8ordo/i18n/docs/GUIDE.md`.
+The locale set is declared once with `defineLocales` as the `locales` export
+of `src/i18n.ts`, and registered through `Register` — generated under
+`@k8ordo/framework`, so never write it there; written once beside the set
+elsewhere. Each message is a `message({ ja, en })` export, called where it
+renders — the same call in a Server and a Client Component. There is no
+provider, no hook and no message grammar: never pass the locale down as a
+prop, interpolate inside the message's own function, format dates and numbers
+with `locales.dateTimeFormat()` / `numberFormat()` / `pluralRules()` (never a
+bare `Intl.DateTimeFormat` without the locale's time zone), and from a Server
+Component hand a `'use client'` component the called string, not the message.
+```
+
+What each surface gives an agent:
 
-- `node_modules/@k8ordo/i18n/docs/GUIDE.md` — the design guide
-- `node_modules/@k8ordo/i18n/docs/llms.txt` — the index
+| Surface                    | Where                                          |
+| -------------------------- | ---------------------------------------------- |
+| Design guide (entry point) | `node_modules/@k8ordo/i18n/docs/GUIDE.md`      |
+| Docs index for LLMs        | `docs/llms.txt` · https://ordo.k8o.me/llms.txt |
+| Markdown twin on the web   | https://ordo.k8o.me/i18n/docs/GUIDE.md         |
 
 ## License
 
-MIT
+MIT License - see [LICENSE](https://github.com/k35o/k8ordo/blob/main/LICENSE) for details.

package/dist/accept-language.d.mts

@@ -1,11 +1,11 @@
 //#region src/accept-language.d.ts
 /**
  * The tags of an `Accept-Language` header, most preferred first: `q` weights
- * decide the order (a tag without one weighs 1), ties keep the header's
- * order, `q=0` and the `*` wildcard are dropped — the wildcard says "anything",
- * which is what the default locale already means. Feed the result to
- * `locales.negotiate`; a missing header (`null`) is an empty list.
+ * decide the order (a tag without one, or with one that is not a number,
+ * weighs 1), ties keep the header's order, a weight of 0 or less (an empty
+ * `q=` reads as 0) and the `*` wildcard are dropped — the wildcard says
+ * "anything", which is what the default locale already means. Feed the result
+ * to `locales.negotiate`; a missing header (`null`) is an empty list.
  */
-declare const parseAcceptLanguage: (header: string | null) => string[];
-//#endregion
-export { parseAcceptLanguage };
+export declare const parseAcceptLanguage: (header: string | null) => string[];
+//#endregion

package/dist/accept-language.mjs

@@ -1,10 +1,11 @@
 //#region src/accept-language.ts
 /**
 * The tags of an `Accept-Language` header, most preferred first: `q` weights
-* decide the order (a tag without one weighs 1), ties keep the header's
-* order, `q=0` and the `*` wildcard are dropped — the wildcard says "anything",
-* which is what the default locale already means. Feed the result to
-* `locales.negotiate`; a missing header (`null`) is an empty list.
+* decide the order (a tag without one, or with one that is not a number,
+* weighs 1), ties keep the header's order, a weight of 0 or less (an empty
+* `q=` reads as 0) and the `*` wildcard are dropped — the wildcard says
+* "anything", which is what the default locale already means. Feed the result
+* to `locales.negotiate`; a missing header (`null`) is an empty list.
 */
 const parseAcceptLanguage = (header) => {
 	if (header === null || header.trim() === "") return [];

package/dist/cookie.d.mts

@@ -0,0 +1,10 @@
+//#region src/cookie.d.ts
+/**
+ * The value of one cookie in a `Cookie` header, or `null` when the header or
+ * the cookie is missing. The first cookie of that name wins — a browser sends
+ * the one with the most specific path first — and a value in double quotes
+ * (RFC 6265 allows them) comes back without them. Values are not
+ * percent-decoded: a locale tag needs no encoding.
+ */
+export declare const readCookie: (header: string | null, name: string) => string | null;
+//#endregion

package/dist/cookie.mjs

@@ -0,0 +1,20 @@
+//#region src/cookie.ts
+/**
+* The value of one cookie in a `Cookie` header, or `null` when the header or
+* the cookie is missing. The first cookie of that name wins — a browser sends
+* the one with the most specific path first — and a value in double quotes
+* (RFC 6265 allows them) comes back without them. Values are not
+* percent-decoded: a locale tag needs no encoding.
+*/
+const readCookie = (header, name) => {
+	if (header === null) return null;
+	for (const pair of header.split(";")) {
+		const separator = pair.indexOf("=");
+		if (separator === -1 || pair.slice(0, separator).trim() !== name) continue;
+		const value = pair.slice(separator + 1).trim();
+		return value.length >= 2 && value.startsWith("\"") && value.endsWith("\"") ? value.slice(1, -1) : value;
+	}
+	return null;
+};
+//#endregion
+export { readCookie };

package/dist/current.d.mts

@@ -1,47 +1,50 @@
+import { RegisteredLocale } from "./register.mjs";
 //#region src/current.d.ts
-/**
- * Where the current locale is kept, on each side of the network.
- *
- * On a server the request that `paramsSchema` accepted (or `locales.run`)
- * names it, and it is carried by `AsyncLocalStorage` so concurrent renders
- * stay apart. The RSC environment and the SSR environment (where client
- * components run on the server) are separate module graphs in one process,
- * so the storage — and the locale set that registered — live on
- * `globalThis`, not in this module.
- *
- * In the browser the URL is the locale: its first segment, read when asked.
- */
-type LocaleStorage = {
+export type LocaleStorage = {
   getStore: () => string | undefined;
   enterWith: (locale: string) => void;
   run: <T>(locale: string, fn: () => T) => T;
 };
 /** What `message()` needs from the locale set: the default, and membership. */
-type RegisteredSet = {
+export type RegisteredSet = {
   readonly default: string;
   readonly is: (value: unknown) => boolean;
 };
-declare const inBrowser: boolean;
+export declare const inBrowser: boolean;
 /**
  * Reached through `process.getBuiltinModule` rather than an import so the
  * same build runs in the browser, where there is no request to scope to.
  */
-declare const localeStorage: () => LocaleStorage | null;
+export declare const localeStorage: () => LocaleStorage | null;
 /**
  * The set messages read is the last one defined; an application has one.
  * Last rather than first so that a dev server re-evaluating the module that
  * defines the set (a locale added under HMR) is what messages see next.
  */
-declare const register: (set: RegisteredSet) => void;
+export declare const register: (set: RegisteredSet) => void;
+/**
+ * The browser's pathname in the application's terms: Vite's `base` taken
+ * off, so the first segment is the one the route table's `[locale]` names —
+ * `/docs/en/ui` is `/en/ui` under `base: '/docs/'`.
+ */
+export declare const browserPathname: () => string;
 /** Whether a set has registered in this environment yet. */
-declare const setRegistered: () => boolean;
+export declare const setRegistered: () => boolean;
 /**
- * The current locale as a string, or `null` when nothing names one: no
+ * The locale named where this runs, or `null` when nothing names one: no
  * segment in the URL, no request in progress. A registered set makes an
  * unknown segment `null` too, so `/fr/…` does not read as a locale.
  */
-declare const currentLocale: () => string | null;
+export declare const namedLocale: () => string | null;
 /** The registered default, when a set registered in this environment. */
-declare const registeredDefault: () => string | null;
-//#endregion
-export { LocaleStorage, RegisteredSet, currentLocale, inBrowser, localeStorage, register, registeredDefault, setRegistered };
+export declare const registeredDefault: () => string | null;
+/**
+ * The current locale as the application's set resolves it — the one named,
+ * else the set's default — or `null` when no set is defined in this
+ * environment. For a library rendering inside an application it does not
+ * know (`@k8ordo/ui`'s built-in text): an application that never defined a
+ * set has no locale, whatever its URL happens to start with, so the server
+ * and the browser both answer `null` and agree.
+ */
+export declare const currentLocale: () => RegisteredLocale | null;
+//#endregion

package/dist/current.mjs

@@ -25,16 +25,29 @@ const localeStorage = () => {
 const register = (set) => {
 	global[SET_KEY] = set;
 };
-/** The first segment of the browser's URL, whatever it spells. */
-const browserSegment = () => global.location?.pathname.split("/")[1] ?? "";
+/**
+* The browser's pathname in the application's terms: Vite's `base` taken
+* off, so the first segment is the one the route table's `[locale]` names —
+* `/docs/en/ui` is `/en/ui` under `base: '/docs/'`.
+*/
+const browserPathname = () => {
+	const pathname = global.location?.pathname ?? "/";
+	const base = import.meta.env === void 0 ? "/" : import.meta.env.BASE_URL;
+	if (!base.startsWith("/") || base === "/") return pathname;
+	const prefix = base.endsWith("/") ? base.slice(0, -1) : base;
+	if (pathname === prefix) return "/";
+	return pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname;
+};
+/** The first segment of the browser's URL below the base, whatever it spells. */
+const browserSegment = () => browserPathname().split("/")[1] ?? "";
 /** Whether a set has registered in this environment yet. */
 const setRegistered = () => global[SET_KEY] !== void 0;
 /**
-* The current locale as a string, or `null` when nothing names one: no
+* The locale named where this runs, or `null` when nothing names one: no
 * segment in the URL, no request in progress. A registered set makes an
 * unknown segment `null` too, so `/fr/…` does not read as a locale.
 */
-const currentLocale = () => {
+const namedLocale = () => {
 	const set = global[SET_KEY];
 	const named = inBrowser ? browserSegment() : localeStorage()?.getStore();
 	if (named === void 0 || named === "") return null;
@@ -43,5 +56,18 @@ const currentLocale = () => {
 };
 /** The registered default, when a set registered in this environment. */
 const registeredDefault = () => global[SET_KEY]?.default ?? null;
+/**
+* The current locale as the application's set resolves it — the one named,
+* else the set's default — or `null` when no set is defined in this
+* environment. For a library rendering inside an application it does not
+* know (`@k8ordo/ui`'s built-in text): an application that never defined a
+* set has no locale, whatever its URL happens to start with, so the server
+* and the browser both answer `null` and agree.
+*/
+const currentLocale = () => {
+	const set = global[SET_KEY];
+	if (set === void 0) return null;
+	return namedLocale() ?? set.default;
+};
 //#endregion
-export { currentLocale, inBrowser, localeStorage, register, registeredDefault, setRegistered };
+export { browserPathname, currentLocale, inBrowser, localeStorage, namedLocale, register, registeredDefault, setRegistered };

package/dist/format.d.mts

@@ -0,0 +1,32 @@
+import { LocaleDefinition } from "./locales.mjs";
+//#region src/format.d.ts
+/**
+ * `Intl.DateTimeFormatOptions` without a `timeZone`: the locale's own is the
+ * only one a date is written in, so the server's HTML and the browser's
+ * render agree. A date that should follow each visitor's zone is `Intl`'s own
+ * business, in a part that renders in the browser only.
+ */
+export type LocaleDateTimeFormatOptions = Intl.DateTimeFormatOptions & {
+  readonly timeZone?: never;
+};
+/**
+ * `Intl`, drawn for the current locale. Each returns the `Intl` object
+ * itself — `format`, `formatToParts`, `formatRange`, `select`,
+ * `resolvedOptions` are all there — made once per locale and options and
+ * reused after that.
+ */
+export type IntlFormats = {
+  /** `Intl.DateTimeFormat` in the current locale and that locale's `timeZone`. */
+  readonly dateTimeFormat: (options?: LocaleDateTimeFormatOptions) => Intl.DateTimeFormat;
+  /** `Intl.NumberFormat` in the current locale. */
+  readonly numberFormat: (options?: Intl.NumberFormatOptions) => Intl.NumberFormat;
+  /** `Intl.RelativeTimeFormat` in the current locale. */
+  readonly relativeTimeFormat: (options?: Intl.RelativeTimeFormatOptions) => Intl.RelativeTimeFormat;
+  /** `Intl.PluralRules` in the current locale. */
+  readonly pluralRules: (options?: Intl.PluralRulesOptions) => Intl.PluralRules;
+  /** `Intl.ListFormat` in the current locale. */
+  readonly listFormat: (options?: Intl.ListFormatOptions) => Intl.ListFormat;
+};
+/** The members of a locale set that draw `Intl` for its current locale. */
+export declare const intlFormats: <L extends string>(getLocale: () => L, definitions: Readonly<Record<L, LocaleDefinition>>) => IntlFormats;
+//#endregion

package/dist/format.mjs

@@ -0,0 +1,31 @@
+//#region src/format.ts
+/**
+* An `Intl` constructor behind a cache keyed by locale and options. The
+* options are keyed by their JSON: two spellings of the same options make two
+* entries, which costs a duplicate, never a wrong answer.
+*/
+const cached = (current, create) => {
+	const made = /* @__PURE__ */ new Map();
+	return (options) => {
+		const locale = current();
+		const key = `${locale}\u0000${JSON.stringify(options ?? {})}`;
+		const existing = made.get(key);
+		if (existing !== void 0) return existing;
+		const created = create(locale, options);
+		made.set(key, created);
+		return created;
+	};
+};
+/** The members of a locale set that draw `Intl` for its current locale. */
+const intlFormats = (getLocale, definitions) => ({
+	dateTimeFormat: cached(getLocale, (locale, options) => new Intl.DateTimeFormat(locale, {
+		...options,
+		timeZone: definitions[locale].timeZone
+	})),
+	numberFormat: cached(getLocale, (locale, options) => new Intl.NumberFormat(locale, options)),
+	relativeTimeFormat: cached(getLocale, (locale, options) => new Intl.RelativeTimeFormat(locale, options)),
+	pluralRules: cached(getLocale, (locale, options) => new Intl.PluralRules(locale, options)),
+	listFormat: cached(getLocale, (locale, options) => new Intl.ListFormat(locale, options))
+});
+//#endregion
+export { intlFormats };

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 import { parseAcceptLanguage } from "./accept-language.mjs";
-import { Delocalized, LocaleOf, LocaleParamsSchema, Locales, LocalesOptions, defineLocales } from "./locales.mjs";
 import { Register, RegisteredLocale } from "./register.mjs";
+import { currentLocale } from "./current.mjs";
+import { Delocalized, LocaleDefinition, LocaleOf, LocaleParamsSchema, Locales, LocalesOptions, NegotiateRequestOptions, defineLocales } from "./locales.mjs";
+import { IntlFormats, LocaleDateTimeFormatOptions } from "./format.mjs";
 import { Message, Variants, message } from "./message.mjs";
-export { type Delocalized, type LocaleOf, type LocaleParamsSchema, type Locales, type LocalesOptions, type Message, type Register, type RegisteredLocale, type Variants, defineLocales, message, parseAcceptLanguage };
+export { type Delocalized, type IntlFormats, type LocaleDateTimeFormatOptions, type LocaleDefinition, type LocaleOf, type LocaleParamsSchema, type Locales, type LocalesOptions, type Message, type NegotiateRequestOptions, type Register, type RegisteredLocale, type Variants, currentLocale, defineLocales, message, parseAcceptLanguage };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { parseAcceptLanguage } from "./accept-language.mjs";
+import { currentLocale } from "./current.mjs";
 import { defineLocales } from "./locales.mjs";
 import { message } from "./message.mjs";
-export { defineLocales, message, parseAcceptLanguage };
+export { currentLocale, defineLocales, message, parseAcceptLanguage };

package/dist/locales.d.mts

@@ -1,11 +1,12 @@
+import { IntlFormats } from "./format.mjs";
 //#region src/locales.d.ts
 /**
  * The one shape every validation library agrees on (Standard Schema), as far
- * as `@k8ordo/static` / `@k8ordo/server` read it for a route's `paramsSchema`.
+ * as `@k8ordo/framework` reads it for a route's `paramsSchema`.
  * Declared here rather than depended on so the package carries no schema
  * library: a locale set is a list, and a list can check membership itself.
  */
-type LocaleParamsSchema<L extends string> = {
+export type LocaleParamsSchema<L extends string> = {
   readonly '~standard': {
     readonly version: 1;
     readonly vendor: '@k8ordo/i18n';
@@ -30,19 +31,37 @@ type LocaleParamsSchema<L extends string> = {
     } | undefined;
   };
 };
-type Delocalized<L extends string> = {
+export type Delocalized<L extends string> = {
   /** The locale the first segment spelled, or `null` when it spelled none. */
   readonly locale: L | null;
   /** The pathname with that segment removed — never empty, `/` at least. */
   readonly pathname: string;
 };
+/**
+ * What a locale carries besides its tag. Both are declared rather than
+ * derived: the runtime's own time zone differs between a server and each
+ * visitor's browser, and `Intl.Locale#getTextInfo` has not reached every
+ * browser.
+ */
+export type LocaleDefinition = {
+  /**
+   * The IANA time zone this locale's dates are shown in (`'Asia/Tokyo'`) —
+   * the same one on the server and in every browser, so a date renders the
+   * same on both sides.
+   */
+  readonly timeZone: string;
+  /** The direction its text runs in: `<html dir>`. */
+  readonly dir: 'ltr' | 'rtl';
+};
 /**
  * An application's locale set. `L` is the union of its tags, `D` the default
  * among them.
  */
-type Locales<L extends string = string, D extends L = L> = {
-  /** Every locale, in the order given; the first is the default unless told otherwise. */
+export type Locales<L extends string = string, D extends L = L> = IntlFormats & {
+  /** Every locale, in the order defined; the first is the default unless told otherwise. */
   readonly all: readonly L[];
+  /** Each locale's definition, as given: `definitions[locale].dir` for `<html dir>`. */
+  readonly definitions: Readonly<Record<L, LocaleDefinition>>;
   /** The locale used when negotiation finds nothing better, and when nothing names one. */
   readonly default: D;
   /** Membership, as a type guard — the check `params.locale` and a pathname segment go through. */
@@ -55,38 +74,75 @@ type Locales<L extends string = string, D extends L = L> = {
    * that is not BCP 47 is skipped, not thrown on: the list is user input.
    */
   readonly negotiate: (requested: Iterable<string>) => L;
-  /** `'/ui'` → `'/en/ui'`, `'/'` → `'/en'`. The pathname must not already carry a locale segment. */
+  /**
+   * The locale a request asks for, for a server that answers before any
+   * page renders — sending `/` to a locale. The cookie named in `options`
+   * comes first, when the request carries it: it is the visitor's own choice,
+   * written where they switched language. Then the `Accept-Language` header,
+   * in its order of preference. Each goes through `negotiate`, so a cookie
+   * holding a locale the set no longer has falls through to the header, and
+   * nothing matching is the default.
+   */
+  readonly negotiateRequest: (request: Request, options?: NegotiateRequestOptions) => L;
+  /**
+   * `'/ui'` → `'/en/ui'`, `'/'` → `'/en'`. Hand it a pathname without a
+   * locale segment, as `delocalize` returns one: that is not checked, so
+   * `localize('/en/ui', 'ja')` is `'/ja/en/ui'`.
+   */
   readonly localize: (pathname: string, locale: L) => string;
   /** The inverse: `'/en/ui'` → `{ locale: 'en', pathname: '/ui' }`, `'/x'` → `{ locale: null, pathname: '/x' }`. */
   readonly delocalize: (pathname: string) => Delocalized<L>;
+  /**
+   * The static build's `paths` option: every pattern that has a `/:locale`
+   * segment, once per locale, so
+   * `framework({ mode: 'static', paths: locales.paths })` is the whole
+   * answer for a site whose only parameter is the locale. A pattern with
+   * another parameter comes back still holding it (`/ja/blog/:slug`), which
+   * the build renders only as the location of a `fallback.tsx`'s shell, and
+   * otherwise refuses: expand the rest in the same function. A shell runs
+   * only its layouts' schemas, so it renders in its locale when this set's
+   * `paramsSchema` sits on `[locale]/layout.tsx`.
+   */
+  readonly paths: (patterns: readonly string[]) => string[];
   /**
    * A params schema for a `[locale]` route segment, in the shape
-   * `@k8ordo/static` / `@k8ordo/server` run: `export const paramsSchema =
+   * `@k8ordo/framework` runs: `export const paramsSchema =
    * locales.paramsSchema` makes `/fr/…` a pathname the pattern does not
-   * answer. Accepting a locale also makes it the current one for the rest of
-   * that request's render, which is how `getLocale()` knows it on the server.
+   * answer. On a server, accepting a locale also makes it the current one for
+   * the render of the page that accepted it, which is how `getLocale()` knows
+   * it there; a server runtime without `AsyncLocalStorage` throws instead.
    */
   readonly paramsSchema: LocaleParamsSchema<L>;
   /**
    * The locale of the render in progress. In the browser it is the first
-   * segment of `location.pathname`; on the server it is what `paramsSchema`
+   * segment of `location.pathname` below Vite's `base`; on the server it is what `paramsSchema`
    * accepted for this request, or what `run` set. Neither names one → the
    * default. Not a hook: call it anywhere, including inside a message.
    */
   readonly getLocale: () => L;
   /**
    * Runs `fn` with `locale` as the current one for everything it starts —
-   * a test, a Server Action, code outside a `[locale]` route. Server only:
-   * in the browser the URL is the locale.
+   * a test, a job, code outside a `[locale]` route. A Server Action posted
+   * from a `[locale]` page already runs in that page's locale under the
+   * framework. Server only: in the browser the URL is the locale.
    */
   readonly run: <T>(locale: L, fn: () => T) => T;
 };
-type LocalesOptions<D extends string> = {
+export type NegotiateRequestOptions = {
+  /**
+   * The cookie holding the visitor's choice (`'locale'`). The name is the
+   * application's: whatever writes it — a language switcher's
+   * `cookieStore.set` — uses the same one. Omitted, only `Accept-Language`
+   * is read.
+   */
+  readonly cookie?: string;
+};
+export type LocalesOptions<D extends string> = {
   /** The default locale. Must be one of the list; the first entry when omitted. */
   readonly default?: D;
 };
 /** The locale union of a `Locales` — `LocaleOf<typeof locales>`. */
-type LocaleOf<Ls> = Ls extends Locales<infer L, infer _D> ? L : never;
+export type LocaleOf<Ls> = Ls extends Locales<infer L, infer _D> ? L : never;
 /**
  * Declares the locale set once. Everything that needs to know which locales
  * exist — the params schema of the `[locale]` segment, the static build's
@@ -94,10 +150,11 @@ type LocaleOf<Ls> = Ls extends Locales<infer L, infer _D> ? L : never;
  * every message — reads this value, so the list is spelled in one place.
  *
  * ```ts
- * export const locales = defineLocales(['ja', 'en']);
- * export const locales = defineLocales(['en-US', 'en-GB', 'ja'], { default: 'ja' });
+ * export const locales = defineLocales({
+ *   ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
+ *   en: { timeZone: 'America/New_York', dir: 'ltr' },
+ * });
  * ```
  */
-declare const defineLocales: <const All extends readonly [string, ...string[]], D extends All[number] = All[0]>(all: All, options?: LocalesOptions<D>) => Locales<All[number], D>;
-//#endregion
-export { Delocalized, LocaleOf, LocaleParamsSchema, Locales, LocalesOptions, defineLocales };
+export declare const defineLocales: <const Definitions extends Readonly<Record<string, LocaleDefinition>>, D extends keyof Definitions & string = keyof Definitions & string>(definitions: Definitions, options?: LocalesOptions<D>) => Locales<keyof Definitions & string, D>;
+//#endregion