@pie-players/pie-default-tool-loaders 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/registrations/calculator.js

@@ -7,32 +7,21 @@
 import { hasMathContent } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createScopedToolId } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createToolElement } from "@pie-players/pie-assessment-toolkit/tools/registration";
-import { CortexToolProvider } from "../calculator-providers/CortexToolProvider.js";
-import { DesmosToolProvider } from "../calculator-providers/DesmosToolProvider.js";
-import { GeoGebraToolProvider } from "../calculator-providers/GeoGebraToolProvider.js";
+import { LazyCalculatorToolProvider, } from "../calculator-providers/LazyCalculatorToolProvider.js";
+import { DEFAULT_CALCULATOR_PROVIDER_ID, PACKAGED_CALCULATOR_PROVIDERS, } from "../calculator-providers/packaged-calculator-providers.js";
 import { resolveOverlayElement } from "./overlay-element-cache.js";
-export const DEFAULT_CALCULATOR_PROVIDER_ID = "calculator-desmos";
-export function resolveCalculatorProviderId(config) {
+export function resolveCalculatorProviderId(config, providers = PACKAGED_CALCULATOR_PROVIDERS) {
     const configured = config?.provider?.id;
     if (configured === undefined || configured === "") {
         return DEFAULT_CALCULATOR_PROVIDER_ID;
     }
-    if (configured === "calculator-desmos" ||
-        configured === "calculator-geogebra" ||
-        configured === "calculator-cortex") {
+    if (typeof configured === "string" && Object.hasOwn(providers, configured)) {
         return configured;
     }
-    throw new Error(`Unsupported calculator provider "${String(configured)}". Expected "calculator-desmos", "calculator-geogebra", or "calculator-cortex".`);
-}
-function createCalculatorToolProvider(config) {
-    switch (resolveCalculatorProviderId(config)) {
-        case "calculator-cortex":
-            return new CortexToolProvider();
-        case "calculator-geogebra":
-            return new GeoGebraToolProvider();
-        default:
-            return new DesmosToolProvider();
-    }
+    const expected = Object.keys(providers)
+        .map((id) => `"${id}"`)
+        .join(", ");
+    throw new Error(`Unsupported calculator provider "${String(configured)}". Expected one of ${expected}.`);
 }
 function getCalculatorInstanceConfig(config) {
     const theme = config?.theme;
@@ -104,169 +93,175 @@ function applyCalculatorParamsToElement(element, calculatorType, availableTypes,
     }
 }
 /**
- * Calculator tool registration
+ * Builds the calculator registration over the packaged backends plus any the
+ * host adds, so a host bundles a backend only by naming it.
  *
  * Supports:
- * - Basic, scientific, and graphing calculators through Desmos, GeoGebra, or Cortex
+ * - Basic, scientific, and graphing calculators through the backend that
+ *   `provider.id` selects, Desmos by default
  * - Context-aware visibility (shows only when math content is detected)
  * - Item level only
  */
-export const calculatorToolRegistration = {
-    toolId: "calculator",
-    name: "Calculator",
-    description: "Multi-type calculator (basic, scientific, graphing)",
-    nameKey: "tools.calculator.name",
-    descriptionKey: "tools.calculator.description",
-    icon: "calculator",
-    provider: {
-        createProvider: createCalculatorToolProvider,
-        getInitConfig: (config) => config?.provider?.init ?? {},
-        getAuthFetcher: (config) => {
-            const runtimeAuthFetcher = config?.provider?.runtime?.authFetcher;
-            return typeof runtimeAuthFetcher === "function"
-                ? runtimeAuthFetcher
-                : undefined;
+export function createCalculatorToolRegistration(options = {}) {
+    const providers = { ...PACKAGED_CALCULATOR_PROVIDERS, ...options.providers };
+    return {
+        toolId: "calculator",
+        name: "Calculator",
+        description: "Multi-type calculator (basic, scientific, graphing)",
+        nameKey: "tools.calculator.name",
+        descriptionKey: "tools.calculator.description",
+        icon: "calculator",
+        provider: {
+            createProvider: (config) => new LazyCalculatorToolProvider(providers[resolveCalculatorProviderId(config, providers)]),
+            getInitConfig: (config) => config?.provider?.init ?? {},
+            getAuthFetcher: (config) => {
+                const runtimeAuthFetcher = config?.provider?.runtime?.authFetcher;
+                return typeof runtimeAuthFetcher === "function"
+                    ? runtimeAuthFetcher
+                    : undefined;
+            },
+            lazy: true,
+        },
+        // Calculator is item-level in this player architecture.
+        supportedLevels: ["item"],
+        /**
+         * Pass 2: Determine if calculator is relevant in this context
+         *
+         * Calculator is relevant when context contains mathematical content
+         * (MathML, LaTeX, arithmetic markers).
+         */
+        isVisibleInContext(context) {
+            return hasMathContent(context);
         },
-        lazy: true,
-    },
-    // Calculator is item-level in this player architecture.
-    supportedLevels: ["item"],
-    /**
-     * Pass 2: Determine if calculator is relevant in this context
-     *
-     * Calculator is relevant when context contains mathematical content
-     * (MathML, LaTeX, arithmetic markers).
-     */
-    isVisibleInContext(context) {
-        return hasMathContent(context);
-    },
-    renderToolbar(context, toolbarContext) {
-        const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
-        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
-            undefined;
-        const calculatorConfig = getCalculatorInstanceConfig(calculatorToolConfig);
-        const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
-        const componentOverrides = toolbarContext.componentOverrides;
-        // Reused across renders: besides keeping state, this spares a Desmos boot
-        // and container mount on every re-render.
-        const overlay = resolveOverlayElement(toolbarContext, fullToolId, () => createToolElement(this.toolId, context, toolbarContext, componentOverrides));
-        overlay.setAttribute("tool-id", fullToolId);
-        applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
-        const button = {
-            toolId: this.toolId,
-            label: displayName,
-            icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
-            // Routes this button through <nds-icon-button> where the host enables NDS
-            // icons. Declared here because which capabilities render in the host's
-            // design system is a composition decision.
-            faIconName: "calculator",
-            disabled: false,
-            // The name stays put across open and closed. The toolbar mirrors
-            // `active` onto the button as `aria-pressed`, so the state is already
-            // exposed; a name that also swapped to "Close …" would contradict it.
-            ariaLabel: displayName,
-            tooltip: displayName,
-            onClick: () => toolbarContext.toggleTool(this.toolId),
-            active: toolbarContext.isToolVisible(this.toolId),
-        };
-        let lastVisibleState = button.active;
-        if (overlay.visible !== button.active) {
-            overlay.visible = button.active;
-        }
-        return {
-            toolId: this.toolId,
-            elements: [
-                {
-                    element: overlay,
-                    mount: "after-buttons",
-                    shell: {
-                        // The variant name the button already carries — "Basic Calculator",
-                        // not the registration's generic one.
-                        title: displayName,
-                        draggable: true,
-                        resizable: true,
-                        closeable: true,
-                        /*
-                         * Sized per type from what each layout measures, rather than one
-                         * size for all three. A shell subtracts ~74px of header from the
-                         * height it is given, and the numbers below are the content each
-                         * type needs plus room for its history tape:
-                         *
-                         * - basic: strip, display, edit row and a four-row keypad measure
-                         *   398px. 560 left ~90px of blank above the entry line, which is
-                         *   the gap that made the panel look mis-sized.
-                         * - scientific: the same plus a keypad layer tab row.
-                         * - graphing: the expression rail beside the plot, whose column
-                         *   wants 486px on its own — viewport controls, a 14rem board floor
-                         *   and the readout that *is* the graph for assistive technology,
-                         *   since the board itself is `aria-hidden`. At 620 that column was
-                         *   12px short and the readout's last line was cut off.
-                         *
-                         * The minimums stay shared across types and providers. This
-                         * registration serves Desmos, GeoGebra and Cortex alike, so a
-                         * graphing-only floor would move the resize limit under two vendors
-                         * whose layouts were never measured for it. Cortex below 42rem
-                         * stacks the rail above the plot and needs 701px there, which no
-                         * spacing tier closes — it scrolls its own content instead of
-                         * clipping it, which is the contract every size below the opening
-                         * one already relies on.
-                         */
-                        initialWidth: calculatorType === "graphing" ? 720 : 380,
-                        initialHeight: calculatorType === "graphing"
-                            ? 660
-                            : calculatorType === "basic"
-                                ? 500
-                                : 560,
-                        minWidth: 380,
-                        minHeight: 480,
-                        /*
-                         * `bottom-right` put a 560-620px-tall shell over the items
-                         * column it shares the viewport with — tall enough, at
-                         * ordinary viewport heights, to sit on top of a sibling
-                         * item's own toolbar row and block its button from mouse
-                         * and touch input. `bottom-left` keeps the same footprint
-                         * over the passage column instead, which carries no
-                         * per-item controls to collide with.
-                         */
-                        initialAlign: "bottom-left",
-                        initialMargin: 16,
-                        // Header controls in the host's design system, and the layout that
-                        // goes with them.
-                        ndsHeaderControls: true,
-                        // A learner reads the question while using the calculator, so Tab and
-                        // Shift+Tab cross between the page and the shell instead of cycling
-                        // inside it.
-                        pageTabOrder: true,
-                        content: {
-                            overflowY: "auto",
-                            preserveMinHeight: true,
+        renderToolbar(context, toolbarContext) {
+            const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
+            const calculatorToolConfig = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
+                undefined;
+            const calculatorConfig = getCalculatorInstanceConfig(calculatorToolConfig);
+            const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
+            const componentOverrides = toolbarContext.componentOverrides;
+            // Reused across renders: besides keeping state, this spares a Desmos boot
+            // and container mount on every re-render.
+            const overlay = resolveOverlayElement(toolbarContext, fullToolId, () => createToolElement(this.toolId, context, toolbarContext, componentOverrides));
+            overlay.setAttribute("tool-id", fullToolId);
+            applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
+            const button = {
+                toolId: this.toolId,
+                label: displayName,
+                icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
+                // Routes this button through <pie-nds-icon-button> where the host enables NDS
+                // icons. Declared here because which capabilities render in the host's
+                // design system is a composition decision.
+                faIconName: "calculator",
+                disabled: false,
+                // The name stays put across open and closed. The toolbar mirrors
+                // `active` onto the button as `aria-pressed`, so the state is already
+                // exposed; a name that also swapped to "Close …" would contradict it.
+                ariaLabel: displayName,
+                tooltip: displayName,
+                onClick: () => toolbarContext.toggleTool(this.toolId),
+                active: toolbarContext.isToolVisible(this.toolId),
+            };
+            let lastVisibleState = button.active;
+            if (overlay.visible !== button.active) {
+                overlay.visible = button.active;
+            }
+            return {
+                toolId: this.toolId,
+                elements: [
+                    {
+                        element: overlay,
+                        mount: "after-buttons",
+                        shell: {
+                            // The variant name the button already carries — "Basic Calculator",
+                            // not the registration's generic one.
+                            title: displayName,
+                            draggable: true,
+                            resizable: true,
+                            closeable: true,
+                            /*
+                             * Sized per type from what each layout measures, rather than one
+                             * size for all three. A shell subtracts ~74px of header from the
+                             * height it is given, and the numbers below are the content each
+                             * type needs plus room for its history tape:
+                             *
+                             * - basic: strip, display, edit row and a four-row keypad measure
+                             *   398px. 560 left ~90px of blank above the entry line, which is
+                             *   the gap that made the panel look mis-sized.
+                             * - scientific: the same plus a keypad layer tab row.
+                             * - graphing: the expression rail beside the plot, whose column
+                             *   wants 486px on its own — viewport controls, a 14rem board floor
+                             *   and the readout that *is* the graph for assistive technology,
+                             *   since the board itself is `aria-hidden`. At 620 that column was
+                             *   12px short and the readout's last line was cut off.
+                             *
+                             * The minimums stay shared across types and backends. One
+                             * registration serves every backend, so a graphing-only floor
+                             * would move the resize limit under vendors whose layouts were
+                             * never measured for it. Cortex below 42rem stacks the rail above
+                             * the plot and needs 701px there, which no spacing tier closes — it
+                             * scrolls its own content instead of clipping it, which is the
+                             * contract every size below the opening one already relies on.
+                             */
+                            initialWidth: calculatorType === "graphing" ? 720 : 380,
+                            initialHeight: calculatorType === "graphing"
+                                ? 660
+                                : calculatorType === "basic"
+                                    ? 500
+                                    : 560,
+                            minWidth: 380,
+                            minHeight: 480,
+                            /*
+                             * `bottom-right` put a 560-620px-tall shell over the items
+                             * column it shares the viewport with — tall enough, at
+                             * ordinary viewport heights, to sit on top of a sibling
+                             * item's own toolbar row and block its button from mouse
+                             * and touch input. `bottom-left` keeps the same footprint
+                             * over the passage column instead, which carries no
+                             * per-item controls to collide with.
+                             */
+                            initialAlign: "bottom-left",
+                            initialMargin: 16,
+                            // Header controls in the host's design system, and the layout that
+                            // goes with them.
+                            ndsHeaderControls: true,
+                            // A learner reads the question while using the calculator, so Tab and
+                            // Shift+Tab cross between the page and the shell instead of cycling
+                            // inside it.
+                            pageTabOrder: true,
+                            content: {
+                                overflowY: "auto",
+                                preserveMinHeight: true,
+                            },
                         },
                     },
+                ],
+                button,
+                sync: () => {
+                    const active = toolbarContext.isToolVisible(this.toolId);
+                    button.active = active;
+                    button.label = displayName;
+                    // Static across the toggle: `aria-pressed` carries the state, and a
+                    // "Close …" template built from a localized noun mixes languages
+                    // ("Close rekenmachine" under nl-NL).
+                    button.ariaLabel = displayName;
+                    button.tooltip = displayName;
+                    if (lastVisibleState !== active) {
+                        overlay.visible = active;
+                        lastVisibleState = active;
+                    }
+                    applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
                 },
-            ],
-            button,
-            sync: () => {
-                const active = toolbarContext.isToolVisible(this.toolId);
-                button.active = active;
-                button.label = displayName;
-                // Static across the toggle: `aria-pressed` carries the state, and a
-                // "Close …" template built from a localized noun mixes languages
-                // ("Close rekenmachine" under nl-NL).
-                button.ariaLabel = displayName;
-                button.tooltip = displayName;
-                if (lastVisibleState !== active) {
-                    overlay.visible = active;
-                    lastVisibleState = active;
-                }
-                applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
-            },
-            subscribeActive: (callback) => {
-                if (!toolbarContext.subscribeVisibility)
-                    return () => { };
-                return toolbarContext.subscribeVisibility(() => {
-                    callback(toolbarContext.isToolVisible(this.toolId));
-                });
-            },
-        };
-    },
-};
+                subscribeActive: (callback) => {
+                    if (!toolbarContext.subscribeVisibility)
+                        return () => { };
+                    return toolbarContext.subscribeVisibility(() => {
+                        callback(toolbarContext.isToolVisible(this.toolId));
+                    });
+                },
+            };
+        },
+    };
+}
+/** The calculator over the packaged Desmos and GeoGebra backends. */
+export const calculatorToolRegistration = createCalculatorToolRegistration();

package/dist/registrations/interaction-tools.d.ts

@@ -4,7 +4,20 @@
  * Registers tools for interacting with question content:
  * - Answer Eliminator (strike through answer choices)
  */
-import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import type { ToolProviderConfig, ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
+/**
+ * The answer eliminator's `tools.providers.answerEliminator` entry.
+ */
+export interface AnswerEliminatorToolConfig extends ToolProviderConfig {
+    /**
+     * The elements the eliminator acts on, by the name `<name>` of their
+     * `@pie-element/<name>` package, such as `["multiple-choice"]`. An element
+     * must also support answer masking. Omitted, every element that supports it
+     * takes the eliminator; empty, none does. A host lists the elements whose
+     * support it has vetted.
+     */
+    elements?: readonly string[];
+}
 /**
  * Answer Eliminator tool registration
  *

package/dist/registrations/interaction-tools.js

@@ -19,24 +19,84 @@ const ANSWER_MASKING = "answer-masking";
  * its supports is decided by its declaration, these two included.
  */
 const UNDECLARED_ANSWER_MASKING_ELEMENTS = new Set(["multiple-choice", "ebsr"]);
-// Content names one element 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`.
-function isUndeclaredAnswerMaskingElement(tag, packageSpec) {
-    const name = tag
+function elementName(tag) {
+    return tag
         .toLowerCase()
         .replace(/--version-[0-9a-z-]+$/, "")
         .replace(/^pie-(element-)?/, "");
-    if (UNDECLARED_ANSWER_MASKING_ELEMENTS.has(name))
-        return true;
-    const packageName = packageSpec?.match(/^@pie-element\/([^@]+)/)?.[1];
-    return !!packageName && UNDECLARED_ANSWER_MASKING_ELEMENTS.has(packageName);
 }
-/** Whether an element of the context supports answer masking. */
-function supportsAnswerMasking(context) {
-    return elementSupports(context).some(({ supports, tag, packageSpec }) => supports
-        ? supports.includes(ANSWER_MASKING)
-        : isUndeclaredAnswerMaskingElement(tag, packageSpec));
+// Content names one element 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`.
+function elementNames(tag, packageSpec) {
+    const names = [elementName(tag)];
+    const packageName = pieElementPackageName(packageSpec);
+    if (packageName)
+        names.push(packageName);
+    return names;
+}
+function pieElementPackageName(packageSpec) {
+    return packageSpec?.match(/^@pie-element\/([^@]+)/)?.[1]?.toLowerCase() ?? null;
+}
+/**
+ * The name an `elements` list matches: the `@pie-element/<name>` package the
+ * item binds the tag to, else the tag's own name. A tag bound to another
+ * package matches no name, whatever the tag says.
+ */
+function listedName(tag, packageSpec) {
+    return packageSpec ? pieElementPackageName(packageSpec) : elementName(tag);
+}
+/**
+ * The element names `config.elements` allows, or `null` for every element. An
+ * `elements` that is not a list allows none: validation reports it, and an
+ * element a host has not vetted stays without the eliminator.
+ */
+function allowedElementNames(config) {
+    const elements = config
+        ?.elements;
+    if (elements === undefined)
+        return null;
+    if (!Array.isArray(elements))
+        return new Set();
+    return new Set(elements
+        .filter((name) => typeof name === "string")
+        .map(elementName));
+}
+/**
+ * The model ids of the context's elements that support answer masking and the
+ * host config allows.
+ */
+function answerMaskingElementIds(context, config) {
+    const allowed = allowedElementNames(config);
+    return elementSupports(context)
+        .filter(({ supports, tag, packageSpec }) => {
+        if (allowed) {
+            const name = listedName(tag, packageSpec);
+            if (name === null || !allowed.has(name))
+                return false;
+        }
+        return supports
+            ? supports.includes(ANSWER_MASKING)
+            : elementNames(tag, packageSpec).some((name) => UNDECLARED_ANSWER_MASKING_ELEMENTS.has(name));
+    })
+        .flatMap(({ elementId }) => (elementId ? [elementId] : []));
+}
+function validateAnswerEliminatorConfig(config) {
+    const { elements } = config;
+    if (elements === undefined)
+        return [];
+    if (Array.isArray(elements) &&
+        elements.every((name) => typeof name === "string" && name.trim() !== "")) {
+        return [];
+    }
+    return [
+        {
+            code: "tools.invalidProviderConfig",
+            severity: "error",
+            path: "providers.answerEliminator.elements",
+            message: '`elements` must be a list of element names, such as ["multiple-choice"].',
+        },
+    ];
 }
 /** The state-store key of each PIE element in the item, by model id. */
 function resolveElementStateKeys(context, toolbarContext) {
@@ -67,23 +127,25 @@ export const answerEliminatorToolRegistration = {
     descriptionKey: "tools.answerEliminator.description",
     icon: "strikethrough",
     supportedLevels: ["item"],
+    validateConfig: validateAnswerEliminatorConfig,
     /**
      * Pass 2: relevant where an element supports answer masking. An element
      * declares it on its class, and the answer eliminator's README says what the
      * element then supplies.
      */
     isVisibleInContext(context) {
-        return supportsAnswerMasking(context);
+        return answerMaskingElementIds(context, null).length > 0;
     },
     /**
-     * Pass 3: the same question, asked as a capability. Elimination controls are
-     * rendered per choice, so an item none of whose elements supports answer
-     * masking gives this tool nothing to act on. Answering the relevance gate
-     * alone left the button on such items for any learner whose profile grants
-     * answer masking.
+     * Pass 3: the same question, asked as a capability and narrowed to the
+     * elements the host config allows. Elimination controls are rendered per
+     * choice, so an item none of whose allowed elements supports answer masking
+     * gives this tool nothing to act on. Answering the relevance gate alone left
+     * the button on such items for any learner whose profile grants answer
+     * masking.
      */
-    isApplicableToContent(context) {
-        return supportsAnswerMasking(context);
+    isApplicableToContent(context, config) {
+        return answerMaskingElementIds(context, config).length > 0;
     },
     renderToolbar(context, toolbarContext) {
         const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);
@@ -94,7 +156,7 @@ export const answerEliminatorToolRegistration = {
         const button = {
             toolId: this.toolId,
             label: this.name,
-            icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M19,3H16.3H7.7H5A2,2 0 0,0 3,5V7.7V16.4V19A2,2 0 0,0 5,21H7.7H16.4H19A2,2 0 0,0 21,19V16.3V7.7V5A2,2 0 0,0 19,3M15.6,17L12,13.4L8.4,17L7,15.6L10.6,12L7,8.4L8.4,7L12,10.6L15.6,7L17,8.4L13.4,12L17,15.6L15.6,17Z"/></svg>',
+            icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
             disabled: false,
             ariaLabel: toolbarContext.i18n.t("tools.answerEliminator.buttonA11y"),
             tooltip: toolbarContext.i18n.t("tools.answerEliminator.tooltip"),
@@ -112,6 +174,12 @@ export const answerEliminatorToolRegistration = {
                     isActive: visibility.isActive,
                 });
                 overlay.elementStateKeys = resolveElementStateKeys(context, toolbarContext);
+                const config = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ??
+                    null;
+                overlay.elementIds =
+                    allowedElementNames(config) === null
+                        ? undefined
+                        : answerMaskingElementIds(context, config);
             },
             subscribeActive: visibility.subscribeActive,
         };

package/dist/registrations/tts.d.ts

@@ -4,12 +4,33 @@
  * Registers the TTS tool for reading content aloud.
  */
 import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { TTSToolProvider } from "@pie-players/pie-assessment-toolkit/tools/registration";
+type TTSToolProviderOptions = NonNullable<ConstructorParameters<typeof TTSToolProvider>[1]>;
+/** A host's own text-to-speech provider, selected by `provider.id`. */
+export interface TTSHostProviderDescriptor {
+    /** Resolves the host's `ITTSProvider` class; imported only when selected. */
+    load: NonNullable<TTSToolProviderOptions["loadHostProvider"]>;
+    /** Wait on `provider.runtime.authFetcher` before initializing. Default `false`. */
+    requiresAuth?: boolean;
+}
+export interface TTSRegistrationOptions {
+    /**
+     * Host providers by `provider.id`. A `textToSpeech` config whose
+     * `provider.id` names none of them, or names none at all, keeps the browser
+     * or server backend its settings select.
+     */
+    providers?: Readonly<Record<string, TTSHostProviderDescriptor>>;
+}
 /**
- * Text-to-Speech tool registration
+ * Builds the text-to-speech registration over the browser and server backends
+ * plus any host providers, so a host bundles its provider only by naming it.
  *
  * Supports:
- * - Reading content aloud using browser TTS or external providers
+ * - Reading content aloud using browser TTS, a TTS server or a host provider
  * - Context-aware visibility (shows when readable text is available)
  * - Item and passage levels
  */
+export declare function createTTSToolRegistration(options?: TTSRegistrationOptions): ToolRegistration;
+/** The text-to-speech registration with the browser and server backends only. */
 export declare const ttsToolRegistration: ToolRegistration;
+export {};