@pie-players/pie-players-shared 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/i18n/provider.js

@@ -9,7 +9,7 @@
  *
  * @module @pie-players/pie-players-shared/i18n/provider
  */
-import { findBestLanguageMatch, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+import { canonicalLanguageTag, findClosestLanguageMatch, languageTagLookupSequence, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
 import enUS from "./messages/en-US.js";
 /** The locale every fallback chain terminates at. */
 export const DEFAULT_LOCALE = "en-US";
@@ -57,6 +57,10 @@ const PLURAL_CATEGORIES = new Set([
     "many",
     "other",
 ]);
+/** A request's tag in canonical form, or its hyphenated spelling where it is not a tag. */
+function requestTag(locale) {
+    return canonicalLanguageTag(locale) ?? toLanguageTag(locale);
+}
 function isPluralGroup(node) {
     if (typeof node !== "object" || node === null)
         return false;
@@ -108,21 +112,35 @@ export function detectBrowserLocale() {
 export class SimpleI18n {
     /** Shared across instances and views: `Intl.PluralRules` is not cheap. */
     static pluralRules = new Map();
-    locale;
+    /** The latest request, canonical; what `getRequestedLocale` names. */
+    requested;
+    /** The request whose strings are served; moves once its catalog is resident. */
+    active;
+    /** The catalog serving `active`, resolved against catalogs alone. */
+    activeCatalog;
     fallbackLocale;
     /** Shared by reference with every `withLocale` view. */
     catalogs;
+    /** Keyed by normalized tag, so `ES`, `es_ES` and `es-es` reach one set. */
     customMessages;
     loading;
+    /** Counts `setLocale` calls, so a slow load cannot overwrite a later request. */
+    requests = 0;
     listeners = new Set();
     config;
     constructor(config = {}) {
         this.config = { ...config };
-        this.fallbackLocale = toLanguageTag(config.fallbackLocale) || DEFAULT_LOCALE;
+        this.fallbackLocale =
+            toLanguageTag(config.fallbackLocale) || DEFAULT_LOCALE;
         this.catalogs = new Map([[DEFAULT_LOCALE, enUS]]);
-        this.customMessages = { ...(config.customMessages ?? {}) };
+        this.customMessages = {};
+        for (const [locale, messages] of Object.entries(config.customMessages ?? {})) {
+            this.mergeCustomMessages(locale, messages);
+        }
         this.loading = new Map();
-        this.locale = this.resolveLocaleTag(config.locale) ?? DEFAULT_LOCALE;
+        this.requested = requestTag(config.locale) || DEFAULT_LOCALE;
+        this.active = this.requested;
+        this.activeCatalog = this.resolveCatalogLocale(this.active);
     }
     /**
      * Set the locale, loading its catalog first.
@@ -138,10 +156,32 @@ export class SimpleI18n {
                 this.addCustomMessages(locale, messages);
             }
         }
-        await this.setLocale(config.locale ?? this.locale);
+        await this.setLocale(config.locale ?? this.requested);
     }
+    /**
+     * The locale the strings are served in: the resolved catalog locale once
+     * resident, else the most specific host-message tag on the request's
+     * truncation chain, canonical, else the fallback. A request nothing serves
+     * names the fallback, so a chrome root stamped from it never names a
+     * language its text is not in.
+     */
     getLocale() {
-        return this.locale;
+        if (this.activeCatalog && this.catalogs.has(this.activeCatalog)) {
+            return this.activeCatalog;
+        }
+        const host = this.hostMessageLocale(this.active);
+        return host === undefined
+            ? this.fallbackLocale
+            : (canonicalLanguageTag(host) ?? host);
+    }
+    /**
+     * The latest `setLocale` request (or the configured `locale`), canonical, as
+     * soon as it is made and whatever its load does. `getLocale` names what is
+     * served instead, so the two differ while a catalog loads, after a load
+     * fails, and for a tag nothing ships.
+     */
+    getRequestedLocale() {
+        return this.requested;
     }
     /**
      * Switch locale.
@@ -149,68 +189,77 @@ export class SimpleI18n {
      * Resolves the request against the catalogs this provider can serve, loads
      * the winner if it is not resident, then notifies subscribers — in that
      * order, so a component's reactive read re-runs against a catalog that is
-     * already in place rather than against the previous locale.
+     * already in place rather than against the previous locale. The last call
+     * wins: a call whose load finishes after a later call's leaves the locale
+     * to that later call.
      */
     async setLocale(locale) {
-        const resolved = this.resolveLocaleTag(locale);
-        if (!resolved) {
-            // A locale we ship no catalog for is legitimate: the host may have
-            // supplied its own messages for it. Honour the tag and let the
-            // fallback chain cover whatever those messages omit.
-            this.locale = toLanguageTag(locale) || DEFAULT_LOCALE;
-            this.notify();
-            return;
-        }
-        // The loader is asked only for tags it declares. A tag that resolved through
-        // host messages alone has nothing to load, and is honoured like the
-        // unresolved case above.
-        if (!this.catalogs.has(resolved) &&
-            this.config.availableLocales?.includes(resolved)) {
-            const inFlight = this.loading.get(resolved);
-            if (inFlight) {
-                await inFlight;
-            }
-            else {
-                const load = this.loadCatalog(resolved);
-                this.loading.set(resolved, load);
-                try {
-                    await load;
-                }
-                finally {
-                    this.loading.delete(resolved);
+        const request = ++this.requests;
+        const tag = requestTag(locale) || DEFAULT_LOCALE;
+        this.requested = tag;
+        // A tag no catalog serves is legitimate: the host may have supplied its own
+        // messages for it, and the fallback chain covers whatever those omit.
+        const catalog = this.resolveCatalogLocale(tag);
+        // The loader is asked only for tags it declares.
+        if (catalog &&
+            !this.catalogs.has(catalog) &&
+            this.config.availableLocales?.includes(catalog)) {
+            try {
+                let load = this.loading.get(catalog);
+                if (!load) {
+                    load = this.loadCatalog(catalog).finally(() => {
+                        this.loading.delete(catalog);
+                    });
+                    this.loading.set(catalog, load);
                 }
+                await load;
+            }
+            catch (error) {
+                // A superseded request stays silent: the later one reports its own
+                // outcome. The current one notifies, since `getRequestedLocale` moved
+                // although the served strings did not, and rejects.
+                if (request !== this.requests)
+                    return;
+                this.notify();
+                throw error;
             }
         }
-        this.locale = resolved;
+        if (request !== this.requests)
+            return;
+        this.active = tag;
+        this.activeCatalog = catalog;
         this.notify();
     }
     t(key, values) {
-        const message = this.lookup(key);
+        const message = this.resolveMessage(key);
         if (message === undefined) {
-            this.config.onMissingKey?.(key, this.locale);
+            this.config.onMissingKey?.(key, this.getLocale());
             return key;
         }
-        return interpolate(message, values);
+        return interpolate(message, values, this.getLocale());
     }
     /**
      * Translate a plural group.
      *
      * The category comes from `Intl.PluralRules` for the active locale, so a
      * locale with more than two forms resolves correctly: Arabic selects among
-     * zero/one/two/few/many/other, Polish among one/few/many/other. A category the
-     * catalog does not carry resolves to `other`.
+     * zero/one/two/few/many/other, Polish among one/few/many/other.
+     *
+     * Each form resolves on its own, tier by tier (`resolveMessage`): a host
+     * overriding one category leaves the others to the catalog, and a locale's
+     * own `other` wins over the fallback's `one`. A group no source completes is
+     * a miss and returns the key.
      */
     plural(key, options) {
-        const group = this.lookupNode(key);
-        if (group === undefined || !isPluralGroup(group)) {
-            return this.t(key, options);
+        const message = this.resolveMessage(key, this.selectPluralCategory(options.count));
+        if (message === undefined) {
+            this.config.onMissingKey?.(key, this.getLocale());
+            return key;
         }
-        const category = this.selectPluralCategory(options.count);
-        const form = group[category] ?? group.other;
-        return interpolate(form, options);
+        return interpolate(message, options, this.getLocale());
     }
     getDirection() {
-        return localeDirection(this.locale);
+        return localeDirection(this.getLocale());
     }
     /**
      * Locales this provider can serve: resident catalogs, whatever the loader
@@ -220,12 +269,12 @@ export class SimpleI18n {
         const tags = new Set([
             ...this.catalogs.keys(),
             ...(this.config.availableLocales ?? []),
-            ...Object.keys(this.customMessages),
+            ...Object.keys(this.customMessages).map((tag) => canonicalLanguageTag(tag) ?? tag),
         ]);
         return [...tags];
     }
     isLocaleLoaded(locale) {
-        const resolved = this.resolveLocaleTag(locale);
+        const resolved = this.resolveCatalogLocale(requestTag(locale));
         return resolved !== undefined && this.catalogs.has(resolved);
     }
     subscribe(listener) {
@@ -235,19 +284,25 @@ export class SimpleI18n {
         };
     }
     hasKey(key) {
-        return this.lookup(key) !== undefined;
+        return this.resolveMessage(key) !== undefined;
     }
     /**
      * Add or override messages for one locale.
      *
      * Deep-merged, so a deployment can override a single label without restating
-     * a catalog.
+     * a catalog, and keyed by normalized tag, so `es-mx` and `es-MX` are one
+     * locale's messages.
      */
     addCustomMessages(locale, messages) {
-        const tag = toLanguageTag(locale);
-        this.customMessages[tag] = deepMerge(this.customMessages[tag] ?? {}, messages);
+        this.mergeCustomMessages(locale, messages);
         this.notify();
     }
+    mergeCustomMessages(locale, messages) {
+        const tag = normalizeLanguageTag(locale);
+        if (!tag)
+            return;
+        this.customMessages[tag] = deepMerge(this.customMessages[tag] ?? {}, messages);
+    }
     /**
      * A view of this provider fixed to another locale.
      *
@@ -257,19 +312,21 @@ export class SimpleI18n {
      * locales: the locale is per-view, the catalogs are per-provider.
      */
     withLocale(locale) {
-        const resolved = this.resolveLocaleTag(locale) ?? toLanguageTag(locale);
-        if (resolved === this.locale)
+        const tag = requestTag(locale) || DEFAULT_LOCALE;
+        if (tag === this.active && tag === this.requested)
             return this;
-        const view = new SimpleI18n({ ...this.config, locale: resolved });
-        view.locale = resolved || DEFAULT_LOCALE;
+        const view = new SimpleI18n({ ...this.config, customMessages: {} });
         view.catalogs = this.catalogs;
         view.customMessages = this.customMessages;
         view.loading = this.loading;
+        view.requested = tag;
+        view.active = tag;
+        view.activeCatalog = view.resolveCatalogLocale(tag);
         return view;
     }
     formatNumber(value, options) {
         try {
-            return new Intl.NumberFormat(this.locale, options).format(value);
+            return new Intl.NumberFormat(this.getLocale(), options).format(value);
         }
         catch {
             return new Intl.NumberFormat(DEFAULT_LOCALE, options).format(value);
@@ -277,15 +334,15 @@ export class SimpleI18n {
     }
     formatDate(date, options) {
         try {
-            return new Intl.DateTimeFormat(this.locale, options).format(date);
+            return new Intl.DateTimeFormat(this.getLocale(), options).format(date);
         }
         catch {
             return new Intl.DateTimeFormat(DEFAULT_LOCALE, options).format(date);
         }
     }
     /** The resolved catalog for a locale, for a host that wants to inspect it. */
-    getBundle(locale = this.locale) {
-        const tag = this.resolveLocaleTag(locale);
+    getBundle(locale = this.getLocale()) {
+        const tag = this.resolveCatalogLocale(requestTag(locale));
         if (!tag)
             return undefined;
         const translations = this.catalogs.get(tag);
@@ -294,24 +351,22 @@ export class SimpleI18n {
         return { locale: tag, translations, direction: localeDirection(tag) };
     }
     /**
-     * Which shipped catalog serves a requested tag.
-     *
-     * RFC 4647 lookup first, so `nl-BE` reaches `nl-NL` through `nl`; then
-     * primary-subtag widening, so a bare `nl` reaches the regional `nl-NL`
-     * catalog we actually ship. POSIX `nl_NL` normalizes on the way in, which is
-     * the form the Learnosity transform emits.
+     * Which catalog serves a requested tag, under `findClosestLanguageMatch`
+     * over the resident catalogs and the loader's declared tags. Host messages
+     * take no part: they resolve separately (`hostMessageLocale`), so a host
+     * override for `es-MX` cannot hide a shipped `es`.
      */
-    resolveLocaleTag(locale) {
-        if (!locale)
-            return undefined;
-        const available = this.getAvailableLocales();
-        const exactOrPrefix = findBestLanguageMatch(locale, available);
-        if (exactOrPrefix)
-            return exactOrPrefix;
-        const requestedLanguage = normalizeLanguageTag(locale).split("-")[0];
-        if (!requestedLanguage)
+    resolveCatalogLocale(tag) {
+        if (!tag)
             return undefined;
-        return available.find((candidate) => normalizeLanguageTag(candidate).split("-")[0] === requestedLanguage);
+        return findClosestLanguageMatch(tag, [
+            ...this.catalogs.keys(),
+            ...(this.config.availableLocales ?? []),
+        ]);
+    }
+    /** The most specific host-message tag on a request's truncation chain, normalized. */
+    hostMessageLocale(tag) {
+        return languageTagLookupSequence(tag).find((step) => this.customMessages[step] !== undefined);
     }
     async loadCatalog(locale) {
         const load = this.config.loadCatalog;
@@ -322,52 +377,74 @@ export class SimpleI18n {
         }
         catch (error) {
             // Rethrown with the locale named: `setLocale` rejects before switching
-            // (it assigns `this.locale` only after the load), so the previous locale
-            // stays active.
+            // (it moves the served state only after the load), so the previous
+            // locale stays active.
             throw new Error(`Failed to load i18n catalog for locale: ${locale}`, {
                 cause: error,
             });
         }
     }
     /**
-     * Resolution order for one key. Host overrides for the active locale win, so
-     * a deployment can rename one label without forking a catalog.
+     * Two tiers in lookup order: host messages along the active request's
+     * truncation chain (`es-MX`, then `es`) and the active catalog, then host
+     * messages and the catalog for the fallback locale. Host overrides win, so a
+     * deployment can rename one label without forking a catalog.
      */
-    lookupNode(key) {
-        const sources = [
-            this.customMessages[this.locale],
-            this.catalogs.get(this.locale),
-            this.customMessages[this.fallbackLocale],
-            this.catalogs.get(this.fallbackLocale),
+    sourceTiers() {
+        return [
+            [
+                ...languageTagLookupSequence(this.active).map((step) => this.customMessages[step]),
+                this.activeCatalog ? this.catalogs.get(this.activeCatalog) : undefined,
+            ],
+            [
+                this.customMessages[normalizeLanguageTag(this.fallbackLocale)],
+                this.catalogs.get(this.fallbackLocale),
+            ],
         ];
-        for (const source of sources) {
-            const hit = readPath(source, key);
-            if (hit !== undefined)
-                return hit;
-        }
-        return undefined;
     }
-    lookup(key) {
-        const node = this.lookupNode(key);
-        if (typeof node === "string")
-            return node;
-        // A plural group resolves to its `other` form. A namespace (`t("common")`)
-        // is a miss: returning the object would put one where the caller expects
-        // a string, and interpolating it throws.
-        if (node !== undefined && isPluralGroup(node))
-            return node.other;
+    /**
+     * The text for `key`. The first source that has it decides its shape: a
+     * string is the text, and a plural group resolves `category`, else `other`,
+     * within the first tier that has a group, so a locale's own `other` wins
+     * over the fallback's `one`. A namespace (`t("common")`) is a miss:
+     * returning the object would put one where the caller expects a string.
+     */
+    resolveMessage(key, category) {
+        const tiers = [];
+        for (const tier of this.sourceTiers()) {
+            const groups = [];
+            for (const source of tier) {
+                const node = readPath(source, key);
+                if (typeof node === "string") {
+                    if (tiers.every((t) => t.length === 0) && groups.length === 0) {
+                        return node;
+                    }
+                }
+                else if (node !== undefined && isPluralGroup(node)) {
+                    groups.push(node);
+                }
+            }
+            tiers.push(groups);
+        }
+        for (const groups of tiers) {
+            const form = (name) => groups.find((group) => typeof group[name] === "string")?.[name];
+            const text = (category === undefined ? undefined : form(category)) ?? form("other");
+            if (text !== undefined)
+                return text;
+        }
         return undefined;
     }
     selectPluralCategory(count) {
-        let rules = SimpleI18n.pluralRules.get(this.locale);
+        const locale = this.getLocale();
+        let rules = SimpleI18n.pluralRules.get(locale);
         if (!rules) {
             try {
-                rules = new Intl.PluralRules(this.locale);
+                rules = new Intl.PluralRules(locale);
             }
             catch {
                 return count === 1 ? "one" : "other";
             }
-            SimpleI18n.pluralRules.set(this.locale, rules);
+            SimpleI18n.pluralRules.set(locale, rules);
         }
         return rules.select(count);
     }
@@ -389,12 +466,41 @@ function readPath(source, key) {
     }
     return current;
 }
-function interpolate(text, values) {
+/**
+ * Substitute `{name}` placeholders.
+ *
+ * A finite numeric value renders through `Intl.NumberFormat` for the active
+ * locale, so digits and grouping follow CLDR locale defaults: `ar` renders
+ * Arabic-Indic digits, `fr` groups with narrow no-break spaces, `en-US` with
+ * commas. Catalog text that spells digits out is untouched.
+ */
+const numberFormats = new Map();
+function formatNumber(value, locale) {
+    let formatter = numberFormats.get(locale);
+    if (!formatter) {
+        try {
+            formatter = new Intl.NumberFormat(locale);
+        }
+        catch {
+            formatter = new Intl.NumberFormat(DEFAULT_LOCALE);
+        }
+        numberFormats.set(locale, formatter);
+    }
+    return formatter.format(value);
+}
+function interpolate(text, values, locale) {
     if (!values)
         return text;
     return text.replace(/\{(\w+)\}/g, (match, name) => {
         const value = values[name];
-        return value === undefined || value === null ? match : String(value);
+        if (value === undefined || value === null)
+            return match;
+        if (locale !== undefined &&
+            typeof value === "number" &&
+            Number.isFinite(value)) {
+            return formatNumber(value, locale);
+        }
+        return String(value);
     });
 }
 function deepMerge(target, source) {
@@ -421,48 +527,124 @@ let defaultProvider;
  * present, and this is that state. A tool mounted bare — in `print-player` or
  * an authoring harness — resolves this and renders English rather than
  * leaking raw message keys onto the screen. It carries no locale loader, so it
- * pulls no catalog beyond the 5 KB English one already in the bundle.
+ * pulls no catalog beyond the English one already in the bundle.
  */
 export function getDefaultI18n() {
     if (!defaultProvider)
         defaultProvider = new SimpleI18n();
     return defaultProvider;
 }
-/**
- * Resolve a component's interface-locale provider from a published context.
- *
- * Returns a **fresh** object on every call. A
- * provider is mutable: `setLocale` swaps its catalog in place, so its identity is
- * unchanged before and after a locale load. A reactive `$derived` reading the
- * provider directly therefore never invalidates, and a label rendered while the
- * catalog was still loading stays English forever — the exact silent failure
- * `composition-context.md` records for a context published without a change
- * signal, and it is silent here too because English is a plausible answer.
- *
- * Deriving this instead gives the component a value whose identity tracks the
- * context republish, so the strings built from it re-render. Call it inside
- * `$derived`, never once at setup:
- *
- * ```ts
- * const interfaceI18n = $derived(resolveInterfaceI18n(runtimeContext));
- * ```
- *
- * A context with no provider — no publisher at all — resolves to the English-only
- * default rather than nothing, which is the graceful default the pull pattern
- * requires.
- */
 export function resolveInterfaceI18n(source) {
     const provider = source?.i18n ?? getDefaultI18n();
     // A thin facade rather than the provider itself: cheap to allocate (a handful
     // of times per session, once per republish) and it carries no state of its own,
-    // so it cannot drift from the provider it delegates to.
+    // so it cannot drift from the provider it delegates to. The locale formatters
+    // are part of the promised surface, so a provider that does not implement
+    // them falls through to `Intl` at the locale the provider resolves — the same
+    // thing the bundled provider does, and the same graceful default every other
+    // optional member here applies.
     return {
-        getLocale: () => provider.getLocale(),
+        // Canonical, because components read this for `lang` attributes; the
+        // provider's own `getLocale()` keeps the tag as resolved for lookups.
+        getLocale: () => {
+            const locale = provider.getLocale();
+            return canonicalLanguageTag(locale) ?? locale;
+        },
+        getRequestedLocale: () => requestedLocaleOf(provider),
         setLocale: (locale) => provider.setLocale(locale),
         t: (key, values) => provider.t(key, values),
         plural: (key, options) => provider.plural?.(key, options) ?? provider.t(key, options),
         getDirection: () => provider.getDirection?.() ?? "ltr",
         hasKey: (key) => provider.hasKey?.(key) ?? false,
         subscribe: (listener) => provider.subscribe?.(listener) ?? (() => { }),
+        formatNumber: (value, options) => provider.formatNumber?.(value, options) ??
+            new Intl.NumberFormat(provider.getLocale(), options).format(value),
+        formatDate: (value, options) => provider.formatDate?.(value, options) ??
+            new Intl.DateTimeFormat(provider.getLocale(), options).format(value),
     };
 }
+/**
+ * Stamp the interface locale's `lang` and `dir` on a chrome element.
+ *
+ * The imperative form of the `lang={…} dir={…}` pair a template puts on its
+ * root, for the elements a template cannot reach: a shadow host whose chrome
+ * is slotted light DOM, a shell built with `document.createElement`, a vanilla
+ * element stamping itself. Call it from whatever already re-runs on a locale
+ * change and on a catalog load: `getLocale()` moves only once the requested
+ * catalog is resident, so a stamp taken at setup alone names the locale that
+ * rendered before the load.
+ */
+export function stampInterfaceLocale(target, provider) {
+    // `lang` takes the canonical form: a host's own provider may report a tag
+    // as the host spelled it, and `NL-nl` is a valid request but not a valid
+    // attribute value. Every `lang` this repository writes goes through the
+    // same rule, so chrome and content stamps match in shape.
+    const locale = provider.getLocale();
+    target.setAttribute("lang", canonicalLanguageTag(locale) ?? locale);
+    target.setAttribute("dir", provider.getDirection?.() ?? "ltr");
+}
+/** A provider's requested tag, canonical; `getLocale` for one that does not track requests. */
+function requestedLocaleOf(provider) {
+    const locale = provider.getRequestedLocale?.() ?? provider.getLocale();
+    return canonicalLanguageTag(locale) ?? locale;
+}
+/**
+ * Whether `provider` was already asked for `locale`. An element handed its
+ * owner's provider together with the owner's `locale` skips asking again, so a
+ * catalog that fails to load is fetched and reported once, by the owner, and
+ * not again by every row and player under it.
+ */
+export function isLocaleRequested(provider, locale) {
+    const requested = provider.getRequestedLocale?.();
+    if (!requested)
+        return false;
+    return ((canonicalLanguageTag(requested) ?? requested) ===
+        (canonicalLanguageTag(locale) ?? locale));
+}
+/**
+ * Whether a host chose a player's interface locale: it set the player's
+ * `locale`, or supplied a provider that was asked for a locale other than
+ * `en-US`.
+ *
+ * A player answers `interfaceLocaleContext` from the first time this holds,
+ * and never before it. An element left unanswered labels its chrome in the
+ * language its item declares, which is how an item declaring Spanish keeps
+ * Spanish labels under a host that sets no locale; a default `en-US` answer
+ * would override that declaration. A supplied provider asked for `en-US` is
+ * not a choice, because hosts supply one to add catalogs or messages; a host
+ * that wants `en-US` chrome over the item's language sets `locale="en-US"`.
+ * Once answering, a player keeps answering, so clearing `locale` republishes
+ * `en-US` to the elements that subscribed.
+ *
+ * The toolkit and the item player both decide through this rule. An item
+ * player a section mounts receives the toolkit's provider, so it answers only
+ * when the toolkit above it would. Callers re-evaluate it on the provider's
+ * change signal, since a supplied provider's locale moves without a property
+ * change.
+ */
+export function hostChoseInterfaceLocale(player) {
+    if (typeof player.locale === "string" && player.locale.trim() !== "") {
+        return true;
+    }
+    // The request, not the served locale: a provider asked for a tag nothing
+    // ships serves `en-US`, and the host still chose that tag.
+    if (!player.i18n)
+        return false;
+    return requestedLocaleOf(player.i18n) !== DEFAULT_LOCALE;
+}
+/**
+ * The tag a player answers `interfaceLocaleContext` with: its `locale`,
+ * canonical, from the moment it is set, else its provider's requested tag.
+ *
+ * The request rather than the players' own catalog match, because elements
+ * resolve the tag against their own catalogs: a host asking for `en-GB` or
+ * `fr-CA` reaches the elements' catalogs and host messages for that tag
+ * whatever the players ship, and neither a players' catalog still loading nor
+ * one that failed holds the elements on the previous locale.
+ */
+export function requestedInterfaceLocale(player) {
+    const locale = typeof player.locale === "string" ? player.locale.trim() : "";
+    if (locale)
+        return requestTag(locale);
+    return requestedLocaleOf(player.i18n);
+}

package/dist/i18n/pseudo.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pseudo-localization: a transform over the English catalog that keeps every key,
+ * plural category and `{placeholder}` intact while making each string accented,
+ * bracketed and padded roughly 40% longer.
+ *
+ * What it is for: the gates check parity, not rendered geometry. A pseudo-locale
+ * makes truncation, clipped labels, strings glued together in code and text that
+ * was never catalog text visible in any demo or e2e run, before a translator or a
+ * reviewer sees a real one. It is the industry's `qps-ploc` (Windows) and
+ * `en-XA`/`ar-XB` (Android) practice; PIE uses the Android tags, registered
+ * through `customMessages`, never shipped as catalogs.
+ */
+import type { MessageCatalog } from "./types.js";
+/** Expanded Latin pseudo-locale: text grows ~40% and carries accents and brackets. */
+export declare const PSEUDO_LOCALE_EXPANDED = "en-XA";
+/**
+ * Right-to-left pseudo-locale: the same transformed English under an `ar` primary
+ * subtag, so `localeDirection` resolves RTL and chrome lays out mirrored without a
+ * word of Arabic on screen.
+ */
+export declare const PSEUDO_LOCALE_RTL = "ar-XB";
+export interface PseudoLocalizeOptions {
+    /** Extra length as a fraction of the original, on top of what accents add. Default 0.4. */
+    expansion?: number;
+    /** Wrap every string in `[` and `]` so concatenated fragments stand out. Default true. */
+    brackets?: boolean;
+    /** Map Latin letters to accented look-alikes. Default true. */
+    accents?: boolean;
+}
+/**
+ * Produce the pseudo-localized twin of a catalog: same keys, same plural
+ * categories, same placeholder sets, longer accented bracketed strings.
+ */
+export declare function pseudoLocalize(catalog: MessageCatalog, options?: PseudoLocalizeOptions): MessageCatalog;