@pie-players/pie-assessment-toolkit 0.3.67 → 0.3.68

package/dist/runtime/SectionRuntimeEngine.d.ts

@@ -48,6 +48,7 @@ import type { SectionEngineInput } from "./core/engine-input.js";
 import type { SectionEngineOutput } from "./core/engine-output.js";
 import { type EffectiveRuntime, type RuntimeInputs } from "./core/engine-resolver.js";
 import { type SectionEngineState } from "./core/engine-state.js";
+import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
 import type { RuntimeRegistrationDetail } from "./registration-events.js";
 import { RuntimeRegistry } from "./RuntimeRegistry.js";
 /**
@@ -95,6 +96,27 @@ interface RuntimeController extends SectionControllerHandle {
     } | null;
     subscribe?: (listener: (event: SectionControllerEvent) => void) => () => void;
     navigateToItem?: (index: number) => unknown;
+    attachMediaTimeSource?: (source: MediaTimeSource, options?: {
+        origin?: "native-adapter" | "host";
+        renderableId?: string;
+    }) => void;
+    detachMediaTimeSource?: (options?: {
+        origin?: "native-adapter" | "host";
+    }) => void;
+    pauseMediaForCompetingAudio?: () => boolean;
+}
+/** What a media-time-source registration reaching the engine has to say. */
+export interface SectionRuntimeMediaTimeSourceAction {
+    renderableId: string;
+    action: "attach" | "detach";
+    source?: MediaTimeSource;
+    origin?: "native-adapter" | "host";
+}
+/** What a formative action reaching the engine has to say. */
+export interface SectionRuntimeFormativeAction {
+    itemId: string;
+    action: "check" | "retry";
+    outcomes?: unknown[];
 }
 /**
  * Initialize args used by the toolkit CE to resolve the coordinator-backed
@@ -109,6 +131,14 @@ interface EngineInitArgs {
     attemptId?: string;
     createDefaultController: () => Promise<RuntimeController> | RuntimeController;
     onCompositionChanged?: (composition: unknown) => void;
+    /**
+     * The controller event that caused a republish, for the few events the toolkit
+     * has to act on rather than merely propagate — a timed-media policy that cannot
+     * be enforced becomes a framework warning, and malformed cue data becomes a
+     * framework error. Every other event reaches hosts through the composition
+     * republish and the coordinator's own subscriptions.
+     */
+    onControllerEvent?: (event: SectionControllerEvent) => void;
 }
 /**
  * Engine-side `attachHost` args. The host element, framework-error bus,
@@ -273,6 +303,32 @@ export declare class SectionRuntimeEngine {
     }): void;
     updateItemSession(itemId: string, session: unknown): unknown;
     navigateToItem(index: number): unknown;
+    /**
+     * Route a learner's formative action to the controller.
+     *
+     * Canonicalized here for the same reason `updateItemSession` is: the runtime
+     * id a card dispatches with is not necessarily the identifier the controller
+     * keys state by.
+     */
+    handleFormativeAction(action: SectionRuntimeFormativeAction): void;
+    /**
+     * Bind or release the section's Media Time Source.
+     *
+     * A pass-through, like `handleFormativeAction`: the engine routes, the
+     * controller decides. `renderableId` travels with the attach because whether the
+     * registering renderable is the one `stimulusRef` names is the controller's call
+     * — it validated `stimulusRef` in the first place.
+     */
+    handleMediaTimeSource(action: SectionRuntimeMediaTimeSourceAction): void;
+    /**
+     * Silence media audio because something else is about to speak.
+     *
+     * A pass-through like `handleMediaTimeSource`, and for the same reason: which
+     * source is authoritative and whether it reports `canPause` are the controller's
+     * to know. Returns whether media audio is now silent, or `true` where there is
+     * no timed-media controller to ask — nothing is playing.
+     */
+    requestMediaPauseForCompetingAudio(): boolean;
     persist(): Promise<void>;
     hydrate(): Promise<void>;
     getRegistry(): RuntimeRegistry;

package/dist/runtime/SectionRuntimeEngine.js

@@ -41,8 +41,10 @@
 import { SectionEngineAdapter, } from "./adapter/SectionEngineAdapter.js";
 import { resolveSectionEngineRuntimeState, } from "./core/engine-resolver.js";
 import { createInitialEngineState, } from "./core/engine-state.js";
+import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared";
 import { RuntimeRegistry } from "./RuntimeRegistry.js";
 import { createRuntimeId } from "./runtime-id.js";
+const logger = createPieLogger("section-runtime-engine", () => isGlobalDebugEnabled());
 export class SectionRuntimeEngine {
     registry = new RuntimeRegistry();
     runtimeId = createRuntimeId("section-engine");
@@ -209,7 +211,17 @@ export class SectionRuntimeEngine {
         this.replayRegisteredShellsIntoController(resolved);
         args.onCompositionChanged?.(resolved.getCompositionModel?.());
         this.unsubscribeController =
-            resolved.subscribe?.(() => {
+            resolved.subscribe?.((event) => {
+                // Isolated deliberately: the controller's emit loop catches per
+                // listener, so a diagnostic handler that throws would take the
+                // composition republish down with it and every cue and Try would stop
+                // reaching the cards — a failure with no symptom except a warning.
+                try {
+                    args.onControllerEvent?.(event);
+                }
+                catch (error) {
+                    logger.warn("onControllerEvent handler threw", error);
+                }
                 args.onCompositionChanged?.(resolved.getCompositionModel?.());
             }) || null;
     }
@@ -333,6 +345,59 @@ export class SectionRuntimeEngine {
     navigateToItem(index) {
         return this.controller?.navigateToItem?.(index) ?? null;
     }
+    /**
+     * Route a learner's formative action to the controller.
+     *
+     * Canonicalized here for the same reason `updateItemSession` is: the runtime
+     * id a card dispatches with is not necessarily the identifier the controller
+     * keys state by.
+     */
+    handleFormativeAction(action) {
+        if (!action?.itemId)
+            return;
+        const canonicalId = this.getCanonicalItemId(action.itemId);
+        if (action.action === "retry") {
+            this.controller?.retryFormativeItem?.({ itemId: canonicalId });
+            return;
+        }
+        this.controller?.recordFormativeTry?.({
+            itemId: canonicalId,
+            outcomes: action.outcomes,
+        });
+    }
+    /**
+     * Bind or release the section's Media Time Source.
+     *
+     * A pass-through, like `handleFormativeAction`: the engine routes, the
+     * controller decides. `renderableId` travels with the attach because whether the
+     * registering renderable is the one `stimulusRef` names is the controller's call
+     * — it validated `stimulusRef` in the first place.
+     */
+    handleMediaTimeSource(action) {
+        if (action?.action === "detach") {
+            this.controller?.detachMediaTimeSource?.({
+                origin: action.origin ?? "host",
+            });
+            return;
+        }
+        if (!action?.source)
+            return;
+        this.controller?.attachMediaTimeSource?.(action.source, {
+            origin: action.origin ?? "host",
+            renderableId: action.renderableId,
+        });
+    }
+    /**
+     * Silence media audio because something else is about to speak.
+     *
+     * A pass-through like `handleMediaTimeSource`, and for the same reason: which
+     * source is authoritative and whether it reports `canPause` are the controller's
+     * to know. Returns whether media audio is now silent, or `true` where there is
+     * no timed-media controller to ask — nothing is playing.
+     */
+    requestMediaPauseForCompetingAudio() {
+        return this.controller?.pauseMediaForCompetingAudio?.() ?? true;
+    }
     async persist() {
         await this.controller?.persist?.();
     }

package/dist/runtime/core/engine-resolver.d.ts

@@ -68,6 +68,18 @@ export type RuntimeConfig = {
      * markup (the default). Purely visual — no engine effect.
      */
     ndsIcons?: boolean;
+    /**
+     * Interface locale: a BCP-47 tag naming the language the player renders its own
+     * UI in. Purely presentational — no engine effect.
+     *
+     * Distinct from content language, which describes the authored item and
+     * travels on `env`. QTI 3's implementation guide states the independence
+     * directly: a candidate may choose an interface language which may or may not
+     * also be the language of the content.
+     *
+     * Unset renders `en-US`. POSIX (`nl_NL`) and bare (`nl`) forms both resolve.
+     */
+    locale?: string;
     toolConfigStrictness?: ToolConfigStrictness;
     onFrameworkError?: FrameworkErrorHandler;
     onStageChange?: StageChangeHandler;
@@ -120,7 +132,7 @@ export declare function resolveRuntime(args: {
     createSectionController: unknown;
     isolation: string;
     env: Record<string, unknown>;
-    toolConfigStrictness: "off" | "warn" | "error";
+    toolConfigStrictness: "off" | "error" | "warn";
     onFrameworkError: FrameworkErrorHandler | undefined;
     onStageChange: StageChangeHandler | undefined;
     onLoadingComplete: LoadingCompleteHandler | undefined;
@@ -134,6 +146,18 @@ export declare function resolveRuntime(args: {
      * markup (the default). Purely visual — no engine effect.
      */
     ndsIcons?: boolean;
+    /**
+     * Interface locale: a BCP-47 tag naming the language the player renders its own
+     * UI in. Purely presentational — no engine effect.
+     *
+     * Distinct from content language, which describes the authored item and
+     * travels on `env`. QTI 3's implementation guide states the independence
+     * directly: a candidate may choose an interface language which may or may not
+     * also be the language of the content.
+     *
+     * Unset renders `en-US`. POSIX (`nl_NL`) and bare (`nl`) forms both resolve.
+     */
+    locale?: string;
 };
 /**
  * Effective runtime returned by `resolveRuntime`. The shape is exposed

package/dist/runtime/registration-events.d.ts

@@ -1,9 +1,12 @@
+import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
 export declare const PIE_REGISTER_EVENT = "pie-register";
 export declare const PIE_UNREGISTER_EVENT = "pie-unregister";
 export declare const PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT = "pie-item-session-changed";
 export declare const PIE_ITEM_SESSION_CHANGED_EVENT = "item-session-changed";
 export declare const PIE_INTERNAL_CONTENT_LOADED_EVENT = "pie-content-loaded";
 export declare const PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT = "pie-item-player-error";
+export declare const PIE_INTERNAL_FORMATIVE_ACTION_EVENT = "pie-formative-action";
+export declare const PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT = "pie-media-time-source";
 export type RuntimeRegistrationKind = "item" | "passage";
 export interface RuntimeRegistrationDetail {
     kind: RuntimeRegistrationKind;
@@ -35,3 +38,52 @@ export interface InternalItemPlayerErrorDetail {
     contentKind?: string;
     error: unknown;
 }
+/**
+ * A learner's formative action, dispatched by the component that owns the
+ * control and the item player node — the only place that can call
+ * `provideScore()`. It reports outcomes rather than interpreting them; the
+ * section controller derives correctness and owns the state.
+ *
+ * `outcomes` is the array `pie-item-player.provideScore()` returned, verbatim,
+ * including the `undefined` slots it leaves for models with no element or
+ * controller.
+ */
+export interface InternalFormativeActionDetail {
+    itemId: string;
+    canonicalItemId?: string;
+    action: "check" | "retry";
+    outcomes?: unknown[];
+}
+/**
+ * A Media Time Source becoming available or going away.
+ *
+ * The one seam through which a timed-media section reaches media, and
+ * deliberately the *only* one: the stimulus card dispatches this with a native
+ * `<video>` adapter, and a host wrapping a third-party player dispatches the same
+ * event with its own port. One code path, two producers — which is what keeps
+ * "a host can supply its own media element without shipping a PIE element" true
+ * rather than aspirational.
+ *
+ * `source` carries a live object, not serializable data. That is fine and
+ * intended: this event never crosses a realm, exactly like the element reference
+ * on `pie-register`.
+ */
+export interface InternalMediaTimeSourceDetail {
+    /** The renderable that owns the media, for matching against `stimulusRef`. */
+    renderableId: string;
+    action: "attach" | "detach";
+    source?: MediaTimeSource;
+    /**
+     * Which producer this came from. `"native-adapter"` is the stimulus card
+     * wrapping a media element it found in its own subtree; anything else is a host
+     * wiring its own player, and omitting the field reads as `"host"` because a
+     * caller constructing this event by hand is one.
+     *
+     * Load-bearing for precedence: the card re-runs its discovery whenever its
+     * content changes, so without this a host that supplied a third-party port would
+     * have it silently replaced by the native element mid-session — and the
+     * capabilities would flip back with it, which is exactly the "appears to enforce"
+     * failure this contract exists to prevent.
+     */
+    origin?: "native-adapter" | "host";
+}

package/dist/runtime/registration-events.js

@@ -4,3 +4,5 @@ export const PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT = "pie-item-session-changed
 export const PIE_ITEM_SESSION_CHANGED_EVENT = "item-session-changed";
 export const PIE_INTERNAL_CONTENT_LOADED_EVENT = "pie-content-loaded";
 export const PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT = "pie-item-player-error";
+export const PIE_INTERNAL_FORMATIVE_ACTION_EVENT = "pie-formative-action";
+export const PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT = "pie-media-time-source";

package/dist/services/AccessibilityCatalogResolver.js

@@ -1,3 +1,4 @@
+import { languageTagLookupSequence, normalizeLanguageTag, } from "@pie-players/pie-players-shared/i18n/language-tags";
 import { catalogOwnerContextFor, collectOwnerCatalogRegistrations, } from "./catalog-owner.js";
 import { sanitizeSsmlString } from "./SSMLExtractor.js";
 /**
@@ -537,14 +538,25 @@ export class AccessibilityCatalogResolver {
      */
     findMatchingCard(catalog, options) {
         const { type, language, useFallback = true, form } = options;
-        // Language rungs, most specific first: requested language, then the default
-        // language, then any. Unchanged — only what happens *within* a rung is new.
+        // Language rungs, most specific first: the requested language, then the
+        // default language, then any.
+        //
+        // Each requested tag expands into its RFC 4647 lookup sequence, so `es-MX`
+        // tries `es-mx` and then `es` before falling through to the default. Matching
+        // was `===`, which made a POSIX `es_ES` card — what the Learnosity transform
+        // emits — unreachable for an `es-ES` request except through the final
+        // no-constraint rung, i.e. by accident.
         const languageRungs = [];
+        const pushLookupRungs = (tag) => {
+            for (const step of languageTagLookupSequence(tag)) {
+                languageRungs.push((card) => normalizeLanguageTag(card.language) === step);
+            }
+        };
         if (language) {
-            languageRungs.push((card) => card.language === language);
+            pushLookupRungs(language);
         }
         if (useFallback) {
-            languageRungs.push((card) => card.language === this.defaultLanguage);
+            pushLookupRungs(this.defaultLanguage);
             languageRungs.push(() => true);
         }
         for (const matchesLanguage of languageRungs) {
@@ -586,7 +598,11 @@ export class AccessibilityCatalogResolver {
         // asking what alternates exist under-reported them.
         const claimed = new Set();
         const add = (card, source) => {
-            const key = `${card.catalog}|${card.language ?? ""}|${catalogCardForm(card)}`;
+            // The language part is normalized, so a POSIX `es_ES` card and a BCP-47
+            // `es-ES` card collapse to one entry here exactly as they now collapse on
+            // the resolution path. Keying on the raw string would report two
+            // alternates where resolution can only ever return one.
+            const key = `${card.catalog}|${normalizeLanguageTag(card.language)}|${catalogCardForm(card)}`;
             if (claimed.has(key))
                 return;
             claimed.add(key);

package/dist/services/I18nService.d.ts

@@ -1,119 +1,47 @@
 /**
  * I18nService
  *
- * Internationalization service with hybrid loading strategy.
- * Manages translations, locale switching, and RTL/LTR direction.
+ * The toolkit's view of the shared i18n provider: a delegating wrapper over
+ * `SimpleI18n` from `players-shared` that adds toolkit-scoped logging and wires
+ * the lazy catalog loaders.
  *
- * Features:
- * - Subscriber/listener pattern for reactive updates
- * - Hybrid loading: Bundle English, lazy-load other locales
- * - Interpolation: {variable} syntax
- * - Pluralization: ICU-style plural rules
- * - RTL detection: Automatic based on locale
- * - Fallback to English for missing keys
+ * It was once a near-verbatim second copy of that class — same fields, same
+ * lookup, same plural selection. Duplicate implementations of one contract drift
+ * silently, because nothing fails when only one of them is fixed. Keep this a
+ * wrapper.
  *
  * Part of PIE Assessment Toolkit.
  */
-import type { I18nConfig, I18nServiceApi, PluralTranslation, TranslationBundle } from "@pie-players/pie-players-shared/i18n";
-export type { I18nConfig, I18nServiceApi, PluralTranslation, TranslationBundle, };
+import type { I18nConfig, I18nProvider, I18nServiceApi, InterpolationValues, LocaleCode, MessageCatalog, MessageKeyInput, PluralOptions, TextDirection } from "@pie-players/pie-players-shared/i18n";
+export type { I18nConfig, I18nProvider, I18nServiceApi, InterpolationValues, LocaleCode, MessageCatalog, MessageKeyInput, PluralOptions, TextDirection, };
 /**
- * I18nService
+ * Toolkit-scoped i18n service.
  *
- * Manages internationalization with reactive state updates.
+ * Serves every locale this repository ships, English resident and the rest
+ * lazily loaded.
  */
 export declare class I18nService implements I18nServiceApi {
-    private locale;
-    private fallbackLocale;
-    private direction;
-    private translations;
-    private listeners;
-    private loadingPromises;
-    private config;
+    private readonly i18n;
     constructor(config?: I18nConfig);
     /**
-     * Initialize i18n with locale and loading strategy
-     */
-    initialize(config: I18nConfig): Promise<void>;
-    /**
-     * Translate a key with optional interpolation
-     *
-     * @param key Translation key (e.g., 'common.save')
-     * @param params Optional parameters for interpolation
-     * @returns Translated string
-     */
-    t(key: string, params?: Record<string, any>): string;
-    /**
-     * Translate with pluralization
+     * Set the locale, loading its catalog first.
      *
-     * @param key Translation key
-     * @param count Count for pluralization
-     * @param params Optional parameters for interpolation
-     * @returns Translated string with plural form
-     */
-    tn(key: string, count: number, params?: Record<string, any>): string;
-    /**
-     * Get current locale
+     * Never falls back to the browser locale: a rendered-string change reaches a
+     * host's live delivery on their next install with no build signal on their
+     * side, so the locale has to be something the host asked for.
      */
+    initialize(config: I18nConfig): Promise<void>;
+    t(key: MessageKeyInput, values?: InterpolationValues): string;
+    plural(key: MessageKeyInput, options: PluralOptions): string;
     getLocale(): string;
-    /**
-     * Change locale (triggers async loading if needed)
-     *
-     * @param locale Locale code (e.g., 'en', 'es', 'zh', 'ar')
-     */
-    setLocale(locale: string): Promise<void>;
-    /**
-     * Get current text direction
-     */
-    getDirection(): "ltr" | "rtl";
-    /**
-     * Get available locales
-     */
+    setLocale(locale: LocaleCode): Promise<void>;
+    getDirection(): TextDirection;
     getAvailableLocales(): string[];
-    /**
-     * Check if locale is loaded
-     */
-    isLocaleLoaded(locale: string): boolean;
-    /**
-     * Subscribe to locale/translation changes
-     * Returns unsubscribe function
-     */
+    isLocaleLoaded(locale: LocaleCode): boolean;
     subscribe(listener: () => void): () => void;
-    /**
-     * Check if a translation key exists
-     */
-    hasKey(key: string): boolean;
-    /**
-     * Notify all listeners of state change
-     */
-    private notifyListeners;
-    /**
-     * Apply locale and notify listeners
-     */
-    private applyLocale;
-    /**
-     * Apply direction to DOM
-     */
-    private applyDOMDirection;
-    /**
-     * Load translations for a locale
-     */
-    private loadTranslationsForLocale;
-    /**
-     * Get translation for a key
-     */
-    private getTranslation;
-    /**
-     * Interpolate variables in translation string
-     * Replaces {variable} with params.variable
-     */
-    private interpolate;
-    /**
-     * Select plural form based on count and locale
-     * Simplified implementation - real implementation would use Intl.PluralRules
-     */
-    private selectPluralForm;
-    /**
-     * Detect browser locale
-     */
-    private detectBrowserLocale;
+    hasKey(key: MessageKeyInput): boolean;
+    addCustomMessages(locale: string, messages: MessageCatalog): void;
+    withLocale(locale: LocaleCode): I18nProvider;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string;
 }