@pie-players/pie-players-shared 0.3.67 → 0.3.69

package/dist/formative/state.js

@@ -0,0 +1,140 @@
+export const FORMATIVE_ITEM_STATE_VERSION = 1;
+export function createFormativeItemState(itemIdentifier) {
+    return {
+        version: FORMATIVE_ITEM_STATE_VERSION,
+        itemIdentifier,
+        tryCount: 0,
+        revealed: false,
+    };
+}
+function triesRemaining(policy, tryCount) {
+    if (policy.maxTries === "unlimited")
+        return "unlimited";
+    return Math.max(0, policy.maxTries - tryCount);
+}
+function hasTriesLeft(remaining) {
+    return remaining === "unlimited" || remaining > 0;
+}
+function shouldReveal(policy, tryCount) {
+    if (policy.feedback === "none")
+        return false;
+    if (policy.revealOn === "on-try")
+        return true;
+    // Defensive: `resolveFormativePolicy` already coerces `"on-final-try"` to
+    // `"on-try"` under unlimited Tries, so this branch only guards a
+    // hand-constructed policy.
+    if (policy.maxTries === "unlimited")
+        return true;
+    return tryCount >= policy.maxTries;
+}
+/**
+ * Record one Try.
+ *
+ * Idempotent against a double submit: a Try is only counted when the current
+ * state can be checked, so a second click landing before the projection
+ * round-trips is dropped rather than spending a Try.
+ */
+export function recordFormativeTry(args) {
+    const current = args.state ?? createFormativeItemState(args.itemIdentifier);
+    if (!args.policy.enabled)
+        return current;
+    const remaining = triesRemaining(args.policy, current.tryCount);
+    if (current.revealed || !hasTriesLeft(remaining))
+        return current;
+    const tryCount = current.tryCount + 1;
+    return {
+        ...current,
+        version: FORMATIVE_ITEM_STATE_VERSION,
+        itemIdentifier: args.itemIdentifier,
+        tryCount,
+        revealed: shouldReveal(args.policy, tryCount),
+        lastOutcome: args.outcome,
+        // First correct Try is recorded once. A later incorrect Try changes
+        // `lastOutcome` but not the fact that the learner got there, which is what
+        // mastery counts.
+        firstCorrectTry: current.firstCorrectTry ??
+            (args.outcome.correctness === "correct" ? tryCount : undefined),
+    };
+}
+/**
+ * Dismiss a reveal and reopen the item for editing. Withdrawing `revealed` is
+ * what withdraws the env override, so the item returns to the section's own
+ * mode.
+ *
+ * A learner action, so it respects the Try budget: an item with none left keeps
+ * its feedback on screen. `hideFormativeItem` is the host-authority version.
+ */
+export function retryFormativeItem(args) {
+    const current = args.state;
+    if (!current || !args.policy.enabled)
+        return current;
+    if (!current.revealed)
+        return current;
+    if (!hasTriesLeft(triesRemaining(args.policy, current.tryCount))) {
+        return current;
+    }
+    return { ...current, revealed: false, revealOverride: undefined };
+}
+/**
+ * Reveal on host authority — a teacher-driven "show the answer".
+ *
+ * Spends no Try and ignores the Try budget and `revealOn`, because none of those
+ * bound a decision the host has already taken. `feedback` is required rather
+ * than defaulted from the policy: a forced reveal under `feedback: "none"` would
+ * project nothing, so the caller states what to show.
+ *
+ * Works on an item with no Try yet. The element renders evaluate mode over
+ * whatever response is there, including none, which is what "show the answer"
+ * means before the learner has answered.
+ */
+export function revealFormativeItem(args) {
+    const current = args.state ?? createFormativeItemState(args.itemIdentifier);
+    if (!args.policy.enabled)
+        return current;
+    if (current.revealed && current.revealOverride === args.feedback) {
+        return current;
+    }
+    return { ...current, revealed: true, revealOverride: args.feedback };
+}
+/**
+ * Withdraw a reveal on host authority. Unlike a learner retry this ignores the
+ * Try budget: a host that revealed an item with no Tries left must be able to
+ * put it back.
+ */
+export function hideFormativeItem(args) {
+    const current = args.state;
+    if (!current || !args.policy.enabled)
+        return current;
+    if (!current.revealed && !current.revealOverride)
+        return current;
+    return { ...current, revealed: false, revealOverride: undefined };
+}
+function envOverrideFor(policy, revealed, revealOverride) {
+    const feedback = revealOverride ?? policy.feedback;
+    if (!revealed || feedback === "none")
+        return undefined;
+    return {
+        mode: "evaluate",
+        role: feedback === "solution" ? "instructor" : "student",
+    };
+}
+/** Derive everything a rendering component needs from policy plus state. */
+export function resolveFormativeItemView(args) {
+    const { policy } = args;
+    const tryCount = args.state?.tryCount ?? 0;
+    const revealed = args.state?.revealed === true;
+    const remaining = triesRemaining(policy, tryCount);
+    const available = policy.enabled && hasTriesLeft(remaining);
+    return {
+        enabled: policy.enabled,
+        tryCount,
+        triesRemaining: remaining,
+        canCheck: available && !revealed,
+        canRetry: available && revealed,
+        revealed,
+        envOverride: policy.enabled
+            ? envOverrideFor(policy, revealed, args.state?.revealOverride)
+            : undefined,
+        lastOutcome: args.state?.lastOutcome,
+    };
+}

package/dist/formative/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Formative delivery vocabulary.
+ *
+ * A **Try** is one submitted-for-checking pass over a single item. It is not
+ * `TestAttemptSession` (the assessment administration) and not
+ * `TestAttemptItemSession.attemptCount` (a count of distinct PIE session ids for
+ * an item). Both of those already own the word "attempt" in this codebase, at
+ * two different scopes, which is why this contract does not use it.
+ *
+ * See `docs/prds/formative-delivery-contract.md` for the ratified contract and
+ * its QTI 3 mapping.
+ */
+/** How many Tries a learner gets on one item. */
+export type FormativeTryLimit = number | "unlimited";
+/**
+ * What the learner sees after a Try.
+ *
+ * PIE does not render feedback — it selects the render mode the element already
+ * implements. `"correctness"` projects `role: "student"`, `"solution"` projects
+ * `role: "instructor"`, which is the element convention for additionally
+ * revealing the authored correct response.
+ */
+export type FormativeFeedbackReveal = "none" | "correctness" | "solution";
+/** When a reveal happens: after every Try, or only once Tries are spent. */
+export type FormativeRevealTiming = "on-try" | "on-final-try";
+/**
+ * Authored policy. Lives on `AssessmentSection.formative` as the section
+ * default and on `AssessmentItemRef.formative` as a per-item override.
+ */
+export interface FormativeDeliveryPolicy {
+    /**
+     * Absent or `false` leaves delivery exactly as it is without this contract:
+     * no control, no projection, no state.
+     */
+    enabled?: boolean;
+    /** Default 1. */
+    maxTries?: FormativeTryLimit;
+    /** Default `"correctness"`. */
+    feedback?: FormativeFeedbackReveal;
+    /** Default `"on-try"`. */
+    revealOn?: FormativeRevealTiming;
+}
+/** Same shape as the section policy; every field overrides independently. */
+export type FormativeItemPolicy = FormativeDeliveryPolicy;
+/** The policy after built-in defaults, section, and item ref are merged. */
+export interface ResolvedFormativePolicy {
+    enabled: boolean;
+    maxTries: FormativeTryLimit;
+    feedback: FormativeFeedbackReveal;
+    revealOn: FormativeRevealTiming;
+}
+/**
+ * `"unknown"` is the honest state for an item no loaded controller can score —
+ * one holding a rubric element, or one whose element bundle exposes no
+ * `outcome`. It is never collapsed into `"incorrect"`.
+ */
+export type FormativeCorrectness = "correct" | "partial" | "incorrect" | "unknown";
+/**
+ * The subset of an element outcome that aggregation reads. `OutcomeResponse` is
+ * assignable to this; the structural type keeps this module free of a
+ * dependency on the entity types, which import policy types from here.
+ */
+export interface FormativeScoredOutcome {
+    score?: number;
+    max?: number;
+    [key: string]: unknown;
+}
+/** The recorded result of one Try. */
+export interface FormativeTryOutcome {
+    correctness: FormativeCorrectness;
+    points?: number;
+    max?: number;
+    scoredElementCount: number;
+    totalElementCount: number;
+    /**
+     * The per-element outcomes the aggregate was derived from, for a host that
+     * renders its own feedback instead of the element's evaluate-mode rendering.
+     *
+     * Element-shaped and unvalidated beyond "an object" — each entry carries
+     * whatever that element's controller returned, keyed to a model by its own
+     * `id`. Empty slots (`provideScore()` leaves one per model with no element or
+     * controller) are dropped; `totalElementCount` still counts them.
+     *
+     * A trade: this persists inside the session slice, so a snapshot grows by
+     * whatever the elements put in their outcomes — some include a scoring trace.
+     */
+    elementOutcomes?: FormativeScoredOutcome[];
+}
+/** Per-item delivery state. Persisted; see `FormativeSectionSlice`. */
+export interface FormativeItemState {
+    version: 1;
+    itemIdentifier: string;
+    tryCount: number;
+    /**
+     * Whether feedback is on screen right now. Live delivery state rather than a
+     * fact about the response: it distinguishes "checked, feedback shown,
+     * editing locked" from "editable again after a retry", and it persists so a
+     * reload restores the screen the learner left.
+     */
+    revealed: boolean;
+    lastOutcome?: FormativeTryOutcome;
+    /** 1-based Try on which the item first scored full credit. Never overwritten. */
+    firstCorrectTry?: number;
+    /**
+     * Reveal level in force for this item, when a host forced the reveal rather
+     * than the learner earning it. Overrides the policy's `feedback` for the env
+     * projection only — the policy still decides Tries.
+     *
+     * Set by `revealFormativeItem`, cleared by `hideFormativeItem` and by a
+     * learner retry, so a teacher-driven "show the answer" does not silently
+     * upgrade every later reveal on that item.
+     */
+    revealOverride?: FormativeFeedbackReveal;
+}
+/** The persisted slice, carried on `SectionControllerSessionState.formative`. */
+export interface FormativeSectionSlice {
+    version: 1;
+    items: Record<string, FormativeItemState>;
+}
+/** Projected over the section env for one revealed item. */
+export interface FormativeEnvOverride {
+    mode: "evaluate";
+    role: "student" | "instructor";
+}
+/**
+ * What a rendering component needs, derived once so no component reimplements
+ * the predicate. Carries no copy — wording belongs to the rendering package.
+ */
+export interface FormativeItemView {
+    enabled: boolean;
+    tryCount: number;
+    triesRemaining: number | "unlimited";
+    canCheck: boolean;
+    canRetry: boolean;
+    revealed: boolean;
+    envOverride?: FormativeEnvOverride;
+    lastOutcome?: FormativeTryOutcome;
+}
+/** Section rollup over Try outcomes. */
+export interface FormativeMasteryRollup {
+    version: 1;
+    totalItems: number;
+    /**
+     * Items not known to be unscorable — total minus those whose last outcome
+     * was `"unknown"`. An untried item counts here: nothing yet says it cannot
+     * be scored.
+     */
+    scorableItems: number;
+    masteredItems: number;
+    triedItems: number;
+    /** Mean `firstCorrectTry` across mastered items. */
+    averageTriesToMastery?: number;
+    complete: boolean;
+}
+/** The composition-model projection layouts read. */
+export interface FormativeSectionProjection {
+    version: 1;
+    enabled: boolean;
+    policies: Record<string, ResolvedFormativePolicy>;
+    states: Record<string, FormativeItemState>;
+    mastery: FormativeMasteryRollup;
+}
+/** The two learner actions a rendering component can request. */
+export type FormativeAction = "check" | "retry";

package/dist/formative/types.js

@@ -0,0 +1,13 @@
+/**
+ * Formative delivery vocabulary.
+ *
+ * A **Try** is one submitted-for-checking pass over a single item. It is not
+ * `TestAttemptSession` (the assessment administration) and not
+ * `TestAttemptItemSession.attemptCount` (a count of distinct PIE session ids for
+ * an item). Both of those already own the word "attempt" in this codebase, at
+ * two different scopes, which is why this contract does not use it.
+ *
+ * See `docs/prds/formative-delivery-contract.md` for the ratified contract and
+ * its QTI 3 mapping.
+ */
+export {};

package/dist/i18n/catalogs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lazy catalog loaders for every locale this repository ships.
+ *
+ * Imported by players, never by tools. A tool resolves its provider from the
+ * toolkit runtime context and needs only the interface plus the English
+ * fallback; reaching this module from a tool entry would emit a locale chunk
+ * 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 absent: it is the fallback for every missing key in every other
+ * locale, so the provider imports it statically and it is always resident.
+ *
+ * @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.
+ *
+ * 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`.
+ */
+export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
+/**
+ * Load one shipped catalog.
+ *
+ * Throws for a locale with no shipped 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.
+ */
+export declare function loadBundledCatalog(locale: string): Promise<MessageCatalog>;

package/dist/i18n/catalogs.js

@@ -0,0 +1,47 @@
+/**
+ * Lazy catalog loaders for every locale this repository ships.
+ *
+ * Imported by players, never by tools. A tool resolves its provider from the
+ * toolkit runtime context and needs only the interface plus the English
+ * fallback; reaching this module from a tool entry would emit a locale chunk
+ * 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 absent: it is the fallback for every missing key in every other
+ * locale, so the provider imports it statically and it is always resident.
+ *
+ * @module @pie-players/pie-players-shared/i18n/catalogs
+ */
+const CATALOG_LOADERS = {
+    "nl-NL": () => import("./messages/nl-NL.js"),
+};
+/**
+ * Every locale tag this repository ships a catalog for, English included.
+ *
+ * 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`.
+ */
+export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
+/**
+ * Load one shipped catalog.
+ *
+ * Throws for a locale with no shipped 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.
+ */
+export async function loadBundledCatalog(locale) {
+    const loader = CATALOG_LOADERS[locale];
+    if (!loader) {
+        throw new Error(`No bundled i18n catalog for locale: ${locale}`);
+    }
+    const module = await loader();
+    return module.default;
+}

package/dist/i18n/index.d.ts

@@ -1,10 +1,34 @@
 /**
  * I18n Module
  *
- * Internationalization system for PIE Players.
+ * Chrome internationalization for PIE Players: the strings our own packages
+ * render. Content language and in-item alternates are separate concerns on
+ * separate channels — see `docs/architecture/internationalization.md`.
+ *
+ * Two entry points, and which one you import decides what ships:
+ *
+ * - **Players** import this module. `createPieI18n()` wires the provider to the
+ *   lazy catalog loaders, so every shipped locale is reachable and each lands in
+ *   its own chunk.
+ * - **Tools** import `./types.js` as `import type` (fully erased) plus
+ *   `getDefaultI18n` from `./provider.js` for the no-publisher default. That
+ *   path never reaches `./catalogs.js`, so no locale chunk is emitted into a
+ *   tool bundle — which matters because every tool `vite.config.ts` sets
+ *   `external: []`.
  *
  * @module @pie-players/pie-players-shared/i18n
  */
-export { BUNDLED_TRANSLATIONS, getAvailableLocales, isRTLLocale, loadTranslations, } from "./loader.js";
-export { SimpleI18n } from "./simple-i18n.js";
-export type { I18nConfig, I18nServiceApi, PluralTranslation, TranslationBundle, } from "./types.js";
+import type { I18nConfig, I18nServiceApi } from "./types.js";
+/**
+ * A provider serving every locale this repository ships.
+ *
+ * Defaults to `en-US` with no locale detection: under fixed lockstep patch-only
+ * versioning a rendered-string change reaches a host's live delivery on their
+ * next install with no build signal on their side, so a player must render
+ * exactly what it rendered before until a host supplies a locale.
+ */
+export declare function createPieI18n(config?: I18nConfig): I18nServiceApi;
+export { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
+export { findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, } from "./language-tags.js";
+export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, } from "./provider.js";
+export type { BundledLocaleCode, DynamicMessageKey, I18nConfig, I18nProvider, I18nServiceApi, InterpolationValues, LocaleCode, MessageCatalog, MessageKey, MessageKeyInput, MessageNode, PluralOptions, PluralTranslation, TextDirection, TranslationBundle, } from "./types.js";

package/dist/i18n/index.js

@@ -1,9 +1,40 @@
 /**
  * I18n Module
  *
- * Internationalization system for PIE Players.
+ * Chrome internationalization for PIE Players: the strings our own packages
+ * render. Content language and in-item alternates are separate concerns on
+ * separate channels — see `docs/architecture/internationalization.md`.
+ *
+ * Two entry points, and which one you import decides what ships:
+ *
+ * - **Players** import this module. `createPieI18n()` wires the provider to the
+ *   lazy catalog loaders, so every shipped locale is reachable and each lands in
+ *   its own chunk.
+ * - **Tools** import `./types.js` as `import type` (fully erased) plus
+ *   `getDefaultI18n` from `./provider.js` for the no-publisher default. That
+ *   path never reaches `./catalogs.js`, so no locale chunk is emitted into a
+ *   tool bundle — which matters because every tool `vite.config.ts` sets
+ *   `external: []`.
  *
  * @module @pie-players/pie-players-shared/i18n
  */
-export { BUNDLED_TRANSLATIONS, getAvailableLocales, isRTLLocale, loadTranslations, } from "./loader.js";
-export { SimpleI18n } from "./simple-i18n.js";
+import { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
+import { SimpleI18n } from "./provider.js";
+/**
+ * A provider serving every locale this repository ships.
+ *
+ * Defaults to `en-US` with no locale detection: under fixed lockstep patch-only
+ * versioning a rendered-string change reaches a host's live delivery on their
+ * next install with no build signal on their side, so a player must render
+ * exactly what it rendered before until a host supplies a locale.
+ */
+export function createPieI18n(config = {}) {
+    return new SimpleI18n({
+        loadCatalog: loadBundledCatalog,
+        availableLocales: BUNDLED_LOCALES,
+        ...config,
+    });
+}
+export { BUNDLED_LOCALES, loadBundledCatalog } from "./catalogs.js";
+export { findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, } from "./language-tags.js";
+export { DEFAULT_LOCALE, detectBrowserLocale, dynamicMessageKey, getDefaultI18n, localeDirection, resolveInterfaceI18n, SimpleI18n, } from "./provider.js";

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

@@ -0,0 +1,51 @@
+/**
+ * BCP-47 language tag comparison.
+ *
+ * Deliberately carries no locale data and no DOM access: this module is the one
+ * piece of language machinery that everything else needs, including the
+ * accessibility catalog resolver and TTS voice selection, neither of which wants
+ * a message catalog. Importing `../i18n/index.js` would pull the eagerly-bundled
+ * English translations, so this stays a separate entry point.
+ *
+ * Content producers do not agree on tag syntax. The Learnosity transform emits
+ * POSIX `es_ES`, QTI catalog cards carry BCP-47 `xml:lang`, and pie-elements-ng
+ * carries a hand-written POSIX-to-BCP-47 mapping table of its own. Comparing
+ * with `===`, as the catalog resolver did, means an `es_ES` card matches no
+ * request for `es-ES` and surfaces only through a no-language-constraint
+ * fallback — resolution by accident.
+ *
+ * @module @pie-players/pie-players-shared/i18n/language-tags
+ */
+/**
+ * Canonicalize a language tag for comparison.
+ *
+ * Converts POSIX underscores to hyphens, strips a POSIX charset or modifier
+ * suffix (`es_ES.UTF-8`, `es_ES@euro`), and lowercases. Lowercasing rather than
+ * applying BCP-47 display casing is intentional — this output is a comparison
+ * key, not something to render.
+ *
+ * Returns an empty string for nullish or blank input, which callers read as
+ * "this card declares no language".
+ */
+export declare function normalizeLanguageTag(tag: string | null | undefined): string;
+/**
+ * Whether two language tags denote the same locale, ignoring separator style and
+ * case. Two tags that both declare no language are not a match.
+ */
+export declare function languageTagsEqual(a: string | null | undefined, b: string | null | undefined): boolean;
+/**
+ * The RFC 4647 lookup sequence for a tag, most specific first.
+ *
+ * `es-MX` yields `["es-mx", "es"]`, so a request for Mexican Spanish reaches a
+ * card tagged plain `es` without also reaching one tagged `es-ES`. Truncation
+ * never stops on a singleton subtag (`x`, `u`), per RFC 4647 §3.4, and never
+ * produces a bare region or script.
+ */
+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.
+ */
+export declare function findBestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;

package/dist/i18n/language-tags.js

@@ -0,0 +1,84 @@
+/**
+ * BCP-47 language tag comparison.
+ *
+ * Deliberately carries no locale data and no DOM access: this module is the one
+ * piece of language machinery that everything else needs, including the
+ * accessibility catalog resolver and TTS voice selection, neither of which wants
+ * a message catalog. Importing `../i18n/index.js` would pull the eagerly-bundled
+ * English translations, so this stays a separate entry point.
+ *
+ * Content producers do not agree on tag syntax. The Learnosity transform emits
+ * POSIX `es_ES`, QTI catalog cards carry BCP-47 `xml:lang`, and pie-elements-ng
+ * carries a hand-written POSIX-to-BCP-47 mapping table of its own. Comparing
+ * with `===`, as the catalog resolver did, means an `es_ES` card matches no
+ * request for `es-ES` and surfaces only through a no-language-constraint
+ * fallback — resolution by accident.
+ *
+ * @module @pie-players/pie-players-shared/i18n/language-tags
+ */
+/**
+ * Canonicalize a language tag for comparison.
+ *
+ * Converts POSIX underscores to hyphens, strips a POSIX charset or modifier
+ * suffix (`es_ES.UTF-8`, `es_ES@euro`), and lowercases. Lowercasing rather than
+ * applying BCP-47 display casing is intentional — this output is a comparison
+ * key, not something to render.
+ *
+ * Returns an empty string for nullish or blank input, which callers read as
+ * "this card declares no language".
+ */
+export function normalizeLanguageTag(tag) {
+    if (!tag)
+        return "";
+    const separatorsUnified = tag.trim().replace(/_/g, "-");
+    const withoutPosixSuffix = separatorsUnified.split(/[.@]/)[0];
+    return withoutPosixSuffix.toLowerCase();
+}
+/**
+ * Whether two language tags denote the same locale, ignoring separator style and
+ * case. Two tags that both declare no language are not a match.
+ */
+export function languageTagsEqual(a, b) {
+    const left = normalizeLanguageTag(a);
+    if (!left)
+        return false;
+    return left === normalizeLanguageTag(b);
+}
+/**
+ * The RFC 4647 lookup sequence for a tag, most specific first.
+ *
+ * `es-MX` yields `["es-mx", "es"]`, so a request for Mexican Spanish reaches a
+ * card tagged plain `es` without also reaching one tagged `es-ES`. Truncation
+ * never stops on a singleton subtag (`x`, `u`), per RFC 4647 §3.4, and never
+ * produces a bare region or script.
+ */
+export function languageTagLookupSequence(tag) {
+    const normalized = normalizeLanguageTag(tag);
+    if (!normalized)
+        return [];
+    const subtags = normalized.split("-");
+    const sequence = [];
+    for (let length = subtags.length; length > 0; length--) {
+        const candidate = subtags.slice(0, length);
+        // A trailing singleton introduces an extension with nothing left in it.
+        if (candidate.length > 1 && candidate[candidate.length - 1].length === 1) {
+            continue;
+        }
+        sequence.push(candidate.join("-"));
+    }
+    return sequence;
+}
+/**
+ * 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.
+ */
+export function findBestLanguageMatch(requested, available) {
+    for (const step of languageTagLookupSequence(requested)) {
+        const hit = available.find((candidate) => normalizeLanguageTag(candidate) === step);
+        if (hit != null)
+            return hit;
+    }
+    return undefined;
+}