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

package/dist/services/I18nService.js

@@ -1,274 +1,84 @@
 /**
  * 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 { createPieI18n } from "@pie-players/pie-players-shared/i18n";
 import { createLogger } from "../utils/logger.js";
 const log = createLogger("I18nService");
 /**
- * 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 class I18nService {
-    locale = "en";
-    fallbackLocale = "en";
-    direction = "ltr";
-    translations = new Map();
-    listeners = new Set();
-    loadingPromises = new Map();
-    config;
+    i18n;
     constructor(config = {}) {
-        this.config = config;
-        this.fallbackLocale = config.fallbackLocale || "en";
-        log("I18nService initialized", { fallbackLocale: this.fallbackLocale });
-        // Load bundled translations (English by default)
-        if (config.bundledTranslations) {
-            for (const [locale, bundle] of Object.entries(config.bundledTranslations)) {
-                this.translations.set(locale, bundle);
-                log(`Loaded bundled translations for: ${locale}`);
-            }
-        }
+        this.i18n = createPieI18n(config);
+        log("I18nService created", {
+            locale: this.i18n.getLocale(),
+            fallbackLocale: config.fallbackLocale ?? "en-US",
+        });
     }
     /**
-     * Initialize i18n with locale and loading strategy
+     * Set the locale, loading its catalog first.
+     *
+     * 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.
      */
     async initialize(config) {
-        Object.assign(this.config, config);
-        const locale = config.locale || this.detectBrowserLocale();
-        log(`Initializing with locale: ${locale}`);
-        await this.setLocale(locale);
+        log(`Initializing with locale: ${config.locale ?? this.i18n.getLocale()}`);
+        await this.i18n.initialize(config);
     }
-    /**
-     * 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, params) {
-        const translation = this.getTranslation(key);
-        return this.interpolate(translation, params);
+    t(key, values) {
+        return this.i18n.t(key, values);
     }
-    /**
-     * Translate with pluralization
-     *
-     * @param key Translation key
-     * @param count Count for pluralization
-     * @param params Optional parameters for interpolation
-     * @returns Translated string with plural form
-     */
-    tn(key, count, params) {
-        const translation = this.getTranslation(key);
-        if (typeof translation === "object") {
-            const pluralForm = this.selectPluralForm(count, this.locale);
-            const text = translation[pluralForm] || translation.other;
-            return this.interpolate(text, { ...params, count });
-        }
-        return this.interpolate(translation, { ...params, count });
+    plural(key, options) {
+        return this.i18n.plural(key, options);
     }
-    /**
-     * Get current locale
-     */
     getLocale() {
-        return this.locale;
+        return this.i18n.getLocale();
     }
-    /**
-     * Change locale (triggers async loading if needed)
-     *
-     * @param locale Locale code (e.g., 'en', 'es', 'zh', 'ar')
-     */
     async setLocale(locale) {
         log(`Setting locale to: ${locale}`);
-        // Check if already loading
-        if (this.loadingPromises.has(locale)) {
-            log(`Locale ${locale} is already loading, waiting...`);
-            await this.loadingPromises.get(locale);
-            return;
-        }
-        // Check if already loaded
-        if (this.translations.has(locale)) {
-            log(`Locale ${locale} already loaded`);
-            this.applyLocale(locale);
-            return;
-        }
-        // Load translations
-        const loadingPromise = this.loadTranslationsForLocale(locale);
-        this.loadingPromises.set(locale, loadingPromise);
-        try {
-            await loadingPromise;
-            this.applyLocale(locale);
-        }
-        finally {
-            this.loadingPromises.delete(locale);
-        }
+        await this.i18n.setLocale(locale);
     }
-    /**
-     * Get current text direction
-     */
     getDirection() {
-        return this.direction;
+        return this.i18n.getDirection();
     }
-    /**
-     * Get available locales
-     */
     getAvailableLocales() {
-        return Array.from(this.translations.keys());
+        return this.i18n.getAvailableLocales();
     }
-    /**
-     * Check if locale is loaded
-     */
     isLocaleLoaded(locale) {
-        return this.translations.has(locale);
+        return this.i18n.isLocaleLoaded(locale);
     }
-    /**
-     * Subscribe to locale/translation changes
-     * Returns unsubscribe function
-     */
     subscribe(listener) {
-        this.listeners.add(listener);
-        return () => {
-            this.listeners.delete(listener);
-        };
+        return this.i18n.subscribe(listener);
     }
-    /**
-     * Check if a translation key exists
-     */
     hasKey(key) {
-        const bundle = this.translations.get(this.locale);
-        return !!bundle?.translations[key];
-    }
-    /**
-     * Notify all listeners of state change
-     */
-    notifyListeners() {
-        this.listeners.forEach((listener) => listener());
-    }
-    /**
-     * Apply locale and notify listeners
-     */
-    applyLocale(locale) {
-        const bundle = this.translations.get(locale);
-        if (!bundle) {
-            log(`No bundle found for locale: ${locale}`, "warn");
-            return;
-        }
-        const previousLocale = this.locale;
-        this.locale = locale;
-        this.direction = bundle.direction;
-        log(`Applied locale: ${locale} (direction: ${this.direction})`);
-        this.applyDOMDirection();
-        this.notifyListeners();
-    }
-    /**
-     * Apply direction to DOM
-     */
-    applyDOMDirection() {
-        if (typeof document === "undefined")
-            return;
-        document.documentElement.setAttribute("dir", this.direction);
-        document.documentElement.setAttribute("lang", this.locale);
-        log(`Applied DOM attributes: dir="${this.direction}" lang="${this.locale}"`);
-    }
-    /**
-     * Load translations for a locale
-     */
-    async loadTranslationsForLocale(locale) {
-        if (!this.config.loadTranslations) {
-            throw new Error(`No translation loader configured for locale: ${locale}`);
-        }
-        log(`Loading translations for: ${locale}`);
-        try {
-            const bundle = await this.config.loadTranslations(locale);
-            this.translations.set(locale, bundle);
-            log(`Loaded translations for: ${locale} (${Object.keys(bundle.translations).length} keys)`);
-        }
-        catch (error) {
-            log(`Failed to load translations for: ${locale}`, "error");
-            throw error;
-        }
+        return this.i18n.hasKey(key);
     }
-    /**
-     * Get translation for a key
-     */
-    getTranslation(key) {
-        // Try current locale
-        const currentBundle = this.translations.get(this.locale);
-        if (currentBundle?.translations[key]) {
-            return currentBundle.translations[key];
-        }
-        // Try fallback locale
-        const fallbackBundle = this.translations.get(this.fallbackLocale);
-        if (fallbackBundle?.translations[key]) {
-            if (this.config.debug) {
-                log(`Using fallback translation for key: ${key}`);
-            }
-            return fallbackBundle.translations[key];
-        }
-        // Missing key handling
-        if (this.config.onMissingKey) {
-            this.config.onMissingKey(key, this.locale);
-        }
-        if (this.config.debug) {
-            log(`Missing translation key: ${key} (locale: ${this.locale})`, "warn");
-        }
-        return key;
+    addCustomMessages(locale, messages) {
+        this.i18n.addCustomMessages(locale, messages);
     }
-    /**
-     * Interpolate variables in translation string
-     * Replaces {variable} with params.variable
-     */
-    interpolate(text, params) {
-        if (!params)
-            return text;
-        return text.replace(/\{(\w+)\}/g, (match, key) => {
-            return params[key]?.toString() || match;
-        });
+    withLocale(locale) {
+        return this.i18n.withLocale(locale);
     }
-    /**
-     * Select plural form based on count and locale
-     * Simplified implementation - real implementation would use Intl.PluralRules
-     */
-    selectPluralForm(count, locale) {
-        // Use Intl.PluralRules if available
-        if (typeof Intl !== "undefined" && Intl.PluralRules) {
-            try {
-                const rules = new Intl.PluralRules(locale);
-                const category = rules.select(count);
-                return category;
-            }
-            catch (error) {
-                log(`Failed to use Intl.PluralRules for locale: ${locale}`, "warn");
-            }
-        }
-        // Fallback to simple rules
-        if (count === 0)
-            return "zero";
-        if (count === 1)
-            return "one";
-        return "other";
+    formatNumber(value, options) {
+        return this.i18n.formatNumber?.(value, options) ?? String(value);
     }
-    /**
-     * Detect browser locale
-     */
-    detectBrowserLocale() {
-        if (typeof navigator === "undefined")
-            return "en";
-        const browserLang = navigator.language ||
-            (navigator.languages && navigator.languages[0]) ||
-            "en";
-        // Extract language code (e.g., 'en-US' -> 'en')
-        return browserLang.split("-")[0];
+    formatDate(date, options) {
+        return this.i18n.formatDate?.(date, options) ?? date.toISOString();
     }
 }

package/dist/services/TTSService.d.ts

@@ -109,6 +109,18 @@ export declare class TTSService {
     setHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;
     /**
      * Set a late-bound provider for optional host TTS highlight target remapping.
+     *
+     * The returned disposer is the only thing that clears the registration: the
+     * caller owns the lifetime, and a provider installed once keeps remapping
+     * across stops, seek-restarts and later playbacks. Playback termination used to
+     * clear it in `stop()` and on both exits of `restartFromSeekIndex`, which left a
+     * host that installs before mount — the case a late-bound provider exists for —
+     * remapping exactly one playback and then silently falling back to identity.
+     *
+     * Installing again replaces the previous provider, so a caller that reinstalls
+     * per playback needs no disposal between them. A stale provider cannot paint
+     * outside its scope in any case: targets are validated by containment in
+     * `context.scopeElement` and a failing one falls back to its native range.
      */
     setHighlightTargetResolverProvider(provider: TTSHighlightTargetResolverProvider | null): () => void;
     /**

package/dist/services/TTSService.js

@@ -15,7 +15,7 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import { applyMediaFragment } from "./catalog-media.js";
+import { applyMediaFragment, enforceMediaFragment } from "./catalog-media.js";
 import { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
 import { resolveSpokenAudioMedia, } from "./spoken-audio-cards.js";
 import { BrowserTTSProvider } from "./tts/browser-provider.js";
@@ -282,6 +282,18 @@ export class TTSService {
     }
     /**
      * Set a late-bound provider for optional host TTS highlight target remapping.
+     *
+     * The returned disposer is the only thing that clears the registration: the
+     * caller owns the lifetime, and a provider installed once keeps remapping
+     * across stops, seek-restarts and later playbacks. Playback termination used to
+     * clear it in `stop()` and on both exits of `restartFromSeekIndex`, which left a
+     * host that installs before mount — the case a late-bound provider exists for —
+     * remapping exactly one playback and then silently falling back to identity.
+     *
+     * Installing again replaces the previous provider, so a caller that reinstalls
+     * per playback needs no disposal between them. A stale provider cannot paint
+     * outside its scope in any case: targets are validated by containment in
+     * `context.scopeElement` and a failing one falls back to its native range.
      */
     setHighlightTargetResolverProvider(provider) {
         this.highlightTargetResolverProvider = provider;
@@ -1731,7 +1743,7 @@ export class TTSService {
         element.src = applyMediaFragment(source.src, media.fragment);
         element.playbackRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate || 1));
         await new Promise((resolve, reject) => {
-            let endGuard;
+            let disposeFragment;
             let didStart = false;
             let settled = false;
             const markStarted = () => {
@@ -1744,8 +1756,7 @@ export class TTSService {
                 element.removeEventListener("ended", onEnded);
                 element.removeEventListener("error", onError);
                 element.removeEventListener("playing", markStarted);
-                if (endGuard !== undefined)
-                    clearInterval(endGuard);
+                disposeFragment?.();
                 if (this.activeRecordedAudio?.element === element) {
                     this.activeRecordedAudio = null;
                 }
@@ -1781,16 +1792,9 @@ export class TTSService {
             element.addEventListener("ended", onEnded);
             element.addEventListener("error", onError);
             element.addEventListener("playing", markStarted);
-            // Browsers honour a Media Fragments start offset but are inconsistent
-            // about the end bound, so the end is enforced here — the same reason the
-            // signing region enforces its own.
-            const endSeconds = media.fragment?.endSeconds;
-            if (endSeconds !== undefined) {
-                endGuard = setInterval(() => {
-                    if (element.currentTime >= endSeconds)
-                        onEnded();
-                }, 100);
-            }
+            // Reaching the slice's end is this clip finishing, so the chunk sequence
+            // advances rather than the element merely pausing.
+            disposeFragment = enforceMediaFragment(element, media.fragment, onEnded);
             Promise.resolve(element.play()).then(markStarted).catch(onError);
         }).finally(() => {
             if (this.activeRecordedAudio?.element === element) {
@@ -2092,7 +2096,6 @@ export class TTSService {
                 return;
             this.setState(PlaybackState.IDLE);
             this.clearHighlightsAndTracking();
-            this.highlightTargetResolverProvider = null;
         }
         catch (error) {
             if (runId !== this.speakRunId)
@@ -2100,7 +2103,6 @@ export class TTSService {
             this.lastError = error instanceof Error ? error.message : String(error);
             this.setState(PlaybackState.ERROR);
             this.clearHighlightsAndTracking();
-            this.highlightTargetResolverProvider = null;
             throw error;
         }
         finally {
@@ -2205,7 +2207,6 @@ export class TTSService {
         this.cancelRecordedAudio();
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
-        this.highlightTargetResolverProvider = null;
         this.setState(PlaybackState.IDLE);
         this.currentText = null;
         // Clear highlights

package/dist/services/ToolRegistry.d.ts

@@ -4,6 +4,7 @@
  * Central registry for all assessment tools. Manages tool metadata, visibility logic,
  * and button/instance creation. Supports dynamic registration and override by integrators.
  */
+import type { I18nProvider } from "@pie-players/pie-players-shared/i18n/types";
 import type { CatalogOwnerSnapshot } from "./AccessibilityCatalogResolver.js";
 import type { ToolContext, ToolLevel } from "./tool-context.js";
 import type { ToolComponentOverrides } from "../tools/tool-tag-map.js";
@@ -30,6 +31,17 @@ export interface ToolToolbarButtonDefinition {
      * `assertToolRegistrationShape` enforces that.
      */
     icon?: string;
+    /**
+     * FontAwesome icon name, opting this button into `<nds-icon-button>` rendering
+     * where the host enables NDS icons (`ndsIcons`). Absent means the toolbar keeps
+     * its own button rendering, which is what every capability got before the NDS
+     * button existed.
+     *
+     * A declaration rather than a toolId lookup in the toolbar: which capabilities
+     * a deployment renders through the host's design system is a composition-layer
+     * decision, and the generic core names no capability.
+     */
+    faIconName?: string;
     ariaLabel: string;
     tooltip?: string;
     onClick: () => void;
@@ -49,7 +61,24 @@ export interface ToolbarContext {
     };
     itemId: string;
     catalogId: string;
+    /**
+     * Content-alternate language: which authored alternate the catalog resolver
+     * should select. Not the interface locale — see {@link ToolbarContext.i18n}. The
+     * two are independent by QTI 3's own statement, and conflating them is how a
+     * Spanish passage ends up forcing Spanish widget chrome.
+     */
     language: string;
+    /**
+     * Interface-locale provider for this capability's own UI strings.
+     *
+     * Required, and always the facade `resolveInterfaceI18n` returns: the toolbar
+     * resolves it once from the toolkit runtime context, so a registration reads
+     * `toolbarContext.i18n` and neither repeats the no-publisher fallback nor
+     * misses the republish that a locale change produces. With no publisher the
+     * facade wraps the English-only default, which is why this can be required
+     * rather than optional.
+     */
+    i18n: I18nProvider;
     ui?: {
         size?: string;
     };
@@ -137,6 +166,23 @@ export interface ToolWindowShellConfig {
     initialMargin?: number;
     content?: ToolWindowShellContentConfig;
     actions?: ToolWindowShellAction[];
+    /**
+     * Render the shell's own header controls as `<nds-icon-button>`s where the host
+     * enables NDS icons. Shells without this keep the plain `<button>` controls, and
+     * an opted-out host gets those either way.
+     */
+    ndsHeaderControls?: boolean;
+    /**
+     * Let Tab and Shift+Tab cross between the page and this shell rather than
+     * cycling inside it.
+     *
+     * The shell is appended to `<body>`, so it sits outside the document order its
+     * opener lives in. A shell a learner works *alongside* — reading the question
+     * while using the tool — needs Tab from the opener to enter it and Shift+Tab
+     * from the first question control to reach its end. A shell a learner works
+     * *inside* wants the default trap, which keeps focus captured until dismissed.
+     */
+    pageTabOrder?: boolean;
 }
 export interface HostedToolContext {
     toolId: string;
@@ -163,6 +209,19 @@ export interface ToolToolbarRenderResult {
     sync?: () => void;
     subscribeActive?: (callback: (active: boolean) => void) => () => void;
 }
+/**
+ * A registration's display name in the interface locale.
+ *
+ * Precedence: the resolved `nameKey`, then `name`. A key that does not resolve
+ * falls back to `name` rather than rendering the key, so a catalog gap degrades
+ * to English instead of to `tools.something.name` on a toolbar button.
+ *
+ * Both display resolvers live here so the toolbars, the settings panels and the
+ * PNP debugger cannot each invent their own precedence.
+ */
+export declare function resolveToolRegistrationName(registration: Pick<ToolRegistration, "name" | "nameKey">, i18n?: I18nProvider): string;
+/** A registration's description in the interface locale. See the name resolver. */
+export declare function resolveToolRegistrationDescription(registration: Pick<ToolRegistration, "description" | "descriptionKey">, i18n?: I18nProvider): string;
 export type ToolActivation = "toolbar-toggle" | "selection-gateway" | "region";
 export type ToolSingletonScope = "section";
 /**
@@ -177,6 +236,13 @@ export interface ToolSurfaceServices {
     toolkitCoordinator: ToolkitCoordinatorApi | null;
     ttsService: TtsServiceApi | null;
     catalogResolver: AccessibilityCatalogResolverApi | null;
+    /**
+     * Interface-locale provider for the surface's own labels — a region's
+     * `aria-label`, a heading it emits. Required, and always the facade
+     * `resolveInterfaceI18n` returns, which wraps the English-only default where
+     * the host published nothing.
+     */
+    i18n: I18nProvider;
 }
 /**
  * What a host tells a capability when asking it to fill a surface.
@@ -310,10 +376,28 @@ export interface ToolSurfaceRenderResult {
 export interface ToolRegistration {
     /** Unique tool identifier (e.g., 'calculator', 'textToSpeech') */
     toolId: string;
-    /** Human-readable name */
+    /**
+     * Human-readable name.
+     *
+     * Required, and stays required: it is part of the contract a host implements
+     * when it contributes its own capability, and a host cannot be made to ship a
+     * message catalog. Treat it as the English source.
+     */
     name: string;
-    /** Description of what the tool does */
+    /** Description of what the tool does. English source, like {@link name}. */
     description: string;
+    /**
+     * Message key resolving to {@link name} in the interface locale.
+     *
+     * Optional by design. A capability that supplies one is localizable; one that
+     * does not renders `name` verbatim, which is what keeps a host-authored
+     * registration working with no catalog. Resolve with
+     * {@link resolveToolRegistrationName} rather than reading either field
+     * directly, so precedence stays in one place.
+     */
+    nameKey?: string;
+    /** Message key resolving to {@link description} in the interface locale. */
+    descriptionKey?: string;
     /**
      * Icon identifier or SVG string. Required for the activations that render a
      * toolbar button; a region capability has no button, so it has no icon.
@@ -399,6 +483,26 @@ export interface ToolRegistration {
      * @returns true if tool should be visible, false to hide
      */
     isVisibleInContext?(context: ToolContext): boolean;
+    /**
+     * Whether this tool can act on this content at all — a capability question,
+     * not a relevance heuristic. Answering `false` withdraws the tool even where
+     * a PNP grant would otherwise keep it, which {@link
+     * ToolRegistration.isVisibleInContext} deliberately cannot do.
+     *
+     * The two gates answer different questions, and most tools declare only the
+     * first. A calculator is *applicable* to every item — a learner granted one
+     * keeps it on an item that does not look mathematical — while its relevance
+     * is a guess about usefulness. An answer eliminator on an item with no choice
+     * interaction has nothing to strike through, so no grant can make it work.
+     *
+     * Declare this only where the tool's own controls provably do nothing:
+     * withdrawing a granted accommodation on a false negative is the more
+     * expensive failure. Omitting it means "applicable".
+     *
+     * @param context - The item or element context the tool would act on
+     * @returns false to withdraw the tool from this context
+     */
+    isApplicableToContent?(context: ToolContext): boolean;
     /**
      * Toolbar render contract. Required for `toolbar-toggle` and
      * `selection-gateway`; a region capability renders through
@@ -541,6 +645,20 @@ export declare class ToolRegistry {
      * @returns Array of visible tool registrations
      */
     filterVisibleInContext(allowedToolIds: string[], context: ToolContext): ToolRegistration[];
+    /**
+     * Whether a tool can act on any of the contexts it would be placed against.
+     * Unlike the relevance pass this is a veto: a `false` here removes the tool
+     * from a toolbar even when a grant protects it, so a tool answers `false`
+     * only where its controls provably do nothing.
+     *
+     * A tool that declares no applicability gate is applicable. So is one
+     * evaluated against no contexts — content that has not resolved yet cannot
+     * establish that a tool is useless.
+     *
+     * @param toolId - Tool to ask
+     * @param contexts - Every context the tool could act on at this placement
+     */
+    isApplicableToAnyContext(toolId: string, contexts: readonly ToolContext[]): boolean;
     /**
      * Get tool metadata for building UIs
      * Useful for building PNP configuration interfaces