@pie-players/pie-assessment-toolkit 1.0.0-beta.7 → 1.0.0-beta.8

package/dist/services/tool-icons.js

@@ -25,6 +25,8 @@ const TOOL_FALLBACK_ICONS = {
     "magnifying-glass": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 14h-.79l-.28-.27A6.47 6.47 0 0 0 16 9.5 6.5 6.5 0 1 0 9.5 16a6.47 6.47 0 0 0 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5Zm-6 0A4.5 4.5 0 1 1 14 9.5 4.49 4.49 0 0 1 9.5 14ZM12 10h-2v2H9v-2H7V9h2V7h1v2h2v1Z" fill="currentColor"/></svg>',
     ruler: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m8.8 10.95 2.15-2.175-1.4-1.425-1.1 1.1-1.4-1.4 1.075-1.1L7 4.825 4.825 7 8.8 10.95Zm8.2 8.225L19.175 17l-1.125-1.125-1.1 1.075-1.4-1.4 1.075-1.1-1.425-1.4-2.15 2.15L17 19.175ZM7.25 21H3v-4.25l4.375-4.375L2 7l5-5 5.4 5.4 3.775-3.8c.2-.2.425-.35.675-.45a2.068 2.068 0 0 1 1.55 0c.25.1.475.25.675.45L20.4 4.95c.2.2.35.425.45.675.1.25.15.508.15.775a1.975 1.975 0 0 1-.6 1.425l-3.775 3.8L22 17l-5 5-5.375-5.375L7.25 21ZM5 19h1.4l9.8-9.775L14.775 7.8 5 17.6V19Z" fill="currentColor"/></svg>',
     "book-open": '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 6.25a6.6 6.6 0 0 0-2.3-1.32A8.6 8.6 0 0 0 7 4.5c-.63 0-1.25.06-1.85.18-.6.12-1.19.3-1.76.54a1.5 1.5 0 0 0-.93 1.4v10.1c0 .52.26.98.68 1.24.42.26.92.28 1.35.06.36-.18.75-.31 1.18-.4.42-.09.86-.13 1.33-.13.78 0 1.53.14 2.24.42.7.28 1.35.7 1.93 1.24l.83-.75.83.75c.58-.54 1.22-.96 1.93-1.24a6.1 6.1 0 0 1 2.24-.42c.47 0 .91.04 1.33.13.43.09.82.22 1.18.4.43.22.93.2 1.35-.06.42-.26.68-.72.68-1.24V6.62c0-.6-.36-1.15-.93-1.4a9.3 9.3 0 0 0-1.76-.54A9.8 9.8 0 0 0 17 4.5a8.6 8.6 0 0 0-2.7.43A6.6 6.6 0 0 0 12 6.25Zm1 10.06V8.02c.55-.5 1.16-.88 1.84-1.13A6 6 0 0 1 17 6.5c.45 0 .89.04 1.32.11.43.08.85.19 1.26.34v9.24a8.2 8.2 0 0 0-1.28-.24A10 10 0 0 0 17 15.85c-.72 0-1.42.09-2.09.26a7.7 7.7 0 0 0-1.91.8Zm-2 0a7.7 7.7 0 0 0-1.91-.8 8.4 8.4 0 0 0-2.09-.26c-.44 0-.87.02-1.3.07-.43.05-.86.13-1.28.24V6.95c.41-.15.83-.26 1.26-.34A7.7 7.7 0 0 1 7 6.5c.76 0 1.48.13 2.16.39.68.25 1.29.63 1.84 1.13Z" fill="currentColor"/></svg>',
+    highlighter: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M22 24H2v-4h20v4ZM13.06 5.19l3.75 3.75L7.75 18H4v-3.75l9.06-9.06Zm4.82 2.68-3.75-3.75 1.83-1.83a1 1 0 0 1 1.41 0l2.34 2.34a1 1 0 0 1 0 1.41l-1.83 1.83Z" fill="currentColor"/></svg>',
+    strikethrough: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2Zm-3.4 14L12 13.4 8.4 17 7 15.6l3.6-3.6L7 8.4 8.4 7l3.6 3.6L15.6 7 17 8.4 13.4 12l3.6 3.6-1.4 1.4Z" fill="currentColor"/></svg>',
     photo: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 21c-.55 0-1.02-.2-1.41-.59A1.93 1.93 0 0 1 2 19V5c0-.55.2-1.02.59-1.41A1.93 1.93 0 0 1 4 3h16c.55 0 1.02.2 1.41.59.39.39.59.86.59 1.41v14c0 .55-.2 1.02-.59 1.41-.39.39-.86.59-1.41.59H4Zm0-2h16V5H4v14Zm1.5-2.5h13l-4.1-5.47-3.4 4.47-2.5-3.25L5.5 16.5ZM8.5 10a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3Z" fill="currentColor"/></svg>',
 };
 /** Icon markup for `name`, or `null` when nothing built in matches. */

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

@@ -0,0 +1,13 @@
+/**
+ * The provider configs a coordinator applies when the host's tools config
+ * names none for a capability.
+ *
+ * This module names capabilities on purpose, like `services/support-conflicts.ts`:
+ * a default is a statement about which capabilities a deployment starts with,
+ * which is not a decision the capability-neutral coordination layer gets to
+ * make. The coordinator applies the table without naming its entries —
+ * `check-capability-neutrality` holds it to that. These are the coordinator's
+ * previous inline defaults, moved verbatim.
+ */
+import type { ToolProvidersConfig } from "./tools-config-normalizer.js";
+export declare const DEFAULT_TOOL_PROVIDERS: ToolProvidersConfig;

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

@@ -0,0 +1,20 @@
+/**
+ * The provider configs a coordinator applies when the host's tools config
+ * names none for a capability.
+ *
+ * This module names capabilities on purpose, like `services/support-conflicts.ts`:
+ * a default is a statement about which capabilities a deployment starts with,
+ * which is not a decision the capability-neutral coordination layer gets to
+ * make. The coordinator applies the table without naming its entries —
+ * `check-capability-neutrality` holds it to that. These are the coordinator's
+ * previous inline defaults, moved verbatim.
+ */
+export const DEFAULT_TOOL_PROVIDERS = {
+    textToSpeech: {
+        enabled: true,
+        backend: "browser",
+    },
+    annotationToolbar: {
+        enabled: true,
+    },
+};

package/dist/services/tts/browser-provider.js

@@ -4,6 +4,7 @@
  * Text-to-speech provider using the browser's Web Speech API.
  * Works in all modern browsers that support SpeechSynthesis.
  */
+import { languageTagWithoutVariants } from "@pie-players/pie-players-shared/i18n/language-tags";
 import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { extractSpokenText, isSsmlDocument } from "./ssml/spoken-text.js";
 import { segmentSentences as segmentTextToSentences } from "./text-segmentation.js";
@@ -383,10 +384,11 @@ class BrowserTTSProviderImpl {
      * The language of the content being read, which the toolkit sets per speak as
      * `providerOptions.contentLanguage` when the content or the host names one.
      */
+    /** The content language without variant or private-use subtags, which voices lack. */
     getContentLocale() {
         const language = this.config?.providerOptions?.contentLanguage;
         return typeof language === "string" && language.trim()
-            ? language.trim()
+            ? languageTagWithoutVariants(language)
             : undefined;
     }
     getSegmentationPolicy() {

package/dist/services/tts/tts-lifecycle.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The text-to-speech lifecycle of a `ToolkitCoordinator`: initialization from
+ * the tool config, readiness, reconfiguration, and the missing-provider report.
+ *
+ * This module is the one place in the toolkit's coordination layer allowed to
+ * name the read-aloud capability, the same way `services/tts/**` already is:
+ * the coordinator stays capability-agnostic — it hands this lifecycle the
+ * services it needs through `TtsLifecycleHost` and answers only generic
+ * questions (`ownsTool`, `isStarted`) about it — and
+ * `check-capability-neutrality` holds the coordinator to that, with one
+ * documented allowance for its public `textToSpeech`-typed config accessors.
+ *
+ * Behavior is moved, not redesigned: each method here was a private
+ * `ToolkitCoordinator` member, and the host adapters bind the same calls the
+ * members made.
+ */
+import type { AccessibilityCatalogResolver } from "../AccessibilityCatalogResolver.js";
+import type { ToolProviderConfig, ToolProvidersConfig } from "../tools-config-normalizer.js";
+import type { TTSService } from "../TTSService.js";
+import type { ToolProviderApi } from "../tool-providers/ToolProviderApi.js";
+import type { ToolRegistration } from "../ToolRegistry.js";
+/** The tool id the read-aloud capability registers under. */
+export declare const TTS_TOOL_ID = "textToSpeech";
+/**
+ * The coordinator services the TTS lifecycle runs against. The coordinator
+ * binds these once, to its own members, so its privates stay private and the
+ * seam between the generic coordinator and the capability stays explicit.
+ */
+export interface TtsLifecycleHost {
+    /** Throws `ToolkitCoordinatorDisposedError` once the coordinator is disposed. */
+    assertNotDisposed(): void;
+    /** Whether disposal has started; in-flight work stops instead of finishing. */
+    isDisposalStarted(): boolean;
+    /** Whether the error is the coordinator's own disposed signal, to rethrow. */
+    isDisposalError(error: unknown): boolean;
+    emitTelemetry(eventName: string, payload?: Record<string, unknown>): Promise<void>;
+    hooks: {
+        onBeforeTTSInit?: ((context: {
+            phase: "tts-init";
+            details: {
+                backend: string;
+            };
+        }) => void | Promise<void>) | undefined;
+        onTTSReady?: (() => void | Promise<void>) | undefined;
+    };
+    toolProviderRegistry: {
+        has(toolId: string): boolean;
+        unregister(toolId: string): Promise<void>;
+    };
+    initializeProvider(toolId: string, fallbackFollows: boolean): Promise<ToolProviderApi>;
+    ttsService: TTSService;
+    catalogResolver: AccessibilityCatalogResolver;
+    clearDegradedTool(toolId: string): void;
+    reportStartFailure(error: unknown, context: {
+        phase: "tts-init";
+    }, toolIds: Iterable<string>): void;
+    isToolGranted(toolId: string): boolean;
+    /** Whether provider initialization waits for a policy grant. */
+    lazyInit: boolean;
+    /** Whether the tool registry may still be replaced by a bound toolkit's. */
+    isToolRegistryPending(): boolean;
+    /** The validated `tools.providers` config, defaults applied. */
+    providersConfig(): ToolProvidersConfig | undefined;
+    getProviderDescriptorTools(): ToolRegistration[];
+    registerProviderFromTool(tool: ToolRegistration, replace?: boolean): Promise<void>;
+    notifyReadyChange(): void;
+}
+/** The read-aloud-specific merge in a generic tool-config update. */
+export declare function deepMergeMathSpeech(toolId: string, current: Partial<ToolProviderConfig>, updates: Partial<ToolProviderConfig>): Record<string, unknown> | undefined;
+export declare class TtsLifecycle {
+    private readonly host;
+    private initialized;
+    /** Text-to-speech failed to start and policy does not grant it. */
+    private degraded;
+    private initPromise?;
+    private reconfigurePromise?;
+    /**
+     * Whether {@link TtsLifecycle.initializeIfNeeded} has already reported a
+     * non-browser backend falling back to browser speech because no
+     * text-to-speech provider is registered. Once per coordinator: a
+     * text-to-speech config change re-runs initialization, and the missing
+     * provider is the same gap each time.
+     */
+    private reportedMissingProvider;
+    /**
+     * The backend of a fallback missing-provider report held back while the
+     * registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    private heldMissingProviderBackend;
+    constructor(host: TtsLifecycleHost);
+    get started(): boolean;
+    get failedUngranted(): boolean;
+    /** Whether `toolId` is the tool this lifecycle brings up. */
+    ownsTool(toolId: string): boolean;
+    /** Whether initialization or a reconfiguration is in flight. */
+    isStarted(): boolean;
+    /** The in-flight initialization and reconfiguration, for disposal flushes. */
+    flushInitPromises(pending: Set<Promise<unknown>>): void;
+    /**
+     * The runtime `mathSpeech` provider options for the current tool config, as
+     * the TTS service's math-speech source reads them.
+     */
+    mathSpeechRuntimeOptions(): import("./math-speech.js").SREMathSpeechOptions | undefined;
+    /**
+     * Initialize the TTS service from the `textToSpeech` tool config.
+     */
+    ensureReady(): Promise<void>;
+    private waitForPendingReconfigure;
+    private initializeIfNeeded;
+    private resolveToolConfig;
+    private initializeService;
+    private reportMissingProvider;
+    /**
+     * Report a missing-provider report held back while the registry was
+     * unsettled, now that the registry has settled without one.
+     */
+    reportHeldMissingProvider(): void;
+    /**
+     * Drop a held missing-provider report without reporting it: a real registry
+     * settled, so the stale gap never applied.
+     */
+    discardHeldMissingProvider(): void;
+    /**
+     * Readiness waits for text-to-speech when it is enabled and either starts
+     * eagerly or is granted: a granted read-aloud fails before the learner starts.
+     */
+    requiredForReadiness(): boolean;
+    /**
+     * Starts text-to-speech for readiness. A failure policy does not grant leaves
+     * the tool degraded, reporting itself unavailable, and readiness settles; a
+     * granted tool's failure rejects.
+     */
+    startForReadiness(): Promise<void>;
+    /**
+     * Re-register the text-to-speech provider for the current config and registry,
+     * then re-initialize unless initialization is lazy. An initialization already
+     * running finishes first: it would otherwise mark its provider ready after the
+     * reset.
+     */
+    scheduleReconfigure(): void;
+    private reconfigure;
+}

package/dist/services/tts/tts-lifecycle.js

@@ -0,0 +1,341 @@
+/**
+ * The text-to-speech lifecycle of a `ToolkitCoordinator`: initialization from
+ * the tool config, readiness, reconfiguration, and the missing-provider report.
+ *
+ * This module is the one place in the toolkit's coordination layer allowed to
+ * name the read-aloud capability, the same way `services/tts/**` already is:
+ * the coordinator stays capability-agnostic — it hands this lifecycle the
+ * services it needs through `TtsLifecycleHost` and answers only generic
+ * questions (`ownsTool`, `isStarted`) about it — and
+ * `check-capability-neutrality` holds the coordinator to that, with one
+ * documented allowance for its public `textToSpeech`-typed config accessors.
+ *
+ * Behavior is moved, not redesigned: each method here was a private
+ * `ToolkitCoordinator` member, and the host adapters bind the same calls the
+ * members made.
+ */
+import { BrowserTTSProvider, browserFallbackConfig, } from "./browser-provider.js";
+import { buildRuntimeTTSConfig, resolveTTSBackend, resolveTTSRuntimeSettings, } from "../tts-runtime-config.js";
+/** The tool id the read-aloud capability registers under. */
+export const TTS_TOOL_ID = "textToSpeech";
+/** The read-aloud-specific merge in a generic tool-config update. */
+export function deepMergeMathSpeech(toolId, current, updates) {
+    if (toolId !== TTS_TOOL_ID ||
+        !isPlainRecord(current.mathSpeech) ||
+        !isPlainRecord(updates.mathSpeech)) {
+        return undefined;
+    }
+    return { ...current.mathSpeech, ...updates.mathSpeech };
+}
+function isPlainRecord(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value));
+}
+export class TtsLifecycle {
+    host;
+    initialized = false;
+    /** Text-to-speech failed to start and policy does not grant it. */
+    degraded = false;
+    initPromise;
+    reconfigurePromise;
+    /**
+     * Whether {@link TtsLifecycle.initializeIfNeeded} has already reported a
+     * non-browser backend falling back to browser speech because no
+     * text-to-speech provider is registered. Once per coordinator: a
+     * text-to-speech config change re-runs initialization, and the missing
+     * provider is the same gap each time.
+     */
+    reportedMissingProvider = false;
+    /**
+     * The backend of a fallback missing-provider report held back while the
+     * registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    heldMissingProviderBackend = null;
+    constructor(host) {
+        this.host = host;
+    }
+    get started() {
+        return this.initialized;
+    }
+    get failedUngranted() {
+        return this.degraded;
+    }
+    /** Whether `toolId` is the tool this lifecycle brings up. */
+    ownsTool(toolId) {
+        return toolId === TTS_TOOL_ID;
+    }
+    /** Whether initialization or a reconfiguration is in flight. */
+    isStarted() {
+        return (this.initialized ||
+            this.initPromise !== undefined ||
+            this.reconfigurePromise !== undefined);
+    }
+    /** The in-flight initialization and reconfiguration, for disposal flushes. */
+    flushInitPromises(pending) {
+        if (this.initPromise)
+            pending.add(this.initPromise);
+        if (this.reconfigurePromise)
+            pending.add(this.reconfigurePromise);
+    }
+    /**
+     * The runtime `mathSpeech` provider options for the current tool config, as
+     * the TTS service's math-speech source reads them.
+     */
+    mathSpeechRuntimeOptions() {
+        return buildRuntimeTTSConfig(resolveTTSRuntimeSettings(this.resolveToolConfig())).providerOptions?.mathSpeech;
+    }
+    /**
+     * Initialize the TTS service from the `textToSpeech` tool config.
+     */
+    async ensureReady() {
+        this.host.assertNotDisposed();
+        await this.waitForPendingReconfigure();
+        this.host.assertNotDisposed();
+        if (this.initialized)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.initializeIfNeeded()
+            .then(() => this.host.assertNotDisposed())
+            .finally(() => {
+            this.initPromise = undefined;
+            this.host.notifyReadyChange();
+        });
+        return this.initPromise;
+    }
+    waitForPendingReconfigure() {
+        let pending = this.reconfigurePromise;
+        const wait = async () => {
+            while (pending) {
+                await pending;
+                pending = this.reconfigurePromise;
+            }
+        };
+        return wait();
+    }
+    async initializeIfNeeded() {
+        if (this.initialized)
+            return;
+        const resolvedToolConfig = this.resolveToolConfig();
+        const runtimeSettings = resolveTTSRuntimeSettings(resolvedToolConfig);
+        const resolvedBackend = resolveTTSBackend(runtimeSettings);
+        const runtimeTTSConfig = buildRuntimeTTSConfig(runtimeSettings);
+        await this.host.hooks.onBeforeTTSInit?.({
+            phase: "tts-init",
+            details: {
+                backend: resolvedBackend,
+            },
+        });
+        this.host.assertNotDisposed();
+        await this.host.emitTelemetry("pie-toolkit-tts-init-start", {
+            backend: resolvedBackend,
+        });
+        await this.host.emitTelemetry("pie-tool-init-start", {
+            toolId: TTS_TOOL_ID,
+            operation: "tts-init",
+            backend: resolvedBackend,
+        });
+        if (this.host.toolProviderRegistry.has(TTS_TOOL_ID)) {
+            try {
+                // Browser speech follows a server provider that fails to start.
+                const ttsProvider = await this.host.initializeProvider(TTS_TOOL_ID, true);
+                const providerInstance = await ttsProvider.createInstance();
+                await this.initializeService(providerInstance, runtimeTTSConfig);
+                await this.host.emitTelemetry("pie-toolkit-tts-init-success", {
+                    provider: "registry",
+                });
+                await this.host.emitTelemetry("pie-tool-init-success", {
+                    toolId: TTS_TOOL_ID,
+                    operation: "tts-init",
+                    backend: resolvedBackend,
+                    provider: "registry",
+                });
+                return;
+            }
+            catch (error) {
+                if (this.host.isDisposalError(error))
+                    throw error;
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                await this.host.emitTelemetry("pie-tool-init-fallback", {
+                    toolId: TTS_TOOL_ID,
+                    operation: "tts-init",
+                    backend: resolvedBackend,
+                    fromProvider: "registry",
+                    toProvider: "browser",
+                    reason: normalized.message,
+                });
+                console.warn("[ToolkitCoordinator] Failed to initialize TTS via registry, falling back to browser provider:", normalized);
+            }
+        }
+        else if (resolvedBackend !== "browser") {
+            this.reportMissingProvider(resolvedBackend);
+        }
+        // Browser speech, configured or standing in for a backend that has no
+        // provider or failed to start.
+        const provider = new BrowserTTSProvider();
+        try {
+            await this.initializeService(provider, resolvedBackend === "browser"
+                ? runtimeTTSConfig
+                : browserFallbackConfig(runtimeTTSConfig));
+            await this.host.emitTelemetry("pie-toolkit-tts-init-success", {
+                provider: "browser-fallback",
+            });
+            await this.host.emitTelemetry("pie-tool-init-success", {
+                toolId: TTS_TOOL_ID,
+                operation: "tts-init",
+                backend: resolvedBackend,
+                provider: "browser-fallback",
+            });
+        }
+        catch (error) {
+            if (this.host.isDisposalError(error))
+                throw error;
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            this.host.reportStartFailure(normalized, { phase: "tts-init" }, [TTS_TOOL_ID]);
+            await this.host.emitTelemetry("pie-toolkit-tts-init-error", {
+                message: normalized.message,
+            });
+            await this.host.emitTelemetry("pie-tool-init-error", {
+                toolId: TTS_TOOL_ID,
+                operation: "tts-init",
+                backend: resolvedBackend,
+                errorType: "TTSInitError",
+                message: normalized.message,
+            });
+            throw normalized;
+        }
+    }
+    resolveToolConfig() {
+        const fromProviders = this.host.providersConfig()?.[TTS_TOOL_ID];
+        return fromProviders || {};
+    }
+    async initializeService(provider, config) {
+        const nextProviderOptions = {
+            ...config.providerOptions,
+            __pieTelemetry: async (eventName, payload) => {
+                await this.host.emitTelemetry(eventName, {
+                    toolId: TTS_TOOL_ID,
+                    ...(payload || {}),
+                });
+            },
+        };
+        const nextConfig = {
+            ...config,
+            providerOptions: nextProviderOptions,
+        };
+        await this.host.ttsService.initialize(provider, nextConfig);
+        this.host.assertNotDisposed();
+        this.host.ttsService.setCatalogResolver(this.host.catalogResolver);
+        this.initialized = true;
+        this.degraded = false;
+        this.host.clearDegradedTool(TTS_TOOL_ID);
+        await this.host.hooks.onTTSReady?.();
+        this.host.assertNotDisposed();
+    }
+    reportMissingProvider(backend) {
+        // The toolkit this coordinator binds to may still supply the provider.
+        if (this.host.isToolRegistryPending()) {
+            this.heldMissingProviderBackend = backend;
+            return;
+        }
+        if (this.reportedMissingProvider)
+            return;
+        this.reportedMissingProvider = true;
+        console.warn(`[ToolkitCoordinator] Text-to-speech is configured for the "${backend}" backend but falls back to browser speech: no "${TTS_TOOL_ID}" tool provider is registered. A coordinator registers tool providers only from its \`toolRegistry\`, or from its toolkit's when constructed without one, so supply one that carries the text-to-speech registration — for the packaged capability set, \`createPackagedToolRegistry()\` from "@pie-players/pie-default-tool-loaders". Reported once per coordinator.`);
+    }
+    /**
+     * Report a missing-provider report held back while the registry was
+     * unsettled, now that the registry has settled without one.
+     */
+    reportHeldMissingProvider() {
+        const heldBackend = this.heldMissingProviderBackend;
+        this.heldMissingProviderBackend = null;
+        if (heldBackend)
+            this.reportMissingProvider(heldBackend);
+    }
+    /**
+     * Drop a held missing-provider report without reporting it: a real registry
+     * settled, so the stale gap never applied.
+     */
+    discardHeldMissingProvider() {
+        this.heldMissingProviderBackend = null;
+    }
+    /**
+     * Readiness waits for text-to-speech when it is enabled and either starts
+     * eagerly or is granted: a granted read-aloud fails before the learner starts.
+     */
+    requiredForReadiness() {
+        if (this.resolveToolConfig()?.enabled === false)
+            return false;
+        return !this.host.lazyInit || this.host.isToolGranted(TTS_TOOL_ID);
+    }
+    /**
+     * Starts text-to-speech for readiness. A failure policy does not grant leaves
+     * the tool degraded, reporting itself unavailable, and readiness settles; a
+     * granted tool's failure rejects.
+     */
+    async startForReadiness() {
+        try {
+            await this.ensureReady();
+        }
+        catch (error) {
+            if (this.host.isDisposalError(error))
+                throw error;
+            if (this.host.isToolGranted(TTS_TOOL_ID))
+                throw error;
+            this.degraded = true;
+            this.host.notifyReadyChange();
+        }
+    }
+    /**
+     * Re-register the text-to-speech provider for the current config and registry,
+     * then re-initialize unless initialization is lazy. An initialization already
+     * running finishes first: it would otherwise mark its provider ready after the
+     * reset.
+     */
+    scheduleReconfigure() {
+        const inFlight = this.initPromise;
+        const reconfigurePromise = inFlight
+            ? inFlight.catch(() => { }).then(() => this.reconfigure())
+            : this.reconfigure();
+        this.reconfigurePromise = reconfigurePromise;
+        void reconfigurePromise.finally(() => {
+            if (this.reconfigurePromise === reconfigurePromise) {
+                this.reconfigurePromise = undefined;
+            }
+        });
+        void reconfigurePromise
+            .then(async () => {
+            if (this.host.isDisposalStarted())
+                return;
+            if (this.requiredForReadiness())
+                await this.startForReadiness();
+        })
+            // Reported where it failed; a granted failure has nowhere else to go.
+            .catch(() => { });
+    }
+    async reconfigure() {
+        this.initialized = false;
+        this.degraded = false;
+        this.host.clearDegradedTool(TTS_TOOL_ID);
+        this.initPromise = undefined;
+        this.host.notifyReadyChange();
+        try {
+            // The next speak waits on readiness, which starts the new provider.
+            this.host.ttsService.releaseProvider();
+        }
+        catch {
+            // noop: release best effort
+        }
+        if (this.host.toolProviderRegistry.has(TTS_TOOL_ID)) {
+            await this.host.toolProviderRegistry.unregister(TTS_TOOL_ID);
+        }
+        if (this.host.isDisposalStarted())
+            return;
+        const ttsRegistration = this.host
+            .getProviderDescriptorTools()
+            .find((tool) => this.ownsTool(tool.toolId));
+        if (!ttsRegistration)
+            return;
+        await this.host.registerProviderFromTool(ttsRegistration);
+    }
+}

package/dist/tools/content-surfaces.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Host surface ids a content capability can fill.
+ *
+ * A renderer opens slots in its own layout — a card's docked-media region, the
+ * full-width slot above its body — and a registration names the slots it can
+ * render into through `ToolRegistration.surfaces`. The ids live here, one
+ * definition for both sides of that exchange: a capability package cannot
+ * import a player to reach the renderer's constants, and a renderer without a
+ * toolbar — print — cannot import the composition layer for the packaged
+ * registrations', so the slot names are the toolkit's to own.
+ *
+ * The ids say nothing about geometry. How wide a slot is, where it sits, or
+ * that it collapses under a breakpoint is the renderer's decision; a
+ * registration declaring `surfaces` promises only that it can render into a
+ * slot with that name, whatever the renderer makes of it.
+ */
+/**
+ * Host slot for media docked beside a card's content.
+ *
+ * Named for the relationship rather than for one card kind, because item cards
+ * and passage cards open the same slot: an alternate is authored against a
+ * content node, and a passage owns content nodes exactly as an item does. A
+ * capability declares this surface once and reaches both.
+ */
+export declare const CONTENT_MEDIA_SURFACE = "content-media";
+/**
+ * Host slot for a text alternate that has to be read in order with the
+ * content: full width, above the card body, in document flow.
+ *
+ * Separate from {@link CONTENT_MEDIA_SURFACE} because the geometry is the
+ * whole difference. Docked media is watched beside the content and is sized by
+ * an aspect ratio; a transcript or a plain-language alternate is read *before*
+ * the control it belongs to, which a sticky side column cannot express.
+ */
+export declare const CONTENT_LEAD_SURFACE = "content-lead";

package/dist/tools/content-surfaces.js

@@ -0,0 +1,35 @@
+/**
+ * Host surface ids a content capability can fill.
+ *
+ * A renderer opens slots in its own layout — a card's docked-media region, the
+ * full-width slot above its body — and a registration names the slots it can
+ * render into through `ToolRegistration.surfaces`. The ids live here, one
+ * definition for both sides of that exchange: a capability package cannot
+ * import a player to reach the renderer's constants, and a renderer without a
+ * toolbar — print — cannot import the composition layer for the packaged
+ * registrations', so the slot names are the toolkit's to own.
+ *
+ * The ids say nothing about geometry. How wide a slot is, where it sits, or
+ * that it collapses under a breakpoint is the renderer's decision; a
+ * registration declaring `surfaces` promises only that it can render into a
+ * slot with that name, whatever the renderer makes of it.
+ */
+/**
+ * Host slot for media docked beside a card's content.
+ *
+ * Named for the relationship rather than for one card kind, because item cards
+ * and passage cards open the same slot: an alternate is authored against a
+ * content node, and a passage owns content nodes exactly as an item does. A
+ * capability declares this surface once and reaches both.
+ */
+export const CONTENT_MEDIA_SURFACE = "content-media";
+/**
+ * Host slot for a text alternate that has to be read in order with the
+ * content: full width, above the card body, in document flow.
+ *
+ * Separate from {@link CONTENT_MEDIA_SURFACE} because the geometry is the
+ * whole difference. Docked media is watched beside the content and is sized by
+ * an aspect ratio; a transcript or a plain-language alternate is read *before*
+ * the control it belongs to, which a sticky side column cannot express.
+ */
+export const CONTENT_LEAD_SURFACE = "content-lead";

package/dist/tools/registration.d.ts

@@ -30,6 +30,7 @@ export type { ToolSelectionAction, ToolSelectionContext, } from "../services/sel
 export { resolveFallbackToolIcon } from "../services/tool-icons.js";
 export type { ContentCapabilityPhase, ContentCapabilityPolicy, ResolveContentCapabilitiesArgs, ResolvedContentCapability, } from "./content-capability-resolution.js";
 export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export { CONTENT_LEAD_SURFACE, CONTENT_MEDIA_SURFACE, } from "./content-surfaces.js";
 export type { ToolSurfaceHost, ToolSurfaceHostInput, ToolSurfaceHostOptions, ToolSurfaceHostSnapshot, ToolSurfaceScope, } from "./tool-surface-host.js";
 export { createToolSurfaceHost } from "./tool-surface-host.js";
 export type { ElementSupports, ToolContext, } from "../services/tool-context.js";
@@ -50,6 +51,7 @@ export { findShellScopeHost, resolveContentRegion, } from "../runtime/content-re
 export { composedClosest, composedContains, flatTextContent, isShadowRootNode, retargetToTree, } from "../services/tts/flat-tree.js";
 export type { ToolPlacementLevel } from "../services/tools-config-normalizer.js";
 export type { CalculatorToolProviderConfig, TextToSpeechToolProviderConfig, ToolProviderConfig, } from "../services/tools-config-normalizer.js";
+export type { ToolConfigDiagnostic, ToolConfigDiagnosticSeverity, } from "../services/tool-config-validation.js";
 export type { ToolProviderApi } from "../services/tool-providers/ToolProviderApi.js";
 export { TTSToolProvider } from "../services/tool-providers/index.js";
 export type { NormalizedTTSSpeedOption, TTSLayoutMode, TTSSpeedOption, } from "../services/tts-runtime-config.js";

package/dist/tools/registration.js

@@ -29,6 +29,11 @@ export { reportToolFailure } from "../services/tool-failure.js";
 // So a gateway button and the toolbar button for the same tool draw one icon.
 export { resolveFallbackToolIcon } from "../services/tool-icons.js";
 export { resolveContentCapabilities } from "./content-capability-resolution.js";
+// The surface ids a registration declares in `surfaces` and a renderer opens in
+// its own layout, one definition for both sides: a capability package cannot
+// import a player, and a renderer with no coordinator — print — cannot import
+// the composition layer for the packaged registrations'.
+export { CONTENT_LEAD_SURFACE, CONTENT_MEDIA_SURFACE, } from "./content-surfaces.js";
 export { createToolSurfaceHost } from "./tool-surface-host.js";
 export { elementSupports, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
 export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";