@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

package/dist/services/tool-providers/TTSToolProvider.js

@@ -7,8 +7,6 @@
  *   `polly` and `google` run on the `pie` transport; `custom` runs on the
  *   `custom` transport to a host's own service, which takes `lang_id`,
  *   `speedRate` and `cache`
- *
- * Part of PIE Assessment Toolkit.
  */
 import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { BrowserTTSProvider } from "../../services/tts/browser-provider.js";
@@ -23,8 +21,6 @@ const logger = createPieLogger("tts-tool-provider", isTtsDebugEnabled);
 function bindServerBackendConfig(provider, bound) {
     return {
         providerId: provider.providerId,
-        providerName: provider.providerName,
-        version: provider.version,
         initialize: (config) => {
             const runtime = config;
             const merged = {
@@ -84,24 +80,15 @@ export class TTSToolProvider {
             console.warn("[TTSToolProvider] telemetry callback failed:", error);
         }
     }
-    /**
-     * Create TTS tool provider
-     *
-     * @param backend TTS backend to use (default: 'browser')
-     * @param options Loader for the server adapter, required by server backends
-     */
+    /** A server backend needs `options.loadServerProvider`. */
     constructor(backend = "browser", options = {}) {
         this.backend = backend;
         this.requiresAuth = backend !== "browser";
         this.loadServerProvider = options.loadServerProvider;
     }
     /**
-     * Initialize TTS provider
-     *
-     * Sets up the appropriate TTS backend.
-     *
-     * @param config Runtime configuration and credentials
-     * @throws Error if initialization fails or required config missing
+     * Set up the backend's TTS provider. Throws when the backend is unavailable
+     * or its required config is missing. Once initialized, a call only warns.
      */
     async initialize(config) {
         if (this.ttsProvider) {
@@ -111,7 +98,7 @@ export class TTSToolProvider {
         this.config = config;
         switch (this.backend) {
             case "browser":
-                await this._initializeBrowserTTS(config);
+                await this._initializeBrowserTTS();
                 break;
             case "server":
                 await this._initializeServerTTS(config);
@@ -121,20 +108,13 @@ export class TTSToolProvider {
         }
         logger.debug(`initialized (backend: ${this.backend})`);
     }
-    /**
-     * Initialize browser TTS (Web Speech API)
-     */
-    async _initializeBrowserTTS(config) {
-        // Check if Web Speech API is available
+    async _initializeBrowserTTS() {
         if (typeof window === "undefined" || !("speechSynthesis" in window)) {
             throw new Error("[TTSToolProvider] Browser TTS not supported (Web Speech API not available)");
         }
         this.ttsProvider = new BrowserTTSProvider();
         logger.debug("browser TTS initialized (Web Speech API)");
     }
-    /**
-     * Initialize server-based TTS
-     */
     async _initializeServerTTS(config) {
         if (!config.apiEndpoint) {
             throw new Error("[TTSToolProvider] apiEndpoint required for server-based TTS backends");
@@ -178,13 +158,8 @@ export class TTSToolProvider {
         logger.debug(`server TTS initialized (provider: ${serverProvider})`);
     }
     /**
-     * Create a TTS provider instance
-     *
-     * Returns the initialized TTS provider.
-     *
-     * @param config Optional instance-specific configuration (currently unused)
-     * @returns TTS provider
-     * @throws Error if provider not initialized
+     * The initialized TTS provider; every call returns the same one and ignores
+     * `config`. Throws before `initialize`.
      */
     async createInstance(config) {
         if (!this.ttsProvider) {
@@ -192,40 +167,9 @@ export class TTSToolProvider {
         }
         return this.ttsProvider;
     }
-    /**
-     * The backend's capabilities. Its features are the speech provider's own,
-     * and all false before {@link initialize} creates it.
-     */
-    getCapabilities() {
-        const isBrowser = this.backend === "browser";
-        const speech = this.ttsProvider?.getCapabilities();
-        return {
-            supportsOffline: isBrowser,
-            requiresAuth: !isBrowser,
-            maxInstances: 1, // Single TTS instance (playback is sequential)
-            features: {
-                wordBoundary: speech?.supportsWordBoundary ?? false,
-                pause: speech?.supportsPause ?? false,
-                resume: speech?.supportsResume ?? false,
-                rateControl: speech?.supportsRateControl ?? false,
-                pitchControl: speech?.supportsPitchControl ?? false,
-                voiceSelection: speech?.supportsVoiceSelection ?? false,
-            },
-        };
-    }
-    /**
-     * Check if provider is ready
-     *
-     * @returns true if provider is initialized
-     */
     isReady() {
         return this.ttsProvider !== null;
     }
-    /**
-     * Clean up provider resources
-     *
-     * Destroys the TTS provider and releases resources.
-     */
     destroy() {
         if (this.ttsProvider) {
             this.ttsProvider.destroy();

package/dist/services/tool-providers/ToolProviderApi.d.ts

@@ -5,12 +5,6 @@
  * configuration, authentication, or external services.
  */
 export type ToolCategory = "calculator" | "tts" | "translation" | "annotation" | "accessibility" | "other";
-export interface ToolProviderCapabilities {
-    supportsOffline: boolean;
-    requiresAuth: boolean;
-    maxInstances?: number | null;
-    features: Record<string, boolean>;
-}
 /**
  * A tool's provider. It registers under its tool's id, which is how the toolkit
  * and the tool find it; it carries no id of its own.
@@ -25,7 +19,6 @@ export interface ToolProviderApi<TInstance = any> {
     readonly requiresAuth: boolean;
     initialize(config: unknown): Promise<void>;
     createInstance(config?: unknown): Promise<TInstance>;
-    getCapabilities(): ToolProviderCapabilities;
     isReady(): boolean;
     destroy(): void;
 }

package/dist/services/tool-providers/ToolProviderRegistry.d.ts

@@ -3,8 +3,6 @@
  *
  * Centralized registry for managing tool providers.
  * Handles initialization, authentication, and lazy loading.
- *
- * Part of PIE Assessment Toolkit.
  */
 import type { ToolProviderApi, ToolCategory } from "./ToolProviderApi.js";
 /**
@@ -36,7 +34,7 @@ export interface ToolProviderRegistration<TConfig = any> {
      * @example
      * ```typescript
      * authFetcher: async () => {
-     *   const response = await fetch('/api/desmos/token');
+     *   const response = await fetch('/api/tools/desmos/auth');
      *   return response.json(); // { apiKey: '...' }
      * }
      * ```
@@ -90,9 +88,6 @@ export declare class ToolProviderRegistry {
      * A registration under an id already registered replaces it: the replaced
      * provider is destroyed once a start in progress settles, and a caller
      * waiting on that start gets the replacement.
-     *
-     * @param toolId Id of the tool the provider serves
-     * @param config Provider configuration
      */
     register(toolId: string, config: ToolProviderRegistration): void;
     /**
@@ -100,10 +95,7 @@ export declare class ToolProviderRegistry {
      *
      * Fetches auth if needed and initializes the provider.
      * Safe to call multiple times - subsequent calls wait for first initialization.
-     *
-     * @param toolId Tool whose provider to initialize
-     * @returns Promise that resolves when initialization complete
-     * @throws Error if provider not registered or initialization fails
+     * Throws when the provider is not registered or its initialization fails.
      */
     initialize(toolId: string): Promise<void>;
     /** Whether a registration replaced `provider` under `toolId`. */
@@ -117,51 +109,24 @@ export declare class ToolProviderRegistry {
      * Get a provider instance
      *
      * Retrieves a registered provider. If autoInitialize is true and provider
-     * is not initialized, initializes it first.
-     *
-     * @param toolId Id of the tool the provider serves
-     * @param autoInitialize Auto-initialize if not ready (default: true)
-     * @returns Provider instance
-     * @throws Error if provider not registered
+     * is not initialized, initializes it first. Throws when the provider is not
+     * registered.
      */
     getProvider<T extends ToolProviderApi = ToolProviderApi>(toolId: string, autoInitialize?: boolean): Promise<T>;
-    /**
-     * The ids of the tools whose provider is in `category`.
-     *
-     * @param category Tool category to filter by
-     */
+    /** The ids of the tools whose provider is in `category`. */
     getProvidersByCategory(category: ToolCategory): string[];
     /**
      * The ids of the tools with a registered provider.
      */
     getProviderIds(): string[];
-    /**
-     * Check if provider is registered
-     *
-     * @param toolId Id of the tool the provider serves
-     * @returns true if provider is registered
-     */
     has(toolId: string): boolean;
-    /**
-     * Check if provider is initialized
-     *
-     * @param toolId Id of the tool the provider serves
-     * @returns true if provider is initialized
-     */
     isInitialized(toolId: string): boolean;
-    /**
-     * Check if provider is currently initializing
-     *
-     * @param toolId Id of the tool the provider serves
-     * @returns true if initialization in progress
-     */
     isInitializing(toolId: string): boolean;
     /**
      * Unregister and destroy a provider
      *
-     * Removes the provider from the registry and calls its destroy method.
-     *
-     * @param toolId Tool whose provider to unregister
+     * Removes the provider from the registry and calls its destroy method,
+     * after any start in progress settles.
      */
     unregister(toolId: string): Promise<void>;
     /**

package/dist/services/tool-providers/ToolProviderRegistry.js

@@ -3,12 +3,17 @@
  *
  * Centralized registry for managing tool providers.
  * Handles initialization, authentication, and lazy loading.
- *
- * Part of PIE Assessment Toolkit.
  */
 import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 // Lifecycle lines need `window.PIE_DEBUG = true`, read on each line.
 const logger = createPieLogger("ToolProviderRegistry", isGlobalDebugEnabled);
+/** The `backend` a provider config names, for telemetry payloads. */
+function telemetryBackend(value) {
+    const backend = value && typeof value === "object"
+        ? value.backend
+        : undefined;
+    return typeof backend === "string" && backend ? backend : "unknown";
+}
 /**
  * Tool Provider Registry
  *
@@ -59,9 +64,6 @@ export class ToolProviderRegistry {
      * A registration under an id already registered replaces it: the replaced
      * provider is destroyed once a start in progress settles, and a caller
      * waiting on that start gets the replacement.
-     *
-     * @param toolId Id of the tool the provider serves
-     * @param config Provider configuration
      */
     register(toolId, config) {
         const replaced = this.providers.get(toolId);
@@ -81,7 +83,6 @@ export class ToolProviderRegistry {
             }
         }
         logger.debug(`${replaced ? "Replaced" : "Registered"} provider "${toolId}" (${config.provider.providerName})`);
-        // Initialize immediately if not lazy
         if (config.lazy === false) {
             this.initialize(toolId).catch((error) => {
                 console.error(`[ToolProviderRegistry] Failed to initialize provider "${toolId}":`, error);
@@ -93,22 +94,16 @@ export class ToolProviderRegistry {
      *
      * Fetches auth if needed and initializes the provider.
      * Safe to call multiple times - subsequent calls wait for first initialization.
-     *
-     * @param toolId Tool whose provider to initialize
-     * @returns Promise that resolves when initialization complete
-     * @throws Error if provider not registered or initialization fails
+     * Throws when the provider is not registered or its initialization fails.
      */
     async initialize(toolId) {
-        // Already initialized
         if (this.initialized.get(toolId)) {
             return;
         }
-        // Initialization in progress - wait for it
         const existingPromise = this.initializationPromises.get(toolId);
         if (existingPromise) {
             return existingPromise;
         }
-        // Start new initialization
         const provider = this.providers.get(toolId);
         const initPromise = this._doInitialize(toolId);
         this.initializationPromises.set(toolId, initPromise);
@@ -116,6 +111,8 @@ export class ToolProviderRegistry {
             await initPromise;
         }
         catch (error) {
+            // When a registration replaced the provider mid-start, this caller
+            // gets the replacement, so the old start's failure is dropped.
             if (!this.isReplaced(toolId, provider))
                 throw error;
         }
@@ -150,26 +147,18 @@ export class ToolProviderRegistry {
         if (!provider || !config) {
             throw new Error(`[ToolProviderRegistry] Provider "${toolId}" not registered`);
         }
-        // Start with base config
         let providerConfig = { ...config.config };
-        const deriveBackend = (value) => {
-            const backend = value && typeof value === "object"
-                ? value.backend
-                : undefined;
-            return typeof backend === "string" && backend ? backend : "unknown";
-        };
         const providerInitStartedAt = Date.now();
         await this.emitTelemetry(config, "pie-tool-init-start", {
             toolId,
-            backend: deriveBackend(providerConfig),
+            backend: telemetryBackend(providerConfig),
             operation: "provider-initialize",
         });
-        // Fetch auth if needed
         if (provider.requiresAuth && config.authFetcher) {
             const authFetchStartedAt = Date.now();
             await this.emitTelemetry(config, "pie-tool-backend-call-start", {
                 toolId,
-                backend: deriveBackend(providerConfig),
+                backend: telemetryBackend(providerConfig),
                 operation: "auth-fetch",
             });
             logger.debug(`Fetching auth for "${toolId}"...`);
@@ -178,7 +167,7 @@ export class ToolProviderRegistry {
                 providerConfig = { ...providerConfig, ...authData };
                 await this.emitTelemetry(config, "pie-tool-backend-call-success", {
                     toolId,
-                    backend: deriveBackend(providerConfig),
+                    backend: telemetryBackend(providerConfig),
                     operation: "auth-fetch",
                     duration: Date.now() - authFetchStartedAt,
                 });
@@ -186,7 +175,7 @@ export class ToolProviderRegistry {
             catch (error) {
                 await this.emitTelemetry(config, "pie-tool-backend-call-error", {
                     toolId,
-                    backend: deriveBackend(providerConfig),
+                    backend: telemetryBackend(providerConfig),
                     operation: "auth-fetch",
                     duration: Date.now() - authFetchStartedAt,
                     errorType: "ProviderAuthFetchError",
@@ -196,7 +185,6 @@ export class ToolProviderRegistry {
                 throw new Error(`Failed to fetch auth credentials for provider "${toolId}"`);
             }
         }
-        // Initialize provider
         try {
             await provider.initialize(providerConfig);
             if (this.providers.get(toolId) === provider) {
@@ -204,7 +192,7 @@ export class ToolProviderRegistry {
             }
             await this.emitTelemetry(config, "pie-tool-init-success", {
                 toolId,
-                backend: deriveBackend(providerConfig),
+                backend: telemetryBackend(providerConfig),
                 operation: "provider-initialize",
                 duration: Date.now() - providerInitStartedAt,
             });
@@ -213,7 +201,7 @@ export class ToolProviderRegistry {
         catch (error) {
             await this.emitTelemetry(config, "pie-tool-init-error", {
                 toolId,
-                backend: deriveBackend(providerConfig),
+                backend: telemetryBackend(providerConfig),
                 operation: "provider-initialize",
                 duration: Date.now() - providerInitStartedAt,
                 errorType: "ProviderInitializationError",
@@ -227,12 +215,8 @@ export class ToolProviderRegistry {
      * Get a provider instance
      *
      * Retrieves a registered provider. If autoInitialize is true and provider
-     * is not initialized, initializes it first.
-     *
-     * @param toolId Id of the tool the provider serves
-     * @param autoInitialize Auto-initialize if not ready (default: true)
-     * @returns Provider instance
-     * @throws Error if provider not registered
+     * is not initialized, initializes it first. Throws when the provider is not
+     * registered.
      */
     async getProvider(toolId, autoInitialize = true) {
         const provider = this.providers.get(toolId);
@@ -243,18 +227,13 @@ export class ToolProviderRegistry {
             });
             throw new Error(`[ToolProviderRegistry] Provider "${toolId}" not registered`);
         }
-        // Auto-initialize if needed
         if (autoInitialize && !this.initialized.get(toolId)) {
             logger.debug("Auto-initializing provider:", toolId);
             await this.initialize(toolId);
         }
         return provider;
     }
-    /**
-     * The ids of the tools whose provider is in `category`.
-     *
-     * @param category Tool category to filter by
-     */
+    /** The ids of the tools whose provider is in `category`. */
     getProvidersByCategory(category) {
         return Array.from(this.providers.entries())
             .filter(([_, provider]) => provider.category === category)
@@ -266,44 +245,24 @@ export class ToolProviderRegistry {
     getProviderIds() {
         return Array.from(this.providers.keys());
     }
-    /**
-     * Check if provider is registered
-     *
-     * @param toolId Id of the tool the provider serves
-     * @returns true if provider is registered
-     */
     has(toolId) {
         return this.providers.has(toolId);
     }
-    /**
-     * Check if provider is initialized
-     *
-     * @param toolId Id of the tool the provider serves
-     * @returns true if provider is initialized
-     */
     isInitialized(toolId) {
         return this.initialized.get(toolId) === true;
     }
-    /**
-     * Check if provider is currently initializing
-     *
-     * @param toolId Id of the tool the provider serves
-     * @returns true if initialization in progress
-     */
     isInitializing(toolId) {
         return this.initializationPromises.has(toolId);
     }
     /**
      * Unregister and destroy a provider
      *
-     * Removes the provider from the registry and calls its destroy method.
-     *
-     * @param toolId Tool whose provider to unregister
+     * Removes the provider from the registry and calls its destroy method,
+     * after any start in progress settles.
      */
     async unregister(toolId) {
         const provider = this.providers.get(toolId);
         if (provider) {
-            // Wait for any pending initialization
             const initPromise = this.initializationPromises.get(toolId);
             if (initPromise) {
                 try {
@@ -318,7 +277,6 @@ export class ToolProviderRegistry {
                     return;
             }
             this.destroyProvider(toolId, provider);
-            // Remove from registry
             this.providers.delete(toolId);
             this.configs.delete(toolId);
             this.initialized.delete(toolId);

package/dist/services/tool-request.d.ts

@@ -19,6 +19,7 @@
  * Core names no capability. The requester supplies the tool id, which is why the
  * pairing of a selection action to a dictionary lives in the composition layer.
  */
+import type { ToolFailurePhase } from "./tool-failure.js";
 import type { ToolPlacementLevel } from "./tools-config-normalizer.js";
 /** Level a request resolves against when the requester names none. */
 export declare const DEFAULT_TOOL_REQUEST_LEVEL: ToolPlacementLevel;
@@ -79,8 +80,11 @@ export interface ToolRequestTarget {
  * earlier one is still mounted does not displace it.
  */
 export declare class ToolRequestRegistry {
+    private readonly onTargetFailure;
     private readonly targets;
     private readonly changeListeners;
+    /** `onTargetFailure` receives a target's throw, which the registry recovers from. */
+    constructor(onTargetFailure?: (toolId: string, phase: ToolFailurePhase, error: unknown) => void);
     registerTarget(target: ToolRequestTarget): () => void;
     /**
      * Whether a request for this tool would reach a toolbar.

package/dist/services/tool-request.js

@@ -28,8 +28,13 @@ export const DEFAULT_TOOL_REQUEST_LEVEL = "section";
  * earlier one is still mounted does not displace it.
  */
 export class ToolRequestRegistry {
+    onTargetFailure;
     targets = new Set();
     changeListeners = new Set();
+    /** `onTargetFailure` receives a target's throw, which the registry recovers from. */
+    constructor(onTargetFailure = (toolId, phase, error) => console.error(`[ToolRequestRegistry] "${toolId}" ${phase} failed:`, error)) {
+        this.onTargetFailure = onTargetFailure;
+    }
     registerTarget(target) {
         this.targets.add(target);
         this.notifyTargetsChange();
@@ -58,7 +63,7 @@ export class ToolRequestRegistry {
             target.open(request.toolId, request.params);
         }
         catch (error) {
-            console.error(`[ToolRequestRegistry] Target failed to open "${request.toolId}":`, error);
+            this.onTargetFailure(request.toolId, "tool-request-open", error);
             return false;
         }
         return true;
@@ -115,7 +120,7 @@ export class ToolRequestRegistry {
             return target.hostsTool(toolId) === true;
         }
         catch (error) {
-            console.warn(`[ToolRequestRegistry] Target at level "${target.level}" failed the host check for "${toolId}":`, error);
+            this.onTargetFailure(toolId, "tool-request-host-check", error);
             return false;
         }
     }

package/dist/services/toolbar-decided-tools.d.ts

@@ -4,6 +4,8 @@ export interface DecidedToolbarTool {
     toolId: string;
     required: boolean;
     alwaysAvailable: boolean;
+    activateAtInit: boolean;
+    parameters?: Record<string, unknown>;
 }
 /**
  * A toolbar's decided tools across re-decisions. The tracker returns its

package/dist/services/toolbar-decided-tools.js

@@ -17,6 +17,8 @@ export function createDecidedToolsTracker() {
             toolId: entry.toolId,
             required: entry.required,
             alwaysAvailable: entry.alwaysAvailable,
+            activateAtInit: entry.activateAtInit,
+            parameters: entry.parameters,
         }));
         if (last?.renderVersion === renderVersion &&
             structurallyEqual(last.tools, tools)) {

package/dist/services/toolbar-items.js

@@ -19,13 +19,10 @@ export function isValidToolbarItemShape(value) {
         return false;
     if (item.disabled !== undefined && typeof item.disabled !== "boolean")
         return false;
+    // A link or a button: exactly one of `href` and `onClick`.
     const hasHref = typeof item.href === "string";
     const hasOnClick = typeof item.onClick === "function";
-    if (hasHref === hasOnClick)
-        return false;
-    if (hasHref)
-        return true;
-    return hasOnClick;
+    return hasHref !== hasOnClick;
 }
 export function isInlineSvgIcon(icon) {
     return typeof icon === "string" && icon.trimStart().startsWith("<svg");

package/dist/services/tools-config-normalizer.d.ts

@@ -76,16 +76,16 @@ export interface ToolProvidersConfig {
 }
 /**
  * PNP/profile enforcement mode, set as `tools.pnpEnforcement` (on a section
- * player, `runtime.tools.pnpEnforcement`).
+ * player, `runtime.tools.pnpEnforcement`) or through `setPnpEnforcement`.
  *
- * - `"on"` — force enforcement (engine applies PNP/profile gates).
- * - `"off"` — opt out (engine ignores PNP/profile inputs).
- * - omitted / `undefined` — auto-mode (the default). The toolkit
- *   coordinator computes the effective mode from PNP/profile policy material on the
- *   bound `AssessmentEntity` / `AssessmentItemRef`. See
+ * - `"on"` — toolbar decisions apply PNP/profile policy.
+ * - `"off"` — toolbar decisions skip it. Feature decisions read it either way.
+ * - omitted — auto-mode (the default): on when the bound assessment carries
+ *   PNP/profile policy material, or, for a decision scoped to an item, when
+ *   that item's settings require or restrict a tool. See
  *   `resolveDefaultPnpEnforcement` in `policy/core/pnp-policy-inputs.ts`.
  */
-export type ToolsPnpEnforcement = "on" | "off";
+export type PnpEnforcementMode = "on" | "off";
 export interface CanonicalToolsConfig {
     policy: ToolPolicyConfig;
     placement: Required<ToolPlacementConfig>;
@@ -93,9 +93,9 @@ export interface CanonicalToolsConfig {
     /**
      * Optional PNP/profile enforcement override, read by
      * `<pie-assessment-toolkit>` and `ToolkitCoordinator`. See
-     * {@link ToolsPnpEnforcement} for semantics.
+     * {@link PnpEnforcementMode} for semantics.
      */
-    pnpEnforcement?: ToolsPnpEnforcement;
+    pnpEnforcement?: PnpEnforcementMode;
 }
 /**
  * The tools config a host supplies. Every part is optional, placement levels
@@ -104,6 +104,15 @@ export interface CanonicalToolsConfig {
 export type ToolsConfigInput = Omit<Partial<CanonicalToolsConfig>, "placement"> & {
     placement?: ToolPlacementConfig;
 };
+/**
+ * Tool ids trimmed, with empty ones dropped and duplicates removed in
+ * first-seen order. Throws on a non-string entry.
+ */
 export declare function normalizeToolList(toolIds: string[] | undefined | null): string[];
 export declare function parseToolList(input: string | undefined | null): string[];
+/**
+ * Check a host's tools config shape, throwing at the first malformed field, and
+ * return it canonical: tool lists trimmed and deduplicated, and every placement
+ * level that names no tool filled with its default.
+ */
 export declare function normalizeToolsConfig(input?: ToolsConfigInput | null): CanonicalToolsConfig;