@longsightgroup/qti3-player 0.3.0 → 0.5.1

package/src/player-adapter.ts

@@ -0,0 +1,253 @@
+import type {
+  QtiAttemptStateV1,
+  QtiCatalogSupportResolution,
+  QtiCatalogSupportResolutionOptions,
+  QtiScoreResult,
+  QtiTextToSpeechTraversal,
+} from "@longsightgroup/qti3-core";
+import type { PlayerMessageCatalog } from "./player-message-catalog.js";
+import type { QtiAssessmentItemPlayer } from "./player-element.js";
+import type { QtiPlayerMessageOverrides } from "./player-message-resolver.js";
+import type {
+  QtiAssessmentItemPlayerEventDetailMap,
+  QtiAssessmentItemPlayerEventName,
+  QtiPlayerFetchXml,
+  QtiPlayerLoadOptions,
+  QtiPlayerResolveAsset,
+  QtiScoreAttemptOptions,
+} from "./player-types.js";
+
+export type QtiAssessmentItemPlayerAdapterEventPropName =
+  | "onReady"
+  | "onResponseChange"
+  | "onStateChange"
+  | "onScore"
+  | "onValidation"
+  | "onSuspend"
+  | "onEndAttempt"
+  | "onPortableCustomMount"
+  | "onDiagnostics"
+  | "onReset"
+  | "onRestore";
+
+export type QtiAssessmentItemPlayerAdapterPropName =
+  | "xml"
+  | "loadOptions"
+  | "languageOfInterface"
+  | "messageCatalog"
+  | "messages"
+  | "onLoadError"
+  | QtiAssessmentItemPlayerAdapterEventPropName;
+
+export type QtiAssessmentItemPlayerAdapterEventCallback<
+  T extends QtiAssessmentItemPlayerEventName,
+> = (detail: QtiAssessmentItemPlayerEventDetailMap[T]) => void;
+
+export type QtiAssessmentItemPlayerAdapterEventHandlerProps = {
+  [K in (typeof qtiAssessmentItemPlayerAdapterEventEntries)[number] as K[1]]?: QtiAssessmentItemPlayerAdapterEventCallback<
+    K[0]
+  >;
+};
+
+export interface QtiAssessmentItemPlayerAdapterProps extends QtiAssessmentItemPlayerAdapterEventHandlerProps {
+  /** Already-prepared candidate-safe XML for delivery, or authoring/preview XML in preview tools. */
+  xml?: string | undefined;
+  loadOptions?: QtiPlayerLoadOptions | undefined;
+  languageOfInterface?: string | undefined;
+  messageCatalog?: PlayerMessageCatalog | undefined;
+  messages?: QtiPlayerMessageOverrides | undefined;
+  onLoadError?: ((error: Error) => void) | undefined;
+}
+
+export interface QtiAssessmentItemPlayerHandle {
+  readonly element: QtiAssessmentItemPlayer;
+  loadXml(xml: string, options?: QtiPlayerLoadOptions): Promise<void>;
+  loadUrl(url: string, options?: QtiPlayerLoadOptions): Promise<void>;
+  scoreAttempt(options?: QtiScoreAttemptOptions): QtiScoreResult | undefined;
+  restore(state: QtiAttemptStateV1): void;
+  suspend(): void;
+  endAttempt(options?: QtiScoreAttemptOptions): void;
+  reset(): void;
+  clearItem(): void;
+  serialize(): QtiAttemptStateV1 | undefined;
+  getTextToSpeechTraversal(): QtiTextToSpeechTraversal | undefined;
+  getCatalogSupportResolution(
+    options?: QtiCatalogSupportResolutionOptions,
+  ): QtiCatalogSupportResolution | undefined;
+}
+
+export const qtiAssessmentItemPlayerAdapterEventEntries = [
+  ["qti-ready", "onReady"],
+  ["qti-responsechange", "onResponseChange"],
+  ["qti-statechange", "onStateChange"],
+  ["qti-score", "onScore"],
+  ["qti-validation", "onValidation"],
+  ["qti-suspend", "onSuspend"],
+  ["qti-endattempt", "onEndAttempt"],
+  ["qti-portable-custom-mount", "onPortableCustomMount"],
+  ["qti-diagnostics", "onDiagnostics"],
+  ["qti-reset", "onReset"],
+  ["qti-restore", "onRestore"],
+] as const satisfies readonly (readonly [
+  QtiAssessmentItemPlayerEventName,
+  QtiAssessmentItemPlayerAdapterEventPropName,
+])[];
+
+export const qtiAssessmentItemPlayerAdapterPropNames = [
+  "xml",
+  "loadOptions",
+  "languageOfInterface",
+  "messageCatalog",
+  "messages",
+  "onLoadError",
+  ...qtiAssessmentItemPlayerAdapterEventEntries.map((entry) => entry[1]),
+] as const satisfies readonly QtiAssessmentItemPlayerAdapterPropName[];
+
+const qtiAssessmentItemPlayerAdapterPropNameSet = new Set<string>(
+  qtiAssessmentItemPlayerAdapterPropNames,
+);
+
+export function isQtiAssessmentItemPlayerAdapterPropName(name: string): boolean {
+  return qtiAssessmentItemPlayerAdapterPropNameSet.has(name);
+}
+
+export type QtiAssessmentItemPlayerLoadDependencies = readonly [
+  string | undefined,
+  QtiPlayerLoadOptions["status"] | undefined,
+  boolean | undefined,
+  boolean | undefined,
+  QtiPlayerFetchXml | undefined,
+  QtiPlayerResolveAsset | undefined,
+];
+
+export function qtiAssessmentItemPlayerLoadStateKey(
+  state: QtiAttemptStateV1 | undefined,
+): string | undefined {
+  if (!state) return undefined;
+  // JSON key order follows insertion order; in-place mutation without reload is not detected.
+  return JSON.stringify(state);
+}
+
+export function qtiAssessmentItemPlayerLoadDependencies(
+  loadOptions: QtiPlayerLoadOptions | undefined,
+): QtiAssessmentItemPlayerLoadDependencies {
+  return [
+    qtiAssessmentItemPlayerLoadStateKey(loadOptions?.state),
+    loadOptions?.status,
+    loadOptions?.sessionControl?.validateResponses,
+    loadOptions?.sessionControl?.showFeedback,
+    loadOptions?.fetchXml,
+    loadOptions?.resolveAsset,
+  ];
+}
+
+export function bindQtiAssessmentItemPlayerAdapterEvents(
+  element: QtiAssessmentItemPlayer,
+  getProps: () => QtiAssessmentItemPlayerAdapterProps,
+): () => void {
+  const removers = qtiAssessmentItemPlayerAdapterEventEntries.map(([eventName, propName]) => {
+    const listener = (event: Event) => {
+      const callback = getProps()[propName] as
+        | QtiAssessmentItemPlayerAdapterEventCallback<typeof eventName>
+        | undefined;
+      callback?.(
+        (event as CustomEvent<QtiAssessmentItemPlayerEventDetailMap[typeof eventName]>).detail,
+      );
+    };
+    element.addEventListener(eventName, listener);
+    return () => element.removeEventListener(eventName, listener);
+  });
+  return () => {
+    for (const remove of removers) remove();
+  };
+}
+
+export function syncQtiAssessmentItemPlayerAdapterChrome(
+  element: QtiAssessmentItemPlayer,
+  props: Pick<
+    QtiAssessmentItemPlayerAdapterProps,
+    "languageOfInterface" | "messageCatalog" | "messages"
+  >,
+): void {
+  element.languageOfInterface = props.languageOfInterface;
+  element.messageCatalog = props.messageCatalog;
+  element.messages = props.messages;
+}
+
+/** @deprecated Use {@link syncQtiAssessmentItemPlayerAdapterChrome}. */
+export const syncQtiAssessmentItemPlayerAdapterMessages = syncQtiAssessmentItemPlayerAdapterChrome;
+
+export interface QtiAssessmentItemPlayerAdapterLoadSyncInput {
+  xml?: string | undefined;
+  loadOptions?: QtiPlayerLoadOptions | undefined;
+  onLoadError?: ((error: Error) => void) | undefined;
+}
+
+export function createQtiAssessmentItemPlayerAdapterLoadSync(): {
+  run(
+    element: QtiAssessmentItemPlayer,
+    input: QtiAssessmentItemPlayerAdapterLoadSyncInput,
+  ): () => void;
+} {
+  let loadSequence = 0;
+
+  return {
+    run(element, input) {
+      if (input.xml === undefined) {
+        loadSequence += 1;
+        element.clearItem();
+        return () => {};
+      }
+
+      let active = true;
+      const sequence = (loadSequence += 1);
+      void element
+        .loadXml(input.xml, input.loadOptions)
+        .then(() => {
+          if (!active || sequence !== loadSequence) return;
+        })
+        .catch((error: unknown) => {
+          if (!active || sequence !== loadSequence) return;
+          input.onLoadError?.(normalizeQtiAssessmentItemPlayerLoadError(error));
+        });
+
+      return () => {
+        active = false;
+      };
+    },
+  };
+}
+
+export function createQtiAssessmentItemPlayerHandle(
+  getElement: () => QtiAssessmentItemPlayer | null,
+): QtiAssessmentItemPlayerHandle {
+  return {
+    get element() {
+      return requiredElement(getElement);
+    },
+    loadXml: (xml, options) => requiredElement(getElement).loadXml(xml, options),
+    loadUrl: (url, options) => requiredElement(getElement).loadUrl(url, options),
+    scoreAttempt: (options) => requiredElement(getElement).scoreAttempt(options),
+    restore: (state) => requiredElement(getElement).restore(state),
+    suspend: () => requiredElement(getElement).suspend(),
+    endAttempt: (options) => requiredElement(getElement).endAttempt(options),
+    reset: () => requiredElement(getElement).reset(),
+    clearItem: () => requiredElement(getElement).clearItem(),
+    serialize: () => requiredElement(getElement).serialize(),
+    getTextToSpeechTraversal: () => requiredElement(getElement).getTextToSpeechTraversal(),
+    getCatalogSupportResolution: (options) =>
+      requiredElement(getElement).getCatalogSupportResolution(options),
+  };
+}
+
+export function normalizeQtiAssessmentItemPlayerLoadError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function requiredElement(
+  getElement: () => QtiAssessmentItemPlayer | null,
+): QtiAssessmentItemPlayer {
+  const element = getElement();
+  if (!element) throw new Error("QTI assessment item player element is not mounted.");
+  return element;
+}

package/src/player-dev.ts

@@ -0,0 +1,14 @@
+/** True when dev warnings are enabled (non-production Node, or browser without NODE_ENV). */
+export function playerDevWarningsEnabled(): boolean {
+  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env
+    ?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+
+const warnedKeys = new Set<string>();
+
+export function warnPlayerMessageOnce(code: string, message: string): void {
+  if (!playerDevWarningsEnabled() || warnedKeys.has(code)) return;
+  warnedKeys.add(code);
+  console.warn(`[qti3-player] ${message}`);
+}

package/src/player-element.ts

@@ -26,7 +26,12 @@ import {
   collectEmbeddedInteractionDiagnostics,
   collectInteractionRenderDiagnostics,
 } from "./interactions/interaction-diagnostics.js";
+import type { PlayerMessageCatalog } from "./player-message-catalog.js";
 import { defaultPlayerLocale, normalizedLocale, resolvePlayerMessages } from "./player-locale.js";
+import type {
+  PlayerMessageResolver,
+  QtiPlayerMessageOverrides,
+} from "./player-message-resolver.js";
 import { syncAttemptAvailability } from "./player/attempt-availability.js";
 import {
   currentTemplateValue,
@@ -48,7 +53,6 @@ import type {
   QtiAssessmentItemPlayerEventDetailMap,
   QtiAssessmentItemPlayerEventName,
   QtiPlayerLoadOptions,
-  QtiPlayerMessageOverrides,
   QtiPlayerResolveAsset,
   QtiPlayerSessionControl,
   QtiScoreAttemptOptions,
@@ -80,11 +84,14 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
   private validationMessages: QtiDiagnostic[] = [];
   private authoringDiagnostics: QtiDiagnostic[] = [];
   private languageOfInterfaceOverride: string | undefined;
+  private messageCatalogOverride: PlayerMessageCatalog | undefined;
   private messageOverrides: QtiPlayerMessageOverrides = {};
+  private resolvedMessagesCache: PlayerMessageResolver | undefined;
   private sessionControl: Required<QtiPlayerSessionControl> = {
     validateResponses: true,
     showFeedback: true,
   };
+  private loadGeneration = 0;
 
   get languageOfInterface(): string {
     return (
@@ -97,6 +104,7 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
 
   set languageOfInterface(value: string | undefined) {
     this.languageOfInterfaceOverride = normalizedLocale(value);
+    this.invalidatePlayerMessages();
     this.rerenderIfLoaded();
   }
 
@@ -114,6 +122,17 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
 
   set messages(value: QtiPlayerMessageOverrides | undefined) {
     this.messageOverrides = value ?? {};
+    this.invalidatePlayerMessages();
+    this.rerenderIfLoaded();
+  }
+
+  get messageCatalog(): PlayerMessageCatalog | undefined {
+    return this.messageCatalogOverride;
+  }
+
+  set messageCatalog(value: PlayerMessageCatalog | undefined) {
+    this.messageCatalogOverride = value;
+    this.invalidatePlayerMessages();
     this.rerenderIfLoaded();
   }
 
@@ -121,15 +140,59 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
     if ((name !== "language-of-interface" && name !== "locale") || oldValue === newValue) {
       return;
     }
+    this.invalidatePlayerMessages();
     this.rerenderIfLoaded();
   }
 
+  private invalidatePlayerMessages(): void {
+    this.resolvedMessagesCache = undefined;
+  }
+
+  /** Clears the loaded item. Does not emit player events; declarative hosts control this via `xml`. */
+  clearItem(): void {
+    this.loadGeneration += 1;
+    delete this.documentModel;
+    delete this.session;
+    this.validationMessages = [];
+    this.authoringDiagnostics = [];
+    this.replaceChildren();
+  }
+
   async loadXml(xml: string, options: QtiPlayerLoadOptions = {}): Promise<void> {
+    const generation = this.beginLoad();
+    await this.applyLoadedXml(generation, xml, options);
+  }
+
+  async loadUrl(url: string, options: QtiPlayerLoadOptions = {}): Promise<void> {
+    const generation = this.beginLoad();
+    const fetchXml = options.fetchXml ?? defaultFetchXml;
+    const xml = await fetchXml(url);
+    if (!this.isCurrentLoad(generation)) return;
+    await this.applyLoadedXml(generation, xml, options);
+  }
+
+  private beginLoad(): number {
+    this.loadGeneration += 1;
+    return this.loadGeneration;
+  }
+
+  private isCurrentLoad(generation: number): boolean {
+    return generation === this.loadGeneration;
+  }
+
+  private async applyLoadedXml(
+    generation: number,
+    xml: string,
+    options: QtiPlayerLoadOptions,
+  ): Promise<void> {
+    if (!this.isCurrentLoad(generation)) return;
+
     this.sessionControl = {
       validateResponses: options.sessionControl?.validateResponses ?? true,
       showFeedback: options.sessionControl?.showFeedback ?? true,
     };
     this.resolveAsset = options.resolveAsset;
+
     const result = parseQtiXml(xml);
     const playerDiagnostics = result.document
       ? [
@@ -137,6 +200,8 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
           ...collectEmbeddedInteractionDiagnostics(result.document.item),
         ]
       : [];
+    if (!this.isCurrentLoad(generation)) return;
+
     this.dispatchEvent(
       new CustomEvent("qti-diagnostics", {
         detail: { diagnostics: [...result.diagnostics, ...playerDiagnostics] },
@@ -146,10 +211,13 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
       playerDiagnostics.filter((diagnostic) => diagnostic.severity === "error"),
     );
     if (!result.document) {
+      if (!this.isCurrentLoad(generation)) return;
       this.replaceChildren(errorView("Unable to parse QTI item."));
       return;
     }
 
+    if (!this.isCurrentLoad(generation)) return;
+
     this.documentModel = result.document;
     this.session = createItemSession(result.document, options.state);
     this.validationMessages = cloneDiagnostics(
@@ -163,11 +231,6 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
     this.emitStateChange();
   }
 
-  async loadUrl(url: string, options: QtiPlayerLoadOptions = {}): Promise<void> {
-    const fetchXml = options.fetchXml ?? defaultFetchXml;
-    await this.loadXml(await fetchXml(url), options);
-  }
-
   scoreAttempt(options: QtiScoreAttemptOptions = {}): QtiScoreResult | undefined {
     const session = this.session;
     if (!session) return undefined;
@@ -288,8 +351,15 @@ export class QtiAssessmentItemPlayer extends HTMLElementBase {
     this.dispatchEvent(new CustomEvent<QtiAssessmentItemPlayerEventDetailMap[T]>(type, { detail }));
   }
 
-  private playerMessages() {
-    return resolvePlayerMessages(this.languageOfInterface, this.messageOverrides);
+  private playerMessages(): PlayerMessageResolver {
+    if (!this.resolvedMessagesCache) {
+      this.resolvedMessagesCache = resolvePlayerMessages(
+        this.languageOfInterface,
+        this.messageOverrides,
+        this.messageCatalogOverride,
+      );
+    }
+    return this.resolvedMessagesCache;
   }
 
   private rerenderIfLoaded(): void {

package/src/player-locale.ts

@@ -1,206 +1,35 @@
-import type { QtiPlayerMessages } from "./player-messages.js";
-import type { QtiPlayerMessageOverrides } from "./player-types.js";
-
-type QtiPlayerMessageCatalog = Readonly<Partial<QtiPlayerMessages>>;
-
-const defaultEnglishPlayerMessages: QtiPlayerMessages = {
-  remove: () => "Remove",
-  removePair: ({ label }) => `Remove ${label}`,
-  clearDrawing: () => "Clear drawing",
-  clearPoints: () => "Clear points",
-  endAttempt: () => "End attempt",
-  uploadResponse: () => "Upload response",
-  movableObject: () => "Movable object",
-  placeObject: () => "Place",
-  inlineChoicePrompt: () => "Choose...",
-  noPointSelected: () => "No point selected",
-  noRegionSelected: () => "No region selected",
-  noAssociationsMade: () => "No associations made",
-  associationsMade: ({ count }) => `${count} ${count === 1 ? "association" : "associations"} made.`,
-  associationPairLabel: ({ source, target }) => `${source} to ${target}`,
-  hotspotSelectedChooseAnother: ({ label }) => `${label} selected. Choose another hotspot.`,
-  moveChoice: ({ label, direction }) => `Move ${label} ${direction}`,
-  movePoint: ({ direction }) => `Move point ${direction}`,
-  moveObject: ({ direction }) => `Move object ${direction}`,
-};
-
-const playerMessages = {
-  defaultEnglish: defaultEnglishPlayerMessages,
-  spanish: {
-    remove: () => "Quitar",
-    removePair: ({ label }) => `Quitar ${label}`,
-    clearDrawing: () => "Borrar dibujo",
-    clearPoints: () => "Borrar puntos",
-    endAttempt: () => "Finalizar intento",
-    uploadResponse: () => "Subir respuesta",
-    movableObject: () => "Objeto movible",
-    placeObject: () => "Colocar",
-    inlineChoicePrompt: () => "Elija...",
-    noPointSelected: () => "Ningun punto seleccionado",
-    noRegionSelected: () => "Ninguna region seleccionada",
-    noAssociationsMade: () => "Ninguna asociacion realizada",
-    associationsMade: ({ count }) =>
-      `${count} ${count === 1 ? "asociacion realizada" : "asociaciones realizadas"}.`,
-    associationPairLabel: ({ source, target }) => `${source} con ${target}`,
-    hotspotSelectedChooseAnother: ({ label }) => `${label} seleccionado. Elija otro punto activo.`,
-    moveChoice: ({ label, direction }) => `Mover ${label} ${spanishDirection(direction)}`,
-    movePoint: ({ direction }) => `Mover punto ${spanishDirection(direction)}`,
-    moveObject: ({ direction }) => `Mover objeto ${spanishDirection(direction)}`,
-  },
-  swedish: {
-    remove: () => "Ta bort",
-    removePair: ({ label }) => `Ta bort ${label}`,
-    clearDrawing: () => "Rensa ritning",
-    clearPoints: () => "Rensa punkter",
-    endAttempt: () => "Avsluta forsok",
-    uploadResponse: () => "Ladda upp svar",
-    movableObject: () => "Flyttbart objekt",
-    placeObject: () => "Placera",
-    inlineChoicePrompt: () => "Valj...",
-    noPointSelected: () => "Ingen punkt vald",
-    noRegionSelected: () => "Ingen region vald",
-    noAssociationsMade: () => "Inga associationer gjorda",
-    associationsMade: ({ count }) =>
-      `${count} ${count === 1 ? "association gjord" : "associationer gjorda"}.`,
-    associationPairLabel: ({ source, target }) => `${source} med ${target}`,
-    hotspotSelectedChooseAnother: ({ label }) => `${label} valt. Valj en annan hotspot.`,
-    moveChoice: ({ label, direction }) => `Flytta ${label} ${swedishDirection(direction)}`,
-    movePoint: ({ direction }) => `Flytta punkt ${swedishDirection(direction)}`,
-    moveObject: ({ direction }) => `Flytta objekt ${swedishDirection(direction)}`,
-  },
-  german: {
-    remove: () => "Entfernen",
-    removePair: ({ label }) => `${label} entfernen`,
-    clearDrawing: () => "Zeichnung loeschen",
-    clearPoints: () => "Punkte loeschen",
-    endAttempt: () => "Versuch beenden",
-    uploadResponse: () => "Antwort hochladen",
-    movableObject: () => "Bewegliches Objekt",
-    placeObject: () => "Platzieren",
-    inlineChoicePrompt: () => "Waehlen...",
-    noPointSelected: () => "Kein Punkt ausgewaehlt",
-    noRegionSelected: () => "Keine Region ausgewaehlt",
-    noAssociationsMade: () => "Keine Zuordnungen erstellt",
-    associationsMade: ({ count }) =>
-      `${count} ${count === 1 ? "Zuordnung erstellt" : "Zuordnungen erstellt"}.`,
-    associationPairLabel: ({ source, target }) => `${source} mit ${target}`,
-    hotspotSelectedChooseAnother: ({ label }) =>
-      `${label} ausgewaehlt. Waehlen Sie einen weiteren Hotspot.`,
-    moveChoice: ({ label, direction }) => `${label} ${germanDirection(direction)} bewegen`,
-    movePoint: ({ direction }) => `Punkt ${germanDirection(direction)} bewegen`,
-    moveObject: ({ direction }) => `Objekt ${germanDirection(direction)} bewegen`,
-  },
-  portuguese: {
-    remove: () => "Remover",
-    removePair: ({ label }) => `Remover ${label}`,
-    clearDrawing: () => "Limpar desenho",
-    clearPoints: () => "Limpar pontos",
-    endAttempt: () => "Finalizar tentativa",
-    uploadResponse: () => "Enviar resposta",
-    movableObject: () => "Objeto movel",
-    placeObject: () => "Posicionar",
-    inlineChoicePrompt: () => "Escolha...",
-    noPointSelected: () => "Nenhum ponto selecionado",
-    noRegionSelected: () => "Nenhuma regiao selecionada",
-    noAssociationsMade: () => "Nenhuma associacao feita",
-    associationsMade: ({ count }) =>
-      `${count} ${count === 1 ? "associacao feita" : "associacoes feitas"}.`,
-    associationPairLabel: ({ source, target }) => `${source} com ${target}`,
-    hotspotSelectedChooseAnother: ({ label }) => `${label} selecionado. Escolha outro ponto ativo.`,
-    moveChoice: ({ label, direction }) => `Mover ${label} ${portugueseDirection(direction)}`,
-    movePoint: ({ direction }) => `Mover ponto ${portugueseDirection(direction)}`,
-    moveObject: ({ direction }) => `Mover objeto ${portugueseDirection(direction)}`,
-  },
-  french: {
-    remove: () => "Supprimer",
-    removePair: ({ label }) => `Supprimer ${label}`,
-    clearDrawing: () => "Effacer le dessin",
-    clearPoints: () => "Effacer les points",
-    endAttempt: () => "Terminer la tentative",
-    uploadResponse: () => "Televerser la reponse",
-    movableObject: () => "Objet mobile",
-    placeObject: () => "Placer",
-    inlineChoicePrompt: () => "Choisir...",
-    noPointSelected: () => "Aucun point selectionne",
-    noRegionSelected: () => "Aucune region selectionnee",
-    noAssociationsMade: () => "Aucune association effectuee",
-    associationsMade: ({ count }) =>
-      `${count} ${count === 1 ? "association effectuee" : "associations effectuees"}.`,
-    associationPairLabel: ({ source, target }) => `${source} avec ${target}`,
-    hotspotSelectedChooseAnother: ({ label }) =>
-      `${label} selectionne. Choisissez un autre point actif.`,
-    moveChoice: ({ label, direction }) => `Deplacer ${label} vers ${frenchDirection(direction)}`,
-    movePoint: ({ direction }) => `Deplacer le point vers ${frenchDirection(direction)}`,
-    moveObject: ({ direction }) => `Deplacer l'objet vers ${frenchDirection(direction)}`,
-  },
-} satisfies Record<string, QtiPlayerMessageCatalog>;
-
-const builtInPlayerMessageCatalogs: ReadonlyMap<string, QtiPlayerMessageCatalog> = new Map([
-  ["en", playerMessages.defaultEnglish],
-  ["es", playerMessages.spanish],
-  ["es-es", playerMessages.spanish],
-  ["es-mx", playerMessages.spanish],
-  ["sv", playerMessages.swedish],
-  ["sv-se", playerMessages.swedish],
-  ["de", playerMessages.german],
-  ["de-de", playerMessages.german],
-  ["pt", playerMessages.portuguese],
-  ["pt-br", playerMessages.portuguese],
-  ["pt-pt", playerMessages.portuguese],
-  ["fr", playerMessages.french],
-  ["fr-ca", playerMessages.french],
-  ["fr-fr", playerMessages.french],
-]);
-
+import type { PlayerMessageCatalog } from "./player-message-catalog.js";
+import { applyPlayerMessageOverrides } from "./player-message-overrides.js";
+import {
+  createPlayerMessageResolver,
+  defaultPlayerMessageResolver,
+  type PlayerMessageResolver,
+} from "./player-message-resolver.js";
+import { warnPlayerMessageOnce } from "./player-dev.js";
+import type { QtiPlayerMessageOverrides } from "./player-message-resolver.js";
+
+function isEnglishLocale(locale: string): boolean {
+  const normalized = normalizedLocale(locale) ?? locale;
+  return normalized.toLowerCase().startsWith("en");
+}
+
+/**
+ * Resolves player chrome messages: catalog (or English defaults) merged with overrides.
+ * `locale` does not select built-in catalogs; use `catalog` via `player.messageCatalog`.
+ */
 export function resolvePlayerMessages(
   locale: string,
   overrides: QtiPlayerMessageOverrides,
-): QtiPlayerMessages {
-  const catalog = builtInPlayerMessageCatalog(locale);
-  return { ...defaultEnglishPlayerMessages, ...catalog, ...overrides };
-}
-
-function spanishDirection(direction: "up" | "down" | "left" | "right"): string {
-  return { up: "arriba", down: "abajo", left: "a la izquierda", right: "a la derecha" }[direction];
-}
-
-function swedishDirection(direction: "up" | "down" | "left" | "right"): string {
-  return { up: "upp", down: "ned", left: "vanster", right: "hoger" }[direction];
-}
-
-function germanDirection(direction: "up" | "down" | "left" | "right"): string {
-  return { up: "nach oben", down: "nach unten", left: "nach links", right: "nach rechts" }[
-    direction
-  ];
-}
-
-function portugueseDirection(direction: "up" | "down" | "left" | "right"): string {
-  return { up: "para cima", down: "para baixo", left: "para a esquerda", right: "para a direita" }[
-    direction
-  ];
-}
-
-function frenchDirection(direction: "up" | "down" | "left" | "right"): string {
-  return { up: "le haut", down: "le bas", left: "la gauche", right: "la droite" }[direction];
-}
-
-function builtInPlayerMessageCatalog(locale: string): QtiPlayerMessageCatalog | undefined {
-  for (const candidate of localeFallbacks(locale)) {
-    const catalog = builtInPlayerMessageCatalogs.get(candidate);
-    if (catalog) return catalog;
-  }
-  return undefined;
-}
-
-function localeFallbacks(locale: string): string[] {
-  const normalized = normalizedLocale(locale)?.toLowerCase();
-  if (!normalized) return ["en"];
-  const parts = normalized.split("-");
-  const fallbacks: string[] = [];
-  for (let length = parts.length; length > 0; length -= 1) {
-    fallbacks.push(parts.slice(0, length).join("-"));
+  catalog?: PlayerMessageCatalog,
+): PlayerMessageResolver {
+  if (!catalog && !isEnglishLocale(locale) && Object.keys(overrides).length === 0) {
+    warnPlayerMessageOnce(
+      `locale-without-catalog:${locale}`,
+      `language-of-interface is "${locale}" but no player.messageCatalog was set; chrome stays English. Load a locale file and assign player.messageCatalog.`,
+    );
   }
-  return fallbacks.includes("en") ? fallbacks : [...fallbacks, "en"];
+  const base = catalog ? createPlayerMessageResolver(catalog) : defaultPlayerMessageResolver;
+  return applyPlayerMessageOverrides(base, overrides);
 }
 
 export function normalizedLocale(value: string | undefined | null): string | undefined {