@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

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

@@ -1,9 +1,9 @@
 /**
  * Placement defaults this package can hold.
  *
- * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
- * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
- * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ * Only the empty one. `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` names
+ * capabilities, so it lives in the composition layer
+ * (`@pie-players/pie-default-tool-loaders`).
  */
 export declare const DEFAULT_TOOL_PLACEMENT: {
     readonly assessment: readonly [];

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

@@ -1,9 +1,9 @@
 /**
  * Placement defaults this package can hold.
  *
- * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
- * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
- * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ * Only the empty one. `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` names
+ * capabilities, so it lives in the composition layer
+ * (`@pie-players/pie-default-tool-loaders`).
  */
 export const DEFAULT_TOOL_PLACEMENT = {
     assessment: [],

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

@@ -1,15 +1,14 @@
-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";
 export type ToolConfigDiagnosticSeverity = "warning" | "error";
 export interface ToolConfigDiagnostic {
-    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.removedProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
+    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
     severity: ToolConfigDiagnosticSeverity;
     path: string;
     message: string;
     toolId?: string;
-    providerId?: string;
 }
 export interface ToolConfigValidationOptions {
     strictness?: ToolConfigStrictness;
@@ -27,4 +26,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: `"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

@@ -34,21 +34,20 @@ function getRegistryToolMap(toolRegistry) {
         .sort((left, right) => left.toolId.localeCompare(right.toolId))
         .map((tool) => [tool.toolId, tool]));
 }
-function sanitizeProviderConfig(providerId, providerConfig, tool, diagnostics) {
-    if (!providerConfig || !tool?.provider?.sanitizeConfig)
+function sanitizeToolConfig(toolId, providerConfig, tool, diagnostics) {
+    if (!providerConfig || !tool?.sanitizeConfig)
         return providerConfig;
     try {
-        const sanitized = tool.provider.sanitizeConfig(providerConfig);
+        const sanitized = tool.sanitizeConfig(providerConfig);
         if (!sanitized ||
             typeof sanitized !== "object" ||
             Array.isArray(sanitized)) {
             diagnostics.push(createDiagnostic({
                 code: "tools.providerSanitizeFailed",
                 severity: "error",
-                path: `providers.${providerId}`,
-                message: `Provider sanitizer for "${providerId}" must return an object.`,
-                providerId,
-                toolId: providerId,
+                path: `providers.${toolId}`,
+                message: `Config sanitizer of tool "${toolId}" must return an object.`,
+                toolId,
             }));
             return providerConfig;
         }
@@ -58,36 +57,33 @@ function sanitizeProviderConfig(providerId, providerConfig, tool, diagnostics) {
         diagnostics.push(createDiagnostic({
             code: "tools.providerSanitizeFailed",
             severity: "error",
-            path: `providers.${providerId}`,
-            message: `Provider sanitizer failed for "${providerId}": ${error instanceof Error ? error.message : String(error)}`,
-            providerId,
-            toolId: providerId,
+            path: `providers.${toolId}`,
+            message: `Config sanitizer of tool "${toolId}" failed: ${error instanceof Error ? error.message : String(error)}`,
+            toolId,
         }));
         return providerConfig;
     }
 }
-function validateProviderConfig(providerId, providerConfig, tool, diagnostics) {
-    if (!providerConfig || !tool?.provider?.validateConfig)
+function validateToolConfig(toolId, providerConfig, tool, diagnostics) {
+    if (!providerConfig || !tool?.validateConfig)
         return;
     try {
-        const providerDiagnostics = tool.provider.validateConfig(providerConfig);
-        if (!Array.isArray(providerDiagnostics)) {
+        const toolDiagnostics = tool.validateConfig(providerConfig);
+        if (!Array.isArray(toolDiagnostics)) {
             diagnostics.push(createDiagnostic({
                 code: "tools.invalidProviderValidation",
                 severity: "error",
-                path: `providers.${providerId}`,
-                message: `Provider validator for "${providerId}" must return an array.`,
-                providerId,
-                toolId: providerId,
+                path: `providers.${toolId}`,
+                message: `Config validator of tool "${toolId}" must return an array.`,
+                toolId,
             }));
             return;
         }
-        for (const diagnostic of providerDiagnostics) {
+        for (const diagnostic of toolDiagnostics) {
             diagnostics.push({
                 ...diagnostic,
-                path: diagnostic.path || `providers.${providerId}`,
-                providerId: diagnostic.providerId || providerId,
-                toolId: diagnostic.toolId || providerId,
+                path: diagnostic.path || `providers.${toolId}`,
+                toolId: diagnostic.toolId || toolId,
             });
         }
     }
@@ -95,10 +91,9 @@ function validateProviderConfig(providerId, providerConfig, tool, diagnostics) {
         diagnostics.push(createDiagnostic({
             code: "tools.providerValidateFailed",
             severity: "error",
-            path: `providers.${providerId}`,
-            message: `Provider validator failed for "${providerId}": ${error instanceof Error ? error.message : String(error)}`,
-            providerId,
-            toolId: providerId,
+            path: `providers.${toolId}`,
+            message: `Config validator of tool "${toolId}" failed: ${error instanceof Error ? error.message : String(error)}`,
+            toolId,
         }));
     }
 }
@@ -176,27 +171,16 @@ function collectPolicyDiagnostics(config, toolMap, diagnostics) {
         }));
     }
 }
-function collectProviderKeyDiagnostics(config, toolMap, hasRemovedTtsKey, diagnostics) {
-    if (hasRemovedTtsKey) {
-        diagnostics.push(createDiagnostic({
-            code: "tools.removedProviderKey",
-            severity: "error",
-            path: "providers.tts",
-            message: `Provider key "tts" is no longer supported. Use "providers.textToSpeech".`,
-            providerId: "tts",
-            toolId: "textToSpeech",
-        }));
-    }
-    for (const providerId of Object.keys(config.providers).sort()) {
-        if (toolMap.size === 0 || toolMap.has(providerId))
+function collectProviderKeyDiagnostics(config, toolMap, diagnostics) {
+    for (const key of Object.keys(config.providers).sort()) {
+        if (toolMap.size === 0 || toolMap.has(key))
             continue;
         diagnostics.push(createDiagnostic({
             code: "tools.unknownProviderKey",
             severity: "error",
-            path: `providers.${providerId}`,
-            message: `Unknown provider key "${providerId}".`,
-            providerId,
-            toolId: providerId,
+            path: `providers.${key}`,
+            message: `Unknown provider key "${key}".`,
+            toolId: key,
         }));
     }
 }
@@ -215,15 +199,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,21 +226,16 @@ 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");
     const nextProviders = {
         ...(normalized.providers || {}),
     };
-    for (const providerId of Object.keys(nextProviders).sort()) {
-        if (providerId === "tts") {
-            delete nextProviders.tts;
-            continue;
-        }
-        const tool = registryTools.get(providerId);
-        nextProviders[providerId] = sanitizeProviderConfig(providerId, nextProviders[providerId], tool, diagnostics);
-        validateProviderConfig(providerId, nextProviders[providerId], tool, diagnostics);
+    for (const toolId of Object.keys(nextProviders).sort()) {
+        const tool = registryTools.get(toolId);
+        nextProviders[toolId] = sanitizeToolConfig(toolId, nextProviders[toolId], tool, diagnostics);
+        validateToolConfig(toolId, nextProviders[toolId], tool, diagnostics);
     }
     const nextConfig = {
         ...normalized,
@@ -257,18 +243,28 @@ 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);
-    }
+    collectProviderKeyDiagnostics(nextConfig, registryTools, diagnostics);
+    return {
+        config: nextConfig,
+        diagnostics,
+    };
+}
+/**
+ * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: `"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";
     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 +272,4 @@ export function normalizeAndValidateToolsConfig(input, options = {}) {
     if (strictness === "error" && blocking.length === 0) {
         emitWarnings(diagnostics, source);
     }
-    return {
-        config: nextConfig,
-        diagnostics,
-    };
 }

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

@@ -101,14 +101,6 @@ export interface ElementToolContext extends BaseToolContext {
  * Union type of all tool contexts
  */
 export type ToolContext = AssessmentToolContext | SectionToolContext | ItemToolContext | PassageToolContext | RubricToolContext | ElementToolContext;
-/**
- * Type guard to check if context is at assessment level
- */
-export declare function isAssessmentContext(context: ToolContext): context is AssessmentToolContext;
-/**
- * Type guard to check if context is at section level
- */
-export declare function isSectionContext(context: ToolContext): context is SectionToolContext;
 /**
  * Type guard to check if context is at item level
  */

package/dist/services/tool-context.js

@@ -4,18 +4,6 @@
  * Defines the context types passed to tools for making visibility and behavior decisions.
  * Each context level provides increasingly specific information about where the tool is being used.
  */
-/**
- * Type guard to check if context is at assessment level
- */
-export function isAssessmentContext(context) {
-    return context.level === "assessment";
-}
-/**
- * Type guard to check if context is at section level
- */
-export function isSectionContext(context) {
-    return context.level === "section";
-}
 /**
  * Type guard to check if context is at item level
  */
@@ -261,20 +249,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 +290,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 +311,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-icons.d.ts

@@ -9,9 +9,10 @@
  * Names are generic shapes ("book-open", "beaker"), never capability names. Core
  * naming a capability is what the composition layer exists to prevent.
  *
- * Exported through `tools/internal` as well: a registration composing a selection
- * gateway renders its own buttons and has to draw the same icon the toolbar button
- * draws, or the learner sees two unrelated affordances for one tool.
+ * `resolveFallbackToolIcon` is exported through `tools/registration` as well: a
+ * registration composing a selection gateway renders its own buttons and has to
+ * draw the same icon the toolbar button draws, or the learner sees two unrelated
+ * affordances for one tool.
  */
 export declare const TOOL_FALLBACK_ICONS: Readonly<Record<string, string>>;
 /** Icon markup for `name`, or `null` when nothing built in matches. */

package/dist/services/tool-icons.js

@@ -9,9 +9,10 @@
  * Names are generic shapes ("book-open", "beaker"), never capability names. Core
  * naming a capability is what the composition layer exists to prevent.
  *
- * Exported through `tools/internal` as well: a registration composing a selection
- * gateway renders its own buttons and has to draw the same icon the toolbar button
- * draws, or the learner sees two unrelated affordances for one tool.
+ * `resolveFallbackToolIcon` is exported through `tools/registration` as well: a
+ * registration composing a selection gateway renders its own buttons and has to
+ * draw the same icon the toolbar button draws, or the learner sees two unrelated
+ * affordances for one tool.
  */
 export const TOOL_FALLBACK_ICONS = {
     calculator: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M7 2h10a2 2 0 0 1 2 2v16a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2Zm0 2v4h10V4H7Zm0 6v2h2v-2H7Zm4 0v2h2v-2h-2Zm4 0v2h2v-2h-2Zm-8 4v2h2v-2H7Zm4 0v2h2v-2h-2Zm4 0v2h2v-2h-2Zm-8 4v2h2v-2H7Zm4 0v2h2v-2h-2Zm4 0v2h2v-2h-2Z" fill="currentColor"/></svg>',

package/dist/services/tool-instance-id.d.ts

@@ -11,4 +11,3 @@ export declare function registerToolScopeLevel(scopeLevel: string): void;
 export declare function isRegisteredToolScopeLevel(scopeLevel: string): scopeLevel is ToolScopeLevel;
 export declare function createScopedToolId(baseToolId: string, scopeLevel: ToolScopeLevel, scopeId: string): string;
 export declare function parseScopedToolId(id: string): ParsedToolInstanceId | null;
-export declare function toOverlayToolId(id: string): string;

package/dist/services/tool-instance-id.js

@@ -46,9 +46,3 @@ export function parseScopedToolId(id) {
         scopeId,
     };
 }
-export function toOverlayToolId(id) {
-    const parsed = parseScopedToolId(id);
-    if (!parsed)
-        return id;
-    return createScopedToolId(parsed.baseToolId, parsed.scopeLevel, parsed.scopeId);
-}

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

@@ -1,126 +1,88 @@
 /**
  * TTS Tool Provider
  *
- * Unified provider for all TTS backends:
- * - Browser Web Speech API (no auth)
- * - AWS Polly (requires auth via server proxy)
- * - Google Cloud TTS (requires auth via server proxy)
+ * Unified provider for both TTS backends:
+ * - `browser`: the Web Speech API (no auth)
+ * - `server`: a TTS server, its service named by the config's `provider`.
+ *   `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 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 credentials and instrumentation this
+ * tool provider reads. The backend is fixed at construction.
  */
-export type TTSBackend = "browser" | "polly" | "google" | "server";
-/**
- * TTS tool provider configuration
- */
-export interface TTSToolProviderConfig extends Partial<TTSConfig> {
-    /**
-     * TTS backend to use
-     */
-    backend: TTSBackend;
-    /**
-     * 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;
+export type TTSToolProviderConfig = RuntimeTTSConfig & {
     /**
-     * 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
  *
- * Wraps TTS providers (Browser, Polly, Google) with the ToolProviderApi interface
+ * Wraps the browser or a server TTS provider with the ToolProviderApi interface
  * for use in the ToolProviderRegistry.
  *
  * @example Browser TTS (no auth)
  * ```typescript
  * const provider = new TTSToolProvider();
- * await provider.initialize({ backend: 'browser' });
+ * await provider.initialize({});
  * const ttsProvider = await provider.createInstance();
  * ```
  *
- * @example Server TTS (with auth)
+ * @example Server TTS
  * ```typescript
- * const provider = new TTSToolProvider();
+ * const provider = new TTSToolProvider('server', {
+ *   loadServerProvider: async () => ServerTTSProvider,
+ * });
  * await provider.initialize({
- *   backend: 'polly',
- *   apiEndpoint: '/api/tts/synthesize',
- *   authToken: 'bearer-token', // Fetched via authFetcher
+ *   provider: 'polly',
+ *   apiEndpoint: '/api/tts',
  * });
  * const ttsProvider = await provider.createInstance();
  * ```
  */
-export declare class TTSToolProvider implements ToolProviderApi<TTSToolProviderConfig, ITTSProvider> {
-    readonly providerId = "tts-service";
+export declare class TTSToolProvider implements ToolProviderApi<ITTSProvider> {
     readonly providerName = "Text-to-Speech";
     readonly category: "tts";
     readonly version = "1.0";
     readonly requiresAuth: boolean;
+    private readonly backend;
     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
      *
      * Sets up the appropriate TTS backend.
      *
-     * @param config Configuration with backend type and credentials
+     * @param config Runtime configuration and credentials
      * @throws Error if initialization fails or required config missing
      */
     initialize(config: TTSToolProviderConfig): Promise<void>;
@@ -129,7 +91,7 @@ export declare class TTSToolProvider implements ToolProviderApi<TTSToolProviderC
      */
     private _initializeBrowserTTS;
     /**
-     * Initialize server-based TTS (Polly, Google)
+     * Initialize server-based TTS
      */
     private _initializeServerTTS;
     /**
@@ -143,9 +105,8 @@ export declare class TTSToolProvider implements ToolProviderApi<TTSToolProviderC
      */
     createInstance(config?: Partial<TTSToolProviderConfig>): Promise<ITTSProvider>;
     /**
-     * Get provider capabilities
-     *
-     * @returns TTS capabilities based on backend
+     * The backend's capabilities. Its features are the speech provider's own,
+     * and all false before {@link initialize} creates it.
      */
     getCapabilities(): ToolProviderCapabilities;
     /**