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

package/dist/services/tool-context.js

@@ -4,28 +4,30 @@
  * 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.
  */
+import { runtimeElementTags } from "@pie-players/pie-players-shared/pie";
+import { parseVersionedTagName } from "@pie-players/pie-players-shared/pie/tag-names";
 /**
  * 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();
@@ -41,6 +43,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.
  *
@@ -85,8 +93,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 = [];
@@ -103,10 +110,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)) {
@@ -148,7 +152,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);
 }
 /**
@@ -157,19 +161,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",
@@ -221,9 +220,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
@@ -234,88 +284,99 @@ 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",
-    "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;
+function packageSpecFor(tag, elements) {
     if (!elements || typeof elements !== "object")
-        return false;
+        return undefined;
     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);
+    const spec = map[tag] ?? map[parseVersionedTagName(tag).baseName];
+    return typeof spec === "string" && spec ? spec : undefined;
+}
+function declaredSupports(elementClass) {
+    let declared;
+    try {
+        declared = elementClass.pieSupports;
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(declared))
+        return undefined;
+    return declared.filter((term) => typeof term === "string");
+}
+function readElementSupports(model, elements) {
+    if (!model || typeof model !== "object")
+        return null;
+    const { id, element } = model;
+    if (typeof element !== "string" || !element)
+        return null;
+    const packageSpec = packageSpecFor(element, elements);
+    const candidates = runtimeElementTags(element, packageSpec);
+    const registry = typeof customElements === "undefined" ? undefined : customElements;
+    for (const tag of candidates) {
+        const elementClass = registry?.get(tag);
+        if (elementClass) {
+            return {
+                elementId: typeof id === "string" ? id : undefined,
+                tag: element,
+                packageSpec,
+                supports: declaredSupports(elementClass),
+                pendingTags: [],
+            };
+        }
+    }
+    return {
+        elementId: typeof id === "string" ? id : undefined,
+        tag: element,
+        packageSpec,
+        supports: undefined,
+        pendingTags: registry ? candidates : [],
+    };
 }
 /**
- * Helper to check if context contains choice-based interactions
+ * The supports each element of a context declares: the element's own at element
+ * level, every element of the item or passage config at those levels, and none
+ * elsewhere. A model that names no element renders nothing and is skipped.
  */
-export function hasChoiceInteraction(context) {
+export function elementSupports(context) {
+    let config;
+    let models;
     if (isElementContext(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);
-        if (!model)
-            return false;
-        const type = model.element || "";
-        return isChoiceElement(type, config.elements);
+        config = context.item.config;
+        models = [findElementModel(config?.models, context.elementId)];
     }
-    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 false;
-            const type = m.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.
-            if (type)
-                return isChoiceElement(type, config?.elements);
-            return Array.isArray(m.choices) && m.choices.length > 0;
-        });
+    else if (isItemContext(context)) {
+        config = context.item?.config;
+        models = normalizeModels(config?.models);
     }
-    return false;
+    else if (isPassageContext(context)) {
+        config = context.passage?.config;
+        models = normalizeModels(config?.models);
+    }
+    else {
+        return [];
+    }
+    return models.flatMap((model) => {
+        const supports = readElementSupports(model, config?.elements);
+        return supports ? [supports] : [];
+    });
 }
 /**
  * Helper to check if context contains text that can be read aloud
@@ -325,15 +386,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,7 +4,7 @@
  * 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.
@@ -14,6 +14,5 @@
  * 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,7 +4,7 @@
  * 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.
@@ -14,7 +14,7 @@
  * 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,13 +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 {};

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,9 +32,8 @@ 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,

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

@@ -7,12 +7,10 @@
  *   `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 } 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 credentials and instrumentation this
@@ -70,55 +68,20 @@ export declare class TTSToolProvider implements ToolProviderApi<ITTSProvider> {
     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 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.
      */
     initialize(config: TTSToolProviderConfig): Promise<void>;
-    /**
-     * Initialize browser TTS (Web Speech API)
-     */
     private _initializeBrowserTTS;
-    /**
-     * Initialize server-based TTS
-     */
     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>;
-    /**
-     * The backend's capabilities. Its features are the speech provider's own,
-     * and all false before {@link initialize} creates it.
-     */
-    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;
 }