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

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;
 }

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