@pie-players/pie-players-shared 1.0.0-beta.5 → 1.0.0-beta.7

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,64 @@ 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;
+/**
+ * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Both stay within
+ * the request's script: `zh` never reaches `zh-TW`, and `sr-Latn` may reach
+ * `sr-ME`. 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. */
+    substitution?: "fallback";
+}
+/**
+ * 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.
+ */
+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,125 @@ 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;
 }
+/**
+ * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Both stay within
+ * the request's script: `zh` never reaches `zh-TW`, and `sr-Latn` may reach
+ * `sr-ME`. 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 sibling = available.find((candidate) => normalizeLanguageTag(candidate).split("-")[0] === language &&
+        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.
+ */
+export function negotiateContentLanguage(requested, available, options = {}) {
+    const { defaultLanguage, fallback = "default", matching = "closest", source } = options;
+    for (const tag of requested) {
+        const language = matching === "exact"
+            ? available.find((candidate) => languageTagsEqual(candidate, tag))
+            : findClosestLanguageMatch(tag, available);
+        if (language != null)
+            return { language };
+    }
+    if (requested.length > 0 && fallback === "none")
+        return undefined;
+    let language = findClosestLanguageMatch(defaultLanguage, available);
+    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

package/dist/i18n/messages/en-US.d.ts

@@ -431,6 +431,12 @@ declare const enUS: {
             description: string;
             buttonA11y: string;
             tooltip: string;
+            /** A choice's toggle; `{choice}` is the choice's own accessible name. */
+            toggleA11y: string;
+            /** Appended to an eliminated choice's label for assistive technology. */
+            eliminatedA11y: string;
+            /** Stands in for `{choice}` when a choice has no text of its own. */
+            unlabeledChoice: string;
         };
         highlighter: {
             name: string;

package/dist/i18n/messages/en-US.js

@@ -448,6 +448,12 @@ const enUS = {
             description: "Strike through answer choices",
             buttonA11y: "Strike Through, eliminate answer choices",
             tooltip: "Strike Through",
+            /** A choice's toggle; `{choice}` is the choice's own accessible name. */
+            toggleA11y: "Toggle elimination for {choice}",
+            /** Appended to an eliminated choice's label for assistive technology. */
+            eliminatedA11y: "(eliminated)",
+            /** Stands in for `{choice}` when a choice has no text of its own. */
+            unlabeledChoice: "Unlabeled choice",
         },
         highlighter: {
             name: "Highlighter",

package/dist/i18n/messages/nl-NL.d.ts

@@ -345,6 +345,9 @@ declare const nlNL: {
             description: string;
             buttonA11y: string;
             tooltip: string;
+            toggleA11y: string;
+            eliminatedA11y: string;
+            unlabeledChoice: string;
         };
         highlighter: {
             name: string;

package/dist/i18n/messages/nl-NL.js

@@ -345,6 +345,9 @@ const nlNL = {
             description: "Antwoordopties doorstrepen",
             buttonA11y: "Doorstrepen, antwoordopties wegstrepen",
             tooltip: "Doorstrepen",
+            toggleA11y: "Wegstrepen aan/uit voor {choice}",
+            eliminatedA11y: "(weggestreept)",
+            unlabeledChoice: "Keuze zonder label",
         },
         highlighter: {
             name: "Markeerstift",

package/dist/i18n/provider.d.ts

@@ -122,12 +122,9 @@ export declare class SimpleI18n implements I18nServiceApi {
     /** The resolved catalog for a locale, for a host that wants to inspect it. */
     getBundle(locale?: LocaleCode): TranslationBundle | undefined;
     /**
-     * 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 shipped catalog serves a requested tag, under
+     * `findClosestLanguageMatch`. POSIX `nl_NL` normalizes on the way in, which
+     * is the form the Learnosity transform emits.
      */
     private resolveLocaleTag;
     private loadCatalog;

package/dist/i18n/provider.js

@@ -9,7 +9,7 @@
  *
  * @module @pie-players/pie-players-shared/i18n/provider
  */
-import { canonicalLanguageTag, findBestLanguageMatch, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
+import { canonicalLanguageTag, findClosestLanguageMatch, 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";
@@ -302,24 +302,14 @@ 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 shipped catalog serves a requested tag, under
+     * `findClosestLanguageMatch`. POSIX `nl_NL` normalizes on the way in, which
+     * is the form the Learnosity transform emits.
      */
     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)
-            return undefined;
-        return available.find((candidate) => normalizeLanguageTag(candidate).split("-")[0] === requestedLanguage);
+        return findClosestLanguageMatch(locale, this.getAvailableLocales());
     }
     async loadCatalog(locale) {
         const load = this.config.loadCatalog;

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from "./ui/pointer-rotate.js";
 export * from "./ui/overlay-containment.js";
 export * from "./ui/overlay-placement.js";
 export * from "./ui/focus-trap.js";
+export * from "./ui/ime.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/safe-storage.js";
 export * from "./ui/scope-css.js";

package/dist/index.js

@@ -15,6 +15,7 @@ export * from "./ui/pointer-rotate.js";
 export * from "./ui/overlay-containment.js";
 export * from "./ui/overlay-placement.js";
 export * from "./ui/focus-trap.js";
+export * from "./ui/ime.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/safe-storage.js";
 export * from "./ui/scope-css.js";

package/dist/loaders/ElementLoader.d.ts

@@ -41,4 +41,4 @@ export type ElementMap = {
  * // }
  * ```
  */
-export declare function aggregateElements(items: ItemEntity[]): ElementMap;
+export declare function aggregateElements(items: ReadonlyArray<Pick<ItemEntity, "config">>): ElementMap;

package/dist/loaders/element-loader.d.ts

@@ -88,7 +88,10 @@ export type EnsureRegisteredOptions = {
  *
  * The primitive is the sole authority on registration state:
  * - Empty element map resolves immediately (no backend call).
- * - Already-registered tags resolve immediately (no backend call).
+ * - Already-registered tags resolve immediately (no backend call). A request
+ *   that loads other tags through an IIFE or ESM backend that loads controllers
+ *   also loads its registered tags with no controller, so their controllers
+ *   fill in.
  * - Concurrent identical requests share one backend call.
  * - After the adapter's `load` settles, a post-load verification pass
  *   (bounded `customElements.whenDefined`) checks every tag. Any missing

package/dist/loaders/element-loader.js

@@ -26,7 +26,7 @@ import { parsePackageName } from "../pie/utils.js";
 import { parseVersionedTagName } from "../pie/versioned-tag.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { clearPackageMetadataRequests, createEsmBackend, } from "./esm-adapter.js";
-import { createIifeBackend } from "./iife-adapter.js";
+import { createIifeBackend, findIifeElementMapConflict, } from "./iife-adapter.js";
 import { assertElementPackagesAllowed, } from "./element-package-policy.js";
 export { AdapterFailure } from "./element-loader-types.js";
 /**
@@ -125,9 +125,10 @@ function registeredPackageName(tag) {
 }
 const DEFAULT_WHEN_DEFINED_TIMEOUT_MS = 5000;
 const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
-// Module-scoped in-flight cache. Key: backend signature + sorted elements.
-// Keeps concurrent identical requests collapsed to one backend call.
+// Requests share a backend call by both the original map and the unresolved
+// subset, so incremental registration does not change an in-flight identity.
 const inFlightRequests = new Map();
+const inFlightKeysByPromise = new Map();
 // An ESM backend keeps page state that later loads build on (the import maps it
 // injected, the shared dependency versions they fixed), so every load with the
 // same config reuses one backend. IIFE backends are created per call.
@@ -139,7 +140,10 @@ const resolvedBackendOverrides = new Map();
  *
  * The primitive is the sole authority on registration state:
  * - Empty element map resolves immediately (no backend call).
- * - Already-registered tags resolve immediately (no backend call).
+ * - Already-registered tags resolve immediately (no backend call). A request
+ *   that loads other tags through an IIFE or ESM backend that loads controllers
+ *   also loads its registered tags with no controller, so their controllers
+ *   fill in.
  * - Concurrent identical requests share one backend call.
  * - After the adapter's `load` settles, a post-load verification pass
  *   (bounded `customElements.whenDefined`) checks every tag. Any missing
@@ -153,30 +157,54 @@ export async function ensureRegistered(elements, options) {
     // Enforce policy before the already-registered fast path: a matching tag in
     // the registry must not turn a disallowed authored package into valid input.
     assertElementPackagesAllowed(elements, options.elementPackagePolicy);
-    const tags = Object.keys(elements);
+    // Preserve the original request identity while tags register mid-flight.
+    const originalDedupKey = buildDedupKey(options.backend, elements);
+    const originalRequest = inFlightRequests.get(originalDedupKey);
+    if (originalRequest)
+        return originalRequest;
+    if (Object.keys(elements).every(isRegistered))
+        return;
+    const loadsControllers = backendLoadsControllers(options.backend);
+    const unresolvedElements = {};
+    for (const [tag, packageSpec] of Object.entries(elements)) {
+        if (!isRegistered(tag) || (loadsControllers && awaitsController(tag))) {
+            unresolvedElements[tag] = packageSpec;
+        }
+    }
+    const tags = Object.keys(unresolvedElements);
     const timeoutMs = options.whenDefinedTimeoutMs ?? DEFAULT_WHEN_DEFINED_TIMEOUT_MS;
     const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
-    // Fast path: everything already registered. Skip backend and dedup
-    // bookkeeping entirely.
-    if (allAlreadyRegistered(tags))
-        return;
-    const dedupKey = buildDedupKey(options.backend, elements);
+    const dedupKey = buildDedupKey(options.backend, unresolvedElements);
     const existing = inFlightRequests.get(dedupKey);
-    if (existing)
+    if (existing) {
+        aliasInFlightRequest(originalDedupKey, existing);
         return existing;
+    }
     const backend = resolveBackend(options.backend);
     const doc = resolveDoc(options.doc);
-    const promise = runEnsureRegistered(elements, tags, backend, { doc, whenDefinedTimeoutMs: timeoutMs }, timeoutMs, loadTimeoutMs);
-    inFlightRequests.set(dedupKey, promise);
+    const loadElements = isIifeConfig(options.backend)
+        ? iifeLoadElements(elements, unresolvedElements)
+        : unresolvedElements;
+    const promise = runEnsureRegistered(loadElements, tags, backend, { doc, whenDefinedTimeoutMs: timeoutMs }, timeoutMs, loadTimeoutMs);
+    aliasInFlightRequest(originalDedupKey, promise);
+    aliasInFlightRequest(dedupKey, promise);
     try {
         await promise;
     }
     finally {
-        if (inFlightRequests.get(dedupKey) === promise) {
-            inFlightRequests.delete(dedupKey);
+        for (const key of inFlightKeysByPromise.get(promise) ?? []) {
+            if (inFlightRequests.get(key) === promise)
+                inFlightRequests.delete(key);
         }
+        inFlightKeysByPromise.delete(promise);
     }
 }
+function aliasInFlightRequest(key, promise) {
+    inFlightRequests.set(key, promise);
+    const keys = inFlightKeysByPromise.get(promise) ?? new Set();
+    keys.add(key);
+    inFlightKeysByPromise.set(promise, keys);
+}
 async function runEnsureRegistered(elements, tags, backend, context, timeoutMs, loadTimeoutMs) {
     let adapterError;
     try {
@@ -273,13 +301,13 @@ function resolveBackend(backend) {
     if (isDirectBackend(backend))
         return backend;
     if ("kind" in backend) {
+        const backendKey = backendKeyOf(backend);
+        const override = resolvedBackendOverrides.get(backendKey);
+        if (override)
+            return override;
         if (backend.kind === "iife")
             return createIifeBackend(backend);
         if (backend.kind === "esm") {
-            const backendKey = backendKeyOf(backend);
-            const override = resolvedBackendOverrides.get(backendKey);
-            if (override)
-                return override;
             const existing = resolvedEsmBackends.get(backendKey);
             if (existing)
                 return existing;
@@ -415,8 +443,32 @@ function getOpaqueObjectRefId(value) {
     }
     return id;
 }
-function allAlreadyRegistered(tags) {
-    return tags.every((tag) => isRegistered(tag));
+function isIifeConfig(backend) {
+    return !isDirectBackend(backend) && "kind" in backend && backend.kind === "iife";
+}
+/**
+ * An IIFE bundle URL names its packages, so the full map keeps it the URL a
+ * host already fetched. Two specs of one package cannot share a bundle, so a
+ * conflict narrows the map: first to the unresolved tags, then to the undefined.
+ */
+function iifeLoadElements(elements, unresolvedElements) {
+    if (!findIifeElementMapConflict(elements))
+        return elements;
+    if (!findIifeElementMapConflict(unresolvedElements))
+        return unresolvedElements;
+    return Object.fromEntries(Object.entries(unresolvedElements).filter(([tag]) => !isRegistered(tag)));
+}
+function backendLoadsControllers(backend) {
+    if (isDirectBackend(backend) || !("kind" in backend))
+        return false;
+    if (backend.kind === "iife")
+        return backend.needsControllers ?? true;
+    if (backend.kind === "esm")
+        return backend.loadControllers ?? true;
+    return false;
+}
+function awaitsController(tag) {
+    return typeof window !== "undefined" && !pieRegistry()[tag]?.controller;
 }
 function isRegistered(tag) {
     if (typeof customElements === "undefined")
@@ -471,6 +523,7 @@ function extractAdapterReason(err, tag) {
 export const __testing = {
     resetDedupState() {
         inFlightRequests.clear();
+        inFlightKeysByPromise.clear();
         resolvedEsmBackends.clear();
         resolvedBackendOverrides.clear();
         clearPackageMetadataRequests();

package/dist/loaders/iife-adapter.d.ts

@@ -21,6 +21,7 @@
 import type { InstrumentationProvider } from "../instrumentation/types.js";
 import { type IifeBundleRetryConfig } from "../loader-config.js";
 import { BundleType } from "../pie/types.js";
+import type { ElementMap } from "./ElementLoader.js";
 import { type ElementLoaderBackend } from "./element-loader-types.js";
 /**
  * Bundle-build retry status emitted while a bundle is being built or after
@@ -77,4 +78,10 @@ export type IifeBackendConfig = {
     instrumentationProvider?: InstrumentationProvider;
 };
 export type IifeBackend = ElementLoaderBackend & {};
+/**
+ * The legacy IIFE bundle global is keyed by unversioned package name. Two
+ * distinct specs for one package therefore cannot coexist in a single bundle:
+ * one constructor would silently be reused for both requested versioned tags.
+ */
+export declare function findIifeElementMapConflict(elements: ElementMap): string | undefined;
 export declare function createIifeBackend(config: IifeBackendConfig): IifeBackend;

package/dist/loaders/iife-adapter.js

@@ -31,7 +31,7 @@ import { AdapterFailure, } from "./element-loader-types.js";
  * distinct specs for one package therefore cannot coexist in a single bundle:
  * one constructor would silently be reused for both requested versioned tags.
  */
-function findIifeElementMapConflict(elements) {
+export function findIifeElementMapConflict(elements) {
     const specsByPackageName = new Map();
     for (const packageSpecValue of Object.values(elements)) {
         const packageSpec = String(packageSpecValue);

package/dist/security/validate-style-url.js

@@ -30,11 +30,11 @@ export function validateExternalStyleUrl(url, options = {}) {
             ? new URL(url, options.baseUrl)
             : new URL(url);
     }
-    catch (err) {
+    catch {
         return {
             ok: false,
             reason: "invalid-url",
-            message: `External stylesheet URL could not be parsed: ${String(err)}`,
+            message: "External stylesheet URL could not be parsed.",
         };
     }
     if (resolvedUrl.protocol !== "http:" && resolvedUrl.protocol !== "https:") {

package/dist/types/index.d.ts

@@ -10,8 +10,10 @@
  */
 import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
 import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
+import type { AdaptationLink, LanguagePolicy } from "./interchange.js";
 export type { FormativeDeliveryPolicy, FormativeItemPolicy };
 export type { TimedMediaSectionData };
+export type { AdaptationLink, ContentSubstitution, LanguagePolicy, ServedContentIdentity, } from "./interchange.js";
 export interface BaseEntity {
     id?: string;
     createdAt?: Date;
@@ -32,12 +34,6 @@ export interface VersionEntity extends BaseEntity {
     signature?: string;
     version: SemVer;
 }
-export interface SearchMetaData {
-    [key: string]: any;
-}
-export interface SearchMetaDataEntity extends BaseEntity {
-    searchMetaData?: SearchMetaData;
-}
 export interface ConfigElements {
     [key: string]: string;
 }
@@ -69,16 +65,29 @@ export interface ConfigEntity {
 export interface ConfigContainerEntity extends BaseEntity {
     config: ConfigEntity;
 }
-export interface PassageEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
+export interface PassageEntity extends VersionEntity, ConfigContainerEntity {
     name: string;
+    /**
+     * BCP 47 tag of the content's language (QTI `xml:lang`). The players render
+     * and score it under this language; absent, the section's `env.locale` holds.
+     */
+    language?: string;
+    /** The source a translated version was adapted from. No player reads it. */
+    isAdaptationOf?: AdaptationLink;
     /** QTI/APIP-style accessibility catalogs owned by this passage content. */
     accessibilityCatalogs?: AccessibilityCatalog[];
     retired?: boolean;
     published?: boolean;
-    highlights?: Record<string, string[]>;
 }
-export interface ItemEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
+export interface ItemEntity extends VersionEntity, ConfigContainerEntity {
     name?: string;
+    /**
+     * BCP 47 tag of the content's language (QTI `xml:lang`). The players render
+     * and score it under this language; absent, the section's `env.locale` holds.
+     */
+    language?: string;
+    /** The source a translated version was adapted from. No player reads it. */
+    isAdaptationOf?: AdaptationLink;
     /**
      * `null` as well as absent, because importers write it: JSON has no
      * `undefined`, so an item transformed from another format carries an
@@ -90,7 +99,6 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
     retired?: boolean;
     published?: boolean;
     configuration?: any;
-    highlights?: Record<string, string[]>;
 }
 /**
  * `baseId` and `version` are optional on an entity a section references. They
@@ -109,20 +117,6 @@ export type ReferencedPassageEntity = Omit<WithOptionalVersion<PassageEntity>, "
 export type ReferencedItemEntity = Omit<WithOptionalVersion<ItemEntity>, "passage"> & {
     passage?: string | ReferencedPassageEntity | null;
 };
-/**
- * Metadata specifically for interpretation by clients, typically containing
- * options that are relevant for the user interface. This is not indexed for search.
- */
-export interface SettingsMetaData {
-    [key: string]: any;
-}
-/**
- * Objects that contain metadata in the settings property, which is NOT indexed for search
- * but typically only relevant for particular client cases.
- */
-export interface SettingsMetaDataEntity {
-    settings?: SettingsMetaData;
-}
 export type RubricBlockView = "author" | "candidate" | "proctor" | "scorer" | "testConstructor" | "tutor";
 export interface RubricBlock {
     identifier?: string;
@@ -150,7 +144,7 @@ export interface RubricBlock {
  * References an item within a section. The item property contains the resolved
  * ItemEntity with its PIE config.
  */
-export interface AssessmentItemRef extends SearchMetaDataEntity {
+export interface AssessmentItemRef extends BaseEntity {
     id?: string;
     identifier: string;
     title?: string;
@@ -175,7 +169,7 @@ export interface AssessmentItemRef extends SearchMetaDataEntity {
      */
     formative?: FormativeItemPolicy;
 }
-export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDataEntity {
+export interface AssessmentSection extends BaseEntity {
     id?: string;
     identifier: string;
     title?: string;
@@ -484,7 +478,7 @@ export interface PersonalNeedsProfile {
      */
     toolParameters?: ToolParameters;
 }
-export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
+export interface AssessmentEntity extends BaseEntity {
     name?: string;
     title?: string;
     identifier?: string;
@@ -499,6 +493,11 @@ export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
     accessibilityCatalogs?: AccessibilityCatalog[];
     /** QTI 3.0: Personal Needs Profile (PNP 3.0) */
     personalNeedsProfile?: PersonalNeedsProfile;
+    /**
+     * The languages the assessment is offered in, read by a backend that
+     * resolves language variants. No player reads it.
+     */
+    languagePolicy?: LanguagePolicy;
     /**
      * QTI 3.0: testParts structure (authoritative for QTI format).
      */
@@ -548,6 +547,13 @@ export interface ToolParameterMap {
     signLanguage: {
         signLang?: string;
     };
+    /**
+     * `language` is the BCP 47 content language the learner reads items in. A
+     * host passes it to delivery as `requestedLanguages`.
+     */
+    itemTranslation: {
+        language?: string;
+    };
     /**
      * `rate` multiplies every playback speed, 1 being the provider's normal
      * speed; `pitch` runs 0–2 with 1 normal; `volume` runs 0–1.

package/dist/types/interchange.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Language-variant interchange types (PIE-1393). Backends and authoring tools
+ * exchange them; no player reads `AdaptationLink` or `LanguagePolicy`.
+ *
+ * A language variant is its own item or passage version that declares
+ * `language` and, when it is a translation, `isAdaptationOf`. Its family is
+ * `isAdaptationOf.baseId ?? baseId`.
+ */
+import type { SemVer } from "./index.js";
+/** The source a translated item or passage was adapted from. */
+export interface AdaptationLink {
+    baseId: string;
+    /** The source version translated. Absent when provenance is unknown. */
+    version?: SemVer;
+}
+/**
+ * The languages an assessment offers and what a backend serves when a family
+ * has no variant in the requested language.
+ */
+export interface LanguagePolicy {
+    /** BCP 47 tags the assessment may be served in. */
+    languages: string[];
+    /**
+     * `"default"` serves an item whose family lacks the requested language in
+     * the closest match for the platform default, `en-US` (so `en` or `en-GB`),
+     * then its content that declares no language, then its source. Fallback is
+     * per item; items sharing a passage fall back together. `"none"` fails the
+     * load.
+     */
+    fallback: "default" | "none";
+    /**
+     * `"closest"`, the default, serves the nearest variant in the requested
+     * language, so `es-MX` reaches `es` or `es-ES`; `"exact"` serves only an
+     * equal tag and leaves anything else to `fallback`.
+     */
+    matching?: "closest" | "exact";
+    /**
+     * `"serve"` serves a variant whose source has a newer release and records
+     * it as stale; `"require-current"` treats that variant as missing.
+     */
+    staleness: "serve" | "require-current";
+}
+/** Why the served content differs from what was requested. */
+export type ContentSubstitution = "fallback" | "stale";
+/** The content version a backend served, and the language it served it in. */
+export interface ServedContentIdentity {
+    baseId: string;
+    version?: SemVer;
+    /** The family key, when the served version belongs to a variant family. */
+    family?: string;
+    /** BCP 47 tag of the served content. */
+    servedLanguage?: string;
+    substitution?: ContentSubstitution;
+}

package/dist/types/interchange.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/focus-trap.js

@@ -1,4 +1,5 @@
 import { collectFocusable } from "./first-focusable.js";
+import { isComposingKeyEvent } from "./ime.js";
 /**
  * Shadow-aware: a trapped panel almost always hosts a custom element rendering into
  * `shadow: "open"`, and a flat `querySelectorAll` would collect only the panel's own
@@ -44,7 +45,8 @@ export function createFocusTrap(container, options = {}) {
     const wrap = options.wrap ?? true;
     const onKeydown = (event) => {
         if (event.key === "Escape") {
-            if (!options.onEscape)
+            // An Escape that cancels an IME composition belongs to the IME.
+            if (!options.onEscape || isComposingKeyEvent(event))
                 return;
             // Claimed, so a page-wide Escape listener does not also act on it.
             event.preventDefault();

package/dist/ui/ime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a keydown belongs to an IME composition, so it must not act as a
+ * shortcut. Safari reports `isComposing` false on the Enter that commits a
+ * composition and marks it only with `keyCode` 229.
+ */
+export declare function isComposingKeyEvent(event: Pick<KeyboardEvent, "isComposing" | "keyCode">): boolean;

package/dist/ui/ime.js

@@ -0,0 +1,10 @@
+/** The legacy `keyCode` a browser reports for a keydown the IME consumes. */
+const IME_PROCESS_KEY_CODE = 229;
+/**
+ * Whether a keydown belongs to an IME composition, so it must not act as a
+ * shortcut. Safari reports `isComposing` false on the Enter that commits a
+ * composition and marks it only with `keyCode` 229.
+ */
+export function isComposingKeyEvent(event) {
+    return event.isComposing || event.keyCode === IME_PROCESS_KEY_CODE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.5",
+	"version": "1.0.0-beta.7",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -106,7 +106,7 @@
 		"dist"
 	],
 	"dependencies": {
-		"@pie-element/shared-utils": "0.1.4",
+		"@pie-element/shared-utils": "0.1.6",
 		"@pie-lib/math-rendering-module": "6.0.0",
 		"dompurify": "^3.4.17",
 		"semver": "^7.8.5"
@@ -122,9 +122,9 @@
 		"scan-hardcoded": "bun run src/i18n/scripts/scan-hardcoded.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.15",
-		"@happy-dom/global-registrator": "^20.14.5",
-		"@pie-element/shared-math-rendering-mathjax": "0.1.7",
+		"@biomejs/biome": "^2.6.2",
+		"@happy-dom/global-registrator": "^21.0.4",
+		"@pie-element/shared-math-rendering-mathjax": "0.1.8",
 		"@playwright/test": "^1.64.1",
 		"@types/semver": "^7.8.0",
 		"es-module-shims": "^2.8.4",