@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/services/tool-context.js

@@ -4,40 +4,28 @@
  * 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
  */
-export function isItemContext(context) {
+function isItemContext(context) {
     return context.level === "item";
 }
 /**
  * Type guard to check if context is at passage level
  */
-export function isPassageContext(context) {
+function isPassageContext(context) {
     return context.level === "passage";
 }
 /**
  * Type guard to check if context is at rubric level
  */
-export function isRubricContext(context) {
+function isRubricContext(context) {
     return context.level === "rubric";
 }
 /**
  * Type guard to check if context is at element level
  */
-export function isElementContext(context) {
+function isElementContext(context) {
     return context.level === "element";
 }
 const stripHtml = (value) => value.replace(/<[^>]*>/g, " ").trim();
@@ -53,6 +41,12 @@ function normalizeModels(modelsRaw) {
     }
     return [];
 }
+/** The model in a config's `models` whose `id` is `elementId`, if any. */
+function findElementModel(modelsRaw, elementId) {
+    return normalizeModels(modelsRaw).find((candidate) => !!candidate &&
+        typeof candidate === "object" &&
+        candidate.id === elementId);
+}
 /**
  * Push every string a model carries, one level into its arrays of objects.
  *
@@ -97,8 +91,7 @@ function collectElementsText(elements, push) {
  *
  * `transform` decides what the caller gets. {@link extractTextContent} strips
  * tags, which is right for prose keyword matching and wrong for structural
- * matching: a MathML item's only math signal *is* the `<math>` tag, and stripping
- * first left `hasMathContent`'s MathML pattern unreachable.
+ * matching: a MathML item's only math signal *is* the `<math>` tag.
  */
 function extractContent(context, transform) {
     const textChunks = [];
@@ -115,10 +108,7 @@ function extractContent(context, transform) {
             push(elementMarkup);
         // Model data keyed by this element id: in many items the math is in
         // `model.prompt`/labels rather than in `elements[elementId]`.
-        const model = normalizeModels(config.models).find((candidate) => !!candidate &&
-            typeof candidate === "object" &&
-            candidate.id === context.elementId);
-        collectModelText(model, push);
+        collectModelText(findElementModel(config.models, context.elementId), push);
         return joined();
     }
     if (isItemContext(context)) {
@@ -160,7 +150,7 @@ function extractContent(context, transform) {
     return "";
 }
 /** The plain text a context carries, tags removed. */
-export function extractTextContent(context) {
+function extractTextContent(context) {
     return extractContent(context, stripHtml);
 }
 /**
@@ -169,19 +159,14 @@ export function extractTextContent(context) {
  * For indicators that live in the markup rather than in the prose — `<math>`
  * above all, whose whole signal is the element name.
  */
-export function extractMarkupContent(context) {
+function extractMarkupContent(context) {
     return extractContent(context, (value) => value);
 }
-/**
- * Helper to check if context contains mathematical content
- * (Basic heuristic - can be overridden by tools)
- */
 /**
  * Chemical element symbols.
  *
  * A real set rather than `[A-Z][a-z]?`: that shape matches "It", "In", "He" and
- * "A", which is why the science gate used to answer `true` for any prose that
- * began a sentence.
+ * "A", so any prose beginning a sentence would read as science.
  */
 const ELEMENT_SYMBOLS = new Set([
     "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne", "Na", "Mg", "Al", "Si",
@@ -233,9 +218,60 @@ function hasChemicalFormula(text) {
     }
     return false;
 }
+/** Numbers joined by slashes: `3/4`, `12 / 4`, `10/10/2026`. */
+const SLASH_RUN = /\d+(?:\s*\/\s*\d+)+/g;
+/** Numbers joined by hyphens spaced on both sides: `15 - 7`, `1809 - 1865`. */
+const SPACED_HYPHEN_RUN = /\d+(?:[.,]\d+)*(?:\s+-\s+\d+(?:[.,]\d+)*)+/g;
+/**
+ * Whether the text holds a fraction or a division: exactly one slash between
+ * two numbers. A second slash makes the run a date — `10/10/2026`, `2026/10/10`.
+ */
+function hasFraction(text) {
+    return (text.match(SLASH_RUN) ?? []).some((run) => run.split("/").length === 2);
+}
+/**
+ * Whether the text holds a subtraction written with a hyphen.
+ *
+ * Between numbers a hyphen is mostly a range, a date or an identifier:
+ * `1990-2000`, `2025-26`, `2026-10-10`, `555-1234`. On its own it counts as
+ * minus only when spaced on both sides, and then only where the numbers fail to
+ * ascend, since a range runs low to high: `15 - 7` counts, `1809 - 1865` does
+ * not. The trade is that `3 - 5` on its own reads as a range; with an equals
+ * sign next to it, it is caught as an equation.
+ */
+function hasSpacedSubtraction(text) {
+    return (text.match(SPACED_HYPHEN_RUN) ?? []).some((run) => {
+        const values = run
+            .split(/\s+-\s+/)
+            .map((value) => Number(value.replace(/,/g, "")));
+        return values.some((value, index) => index > 0 && value <= values[index - 1]);
+    });
+}
+const PERCENTAGE = /\d\s*%/;
+/** A percentage taken of a number: `20% of 50`, `15% of $80`, `el 20% de 50`. */
+const PERCENTAGE_OF_NUMBER = /\d\s*%\s+(?:of|de|van)\s+[$€£]?\s?\d/i;
+/** A money amount: `$40`, `€ 12`, `12,50 €`. */
+const MONEY = /[$€£]\s?\d|\d\s?[€£]/;
+/**
+ * Whether the text applies a percentage to a quantity.
+ *
+ * A percentage on its own is a statistic in prose — "40% of voters", "70% of
+ * Earth's surface" — so it counts when taken of a number or when the text
+ * carries a money amount, as discount, tax and interest problems do. Beside an
+ * operator (`25% = 0.25`) it is caught with the operator.
+ */
+function hasAppliedPercentage(text) {
+    if (PERCENTAGE_OF_NUMBER.test(text))
+        return true;
+    return PERCENTAGE.test(text) && MONEY.test(text);
+}
+/**
+ * Helper to check if context contains mathematical content
+ * (Basic heuristic - can be overridden by tools)
+ */
 export function hasMathContent(context) {
-    // Structural signals live in the markup: stripping tags first is what left the
-    // MathML pattern unable to match anything at all.
+    // Structural signals live in the markup, so they match before tags are
+    // stripped.
     const markup = extractMarkupContent(context);
     const structuralIndicators = [
         /<math[>\s]/i, // MathML
@@ -246,20 +282,23 @@ export function hasMathContent(context) {
     if (structuralIndicators.some((pattern) => pattern.test(markup)))
         return true;
     const text = extractTextContent(context);
-    // No bare-operator pattern. `/[+\-*/=<>≤≥∑∫√π]/` matched any hyphen or slash,
-    // so "well-known" and "and/or" made every item mathematical and this predicate
-    // answered `true` for essentially all content — a gate that does not gate. An
-    // operator counts only with operands around it, or when the character has no
-    // prose reading at all.
+    // No bare-operator pattern: a lone hyphen or slash matches "well-known" and
+    // "and/or", which would make nearly every item mathematical. An operator
+    // counts only with operands around it, or when the character has no prose
+    // reading at all. Hyphens and slashes between numbers also write dates and
+    // ranges, and a percentage alone is a statistic, so those have their own
+    // predicates below. An operand may carry a percent sign (`25% = 0.25`).
     const textIndicators = [
         /[≤≥≠±×÷∑∫√∞π]/, // Symbols with no prose reading
-        /\d+\s*[+\-*/×÷=]\s*\d+/, // Simple arithmetic
-        /\d\s*[<>]\s*\d/, // Numeric comparison
-        /\b\d+\s*\/\s*\d+\b/, // Fractions
-        /\b\d+(?:\.\d+)?\s*%/, // Percentages
+        /\d\s*%?\s*[+*×÷=−]\s*\d/, // Operators with no date or range reading
+        /\d\s*[-/]\s*\d[\d.,]*\s*=|=\s*\d[\d.,]*\s*[-/]\s*\d/, // Hyphen or slash in an equation
+        /\d\s*%?\s*[<>]\s*\d/, // Numeric comparison
         /\^\s*\d/, // Exponents
     ];
-    return textIndicators.some((pattern) => pattern.test(text));
+    return (textIndicators.some((pattern) => pattern.test(text)) ||
+        hasFraction(text) ||
+        hasSpacedSubtraction(text) ||
+        hasAppliedPercentage(text));
 }
 const CHOICE_INTERACTION_ELEMENTS = new Set([
     "multiple-choice",
@@ -294,11 +333,7 @@ export function hasChoiceInteraction(context) {
         const config = context.item.config;
         if (!config?.models)
             return false;
-        // Find model for this element
-        const models = Array.isArray(config.models)
-            ? config.models
-            : Object.values(config.models);
-        const model = models.find((m) => m && typeof m === "object" && m.id === context.elementId);
+        const model = findElementModel(config.models, context.elementId);
         if (!model)
             return false;
         const type = model.element || "";
@@ -306,25 +341,19 @@ export function hasChoiceInteraction(context) {
     }
     if (isItemContext(context)) {
         const config = context.item.config;
-        const modelsRaw = config?.models;
-        const models = Array.isArray(modelsRaw)
-            ? modelsRaw
-            : modelsRaw && typeof modelsRaw === "object"
-                ? Object.values(modelsRaw)
-                : [];
-        return models.some((m) => {
-            if (!m || typeof m !== "object")
+        return normalizeModels(config?.models).some((candidate) => {
+            if (!candidate || typeof candidate !== "object")
                 return false;
-            const type = m.element || "";
+            const model = candidate;
+            const type = model.element || "";
             // A model that names its element has answered the question, whichever way
-            // the answer falls. `choices` is carried by interactions that are not
-            // choice interactions at all — `placement-ordering`, `categorize` and
-            // `drag-in-the-blank` each hold their draggables there — so reading it on
-            // a named model showed the answer eliminator on items where the tool does
-            // nothing. The heuristic remains for configs that name no element.
+            // the answer falls: `placement-ordering`, `categorize` and
+            // `drag-in-the-blank` each hold their draggables in `choices` without
+            // being choice interactions. The `choices` heuristic remains for configs
+            // that name no element.
             if (type)
                 return isChoiceElement(type, config?.elements);
-            return Array.isArray(m.choices) && m.choices.length > 0;
+            return Array.isArray(model.choices) && model.choices.length > 0;
         });
     }
     return false;
@@ -337,15 +366,20 @@ export function hasReadableText(context) {
     // Must have at least 10 characters of text (arbitrary threshold)
     return text.trim().length >= 10;
 }
+/**
+ * Whether read-aloud has something to read: readable text, or markup carrying
+ * a catalog idref, whose spoken card reads for content with no text.
+ */
+export function hasSpokenContent(context) {
+    return (hasReadableText(context) ||
+        /\bdata-catalog-idref\s*=/.test(extractMarkupContent(context)));
+}
 /**
  * Helper to check if context contains science content
  * (Basic heuristic - can be overridden by tools)
  */
 export function hasScienceContent(context) {
     const text = extractTextContent(context);
-    // The element-symbol pattern used to be `/\b[A-Z][a-z]?\d*\b/`, which matches
-    // any one- or two-letter capitalised word: "It", "In", "A", "No". Every item
-    // beginning a sentence with one read as science.
     if (hasChemicalFormula(text))
         return true;
     if (/[A-Z][a-z]?[\u2080-\u2089]/.test(text))

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

@@ -0,0 +1,30 @@
+/**
+ * Where a tool failed, as reported to the toolkit's tool failure policy.
+ *
+ * `tool-module-load` follows the start-failure policy: the tool degrades unless
+ * policy grants it, in which case the failure is fatal. Every other phase keeps a
+ * recovery at its report site and is recoverable:
+ *
+ * - `tool-request-open`: a toolbar threw opening a requested tool; the request
+ *   reports that no toolbar claimed it.
+ * - `tool-request-host-check`: a toolbar threw answering whether it hosts a tool,
+ *   and is passed by.
+ * - `tool-visibility`: a registration's relevance check threw; the tool is
+ *   withheld unless a grant protects it.
+ * - `tool-applicability`: a registration's applicability gate threw; the tool
+ *   counts as applicable.
+ * - `tool-state-load`, `tool-state-save`: a tool could not restore or keep its
+ *   own learner state, as the annotation toolbar's highlights.
+ * - `tool-playback`: a tool could not play, seek or change the rate of speech
+ *   after speech started; a start failure is reported as `tts-init`.
+ */
+export type ToolFailurePhase = "tool-module-load" | "tool-request-open" | "tool-request-host-check" | "tool-visibility" | "tool-applicability" | "tool-state-load" | "tool-state-save" | "tool-playback";
+/** The coordinator surface a failing tool reports through. */
+export interface ToolFailureReporter {
+    reportToolFailure?(toolId: string, phase: ToolFailurePhase, error: unknown): void;
+}
+/**
+ * Report a tool failure to the coordinator in scope, or log it when there is
+ * none, as for a tool mounted outside a toolkit.
+ */
+export declare function reportToolFailure(coordinator: ToolFailureReporter | null | undefined, toolId: string, phase: ToolFailurePhase, error: unknown): void;

package/dist/services/tool-failure.js

@@ -0,0 +1,11 @@
+/**
+ * Report a tool failure to the coordinator in scope, or log it when there is
+ * none, as for a tool mounted outside a toolkit.
+ */
+export function reportToolFailure(coordinator, toolId, phase, error) {
+    if (typeof coordinator?.reportToolFailure === "function") {
+        coordinator.reportToolFailure(toolId, phase, error);
+        return;
+    }
+    console.error(`[${toolId}] ${phase} failed:`, error);
+}

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

@@ -4,15 +4,15 @@
  * A registration names an icon rather than shipping markup, so a host swapping the
  * button chrome gets one consistent set. A name with no entry here renders no icon
  * at all, and an icon-only button with no icon is a blank square — so a registration
- * naming an icon and this map are one change, not two.
+ * that names a new icon adds its entry here in the same change.
  *
  * 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. */
 export declare function resolveFallbackToolIcon(name: string): string | null;

package/dist/services/tool-icons.js

@@ -4,16 +4,17 @@
  * A registration names an icon rather than shipping markup, so a host swapping the
  * button chrome gets one consistent set. A name with no entry here renders no icon
  * at all, and an icon-only button with no icon is a blank square — so a registration
- * naming an icon and this map are one change, not two.
+ * that names a new icon adds its entry here in the same change.
  *
  * 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 = {
+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>',
     "volume-up": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 3.23v2.06A7.002 7.002 0 0 1 19 12a7 7 0 0 1-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77Zm-2 17.75V3L7 8H3v8h4l5 5Zm4.5-9a4.5 4.5 0 0 0-2.5-4.03v8.05A4.5 4.5 0 0 0 16.5 12Z" fill="currentColor"/></svg>',
     swatch: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 3a9 9 0 1 0 9 9c0-.55-.45-1-1-1h-2.5a1.5 1.5 0 0 1 0-3H20a1 1 0 0 0 1-1 8.99 8.99 0 0 0-9-4Zm-5.5 9A1.5 1.5 0 1 1 8 13.5 1.5 1.5 0 0 1 6.5 12Zm3-4A1.5 1.5 0 1 1 11 9.5 1.5 1.5 0 0 1 9.5 8Zm5 0A1.5 1.5 0 1 1 16 9.5 1.5 1.5 0 0 1 14.5 8Z" fill="currentColor"/></svg>',

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

@@ -1,14 +1,15 @@
-export declare const DEFAULT_TOOL_SCOPE_LEVELS: readonly ["assessment", "section", "item", "passage", "rubric"];
-export type BuiltinToolScopeLevel = (typeof DEFAULT_TOOL_SCOPE_LEVELS)[number];
-export type ToolScopeLevel = BuiltinToolScopeLevel | (string & {});
+declare const TOOL_SCOPE_LEVELS: readonly ["assessment", "section", "item", "passage", "rubric"];
+export type ToolScopeLevel = (typeof TOOL_SCOPE_LEVELS)[number];
 export interface ParsedToolInstanceId {
     baseToolId: string;
     scopeLevel: ToolScopeLevel;
     scopeId: string;
 }
-export declare function getRegisteredToolScopeLevels(): string[];
-export declare function registerToolScopeLevel(scopeLevel: string): void;
-export declare function isRegisteredToolScopeLevel(scopeLevel: string): scopeLevel is ToolScopeLevel;
+/**
+ * A tool instance id, `<baseToolId>:<scopeLevel>:<scopeId>`, from trimmed parts.
+ * Throws on an empty part or an unknown scope level.
+ */
 export declare function createScopedToolId(baseToolId: string, scopeLevel: ToolScopeLevel, scopeId: string): string;
+/** The parts of a tool instance id, or `null` when `id` is not one. */
 export declare function parseScopedToolId(id: string): ParsedToolInstanceId | null;
-export declare function toOverlayToolId(id: string): string;
+export {};

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

@@ -1,35 +1,30 @@
-export const DEFAULT_TOOL_SCOPE_LEVELS = [
+const TOOL_SCOPE_LEVELS = [
     "assessment",
     "section",
     "item",
     "passage",
     "rubric",
 ];
-const registeredToolScopeLevels = new Set(DEFAULT_TOOL_SCOPE_LEVELS);
-export function getRegisteredToolScopeLevels() {
-    return Array.from(registeredToolScopeLevels.values());
-}
-export function registerToolScopeLevel(scopeLevel) {
-    const normalized = scopeLevel.trim();
-    if (!normalized) {
-        throw new Error("Tool scope level must be a non-empty string");
-    }
-    registeredToolScopeLevels.add(normalized);
-}
-export function isRegisteredToolScopeLevel(scopeLevel) {
-    return registeredToolScopeLevels.has(scopeLevel);
+const toolScopeLevels = new Set(TOOL_SCOPE_LEVELS);
+function isToolScopeLevel(scopeLevel) {
+    return toolScopeLevels.has(scopeLevel);
 }
+/**
+ * A tool instance id, `<baseToolId>:<scopeLevel>:<scopeId>`, from trimmed parts.
+ * Throws on an empty part or an unknown scope level.
+ */
 export function createScopedToolId(baseToolId, scopeLevel, scopeId) {
     const normalizedBase = baseToolId.trim();
     const normalizedScopeId = scopeId.trim();
     if (!normalizedBase || !normalizedScopeId) {
         throw new Error("Tool instance ids require non-empty tool and scope ids");
     }
-    if (!isRegisteredToolScopeLevel(scopeLevel)) {
-        throw new Error(`Unknown tool scope level '${scopeLevel}'. Register custom levels with registerToolScopeLevel().`);
+    if (!isToolScopeLevel(scopeLevel)) {
+        throw new Error(`Unknown tool scope level '${scopeLevel}'.`);
     }
     return `${normalizedBase}:${scopeLevel}:${normalizedScopeId}`;
 }
+/** The parts of a tool instance id, or `null` when `id` is not one. */
 export function parseScopedToolId(id) {
     const parts = id.split(":");
     if (parts.length !== 3)
@@ -37,18 +32,11 @@ export function parseScopedToolId(id) {
     const [baseToolId, scopeLevelRaw, scopeId] = parts;
     if (!baseToolId || !scopeId)
         return null;
-    if (!isRegisteredToolScopeLevel(scopeLevelRaw)) {
+    if (!isToolScopeLevel(scopeLevelRaw))
         return null;
-    }
     return {
         baseToolId,
         scopeLevel: scopeLevelRaw,
         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,24 +1,22 @@
 /**
  * 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)
- *
- * Part of PIE Assessment Toolkit.
+ * 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`
  */
 import type { ITTSProvider } from "@pie-players/pie-tts";
 import type { RuntimeTTSConfig, TTSRuntimeSettings } from "../tts-runtime-config.js";
-import type { ToolProviderApi, ToolProviderCapabilities } from "./ToolProviderApi.js";
+import type { ToolProviderApi } from "./ToolProviderApi.js";
 export type TTSBackend = NonNullable<TTSRuntimeSettings["backend"]>;
 /**
- * The runtime provider config plus the backend selection and instrumentation
- * this tool provider reads.
+ * The runtime provider config plus the credentials and instrumentation this
+ * tool provider reads. The backend is fixed at construction.
  */
 export type TTSToolProviderConfig = RuntimeTTSConfig & {
-    backend: TTSBackend;
-    serverProvider?: TTSRuntimeSettings["serverProvider"];
     /**
      * Bearer token for a server backend, sent as `Authorization`. A host supplies
      * it through `provider.runtime.authFetcher`.
@@ -38,88 +36,52 @@ export type TTSToolProviderOptions = {
 /**
  * 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
  * ```typescript
- * const provider = new TTSToolProvider('polly', {
+ * const provider = new TTSToolProvider('server', {
  *   loadServerProvider: async () => ServerTTSProvider,
  * });
  * await provider.initialize({
- *   backend: 'polly',
+ *   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
-     */
+    /** A server backend needs `options.loadServerProvider`. */
     constructor(backend?: TTSBackend, options?: TTSToolProviderOptions);
     /**
-     * Initialize TTS provider
-     *
-     * Sets up the appropriate TTS backend.
-     *
-     * @param config Configuration with backend type 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.
      */
     initialize(config: TTSToolProviderConfig): Promise<void>;
-    /**
-     * Initialize browser TTS (Web Speech API)
-     */
     private _initializeBrowserTTS;
-    /**
-     * Initialize server-based TTS (Polly, Google)
-     */
     private _initializeServerTTS;
     /**
-     * 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`.
      */
     createInstance(config?: Partial<TTSToolProviderConfig>): Promise<ITTSProvider>;
-    /**
-     * Get provider capabilities
-     *
-     * @returns TTS capabilities based on backend
-     */
-    getCapabilities(): ToolProviderCapabilities;
-    /**
-     * Check if provider is ready
-     *
-     * @returns true if provider is initialized
-     */
     isReady(): boolean;
-    /**
-     * Clean up provider resources
-     *
-     * Destroys the TTS provider and releases resources.
-     */
     destroy(): void;
 }