@pie-players/pie-assessment-toolkit 0.2.7 → 0.2.9

package/dist/services/ToolkitCoordinator.js

@@ -13,13 +13,14 @@
  *
  * Part of PIE Assessment Toolkit.
  */
+import { normalizeToolsConfig, resolveToolsForLevel, } from "./tools-config-normalizer.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
 import { ElementToolStateStore } from "./ElementToolStateStore.js";
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
 import { ToolCoordinator } from "./ToolCoordinator.js";
 import { TTSService } from "./TTSService.js";
 import { BrowserTTSProvider } from "./tts/browser-provider.js";
-import { ToolProviderRegistry, DesmosToolProvider, TIToolProvider, TTSToolProvider, } from "./tool-providers/index.js";
+import { ToolProviderRegistry, DesmosToolProvider, MathJsToolProvider, TIToolProvider, TTSToolProvider, } from "./tool-providers/index.js";
 /**
  * ToolkitCoordinator - Orchestrates all assessment toolkit services
  *
@@ -54,106 +55,447 @@ export class ToolkitCoordinator {
     elementToolStateStore;
     catalogResolver;
     toolProviderRegistry;
+    hooks;
+    lazyInit;
     /** Track TTS initialization state */
     ttsInitialized = false;
+    ttsInitPromise;
+    stateLoaded = false;
+    stateLoadPromise;
+    coordinatorReadyPromise;
+    coordinatorReadyNotified = false;
+    providerInitPromises = new Map();
+    sectionControllers = new Map();
+    sectionControllerInitPromises = new Map();
+    sectionPersistenceStrategies = new Map();
     /** Callback for floating tools changes */
     floatingToolsChangeCallback = null;
+    static resolveConfig(config) {
+        const normalized = normalizeToolsConfig(config.tools);
+        const defaultProviders = {
+            tts: {
+                enabled: true,
+                backend: "browser",
+            },
+            calculator: {
+                enabled: true,
+                provider: "desmos",
+            },
+        };
+        return {
+            ...config,
+            tools: {
+                ...normalized,
+                providers: {
+                    ...defaultProviders,
+                    ...normalized.providers,
+                },
+            },
+            accessibility: {
+                language: "en-US",
+                ...(config.accessibility ?? {}),
+                catalogs: config.accessibility?.catalogs ?? [],
+            },
+        };
+    }
     constructor(config) {
         if (!config.assessmentId) {
             throw new Error("ToolkitCoordinator requires assessmentId in config");
         }
-        this.assessmentId = config.assessmentId;
-        this.config = config;
+        const resolvedConfig = ToolkitCoordinator.resolveConfig(config);
+        this.assessmentId = resolvedConfig.assessmentId;
+        this.config = resolvedConfig;
+        this.hooks = resolvedConfig.hooks ?? {};
+        this.lazyInit = config.lazyInit === true;
         // Initialize all services
         this.toolCoordinator = new ToolCoordinator();
         this.highlightCoordinator = new HighlightCoordinator();
         this.elementToolStateStore = new ElementToolStateStore();
-        this.catalogResolver = new AccessibilityCatalogResolver(config.accessibility?.catalogs || [], config.accessibility?.language || "en-US");
+        this.catalogResolver = new AccessibilityCatalogResolver(resolvedConfig.accessibility?.catalogs || [], resolvedConfig.accessibility?.language || "en-US");
         // Initialize tool provider registry
         this.toolProviderRegistry = new ToolProviderRegistry();
         this._registerToolProviders();
         // Initialize TTS service based on config
         this.ttsService = new TTSService();
-        const ttsConfig = config.tools?.tts;
-        if (ttsConfig?.enabled !== false) {
-            // Initialize async (fire and forget - service will become available when ready)
-            this._initializeTTS(ttsConfig).catch((err) => {
-                console.error("[ToolkitCoordinator] Failed to initialize TTS:", err);
+        this.setupStatePersistenceHooks();
+        if (!this.lazyInit) {
+            void this.waitUntilReady().catch((err) => {
+                console.error("[ToolkitCoordinator] Failed eager initialization:", err);
+                this.handleError(err, { phase: "coordinator-ready" });
             });
         }
     }
+    async emitTelemetry(eventName, payload) {
+        try {
+            await this.hooks.onTelemetry?.(eventName, payload);
+        }
+        catch (err) {
+            console.warn("[ToolkitCoordinator] telemetry hook failed:", err);
+        }
+    }
+    handleError(error, context) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        try {
+            this.hooks.onError?.(normalized, context);
+        }
+        catch (hookError) {
+            console.warn("[ToolkitCoordinator] onError hook failed:", hookError);
+        }
+    }
+    getSectionControllerMapKey(key) {
+        return `${key.assessmentId}::${key.sectionId}::${key.attemptId || ""}`;
+    }
+    createDefaultSectionPersistence() {
+        const storage = (() => {
+            try {
+                if (typeof window === "undefined")
+                    return null;
+                return window.localStorage;
+            }
+            catch {
+                return null;
+            }
+        })();
+        const getStorageKey = (context) => {
+            const { assessmentId, sectionId, attemptId } = context.key;
+            return `pie:section-controller:v1:${assessmentId}:${sectionId}:${attemptId || "default"}`;
+        };
+        return {
+            async load(context) {
+                if (!storage)
+                    return null;
+                const value = storage.getItem(getStorageKey(context));
+                if (!value)
+                    return null;
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return null;
+                }
+            },
+            async save(context, snapshot) {
+                if (!storage)
+                    return;
+                storage.setItem(getStorageKey(context), JSON.stringify(snapshot));
+            },
+            async clear(context) {
+                if (!storage)
+                    return;
+                storage.removeItem(getStorageKey(context));
+            },
+        };
+    }
+    async resolveSectionPersistence(context) {
+        const cacheKey = this.getSectionControllerMapKey(context.key);
+        const existing = this.sectionPersistenceStrategies.get(cacheKey);
+        if (existing)
+            return existing;
+        const defaults = {
+            createDefaultPersistence: () => this.createDefaultSectionPersistence(),
+        };
+        const strategy = (await this.hooks.createSectionPersistence?.(context, defaults)) ??
+            (await defaults.createDefaultPersistence());
+        this.sectionPersistenceStrategies.set(cacheKey, strategy);
+        return strategy;
+    }
+    setupStatePersistenceHooks() {
+        this.elementToolStateStore.setOnStateChange((state) => {
+            if (!this.hooks.saveToolState)
+                return;
+            void Promise.resolve(this.hooks.saveToolState(state)).catch((err) => {
+                this.handleError(err, { phase: "state-save" });
+            });
+        });
+    }
+    async ensureStateLoaded() {
+        if (this.stateLoaded)
+            return;
+        if (this.stateLoadPromise)
+            return this.stateLoadPromise;
+        this.stateLoadPromise = (async () => {
+            const loader = this.hooks.loadToolState;
+            if (!loader) {
+                return;
+            }
+            try {
+                const state = await loader();
+                if (state && typeof state === "object") {
+                    this.elementToolStateStore.loadState(state);
+                }
+                this.stateLoaded = true;
+                await this.emitTelemetry("tool-state-loaded", {
+                    hasState: Boolean(state),
+                });
+            }
+            catch (err) {
+                this.handleError(err, { phase: "state-load" });
+            }
+        })().finally(() => {
+            this.stateLoadPromise = undefined;
+        });
+        return this.stateLoadPromise;
+    }
     /**
      * Register tool providers in the registry
      */
     _registerToolProviders() {
         // Register TTS provider
-        const ttsConfig = this.config.tools?.tts;
+        const ttsConfig = this.config.tools?.providers?.tts;
         if (ttsConfig?.enabled !== false) {
             const backend = ttsConfig?.backend || "browser";
-            try {
-                this.toolProviderRegistry.register("tts", {
-                    provider: new TTSToolProvider(backend),
-                    config: {
-                        backend,
-                        apiEndpoint: ttsConfig?.apiEndpoint,
-                        voice: ttsConfig?.defaultVoice,
-                        rate: ttsConfig?.rate,
-                        pitch: ttsConfig?.pitch,
-                    },
-                    lazy: true,
-                    authFetcher: ttsConfig?.authFetcher,
-                });
-            }
-            catch (error) {
-                console.warn("[ToolkitCoordinator] Failed to register TTS provider:", error);
-            }
+            void this.registerProvider("tts", {
+                provider: new TTSToolProvider(backend),
+                config: {
+                    backend,
+                    apiEndpoint: ttsConfig?.apiEndpoint,
+                    voice: ttsConfig?.defaultVoice,
+                    rate: ttsConfig?.rate,
+                    pitch: ttsConfig?.pitch,
+                },
+                lazy: true,
+                authFetcher: ttsConfig?.authFetcher,
+            });
         }
         // Register calculator providers
-        const floatingTools = this.config.tools?.floatingTools;
-        const calculatorConfig = floatingTools?.calculator;
+        const calculatorConfig = this.config.tools?.providers?.calculator;
         if (calculatorConfig?.enabled !== false) {
             const provider = calculatorConfig?.provider || "desmos";
             if (provider === "desmos") {
-                try {
-                    this.toolProviderRegistry.register("calculator-desmos", {
-                        provider: new DesmosToolProvider(),
-                        config: {},
-                        lazy: true,
-                        authFetcher: calculatorConfig?.authFetcher,
-                    });
-                }
-                catch (error) {
-                    console.warn("[ToolkitCoordinator] Failed to register Desmos calculator provider:", error);
-                }
+                void this.registerProvider("calculator-desmos", {
+                    provider: new DesmosToolProvider(),
+                    config: {},
+                    lazy: true,
+                    authFetcher: calculatorConfig?.authFetcher,
+                });
             }
             else if (provider === "ti") {
-                try {
-                    this.toolProviderRegistry.register("calculator-ti", {
-                        provider: new TIToolProvider(),
-                        config: {},
-                        lazy: true,
-                    });
-                }
-                catch (error) {
-                    console.warn("[ToolkitCoordinator] Failed to register TI calculator provider:", error);
-                }
+                void this.registerProvider("calculator-ti", {
+                    provider: new TIToolProvider(),
+                    config: {},
+                    lazy: true,
+                });
+            }
+            else if (provider === "mathjs") {
+                void this.registerProvider("calculator-mathjs", {
+                    provider: new MathJsToolProvider(),
+                    config: {},
+                    lazy: true,
+                });
             }
         }
     }
+    async registerProvider(providerId, config) {
+        try {
+            this.toolProviderRegistry.register(providerId, config);
+            const meta = {
+                providerId,
+                providerName: config.provider.providerName,
+            };
+            await this.hooks.onProviderRegistered?.(providerId, meta);
+            await this.emitTelemetry("provider-registered", {
+                providerId,
+                providerName: config.provider.providerName,
+            });
+        }
+        catch (err) {
+            console.warn(`[ToolkitCoordinator] Failed to register provider "${providerId}":`, err);
+            this.handleError(err, { phase: "provider-register", providerId });
+            this.hooks.onProviderError?.(providerId, err, {
+                phase: "provider-register",
+                providerId,
+            });
+        }
+    }
+    async ensureProviderReady(providerId) {
+        const existing = this.providerInitPromises.get(providerId);
+        if (existing)
+            return existing;
+        const promise = (async () => {
+            const provider = await this.toolProviderRegistry.getProvider(providerId, false);
+            const meta = {
+                providerId,
+                providerName: provider.providerName,
+            };
+            try {
+                await this.hooks.onProviderInitStart?.(providerId, meta);
+                await this.toolProviderRegistry.initialize(providerId);
+                await this.hooks.onProviderReady?.(providerId, meta);
+                await this.emitTelemetry("provider-ready", { providerId });
+                return provider;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.hooks.onProviderError?.(providerId, error, {
+                    phase: "provider-init",
+                    providerId,
+                });
+                this.handleError(error, { phase: "provider-init", providerId });
+                throw error;
+            }
+        })().finally(() => {
+            this.providerInitPromises.delete(providerId);
+        });
+        this.providerInitPromises.set(providerId, promise);
+        return promise;
+    }
+    setHooks(hooks) {
+        Object.assign(this.hooks, hooks);
+        this.setupStatePersistenceHooks();
+        if (hooks.onCoordinatorReady && this.isReady()) {
+            void Promise.resolve(hooks.onCoordinatorReady(this)).catch((err) => {
+                this.handleError(err, { phase: "coordinator-ready" });
+            });
+        }
+    }
+    getSectionController(args) {
+        const key = {
+            assessmentId: this.assessmentId,
+            sectionId: args.sectionId,
+            attemptId: args.attemptId,
+        };
+        return this.sectionControllers.get(this.getSectionControllerMapKey(key));
+    }
+    async getOrCreateSectionController(args) {
+        const key = {
+            assessmentId: this.assessmentId,
+            sectionId: args.sectionId,
+            attemptId: args.attemptId,
+        };
+        const mapKey = this.getSectionControllerMapKey(key);
+        const existingController = this.sectionControllers.get(mapKey);
+        if (existingController) {
+            if (args.updateExisting !== false) {
+                await existingController.updateInput?.(args.input);
+            }
+            return existingController;
+        }
+        const existingPromise = this.sectionControllerInitPromises.get(mapKey);
+        if (existingPromise)
+            return existingPromise;
+        const initPromise = (async () => {
+            const context = {
+                key,
+                coordinator: this,
+                input: args.input,
+            };
+            const persistence = await this.resolveSectionPersistence(context);
+            const defaults = {
+                createDefaultController: args.createDefaultController,
+            };
+            const controller = (await this.hooks.createSectionController?.(context, defaults)) ??
+                (await defaults.createDefaultController());
+            await controller.setPersistenceStrategy?.(persistence);
+            await controller.setPersistenceContext?.(context);
+            await controller.initialize?.(args.input);
+            await controller.hydrate?.();
+            this.sectionControllers.set(mapKey, controller);
+            await this.hooks.onSectionControllerReady?.(context, controller);
+            await this.emitTelemetry("section-controller-ready", {
+                assessmentId: key.assessmentId,
+                sectionId: key.sectionId,
+                attemptId: key.attemptId,
+            });
+            return controller;
+        })().catch((err) => {
+            this.handleError(err, {
+                phase: "section-controller-init",
+                details: {
+                    sectionId: args.sectionId,
+                    attemptId: args.attemptId,
+                },
+            });
+            throw err;
+        }).finally(() => {
+            this.sectionControllerInitPromises.delete(mapKey);
+        });
+        this.sectionControllerInitPromises.set(mapKey, initPromise);
+        return initPromise;
+    }
+    async disposeSectionController(args) {
+        const key = {
+            assessmentId: this.assessmentId,
+            sectionId: args.sectionId,
+            attemptId: args.attemptId,
+        };
+        const mapKey = this.getSectionControllerMapKey(key);
+        const controller = this.sectionControllers.get(mapKey);
+        if (!controller)
+            return;
+        const context = {
+            key,
+            coordinator: this,
+        };
+        try {
+            if (args.persistBeforeDispose !== false) {
+                await controller.persist?.();
+            }
+            await controller.dispose?.();
+            await this.hooks.onSectionControllerDispose?.(context, controller);
+            await this.emitTelemetry("section-controller-disposed", {
+                assessmentId: key.assessmentId,
+                sectionId: key.sectionId,
+                attemptId: key.attemptId,
+            });
+        }
+        catch (err) {
+            this.handleError(err, {
+                phase: "section-controller-dispose",
+                details: {
+                    sectionId: args.sectionId,
+                    attemptId: args.attemptId,
+                },
+            });
+        }
+        finally {
+            this.sectionControllers.delete(mapKey);
+            if (args.clearPersistence) {
+                const strategy = this.sectionPersistenceStrategies.get(mapKey);
+                await strategy?.clear?.(context);
+            }
+            this.sectionPersistenceStrategies.delete(mapKey);
+        }
+    }
     /**
      * Initialize TTS service with provider
      */
+    async ensureTTSReady(config) {
+        if (this.ttsInitialized)
+            return;
+        if (this.ttsInitPromise)
+            return this.ttsInitPromise;
+        this.ttsInitPromise = this._initializeTTS(config).finally(() => {
+            this.ttsInitPromise = undefined;
+        });
+        return this.ttsInitPromise;
+    }
     async _initializeTTS(config) {
         if (this.ttsInitialized)
             return;
+        await this.hooks.onBeforeTTSInit?.({
+            phase: "tts-init",
+            details: {
+                backend: config?.backend,
+            },
+        });
+        await this.emitTelemetry("tts-init-start", {
+            backend: config?.backend ??
+                this.config.tools?.providers?.tts
+                    ?.backend ??
+                "browser",
+        });
         // Try to use TTS provider from registry if available
         if (this.toolProviderRegistry.has("tts")) {
             try {
-                const ttsProvider = await this.toolProviderRegistry.getProvider("tts");
+                const ttsProvider = await this.ensureProviderReady("tts");
                 const providerInstance = await ttsProvider.createInstance();
                 await this.ttsService.initialize(providerInstance);
                 this.ttsService.setCatalogResolver(this.catalogResolver);
                 this.ttsInitialized = true;
+                await this.hooks.onTTSReady?.();
+                await this.emitTelemetry("tts-init-success", {
+                    provider: "registry",
+                });
                 console.log("[ToolkitCoordinator] TTS initialized via ToolProviderRegistry");
                 return;
             }
@@ -163,14 +505,24 @@ export class ToolkitCoordinator {
         }
         // Fallback to browser provider
         const provider = new BrowserTTSProvider();
-        await this.ttsService.initialize(provider);
-        this.ttsService.setCatalogResolver(this.catalogResolver);
-        // Apply TTS-specific configuration
-        if (config) {
-            // Future: Apply voice, rate, pitch settings to provider
-            // For now, these are hints for UI (voice picker, rate slider)
+        try {
+            await this.ttsService.initialize(provider, config);
+            this.ttsService.setCatalogResolver(this.catalogResolver);
+            this.ttsInitialized = true;
+            await this.hooks.onTTSReady?.();
+            await this.emitTelemetry("tts-init-success", {
+                provider: "browser-fallback",
+            });
+        }
+        catch (error) {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            this.hooks.onTTSError?.(normalized, { phase: "tts-init" });
+            this.handleError(normalized, { phase: "tts-init" });
+            await this.emitTelemetry("tts-init-error", {
+                message: normalized.message,
+            });
+            throw normalized;
         }
-        this.ttsInitialized = true;
     }
     /**
      * Get all services as a bundle for section player convenience.
@@ -193,7 +545,48 @@ export class ToolkitCoordinator {
      * @returns Tool provider instance
      */
     async getToolProvider(providerId) {
-        return this.toolProviderRegistry.getProvider(providerId);
+        return this.ensureProviderReady(providerId);
+    }
+    async waitUntilReady() {
+        if (this.isReady())
+            return;
+        if (this.coordinatorReadyPromise)
+            return this.coordinatorReadyPromise;
+        this.coordinatorReadyPromise = (async () => {
+            await this.ensureStateLoaded();
+            const ttsConfig = this.config.tools?.providers?.tts;
+            if (ttsConfig?.enabled !== false) {
+                await this.ensureTTSReady(ttsConfig);
+            }
+            if (!this.coordinatorReadyNotified) {
+                this.coordinatorReadyNotified = true;
+                await this.hooks.onCoordinatorReady?.(this);
+                await this.emitTelemetry("coordinator-ready", {
+                    assessmentId: this.assessmentId,
+                });
+            }
+        })().finally(() => {
+            this.coordinatorReadyPromise = undefined;
+        });
+        return this.coordinatorReadyPromise;
+    }
+    isReady() {
+        return this.getInitStatus().coordinator;
+    }
+    getInitStatus() {
+        const providers = {};
+        for (const providerId of this.toolProviderRegistry.getProviderIds()) {
+            providers[providerId] = this.toolProviderRegistry.isInitialized(providerId);
+        }
+        return {
+            tts: this.ttsInitialized,
+            stateLoaded: this.stateLoaded || !this.hooks.loadToolState,
+            coordinator: (this.stateLoaded || !this.hooks.loadToolState) &&
+                (this.ttsInitialized ||
+                    this.config.tools?.providers?.tts
+                        ?.enabled === false),
+            providers,
+        };
     }
     /**
      * Check if a tool is enabled.
@@ -203,7 +596,7 @@ export class ToolkitCoordinator {
      * @returns True if tool is enabled
      */
     isToolEnabled(toolId) {
-        const toolConfig = this.config.tools?.[toolId];
+        const toolConfig = this.config.tools?.providers?.[toolId];
         // Enabled by default unless explicitly set to false
         return toolConfig?.enabled !== false;
     }
@@ -214,7 +607,7 @@ export class ToolkitCoordinator {
      * @returns Tool configuration or null if not configured
      */
     getToolConfig(toolId) {
-        return this.config.tools?.[toolId] || null;
+        return this.config.tools?.providers?.[toolId] || null;
     }
     /**
      * Update tool configuration.
@@ -227,9 +620,12 @@ export class ToolkitCoordinator {
         // Update config
         const current = this.getToolConfig(toolId) || {};
         if (!this.config.tools) {
-            this.config.tools = {};
+            this.config.tools = normalizeToolsConfig();
+        }
+        if (!this.config.tools.providers) {
+            this.config.tools.providers = {};
         }
-        this.config.tools[toolId] = { ...current, ...updates };
+        this.config.tools.providers[toolId] = { ...current, ...updates };
         // Apply configuration changes to services
         this._applyToolConfigChange(toolId, updates);
     }
@@ -241,12 +637,12 @@ export class ToolkitCoordinator {
      */
     updateFloatingTools(toolIds) {
         if (!this.config.tools) {
-            this.config.tools = {};
+            this.config.tools = normalizeToolsConfig();
         }
-        if (!this.config.tools.floatingTools) {
-            this.config.tools.floatingTools = {};
+        if (!this.config.tools.placement) {
+            this.config.tools.placement = normalizeToolsConfig().placement;
         }
-        this.config.tools.floatingTools.enabledTools = toolIds;
+        this.config.tools.placement.section = [...toolIds];
         // Notify listener of change
         if (this.floatingToolsChangeCallback) {
             this.floatingToolsChangeCallback(toolIds);
@@ -258,7 +654,9 @@ export class ToolkitCoordinator {
      * @returns Array of enabled tool IDs
      */
     getFloatingTools() {
-        return this.config.tools?.floatingTools?.enabledTools || [];
+        if (!this.config.tools)
+            return [];
+        return resolveToolsForLevel(this.config.tools, "section");
     }
     /**
      * Set a callback to be notified when floating tools change.
@@ -279,12 +677,16 @@ export class ToolkitCoordinator {
      * Apply tool configuration changes to underlying services.
      * Called after updateToolConfig().
      */
-    _applyToolConfigChange(toolId, updates) {
+    _applyToolConfigChange(toolId, _updates) {
         // Apply configuration changes based on tool
         switch (toolId) {
             case "tts":
-                // Future: Update TTSService with voice/rate/pitch changes
-                // For now, config is used by UI widgets to show current settings
+                void this._reconfigureTTSProvider().then(async () => {
+                    const ttsConfig = this.config.tools?.providers?.tts;
+                    if (!this.lazyInit && ttsConfig?.enabled !== false) {
+                        await this.ensureTTSReady(ttsConfig);
+                    }
+                });
                 break;
             case "answerEliminator":
                 // Future: Could notify answer eliminator tools of strategy change
@@ -292,5 +694,34 @@ export class ToolkitCoordinator {
             // Add cases for other tools as needed
         }
     }
+    async _reconfigureTTSProvider() {
+        this.ttsInitialized = false;
+        this.ttsInitPromise = undefined;
+        try {
+            this.ttsService.stop();
+        }
+        catch {
+            // noop: stop best effort
+        }
+        if (this.toolProviderRegistry.has("tts")) {
+            await this.toolProviderRegistry.unregister("tts");
+        }
+        const ttsConfig = this.config.tools?.providers?.tts;
+        if (ttsConfig?.enabled === false)
+            return;
+        const backend = ttsConfig?.backend || "browser";
+        await this.registerProvider("tts", {
+            provider: new TTSToolProvider(backend),
+            config: {
+                backend,
+                apiEndpoint: ttsConfig?.apiEndpoint,
+                voice: ttsConfig?.defaultVoice,
+                rate: ttsConfig?.rate,
+                pitch: ttsConfig?.pitch,
+            },
+            lazy: true,
+            authFetcher: ttsConfig?.authFetcher,
+        });
+    }
 }
 //# sourceMappingURL=ToolkitCoordinator.js.map