@pie-players/pie-assessment-toolkit 0.3.72 → 0.3.74

package/dist/services/interfaces.d.ts

@@ -14,7 +14,7 @@ import type { CatalogOwnerContext } from "./catalog-owner.js";
 import type { FrameworkErrorListener } from "./framework-error-bus.js";
 import type { FrameworkErrorModel } from "./framework-error.js";
 import type { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
-import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks, ToolkitInitStatus } from "./ToolkitCoordinator.js";
+import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks, ToolkitInitStatus, TTSToolConfig } from "./ToolkitCoordinator.js";
 import type { ThemeConfig } from "./ThemeProvider.js";
 import type { ZIndexLayer } from "./ToolCoordinator.js";
 import type { PlaybackState, TTSConfig } from "./TTSService.js";
@@ -244,6 +244,12 @@ export interface TtsServiceApi {
      * Get currently speaking text
      */
     getCurrentText(): string | null;
+    /**
+     * Whether a catalog holds spoken content this service could speak.
+     * Optional: a service without one resolves a selection to the nearest
+     * docked catalog id.
+     */
+    hasSpokenAlternate?(catalogId: string, language?: string): boolean;
     /**
      * Subscribe to state changes
      */
@@ -421,14 +427,6 @@ export interface ToolkitCoordinatorApi {
      * Assessment identifier
      */
     readonly assessmentId: string;
-    /**
-     * Configuration
-     */
-    readonly config: {
-        tools?: {
-            providers?: Record<string, ToolProviderConfig | undefined>;
-        };
-    };
     /**
      * TTS service
      */
@@ -491,10 +489,12 @@ export interface ToolkitCoordinatorApi {
     /**
      * Get tool configuration
      */
+    getToolConfig(toolId: "textToSpeech"): TTSToolConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
      * Update tool configuration
      */
+    updateToolConfig(toolId: "textToSpeech", updates: Partial<TTSToolConfig>): void;
     updateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;
     /**
      * Update the enabled tool list for one placement level.

package/dist/services/pnp-standard-features.d.ts

@@ -167,7 +167,7 @@ export declare const QTI_STANDARD_ACCESS_FEATURES: {
 /**
  * Flat list of all standard access features for validation
  */
-export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "calculator" | "graph" | "periodicTable" | "ruler" | "protractor" | "answerEliminator" | "signLanguage" | "readAloud" | "strikethrough" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastDisplay" | "highContrastAudio" | "colorContrast" | "invertColors" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "annotations" | "bookmarking" | "highlighting" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "readingMask" | "readingGuide" | "readingRuler" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "graphingCalculator" | "formulaSheet" | "answerMasking" | "itemGlossary" | "tutorialAvailable")[];
+export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "calculator" | "graph" | "periodicTable" | "ruler" | "protractor" | "answerEliminator" | "signLanguage" | "readAloud" | "index" | "strikethrough" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastDisplay" | "highContrastAudio" | "colorContrast" | "invertColors" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "annotations" | "bookmarking" | "highlighting" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "readingMask" | "readingGuide" | "readingRuler" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "graphingCalculator" | "formulaSheet" | "answerMasking" | "itemGlossary" | "tutorialAvailable")[];
 /**
  * Example PNP configurations for common accessibility needs
  * These are NOT official profiles but illustrative examples showing

package/dist/services/section-controller-types.d.ts

@@ -1,5 +1,6 @@
 import type { FormativeFeedbackReveal, FormativeMasteryRollup, FormativeSectionProjection, FormativeTryOutcome } from "@pie-players/pie-players-shared/formative";
 import type { MediaTimeSource, TimedMediaDegradation, TimedMediaSectionProjection, TimedMediaValidationError } from "@pie-players/pie-players-shared/timed-media";
+import type { SessionCommitReason } from "@pie-players/pie-players-shared/pie";
 import type { SectionControllerSessionState } from "@pie-players/pie-players-shared/types";
 /**
  * Re-exported so every existing import site keeps its specifier. The shape is
@@ -80,16 +81,30 @@ export type SectionControllerItemSessionDataChangedEvent = SectionControllerEven
     canonicalItemId: string;
     session: unknown;
     intent?: string;
+    /** The reported completion: the element's own when `elementId` is set. */
     complete?: boolean;
     component?: string;
+    /** The id of the element that reported, when the change names one. */
+    elementId?: string;
+    /** The controller input's `sectionId`. */
+    sectionId?: string;
+    /** Set when the change is a commit at a teardown, navigation or page-hidden seam. */
+    sessionCommitReason?: SessionCommitReason;
     currentItemIndex: number;
 };
 export type SectionControllerItemSessionMetaChangedEvent = SectionControllerEventBase & {
     type: "item-session-meta-changed";
     itemId: string;
     canonicalItemId: string;
+    /** The reported completion: the element's own when `elementId` is set. */
     complete?: boolean;
     component?: string;
+    /** The id of the element that reported, when the change names one. */
+    elementId?: string;
+    /** The controller input's `sectionId`. */
+    sectionId?: string;
+    /** Set when the change is a commit at a teardown, navigation or page-hidden seam. */
+    sessionCommitReason?: SessionCommitReason;
     currentItemIndex: number;
 };
 export type SectionControllerItemSelectedEvent = SectionControllerEventBase & {
@@ -392,6 +407,21 @@ export interface SectionControllerHandle {
      * is what the strategy load/save methods exchange.
      */
     configureSessionPersistence?(config: SectionSessionPersistenceConfig): void | Promise<void>;
+    /**
+     * Register a commit for the section's pending element sessions.
+     *
+     * A delivery element coalesces its `session-changed` dispatch, so a response
+     * can still be pending when the controller reaches a boundary that reads or
+     * discards the session - `updateInput()`, `navigateToItem()`, `persist()`.
+     * The controller is DOM-free, so the owner of the section's DOM supplies the
+     * commit and the controller calls it before those boundaries.
+     *
+     * The player that mounts the section registers this on every controller it
+     * creates. A host-built controller that leaves it unimplemented keeps the
+     * behaviour it had before the hook existed, and loses a pending response at
+     * those boundaries.
+     */
+    setPendingSessionCommit?(commit: (() => void) | null): void;
     /**
      * Record one Try for an item: derive correctness from the element outcomes,
      * increment the Try count, and reveal feedback if the item's resolved

package/dist/services/spoken-audio-cards.js

@@ -20,7 +20,7 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import { isUnsupportedMediaAssetVersion, normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "./catalog-media.js";
+import { isUnsupportedMediaAssetVersion, normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "@pie-players/pie-players-shared/media";
 /** Catalog type token for spoken alternates. Matches QTI 3's `support` value. */
 export const SPOKEN_CATALOG_TYPE = "spoken";
 /**

package/dist/services/tool-config-validation.d.ts

@@ -1,4 +1,4 @@
-import { type CanonicalToolsConfig } from "./tools-config-normalizer.js";
+import { type CanonicalToolsConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
 import { type FrameworkErrorModel } from "./framework-error.js";
 import type { ToolRegistry } from "./ToolRegistry.js";
 export type ToolConfigStrictness = "off" | "warn" | "error";
@@ -27,4 +27,15 @@ export declare function frameworkErrorFromToolConfigValidation(args: {
     recoverable?: boolean;
 }): FrameworkErrorModel;
 export declare function normalizeToolConfigStrictness(value: unknown): ToolConfigStrictness;
-export declare function normalizeAndValidateToolsConfig(input?: Partial<CanonicalToolsConfig> | null, options?: ToolConfigValidationOptions): ToolConfigValidationResult;
+export declare function normalizeAndValidateToolsConfig(input?: ToolsConfigInput | null, options?: ToolConfigValidationOptions): ToolConfigValidationResult;
+/**
+ * The normalization and diagnostics of {@link normalizeAndValidateToolsConfig},
+ * without reporting: nothing is printed or thrown.
+ */
+export declare function collectToolConfigDiagnostics(input: ToolsConfigInput | null | undefined, toolRegistry: ToolRegistry | null | undefined): ToolConfigValidationResult;
+/**
+ * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: a removed
+ * provider key throws at every strictness, `"warn"` prints every diagnostic, and
+ * `"error"` throws the blocking ones or, when there are none, prints the rest.
+ */
+export declare function reportToolConfigDiagnostics(diagnostics: ToolConfigDiagnostic[], options?: Pick<ToolConfigValidationOptions, "strictness" | "source">): void;

package/dist/services/tool-config-validation.js

@@ -215,15 +215,22 @@ function throwValidationError(diagnostics, source) {
     throw new Error(`[tool-config-validation:${source}] Invalid tools config:\n${formatted}`);
 }
 export function normalizeAndValidateToolsConfig(input, options = {}) {
-    const strictness = normalizeToolConfigStrictness(options.strictness);
-    const source = options.source ?? "tools";
-    const registryTools = getRegistryToolMap(options.toolRegistry);
+    const result = collectToolConfigDiagnostics(input, options.toolRegistry);
+    reportToolConfigDiagnostics(result.diagnostics, options);
+    return result;
+}
+/**
+ * The normalization and diagnostics of {@link normalizeAndValidateToolsConfig},
+ * without reporting: nothing is printed or thrown.
+ */
+export function collectToolConfigDiagnostics(input, toolRegistry) {
+    const registryTools = getRegistryToolMap(toolRegistry);
     const normalized = normalizeToolsConfig(input);
     const diagnostics = [];
     // Tool-id and provider checks need a registry to check against, and every
     // collector below returns early without one. Say so: this package no longer
     // falls back to a packaged registry, so a caller that used to get id
-    // validation for free now gets none, and a silent downgrade from "your ids are
+    // validation for free now gets none, and a silent downgrade of "your ids are
     // valid" to "nobody looked" is the kind of change that surfaces as a typo
     // reaching a learner.
     const hasConfiguredTools = Object.values(normalized.placement).some((ids) => ids.length > 0) ||
@@ -235,7 +242,7 @@ export function normalizeAndValidateToolsConfig(input, options = {}) {
             code: "tools.registryUnavailable",
             severity: "warning",
             path: "tools",
-            message: 'No tool registry was supplied, so tool ids, placement levels and provider config were not validated. Pass `toolRegistry` — for the packaged capability set, `createPackagedToolRegistry()` from "@pie-players/pie-default-tool-loaders".',
+            message: 'No tool registry was supplied, so tool ids, placement levels and provider config were not validated, and a coordinator without one registers no tool providers. Pass `toolRegistry` to the coordinator or the toolkit it is bound to — for the packaged capability set, `createPackagedToolRegistry()` from "@pie-players/pie-default-tool-loaders".',
         }));
     }
     const hasRemovedTtsKey = Object.hasOwn(normalized.providers, "tts");
@@ -258,17 +265,31 @@ export function normalizeAndValidateToolsConfig(input, options = {}) {
     collectPlacementDiagnostics(nextConfig, registryTools, diagnostics);
     collectPolicyDiagnostics(nextConfig, registryTools, diagnostics);
     collectProviderKeyDiagnostics(nextConfig, registryTools, hasRemovedTtsKey, diagnostics);
-    if (hasRemovedTtsKey) {
-        throwValidationError(diagnostics.filter((entry) => entry.code === "tools.removedProviderKey"), source);
+    return {
+        config: nextConfig,
+        diagnostics,
+    };
+}
+/**
+ * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: a removed
+ * provider key throws at every strictness, `"warn"` prints every diagnostic, and
+ * `"error"` throws the blocking ones or, when there are none, prints the rest.
+ */
+export function reportToolConfigDiagnostics(diagnostics, options = {}) {
+    const strictness = normalizeToolConfigStrictness(options.strictness);
+    const source = options.source ?? "tools";
+    const removedKeys = diagnostics.filter((entry) => entry.code === "tools.removedProviderKey");
+    if (removedKeys.length > 0) {
+        throwValidationError(removedKeys, source);
     }
     if (strictness === "warn") {
         emitWarnings(diagnostics, source);
     }
-    // Severity decides what `strictness: "error"` rejects. Every diagnostic this
-    // function raised was `"error"` until `tools.registryUnavailable`, which
-    // reports that validation could not run rather than that the config is wrong —
-    // throwing on it would turn "no registry supplied" from a host's existing,
-    // working setup into a construction failure.
+    // Severity decides what `strictness: "error"` rejects. Every diagnostic was
+    // `"error"` until `tools.registryUnavailable`, which reports that validation
+    // could not run rather than that the config is wrong — throwing on it would
+    // turn "no registry supplied" from a host's existing, working setup into a
+    // construction failure.
     const blocking = diagnostics.filter((entry) => entry.severity === "error");
     if (strictness === "error" && blocking.length > 0) {
         throwValidationError(blocking, source);
@@ -276,8 +297,4 @@ export function normalizeAndValidateToolsConfig(input, options = {}) {
     if (strictness === "error" && blocking.length === 0) {
         emitWarnings(diagnostics, source);
     }
-    return {
-        config: nextConfig,
-        diagnostics,
-    };
 }

package/dist/services/tool-context.js

@@ -261,20 +261,35 @@ export function hasMathContent(context) {
     ];
     return textIndicators.some((pattern) => pattern.test(text));
 }
+const CHOICE_INTERACTION_ELEMENTS = new Set([
+    "multiple-choice",
+    "inline-choice",
+    "select-text",
+    "ebsr",
+]);
+// Content names one interaction several ways: `multiple-choice`, `pie-multiple-choice`,
+// `pie-element-multiple-choice`, a runtime `--version-*` tag, or any tag the item's
+// `elements` map binds to `@pie-element/multiple-choice`.
+const baseElementName = (tag) => tag
+    .toLowerCase()
+    .replace(/--version-[0-9a-z-]+$/, "")
+    .replace(/^pie-(element-)?/, "");
+function isChoiceElement(tag, elements) {
+    if (CHOICE_INTERACTION_ELEMENTS.has(baseElementName(tag)))
+        return true;
+    if (!elements || typeof elements !== "object")
+        return false;
+    const map = elements;
+    const spec = map[tag] ?? map[tag.replace(/--version-[0-9A-Za-z-]+$/, "")];
+    if (typeof spec !== "string")
+        return false;
+    const packageName = spec.match(/^@pie-element\/([^@]+)/)?.[1];
+    return !!packageName && CHOICE_INTERACTION_ELEMENTS.has(packageName);
+}
 /**
  * Helper to check if context contains choice-based interactions
  */
 export function hasChoiceInteraction(context) {
-    const interactionTypes = [
-        "pie-multiple-choice",
-        "pie-inline-choice",
-        "pie-select-text",
-        "pie-ebsr",
-        "multiple-choice",
-        "inline-choice",
-        "select-text",
-        "ebsr",
-    ];
     if (isElementContext(context)) {
         const config = context.item.config;
         if (!config?.models)
@@ -287,10 +302,11 @@ export function hasChoiceInteraction(context) {
         if (!model)
             return false;
         const type = model.element || "";
-        return interactionTypes.includes(type);
+        return isChoiceElement(type, config.elements);
     }
     if (isItemContext(context)) {
-        const modelsRaw = context.item.config?.models;
+        const config = context.item.config;
+        const modelsRaw = config?.models;
         const models = Array.isArray(modelsRaw)
             ? modelsRaw
             : modelsRaw && typeof modelsRaw === "object"
@@ -307,7 +323,7 @@ export function hasChoiceInteraction(context) {
             // a named model showed the answer eliminator on items where the tool does
             // nothing. The heuristic remains for configs that name no element.
             if (type)
-                return interactionTypes.includes(type);
+                return isChoiceElement(type, config?.elements);
             return Array.isArray(m.choices) && m.choices.length > 0;
         });
     }

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

@@ -8,74 +8,33 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import type { ITTSProvider, TTSConfig } from "@pie-players/pie-tts";
+import type { ITTSProvider } from "@pie-players/pie-tts";
+import type { RuntimeTTSConfig, TTSRuntimeSettings } from "../tts-runtime-config.js";
 import type { ToolProviderApi, ToolProviderCapabilities } from "./ToolProviderApi.js";
+export type TTSBackend = NonNullable<TTSRuntimeSettings["backend"]>;
 /**
- * TTS backend type
+ * The runtime provider config plus the backend selection and instrumentation
+ * this tool provider reads.
  */
-export type TTSBackend = "browser" | "polly" | "google" | "server";
-/**
- * TTS tool provider configuration
- */
-export interface TTSToolProviderConfig extends Partial<TTSConfig> {
-    /**
-     * TTS backend to use
-     */
+export type TTSToolProviderConfig = RuntimeTTSConfig & {
     backend: TTSBackend;
+    serverProvider?: TTSRuntimeSettings["serverProvider"];
     /**
-     * Server API endpoint (for server backends)
-     * @example '/api/tts/synthesize'
-     * @example 'https://api.example.com/tts/synthesize'
-     */
-    apiEndpoint?: string;
-    /**
-     * Provider to use on server ('polly', 'google')
-     * Only used when backend is 'server', 'polly', or 'google'
-     */
-    serverProvider?: "polly" | "google" | "custom";
-    /**
-     * Explicit transport mode for server provider payload translation.
-     */
-    transportMode?: "pie" | "custom";
-    /**
-     * Endpoint style used by the server-backed provider.
-     */
-    endpointMode?: "synthesizePath" | "rootPost";
-    /**
-     * Endpoint validation strategy when validateEndpoint=true.
-     */
-    endpointValidationMode?: "voices" | "endpoint" | "none";
-    /**
-     * Include auth header when fetching remote audio/speech-mark assets.
-     */
-    includeAuthOnAssetFetch?: boolean;
-    /**
-     * Auth token (if required)
-     * Typically fetched via authFetcher in ToolProviderRegistry
+     * Bearer token for a server backend, sent as `Authorization`. A host supplies
+     * it through `provider.runtime.authFetcher`.
      */
     authToken?: string;
-    /**
-     * Organization ID for multi-tenant applications
-     */
-    organizationId?: string;
-    /**
-     * Default voice to use
-     */
-    voice?: string;
-    /**
-     * Speech rate (0.25 to 4.0, default 1.0)
-     */
-    rate?: number;
-    /**
-     * Speech pitch (0 to 2, default 1.0)
-     * Note: Only browser backend supports pitch
-     */
-    pitch?: number;
-    /**
-     * Optional telemetry callback for tool/backend instrumentation.
-     */
     onTelemetry?: (eventName: string, payload?: Record<string, unknown>) => void | Promise<void>;
-}
+};
+/**
+ * Construction options. `loadServerProvider` resolves the server adapter's
+ * provider class; a server backend fails to initialize without it. The toolkit
+ * leaves the adapter to its caller so that a bundler building the toolkit never
+ * has to resolve `@pie-players/tts-client-server`.
+ */
+export type TTSToolProviderOptions = {
+    loadServerProvider?: () => Promise<new () => ITTSProvider>;
+};
 /**
  * TTS Tool Provider
  *
@@ -89,13 +48,14 @@ export interface TTSToolProviderConfig extends Partial<TTSConfig> {
  * const ttsProvider = await provider.createInstance();
  * ```
  *
- * @example Server TTS (with auth)
+ * @example Server TTS
  * ```typescript
- * const provider = new TTSToolProvider();
+ * const provider = new TTSToolProvider('polly', {
+ *   loadServerProvider: async () => ServerTTSProvider,
+ * });
  * await provider.initialize({
  *   backend: 'polly',
- *   apiEndpoint: '/api/tts/synthesize',
- *   authToken: 'bearer-token', // Fetched via authFetcher
+ *   apiEndpoint: '/api/tts',
  * });
  * const ttsProvider = await provider.createInstance();
  * ```
@@ -108,13 +68,15 @@ export declare class TTSToolProvider implements ToolProviderApi<TTSToolProviderC
     readonly requiresAuth: boolean;
     private ttsProvider;
     private config;
+    private readonly loadServerProvider;
     private emitTelemetry;
     /**
      * Create TTS tool provider
      *
      * @param backend TTS backend to use (default: 'browser')
+     * @param options Loader for the server adapter, required by server backends
      */
-    constructor(backend?: TTSBackend);
+    constructor(backend?: TTSBackend, options?: TTSToolProviderOptions);
     /**
      * Initialize TTS provider
      *

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

@@ -9,6 +9,36 @@
  * Part of PIE Assessment Toolkit.
  */
 import { BrowserTTSProvider } from "../../services/tts/browser-provider.js";
+/**
+ * Binds a server backend's provider to the config the registry initialized this
+ * tool provider with, including what `provider.runtime.authFetcher` returned.
+ * The bound config wins over the runtime config the TTS service initializes the
+ * provider with; `headers` and `providerOptions` merge key by key, keeping the
+ * host's headers and the service's telemetry reporter.
+ */
+function bindServerBackendConfig(provider, bound) {
+    return {
+        providerId: provider.providerId,
+        providerName: provider.providerName,
+        version: provider.version,
+        initialize: (config) => {
+            const runtime = config;
+            const merged = {
+                ...runtime,
+                ...bound,
+                headers: { ...runtime.headers, ...bound.headers },
+                providerOptions: {
+                    ...runtime.providerOptions,
+                    ...bound.providerOptions,
+                },
+            };
+            return provider.initialize(merged);
+        },
+        supportsFeature: (feature) => provider.supportsFeature(feature),
+        getCapabilities: () => provider.getCapabilities(),
+        destroy: () => provider.destroy(),
+    };
+}
 /**
  * TTS Tool Provider
  *
@@ -22,13 +52,14 @@ import { BrowserTTSProvider } from "../../services/tts/browser-provider.js";
  * const ttsProvider = await provider.createInstance();
  * ```
  *
- * @example Server TTS (with auth)
+ * @example Server TTS
  * ```typescript
- * const provider = new TTSToolProvider();
+ * const provider = new TTSToolProvider('polly', {
+ *   loadServerProvider: async () => ServerTTSProvider,
+ * });
  * await provider.initialize({
  *   backend: 'polly',
- *   apiEndpoint: '/api/tts/synthesize',
- *   authToken: 'bearer-token', // Fetched via authFetcher
+ *   apiEndpoint: '/api/tts',
  * });
  * const ttsProvider = await provider.createInstance();
  * ```
@@ -41,6 +72,7 @@ export class TTSToolProvider {
     requiresAuth;
     ttsProvider = null;
     config = null;
+    loadServerProvider;
     async emitTelemetry(eventName, payload) {
         try {
             await this.config?.onTelemetry?.(eventName, payload);
@@ -53,9 +85,11 @@ export class TTSToolProvider {
      * Create TTS tool provider
      *
      * @param backend TTS backend to use (default: 'browser')
+     * @param options Loader for the server adapter, required by server backends
      */
-    constructor(backend = "browser") {
+    constructor(backend = "browser", options = {}) {
         this.requiresAuth = backend !== "browser";
+        this.loadServerProvider = options.loadServerProvider;
     }
     /**
      * Initialize TTS provider
@@ -103,16 +137,19 @@ export class TTSToolProvider {
         if (!config.apiEndpoint) {
             throw new Error("[TTSToolProvider] apiEndpoint required for server-based TTS backends");
         }
-        // Server backends are optional; load implementation only when requested.
+        const loadServerProvider = this.loadServerProvider;
+        if (!loadServerProvider) {
+            throw new Error("[TTSToolProvider] server-based TTS backends need the loadServerProvider option");
+        }
         const moduleLoadStartedAt = Date.now();
         await this.emitTelemetry("pie-tool-library-load-start", {
             toolId: "textToSpeech",
             operation: "server-provider-module-import",
             backend: config.serverProvider || config.backend,
         });
-        const serverModule = await (async () => {
+        const ServerProvider = await (async () => {
             try {
-                const loaded = (await import("@pie-players/tts-client-server"));
+                const loaded = await loadServerProvider();
                 await this.emitTelemetry("pie-tool-library-load-success", {
                     toolId: "textToSpeech",
                     operation: "server-provider-module-import",
@@ -133,7 +170,8 @@ export class TTSToolProvider {
                 throw error;
             }
         })();
-        this.ttsProvider = new serverModule.ServerTTSProvider();
+        const { backend, serverProvider, onTelemetry, ...backendConfig } = config;
+        this.ttsProvider = bindServerBackendConfig(new ServerProvider(), backendConfig);
         console.log(`[TTSToolProvider] Server TTS initialized (provider: ${config.serverProvider || config.backend})`);
     }
     /**

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

@@ -61,18 +61,18 @@ export interface ToolProviderConfig<TConfig = any> {
  * const registry = new ToolProviderRegistry();
  *
  * // Register a provider with auth fetcher
- * registry.register('desmos-calculator', {
- *   provider: new DesmosToolProvider(),
+ * registry.register('example-provider', {
+ *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
  *   authFetcher: async () => {
- *     const response = await fetch('/api/desmos/token');
+ *     const response = await fetch('/api/example/token');
  *     return response.json();
  *   },
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const desmosProvider = await registry.getProvider('desmos-calculator');
+ * const provider = await registry.getProvider('example-provider');
  * ```
  */
 export declare class ToolProviderRegistry {

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

@@ -20,18 +20,18 @@
  * const registry = new ToolProviderRegistry();
  *
  * // Register a provider with auth fetcher
- * registry.register('desmos-calculator', {
- *   provider: new DesmosToolProvider(),
+ * registry.register('example-provider', {
+ *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
  *   authFetcher: async () => {
- *     const response = await fetch('/api/desmos/token');
+ *     const response = await fetch('/api/example/token');
  *     return response.json();
  *   },
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const desmosProvider = await registry.getProvider('desmos-calculator');
+ * const provider = await registry.getProvider('example-provider');
  * ```
  */
 export class ToolProviderRegistry {
@@ -209,13 +209,6 @@ export class ToolProviderRegistry {
      * @throws Error if provider not registered
      */
     async getProvider(providerId, autoInitialize = true) {
-        console.log("[ToolProviderRegistry] getProvider called", {
-            providerId,
-            autoInitialize,
-            isRegistered: this.providers.has(providerId),
-            isInitialized: this.initialized.get(providerId),
-            allProviderIds: Array.from(this.providers.keys()),
-        });
         const provider = this.providers.get(providerId);
         if (!provider) {
             console.error("[ToolProviderRegistry] Provider not found:", {
@@ -229,11 +222,6 @@ export class ToolProviderRegistry {
             console.log("[ToolProviderRegistry] Auto-initializing provider:", providerId);
             await this.initialize(providerId);
         }
-        console.log("[ToolProviderRegistry] Returning provider:", {
-            providerId,
-            providerName: provider.providerName,
-            isReady: provider.isReady(),
-        });
         return provider;
     }
     /**

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

@@ -6,14 +6,5 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-export type { ToolProviderApi, ToolCategory, ToolProviderCapabilities, } from "./ToolProviderApi.js";
 export { ToolProviderRegistry } from "./ToolProviderRegistry.js";
-export type { ToolProviderConfig } from "./ToolProviderRegistry.js";
-export { DesmosToolProvider } from "./DesmosToolProvider.js";
-export type { DesmosToolProviderConfig } from "./DesmosToolProvider.js";
-export { CortexToolProvider } from "./CortexToolProvider.js";
-export type { CortexToolProviderConfig } from "./CortexToolProvider.js";
-export { GeoGebraToolProvider } from "./GeoGebraToolProvider.js";
-export type { GeoGebraToolProviderConfig } from "./GeoGebraToolProvider.js";
 export { TTSToolProvider } from "./TTSToolProvider.js";
-export type { TTSToolProviderConfig, TTSBackend, } from "./TTSToolProvider.js";

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

@@ -8,8 +8,6 @@
  */
 // Registry
 export { ToolProviderRegistry } from "./ToolProviderRegistry.js";
-// Concrete providers
-export { DesmosToolProvider } from "./DesmosToolProvider.js";
-export { CortexToolProvider } from "./CortexToolProvider.js";
-export { GeoGebraToolProvider } from "./GeoGebraToolProvider.js";
+// Concrete providers. The calculator adapters live in the composition layer,
+// `@pie-players/pie-default-tool-loaders`, which owns the engine imports.
 export { TTSToolProvider } from "./TTSToolProvider.js";