@pie-players/pie-players-shared 1.0.0-beta.6 → 1.0.0-beta.8

package/README.md

@@ -20,6 +20,7 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `@pie-players/pie-players-shared` | The root: the loader, PIE, security and object helpers, loader config, instrumentation providers, the item-player strategy helpers, the default bundle host URL (`BUILDER_BUNDLE_URL`), a subset of the shared types, and the UI helpers (attribute coercion, content styles, pointer gestures, overlay placement, focus trap, safe storage, scoped CSS) |
 | `/loader-config` | `LoaderConfig` and its defaults: instrumentation (`trackPageActions`, `instrumentationProvider`), resource retry, and IIFE bundle retry |
 | `/security` | The item-markup sanitizer (`sanitizeItemMarkup`, `createDefaultItemMarkupSanitizer`, `buildAuthoringAllowList`), external-stylesheet URL validation, the SVG icon and `style` attribute sanitizers, and the wrappers that put overwide images and tables in a scrollable region |
+| `/security/private-hosts` | `isPrivateHostname` and `isCloudMetadataHostname`, the host classification for a URL a server fetches on someone else's behalf. Node-safe: it loads none of the markup sanitizers |
 | `/object` | `mergeObjectsIgnoringNullUndefined`, `cloneDeep`, `isPlainRecord` |
 | `/types` | The shared types: item, passage, section and session entities, PIE models and controllers, accessibility catalogs, and the [media vocabulary](#media-validation) |
 | `/formative` | [Formative delivery](#formative-delivery) |
@@ -33,9 +34,10 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `/i18n/provider` | `SimpleI18n`, `getDefaultI18n` and `resolveInterfaceI18n`, with the English catalog only |
 | `/i18n/catalogs` | `BUNDLED_LOCALES` and lazy loaders for the bundled locales other than English |
 | `/i18n/language-tags` | BCP 47 language tag normalization and matching |
-| `/nds-icon-button` | `<nds-icon-button>`, an icon button vendored as a prebuilt bundle with Lit inlined; importing it registers the tag. The assessment toolkit and `@pie-players/pie-tool-tts-inline` render it |
+| `/nds-icon-button` | `<nds-icon-button>`, an icon button vendored as a prebuilt bundle with Lit inlined; importing it registers the tag. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` render it |
 | `/ui/attribute-coercion` | Boolean attribute coercion for custom elements |
 | `/ui/content-styles` | `installContentStyles`, `auditContentStyles` and the opt-out checks behind the item player's content styles |
+| `/ui/fontawesome` | The FontAwesome `<nds-icon-button>` glyphs need: the one FA Free pin, Pro detection, the `<head>` and shadow-root installs, and the glyph weight. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` use it |
 | `/tools/term-lookup` | Term normalization and the lookup session the dictionary tools share; the host supplies the endpoint or a resolver |
 
 ## Formative Delivery

package/dist/i18n/catalogs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lazy catalog loaders for every locale this repository ships.
+ * The bundled catalog loader: `en-US`, the one statically shipped catalog.
  *
  * Imported by players, never by tools. A tool resolves its provider from the
  * toolkit runtime context and needs only the interface plus the English
@@ -7,25 +7,32 @@
  * into a bundle that never calls `setLocale`, because every tool
  * `vite.config.ts` sets `external: []`.
  *
- * An explicit static map rather than a bundler macro: `tsc` emits these
- * `import()` calls verbatim, so `players-shared/dist` evaluates anywhere ESM
- * does — webpack, esbuild, Rollup, Node, or a browser loading the files
- * directly. `pie-qti` used `import.meta.glob` and shipped a `dist` that throws
- * under every one of those. Each bundler still sees the specifiers statically,
- * so each locale stays its own chunk. Adding a locale means adding one line here
- * alongside the file.
+ * `en-US` is the source of truth — the fallback for every missing key in every
+ * other locale — so the provider imports it statically and it is always
+ * resident. It is the only catalog this package ships: every other locale this
+ * repository ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), whose loaders a host composes after
+ * this one. The composed shape is that package's README's wiring example:
  *
- * `en-US` is absent: it is the fallback for every missing key in every other
- * locale, so the provider imports it statically and it is always resident.
+ * ```ts
+ * loadCatalog: (locale) =>
+ *   loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale));
+ * ```
+ *
+ * A request this function cannot serve rejects, and the provider treats that
+ * as "resolve through the fallback chain" rather than an error, so a host
+ * locale nothing ships still renders English.
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
 import type { BundledLocaleCode, MessageCatalog } from "./types.js";
 /**
- * Every locale tag this repository ships a catalog for, English included.
+ * Every locale tag this repository bundles a catalog for. `en-US` alone: the
+ * statically resident source of truth.
  *
  * The provider resolves a request against this list through RFC 4647 lookup and
- * primary-subtag widening, so `nl`, `nl_NL` and `nl-BE` all reach `nl-NL`.
+ * primary-subtag widening, so `en`, `en_US` and `en-GB`-without-a-catalog all
+ * land on `en-US` unless a composed loader serves the region.
  */
 export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
 /**
@@ -36,7 +43,7 @@ export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
  * or a pseudo-localization of the English catalog — asks for it by name like
  * any other locale.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * Rejects for a locale with no bundled catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */

package/dist/i18n/catalogs.js

@@ -1,5 +1,5 @@
 /**
- * Lazy catalog loaders for every locale this repository ships.
+ * The bundled catalog loader: `en-US`, the one statically shipped catalog.
  *
  * Imported by players, never by tools. A tool resolves its provider from the
  * toolkit runtime context and needs only the interface plus the English
@@ -7,30 +7,34 @@
  * into a bundle that never calls `setLocale`, because every tool
  * `vite.config.ts` sets `external: []`.
  *
- * An explicit static map rather than a bundler macro: `tsc` emits these
- * `import()` calls verbatim, so `players-shared/dist` evaluates anywhere ESM
- * does — webpack, esbuild, Rollup, Node, or a browser loading the files
- * directly. `pie-qti` used `import.meta.glob` and shipped a `dist` that throws
- * under every one of those. Each bundler still sees the specifiers statically,
- * so each locale stays its own chunk. Adding a locale means adding one line here
- * alongside the file.
+ * `en-US` is the source of truth — the fallback for every missing key in every
+ * other locale — so the provider imports it statically and it is always
+ * resident. It is the only catalog this package ships: every other locale this
+ * repository ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), whose loaders a host composes after
+ * this one. The composed shape is that package's README's wiring example:
  *
- * `en-US` is absent: it is the fallback for every missing key in every other
- * locale, so the provider imports it statically and it is always resident.
+ * ```ts
+ * loadCatalog: (locale) =>
+ *   loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale));
+ * ```
+ *
+ * A request this function cannot serve rejects, and the provider treats that
+ * as "resolve through the fallback chain" rather than an error, so a host
+ * locale nothing ships still renders English.
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
 import enUS from "./messages/en-US.js";
-const CATALOG_LOADERS = {
-    "nl-NL": () => import("./messages/nl-NL.js"),
-};
 /**
- * Every locale tag this repository ships a catalog for, English included.
+ * Every locale tag this repository bundles a catalog for. `en-US` alone: the
+ * statically resident source of truth.
  *
  * The provider resolves a request against this list through RFC 4647 lookup and
- * primary-subtag widening, so `nl`, `nl_NL` and `nl-BE` all reach `nl-NL`.
+ * primary-subtag widening, so `en`, `en_US` and `en-GB`-without-a-catalog all
+ * land on `en-US` unless a composed loader serves the region.
  */
-export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
+export const BUNDLED_LOCALES = ["en-US"];
 /**
  * Load one shipped catalog.
  *
@@ -39,7 +43,7 @@ export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
  * or a pseudo-localization of the English catalog — asks for it by name like
  * any other locale.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * Rejects for a locale with no bundled catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */
@@ -47,10 +51,5 @@ export async function loadBundledCatalog(locale) {
     if (locale === "en-US") {
         return enUS;
     }
-    const loader = CATALOG_LOADERS[locale];
-    if (!loader) {
-        throw new Error(`No bundled i18n catalog for locale: ${locale}`);
-    }
-    const module = await loader();
-    return module.default;
+    throw new Error(`No bundled i18n catalog for locale: ${locale}`);
 }

package/dist/i18n/content-language.d.ts

@@ -12,8 +12,32 @@
  * The player reflects the resolved language onto its content subtree's root as
  * `lang` and `dir`, so a screen reader takes the content's voice rules and RTL
  * content lays out right to left, independent of the chrome's locale.
+ *
+ * Content that declares nothing falls back to a default the container names:
+ * a section's `runtime.contentLanguage`, or {@link UNDECLARED_CONTENT_LANGUAGE}
+ * once the host sets an interface locale, which stamps `lang=""` and
+ * `dir="auto"` so the content takes neither the interface's language nor its
+ * direction. With neither, undeclared content inherits its context, which keeps
+ * hosts that set no interface locale rendering as they always have.
  */
 import type { TextDirection } from "./types.js";
+/**
+ * The content-language default for content that declares no language under a
+ * host-set interface locale: `lang=""` names the language unknown and
+ * `dir="auto"` takes direction from the content's first strong character.
+ */
+export declare const UNDECLARED_CONTENT_LANGUAGE = "auto";
+/**
+ * The default a player stamps on content whose `env` declares no language: the
+ * host's content language, else {@link UNDECLARED_CONTENT_LANGUAGE} when the
+ * host set an interface locale, else `undefined`, which leaves undeclared
+ * content inheriting its context. Inputs are read defensively, since both
+ * arrive from attributes.
+ */
+export declare function defaultContentLanguage(options: {
+    contentLanguage?: unknown;
+    interfaceLocale?: unknown;
+}): string | undefined;
 /** `lang` and `dir` for declared content, or `null` when nothing is declared. */
 export interface ContentLanguageAttributes {
     lang: string;
@@ -28,8 +52,26 @@ export interface ContentLanguageAttributes {
  */
 export declare function contentLanguageAttributes(env: unknown): ContentLanguageAttributes | null;
 /**
- * Stamps `contentLanguageAttributes(env)` onto `target`, removing both
- * attributes when the env declares no language — a model set can drop the
- * language a previous one declared. No-op without a target.
+ * Stamps the content language onto `target`: `contentLanguageAttributes(env)`,
+ * else `fallback` — a tag, or {@link UNDECLARED_CONTENT_LANGUAGE} for
+ * `lang=""` and `dir="auto"` — else neither attribute, so a model set can drop
+ * the language a previous one declared. A fallback that is not a usable tag
+ * counts as absent. No-op without a target.
+ */
+export declare function stampContentLanguage(target: Element | null | undefined, env: unknown, fallback?: string | null): void;
+/**
+ * The direction of the first letter in `root`'s text, skipping `script`,
+ * `style` and `template`, or `null` when it has none. Letters only, which is
+ * where the bidi algorithm's strong characters overwhelmingly sit.
+ */
+export declare function firstStrongDirection(root: Node): TextDirection | null;
+/**
+ * The mismatch between undeclared content's script and the direction a
+ * fallback stamped on `root`, or `null` when there is none to report: the env
+ * declares a language, `root` carries no stamped direction or `dir="auto"`, or
+ * the content has no letters.
  */
-export declare function stampContentLanguage(target: Element | null | undefined, env: unknown): void;
+export declare function undeclaredDirectionMismatch(root: Element, env: unknown): {
+    stamped: TextDirection;
+    script: TextDirection;
+} | null;

package/dist/i18n/content-language.js

@@ -12,9 +12,40 @@
  * The player reflects the resolved language onto its content subtree's root as
  * `lang` and `dir`, so a screen reader takes the content's voice rules and RTL
  * content lays out right to left, independent of the chrome's locale.
+ *
+ * Content that declares nothing falls back to a default the container names:
+ * a section's `runtime.contentLanguage`, or {@link UNDECLARED_CONTENT_LANGUAGE}
+ * once the host sets an interface locale, which stamps `lang=""` and
+ * `dir="auto"` so the content takes neither the interface's language nor its
+ * direction. With neither, undeclared content inherits its context, which keeps
+ * hosts that set no interface locale rendering as they always have.
  */
 import { canonicalLanguageTag } from "./language-tags.js";
 import { localeDirection } from "./provider.js";
+/**
+ * The content-language default for content that declares no language under a
+ * host-set interface locale: `lang=""` names the language unknown and
+ * `dir="auto"` takes direction from the content's first strong character.
+ */
+export const UNDECLARED_CONTENT_LANGUAGE = "auto";
+/**
+ * The default a player stamps on content whose `env` declares no language: the
+ * host's content language, else {@link UNDECLARED_CONTENT_LANGUAGE} when the
+ * host set an interface locale, else `undefined`, which leaves undeclared
+ * content inheriting its context. Inputs are read defensively, since both
+ * arrive from attributes.
+ */
+export function defaultContentLanguage(options) {
+    const named = typeof options.contentLanguage === "string"
+        ? options.contentLanguage.trim()
+        : "";
+    if (named)
+        return named;
+    const requested = typeof options.interfaceLocale === "string"
+        ? options.interfaceLocale.trim()
+        : "";
+    return requested ? UNDECLARED_CONTENT_LANGUAGE : undefined;
+}
 /**
  * `lang` and `dir` for the content an `env` describes, or `null` when it
  * declares no usable language. Reads `env.locale` defensively — `env` is
@@ -32,14 +63,19 @@ export function contentLanguageAttributes(env) {
     return { lang, dir: localeDirection(lang) };
 }
 /**
- * Stamps `contentLanguageAttributes(env)` onto `target`, removing both
- * attributes when the env declares no language — a model set can drop the
- * language a previous one declared. No-op without a target.
+ * Stamps the content language onto `target`: `contentLanguageAttributes(env)`,
+ * else `fallback` — a tag, or {@link UNDECLARED_CONTENT_LANGUAGE} for
+ * `lang=""` and `dir="auto"` — else neither attribute, so a model set can drop
+ * the language a previous one declared. A fallback that is not a usable tag
+ * counts as absent. No-op without a target.
  */
-export function stampContentLanguage(target, env) {
+export function stampContentLanguage(target, env, fallback) {
     if (!target)
         return;
-    const attributes = contentLanguageAttributes(env);
+    const attributes = contentLanguageAttributes(env) ??
+        (fallback === UNDECLARED_CONTENT_LANGUAGE
+            ? { lang: "", dir: "auto" }
+            : contentLanguageAttributes({ locale: fallback }));
     if (attributes) {
         target.setAttribute("lang", attributes.lang);
         target.setAttribute("dir", attributes.dir);
@@ -49,3 +85,45 @@ export function stampContentLanguage(target, env) {
         target.removeAttribute("dir");
     }
 }
+/** Scripts written right to left, for {@link firstStrongDirection}. */
+const RTL_LETTER = /[\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}\p{Script=Adlam}\p{Script=Hanifi_Rohingya}\p{Script=Mandaic}\p{Script=Samaritan}]/u;
+const LETTER = /\p{L}/u;
+/**
+ * The direction of the first letter in `root`'s text, skipping `script`,
+ * `style` and `template`, or `null` when it has none. Letters only, which is
+ * where the bidi algorithm's strong characters overwhelmingly sit.
+ */
+export function firstStrongDirection(root) {
+    const doc = root.ownerDocument ?? root;
+    const walker = doc.createTreeWalker(root, 4 /* NodeFilter.SHOW_TEXT */, {
+        acceptNode: (node) => node.parentElement?.closest("script, style, template")
+            ? 2 /* NodeFilter.FILTER_REJECT */
+            : 1 /* NodeFilter.FILTER_ACCEPT */,
+    });
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        for (const char of node.nodeValue ?? "") {
+            if (RTL_LETTER.test(char))
+                return "rtl";
+            if (LETTER.test(char))
+                return "ltr";
+        }
+    }
+    return null;
+}
+/**
+ * The mismatch between undeclared content's script and the direction a
+ * fallback stamped on `root`, or `null` when there is none to report: the env
+ * declares a language, `root` carries no stamped direction or `dir="auto"`, or
+ * the content has no letters.
+ */
+export function undeclaredDirectionMismatch(root, env) {
+    if (contentLanguageAttributes(env))
+        return null;
+    const stamped = root.getAttribute("dir");
+    if (stamped !== "ltr" && stamped !== "rtl")
+        return null;
+    const script = firstStrongDirection(root);
+    if (!script)
+        return null;
+    return script === stamped ? null : { stamped, script };
+}

package/dist/i18n/index.d.ts

@@ -28,9 +28,10 @@ import type { I18nConfig, I18nServiceApi } from "./types.js";
  */
 export declare function createPieI18n(config?: I18nConfig): I18nServiceApi;
 export { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
-export { canonicalLanguageTag, findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+export { canonicalLanguageTag, findBestLanguageMatch, findClosestLanguageMatch, languageTagLookupSequence, languageTagScriptLookupSequence, languageTagsEqual, negotiateContentLanguage, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+export type { ContentLanguageMatch } from "./language-tags.js";
 export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, stampInterfaceLocale, } from "./provider.js";
-export { type ContentLanguageAttributes, contentLanguageAttributes, stampContentLanguage, } from "./content-language.js";
+export { type ContentLanguageAttributes, contentLanguageAttributes, defaultContentLanguage, firstStrongDirection, stampContentLanguage, UNDECLARED_CONTENT_LANGUAGE, undeclaredDirectionMismatch, } from "./content-language.js";
 export { type InterfaceLocaleLoadErrorModel, reportInterfaceLocaleLoadError, } from "./locale-load-error.js";
 export { PSEUDO_LOCALE_EXPANDED, PSEUDO_LOCALE_RTL, pseudoLocalize, } from "./pseudo.js";
 export type { PseudoLocalizeOptions } from "./pseudo.js";

package/dist/i18n/index.js

@@ -35,8 +35,8 @@ export function createPieI18n(config = {}) {
     });
 }
 export { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
-export { canonicalLanguageTag, findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+export { canonicalLanguageTag, findBestLanguageMatch, findClosestLanguageMatch, languageTagLookupSequence, languageTagScriptLookupSequence, languageTagsEqual, negotiateContentLanguage, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
 export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, stampInterfaceLocale, } from "./provider.js";
-export { contentLanguageAttributes, stampContentLanguage, } from "./content-language.js";
+export { contentLanguageAttributes, defaultContentLanguage, firstStrongDirection, stampContentLanguage, UNDECLARED_CONTENT_LANGUAGE, undeclaredDirectionMismatch, } from "./content-language.js";
 export { reportInterfaceLocaleLoadError, } from "./locale-load-error.js";
 export { PSEUDO_LOCALE_EXPANDED, PSEUDO_LOCALE_RTL, pseudoLocalize, } from "./pseudo.js";

package/dist/i18n/language-tags.d.ts

@@ -51,12 +51,81 @@ export declare function languageTagsEqual(a: string | null | undefined, b: strin
  */
 export declare function languageTagLookupSequence(tag: string | null | undefined): string[];
 /**
- * Best available tag for a request, by RFC 4647 lookup, or `undefined` when
- * nothing matches. Ranking is by the request's specificity rather than the
- * candidates' order, so `es-MX` prefers an `es-MX` candidate over an `es` one
- * however they were authored.
+ * The script a tag is written in, lowercased: explicit (`sr-Latn`), or the
+ * CLDR likely script (`zh-TW` maximizes to Hant, `sr` to Cyrl). `undefined`
+ * when the tag has no script data or the runtime has no `Intl.Locale`.
+ */
+export declare function languageTagScript(tag: string | null | undefined): string | undefined;
+/**
+ * Whether a catalog reached by widening serves a request in the same script.
+ * A tag without script data passes, so a runtime without `Intl.Locale`
+ * resolves as plain RFC 4647 lookup.
+ */
+export declare function languageTagScriptsMatch(requested: string | null | undefined, candidate: string | null | undefined): boolean;
+/**
+ * The script-aware lookup sequence: the RFC 4647 sequence with the language
+ * and likely script inserted before the bare language, so `zh-TW` yields
+ * `["zh-tw", "zh-hant", "zh"]`. A bare-language step serves the request only
+ * in the same script, which `findBestLanguageMatch` checks.
+ */
+export declare function languageTagScriptLookupSequence(tag: string | null | undefined): string[];
+/**
+ * Best available tag for a request, or `undefined` when nothing matches.
+ * Ranking is by the request's specificity rather than the candidates' order,
+ * so `es-MX` prefers an `es-MX` candidate over an `es` one however they were
+ * authored, and `zh-TW` reaches `zh-Hant`. A catalog shorter than the request
+ * serves it only in the same script: a bare `zh` catalog is Simplified, so
+ * `zh-TW` passes it by.
  */
 export declare function findBestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
+/**
+ * A tag without its variant, extension and private-use subtags, casing kept:
+ * `en-GB-x-gulf` yields `en-GB`. The form for a speech engine, whose voices
+ * are keyed by language and region.
+ */
+export declare function languageTagWithoutVariants(tag: string | null | undefined): string;
+/**
+ * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Widening stays
+ * within the request's script and keeps its variant subtags: `zh` never
+ * reaches `zh-TW`, `sr-Latn` may reach `sr-ME`, `en-GB` never reaches
+ * `en-GB-x-gulf`, and `en-US-x-gulf` may reach `en-GB-x-gulf`. Among several
+ * siblings the first in `available` wins. The rule that picks an interface
+ * catalog and a content variant alike.
+ */
+export declare function findClosestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
+/** The content language a backend serves, and whether it is a substitute. */
+export interface ContentLanguageMatch {
+    /** The `available` entry served, as authored; `null` for content that declares no language. */
+    language: string | null;
+    /**
+     * `"fallback"` when the served content stands in for the request;
+     * `"variety"` when it is another variety of the requested language.
+     */
+    substitution?: "fallback" | "variety";
+}
+/**
+ * The language to serve content in: the closest `available` match for the
+ * first `requested` tag that has one, under `findClosestLanguageMatch`, or with
+ * `matching: "exact"` only an equal tag, so `es-MX` then passes an `es`
+ * variant by. With no match and `fallback` other than `"none"`, the fallback
+ * chain serves the closest match for `defaultLanguage` (`en-US` reaches `en`),
+ * then content that declares no language (a `null` entry), then `source`;
+ * `matching` does not narrow it. `undefined` means nothing can be served. No
+ * requested languages run the chain without a substitution. A closest match
+ * in another variety, `es-MX` served `es-ES`, records `"variety"`; a host
+ * that must not serve one sets `matching: "exact"` and lists the varieties it
+ * accepts. Candidates rank
+ * `source` first, then by tag, so the order of `available` never decides
+ * between two siblings.
+ */
+export declare function negotiateContentLanguage(requested: readonly string[], available: readonly (string | null)[], options?: {
+    defaultLanguage?: string;
+    fallback?: "default" | "none";
+    matching?: "closest" | "exact";
+    /** The family source's `available` entry. */
+    source?: string | null;
+}): ContentLanguageMatch | undefined;
 /**
  * The canonical form of a usable language tag, or `undefined` for anything a
  * language in use would not be: `es_MX` normalizes to `es-MX`, `NL-nl` to

package/dist/i18n/language-tags.js

@@ -78,20 +78,190 @@ export function languageTagLookupSequence(tag) {
     }
     return sequence;
 }
+/** `maximize()` runs on every resolution, for each candidate catalog. */
+const scripts = new Map();
 /**
- * Best available tag for a request, by RFC 4647 lookup, or `undefined` when
- * nothing matches. Ranking is by the request's specificity rather than the
- * candidates' order, so `es-MX` prefers an `es-MX` candidate over an `es` one
- * however they were authored.
+ * The script a tag is written in, lowercased: explicit (`sr-Latn`), or the
+ * CLDR likely script (`zh-TW` maximizes to Hant, `sr` to Cyrl). `undefined`
+ * when the tag has no script data or the runtime has no `Intl.Locale`.
+ */
+export function languageTagScript(tag) {
+    const normalized = normalizeLanguageTag(tag);
+    if (!normalized ||
+        typeof Intl === "undefined" ||
+        typeof Intl.Locale !== "function") {
+        return undefined;
+    }
+    if (scripts.has(normalized))
+        return scripts.get(normalized);
+    let script;
+    try {
+        script = new Intl.Locale(normalized).maximize().script?.toLowerCase();
+    }
+    catch {
+        // Not a tag `Intl.Locale` parses: no script data.
+    }
+    scripts.set(normalized, script);
+    return script;
+}
+/**
+ * Whether a catalog reached by widening serves a request in the same script.
+ * A tag without script data passes, so a runtime without `Intl.Locale`
+ * resolves as plain RFC 4647 lookup.
+ */
+export function languageTagScriptsMatch(requested, candidate) {
+    const requestedScript = languageTagScript(requested);
+    const candidateScript = languageTagScript(candidate);
+    return (!requestedScript || !candidateScript || requestedScript === candidateScript);
+}
+/**
+ * The script-aware lookup sequence: the RFC 4647 sequence with the language
+ * and likely script inserted before the bare language, so `zh-TW` yields
+ * `["zh-tw", "zh-hant", "zh"]`. A bare-language step serves the request only
+ * in the same script, which `findBestLanguageMatch` checks.
+ */
+export function languageTagScriptLookupSequence(tag) {
+    const sequence = languageTagLookupSequence(tag);
+    const script = languageTagScript(tag);
+    if (!script || sequence.length < 2)
+        return sequence;
+    const language = sequence[sequence.length - 1];
+    const withScript = `${language}-${script}`;
+    if (sequence.includes(withScript))
+        return sequence;
+    return [...sequence.slice(0, -1), withScript, language];
+}
+/**
+ * Best available tag for a request, or `undefined` when nothing matches.
+ * Ranking is by the request's specificity rather than the candidates' order,
+ * so `es-MX` prefers an `es-MX` candidate over an `es` one however they were
+ * authored, and `zh-TW` reaches `zh-Hant`. A catalog shorter than the request
+ * serves it only in the same script: a bare `zh` catalog is Simplified, so
+ * `zh-TW` passes it by.
  */
 export function findBestLanguageMatch(requested, available) {
-    for (const step of languageTagLookupSequence(requested)) {
-        const hit = available.find((candidate) => normalizeLanguageTag(candidate) === step);
+    const exact = normalizeLanguageTag(requested);
+    for (const step of languageTagScriptLookupSequence(requested)) {
+        const hit = available.find((candidate) => normalizeLanguageTag(candidate) === step &&
+            (step === exact || languageTagScriptsMatch(requested, candidate)));
         if (hit != null)
             return hit;
     }
     return undefined;
 }
+/**
+ * A tag's subtags split at the end of its language, script and region:
+ * `en-GB-x-gulf` yields `[["en", "GB"], ["x", "gulf"]]`. The second part holds
+ * variants, extensions and private use, as authored.
+ */
+function splitVariantSubtags(tag) {
+    const subtags = toLanguageTag(tag).split(/[.@]/)[0].split("-");
+    let length = 1;
+    if (/^[a-z]{4}$/i.test(subtags[length] ?? ""))
+        length++;
+    if (/^([a-z]{2}|\d{3})$/i.test(subtags[length] ?? ""))
+        length++;
+    return [subtags.slice(0, length), subtags.slice(length)];
+}
+/** The variant, extension and private-use subtags as a comparison key. */
+function variantSubtagsKey(tag) {
+    return splitVariantSubtags(tag)[1].join("-").toLowerCase();
+}
+/**
+ * Whether `served` is another variety of `requested`: it names a different
+ * region, or different variant or private-use subtags. `es-MX` served `es-ES`
+ * or `en-GB-x-gulf` served `en-GB` is; `es-MX` served `es`, or `zh-TW` served
+ * `zh-Hant`, is not.
+ */
+function isOtherLanguageVariety(requested, served) {
+    const region = (tag) => {
+        const [base] = splitVariantSubtags(tag);
+        const last = base.length > 1 ? base[base.length - 1] : "";
+        return /^([a-z]{2}|\d{3})$/i.test(last) ? last.toLowerCase() : undefined;
+    };
+    const requestedRegion = region(requested);
+    const servedRegion = region(served);
+    return ((requestedRegion !== undefined &&
+        servedRegion !== undefined &&
+        requestedRegion !== servedRegion) ||
+        variantSubtagsKey(requested) !== variantSubtagsKey(served));
+}
+/**
+ * A tag without its variant, extension and private-use subtags, casing kept:
+ * `en-GB-x-gulf` yields `en-GB`. The form for a speech engine, whose voices
+ * are keyed by language and region.
+ */
+export function languageTagWithoutVariants(tag) {
+    return splitVariantSubtags(tag)[0].join("-");
+}
+/**
+ * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Widening stays
+ * within the request's script and keeps its variant subtags: `zh` never
+ * reaches `zh-TW`, `sr-Latn` may reach `sr-ME`, `en-GB` never reaches
+ * `en-GB-x-gulf`, and `en-US-x-gulf` may reach `en-GB-x-gulf`. Among several
+ * siblings the first in `available` wins. The rule that picks an interface
+ * catalog and a content variant alike.
+ */
+export function findClosestLanguageMatch(requested, available) {
+    const best = findBestLanguageMatch(requested, available);
+    if (best !== undefined)
+        return best;
+    const language = normalizeLanguageTag(requested).split("-")[0];
+    if (!language)
+        return undefined;
+    const variants = variantSubtagsKey(requested);
+    const sibling = available.find((candidate) => normalizeLanguageTag(candidate).split("-")[0] === language &&
+        variantSubtagsKey(candidate) === variants &&
+        languageTagScriptsMatch(requested, candidate));
+    return sibling ?? undefined;
+}
+/**
+ * The language to serve content in: the closest `available` match for the
+ * first `requested` tag that has one, under `findClosestLanguageMatch`, or with
+ * `matching: "exact"` only an equal tag, so `es-MX` then passes an `es`
+ * variant by. With no match and `fallback` other than `"none"`, the fallback
+ * chain serves the closest match for `defaultLanguage` (`en-US` reaches `en`),
+ * then content that declares no language (a `null` entry), then `source`;
+ * `matching` does not narrow it. `undefined` means nothing can be served. No
+ * requested languages run the chain without a substitution. A closest match
+ * in another variety, `es-MX` served `es-ES`, records `"variety"`; a host
+ * that must not serve one sets `matching: "exact"` and lists the varieties it
+ * accepts. Candidates rank
+ * `source` first, then by tag, so the order of `available` never decides
+ * between two siblings.
+ */
+export function negotiateContentLanguage(requested, available, options = {}) {
+    const { defaultLanguage, fallback = "default", matching = "closest", source } = options;
+    const candidates = [...available].sort((a, b) => {
+        if ((a === source) !== (b === source))
+            return a === source ? -1 : 1;
+        const left = normalizeLanguageTag(a);
+        const right = normalizeLanguageTag(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+    for (const tag of requested) {
+        const language = matching === "exact"
+            ? candidates.find((candidate) => languageTagsEqual(candidate, tag))
+            : findClosestLanguageMatch(tag, candidates);
+        if (language != null) {
+            return isOtherLanguageVariety(tag, language)
+                ? { language, substitution: "variety" }
+                : { language };
+        }
+    }
+    if (requested.length > 0 && fallback === "none")
+        return undefined;
+    let language = findClosestLanguageMatch(defaultLanguage, candidates);
+    if (language === undefined && available.includes(null))
+        language = null;
+    if (language === undefined && source !== undefined && available.includes(source)) {
+        language = source;
+    }
+    if (language === undefined)
+        return undefined;
+    return requested.length > 0 ? { language, substitution: "fallback" } : { language };
+}
 /**
  * The canonical form of a usable language tag, or `undefined` for anything a
  * language in use would not be: `es_MX` normalizes to `es-MX`, `NL-nl` to