@pie-players/pie-assessment-toolkit 0.3.64 → 0.3.66

package/dist/services/defaultPersonalNeedsProfile.js

@@ -1,46 +1,25 @@
-import { createPackagedToolRegistry } from "./createDefaultToolRegistry.js";
 /**
- * PNP support ids that must never enter the computed default profile, however
- * they reach the registry.
+ * An empty personal-needs profile: nothing granted, nothing prohibited, nothing
+ * activated at init.
  *
- * `computeDefaultSupports()` derives the fallback profile from every registered
- * tool's `pnpSupportIds`, which is right for universal features — a highlighter
- * or a zoom control should be there for every student by default. It is wrong
- * for an **accommodation**: signing requires a documented need (IEP / 504), so
- * granting it to every host that does not supply its own profile would invert
- * the eligibility tier. Registry membership is about being policy-addressable,
- * not about who may enable it.
+ * The core ships no populated default on purpose. It once derived one from every
+ * registered tool's `pnpSupportIds`, which read *registry membership* as
+ * *eligibility tier* — registration means "policy-addressable", not "universal,
+ * on by default" — so an accommodation-tier capability was granted to every
+ * student of every host that supplied no profile. The remedy at the time was a
+ * compile-time list of ids to exclude, which a host could not extend for its own
+ * accommodation.
  *
- * Excluded here rather than by declining to register, so the guarantee holds
- * even if a signing tool is later registered for some other reason.
+ * Which capabilities a deployment grants by default is a property of the
+ * program, not of this package: TTS is a universal feature in one program and a
+ * documented accommodation in another. That belongs in policy configuration
+ * alongside the district and test-administration levels. A named preset of
+ * today's universal set ships as data from
+ * `@pie-players/pie-default-tool-loaders`, for hosts that want it.
  */
-export const ACCOMMODATION_ONLY_SUPPORT_IDS = [
-    // QTI 3.0 / AfA `signLanguage`. Signed alternates are rendered by
-    // section-player's per-item media region, gated on this id.
-    "signLanguage",
-];
-function computeDefaultSupports() {
-    const registry = createPackagedToolRegistry();
-    const supports = new Set();
-    const excluded = new Set(ACCOMMODATION_ONLY_SUPPORT_IDS);
-    for (const tool of registry.getAllTools()) {
-        for (const supportId of tool.pnpSupportIds || []) {
-            if (excluded.has(supportId))
-                continue;
-            supports.add(supportId);
-        }
-    }
-    return [...supports].sort();
-}
-const DEFAULT_SUPPORTS = computeDefaultSupports();
-export const DEFAULT_PERSONAL_NEEDS_PROFILE = {
-    supports: [...DEFAULT_SUPPORTS],
-    prohibitedSupports: [],
-    activateAtInit: [],
-};
-export function createDefaultPersonalNeedsProfile() {
+export function createEmptyPersonalNeedsProfile() {
     return {
-        supports: [...DEFAULT_SUPPORTS],
+        supports: [],
         prohibitedSupports: [],
         activateAtInit: [],
     };

package/dist/services/framework-error.d.ts

@@ -1,5 +1,5 @@
 import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
-export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispose" | "coordinator-init" | "provider-init" | "provider-register" | "tts-init" | "tool-state-load" | "tool-state-save" | "section-controller-init" | "section-controller-dispose" | "unknown";
+export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispose" | "coordinator-init" | "provider-init" | "provider-register" | "tts-init" | "tool-state-load" | "tool-state-save" | "section-controller-init" | "section-controller-dispose" | "tool-surface" | "unknown";
 export type FrameworkErrorSeverity = "warning" | "error";
 export interface FrameworkErrorModel {
     kind: FrameworkErrorKind;

package/dist/services/interfaces.d.ts

@@ -8,8 +8,11 @@
  * Part of PIE Assessment Toolkit.
  */
 import type { I18nServiceApi } from "@pie-players/pie-players-shared/i18n";
-import type { AccessibilityCatalogResolver, CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerContext, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
+import type { AccessibilityCatalog } from "@pie-players/pie-players-shared/types";
+import type { AccessibilityCatalogResolver, CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerRegistration, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
+import type { CatalogOwnerContext } from "./catalog-owner.js";
 import type { FrameworkErrorListener } from "./framework-error-bus.js";
+import type { FrameworkErrorModel } from "./framework-error.js";
 import type { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
 import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks, ToolkitInitStatus } from "./ToolkitCoordinator.js";
 import type { ThemeConfig } from "./ThemeProvider.js";
@@ -291,11 +294,15 @@ export interface AccessibilityCatalogResolverApi {
     /**
      * Add item-level catalogs (called when rendering a new item)
      */
-    addItemCatalogs(catalogs: any[]): void;
+    addItemCatalogs(catalogs: AccessibilityCatalog[]): void;
     /**
      * Register catalogs scoped to a mounted content owner.
      */
-    registerCatalogs?(context: CatalogOwnerContext, catalogs: any[]): () => void;
+    registerCatalogs(context: CatalogOwnerContext, catalogs: AccessibilityCatalog[]): () => void;
+    /** Register every catalog carried by one mounted item or passage. */
+    registerOwner(registration: CatalogOwnerRegistration): () => void;
+    /** Bind read and change observation to one catalog owner. */
+    forOwner(context: CatalogOwnerContext): CatalogOwnerView;
     /**
      * Clear item-level catalogs (called when leaving an item)
      */
@@ -586,6 +593,11 @@ export interface ToolkitCoordinatorApi {
      * `<pie-assessment-toolkit>` consume the same bus.
      */
     subscribeFrameworkErrors(listener: FrameworkErrorListener): () => void;
+    /**
+     * Report a pre-built framework warning or error through the canonical bus.
+     * Optional so structural host coordinators remain assignable.
+     */
+    reportFrameworkError?(model: FrameworkErrorModel): void;
     /**
      * Resolve the visible tool set for a given placement level + scope.
      * Returns the engine's full decision (visible tools, diagnostics,

package/dist/services/pnp-standard-features.d.ts

@@ -167,7 +167,7 @@ export declare const QTI_STANDARD_ACCESS_FEATURES: {
 /**
  * Flat list of all standard access features for validation
  */
-export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "graph" | "periodicTable" | "calculator" | "answerEliminator" | "ruler" | "protractor" | "graphingCalculator" | "readAloud" | "strikethrough" | "answerMasking" | "readingMask" | "readingGuide" | "readingRuler" | "highContrastDisplay" | "colorContrast" | "invertColors" | "highlighting" | "annotations" | "signLanguage" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastAudio" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "bookmarking" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "formulaSheet" | "itemGlossary" | "tutorialAvailable")[];
+export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "calculator" | "strikethrough" | "answerEliminator" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastDisplay" | "highContrastAudio" | "colorContrast" | "invertColors" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "readAloud" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "signLanguage" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "annotations" | "bookmarking" | "highlighting" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "readingMask" | "readingGuide" | "readingRuler" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "protractor" | "ruler" | "graph" | "graphingCalculator" | "periodicTable" | "formulaSheet" | "answerMasking" | "itemGlossary" | "tutorialAvailable")[];
 /**
  * Example PNP configurations for common accessibility needs
  * These are NOT official profiles but illustrative examples showing

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

@@ -1,3 +1,10 @@
+/**
+ * Placement defaults this package can hold.
+ *
+ * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
+ * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
+ * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ */
 export declare const DEFAULT_TOOL_PLACEMENT: {
     readonly assessment: readonly [];
     readonly section: readonly [];
@@ -6,26 +13,3 @@ export declare const DEFAULT_TOOL_PLACEMENT: {
     readonly rubric: readonly [];
     readonly element: readonly [];
 };
-/**
- * Complete placement preset for hosts that want to enable all packaged tools.
- * Prefer explicit host configuration over implicit defaults.
- */
-export declare const PACKAGED_TOOL_PLACEMENT: {
-    readonly assessment: readonly ["theme"];
-    readonly section: readonly ["theme"];
-    readonly item: readonly ["textToSpeech", "highlighter", "annotationToolbar", "graph", "periodicTable"];
-    readonly passage: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
-    readonly rubric: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
-    readonly element: readonly ["calculator", "answerEliminator", "textToSpeech", "ruler", "protractor", "highlighter", "annotationToolbar", "graph", "periodicTable"];
-};
-/**
- * Opt-in section-player placement preset for hosts that want to expose every
- * packaged tool once at its normal assessment surface. This is not exhaustive:
- * `supportedLevels` still defines where tools can run, and hosts can still
- * choose different placement for custom UX.
- */
-export declare const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT: {
-    section: string[];
-    item: string[];
-    passage: string[];
-};

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

@@ -1,3 +1,10 @@
+/**
+ * Placement defaults this package can hold.
+ *
+ * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
+ * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
+ * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ */
 export const DEFAULT_TOOL_PLACEMENT = {
     assessment: [],
     section: [],
@@ -6,49 +13,3 @@ export const DEFAULT_TOOL_PLACEMENT = {
     rubric: [],
     element: [],
 };
-/**
- * Complete placement preset for hosts that want to enable all packaged tools.
- * Prefer explicit host configuration over implicit defaults.
- */
-export const PACKAGED_TOOL_PLACEMENT = {
-    assessment: ["theme"],
-    section: ["theme"],
-    item: [
-        "textToSpeech",
-        "highlighter",
-        "annotationToolbar",
-        "graph",
-        "periodicTable",
-    ],
-    passage: ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"],
-    rubric: ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"],
-    element: [
-        "calculator",
-        "answerEliminator",
-        "textToSpeech",
-        "ruler",
-        "protractor",
-        "highlighter",
-        "annotationToolbar",
-        "graph",
-        "periodicTable",
-    ],
-};
-/**
- * Opt-in section-player placement preset for hosts that want to expose every
- * packaged tool once at its normal assessment surface. This is not exhaustive:
- * `supportedLevels` still defines where tools can run, and hosts can still
- * choose different placement for custom UX.
- */
-export const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT = {
-    section: [
-        "theme",
-        "graph",
-        "periodicTable",
-        "lineReader",
-        "ruler",
-        "protractor",
-    ],
-    item: ["calculator", "textToSpeech", "answerEliminator", "annotationToolbar"],
-    passage: ["textToSpeech", "annotationToolbar"],
-};

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

@@ -4,7 +4,7 @@ import type { ToolRegistry } from "./ToolRegistry.js";
 export type ToolConfigStrictness = "off" | "warn" | "error";
 export type ToolConfigDiagnosticSeverity = "warning" | "error";
 export interface ToolConfigDiagnostic {
-    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unknownProviderKey" | "tools.removedProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
+    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.removedProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
     severity: ToolConfigDiagnosticSeverity;
     path: string;
     message: string;

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

@@ -1,6 +1,5 @@
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
 import { frameworkErrorFromToolConfigDiagnostics, frameworkErrorFromUnknown, } from "./framework-error.js";
-import { createPackagedToolRegistry } from "./createDefaultToolRegistry.js";
 export function frameworkErrorFromToolConfigValidation(args) {
     if (Array.isArray(args.diagnostics) && args.diagnostics.length > 0) {
         return frameworkErrorFromToolConfigDiagnostics({
@@ -120,6 +119,20 @@ function collectPlacementDiagnostics(config, toolMap, diagnostics) {
                 }));
                 continue;
             }
+            if (tool.activation === "region") {
+                // A region capability has no toolbar button, so placing it names a
+                // surface that will never render it. Reported at the placement rather
+                // than at render time, where the symptom is an absent accommodation and
+                // no error.
+                diagnostics.push(createDiagnostic({
+                    code: "tools.unplaceableActivation",
+                    severity: "error",
+                    path: `placement.${level}`,
+                    message: `Tool "${toolId}" renders into a host surface (activation "region") and cannot be placed on the ${level} toolbar. Remove it from placement.${level}; its availability comes from policy plus its content dependency.`,
+                    toolId,
+                }));
+                continue;
+            }
             const supportsLevel = tool.supportedLevels.includes(level);
             // Leniency policy: section-capable tools are tolerated in item placement.
             // This avoids strict failures for common host config patterns while still
@@ -204,9 +217,27 @@ function throwValidationError(diagnostics, source) {
 export function normalizeAndValidateToolsConfig(input, options = {}) {
     const strictness = normalizeToolConfigStrictness(options.strictness);
     const source = options.source ?? "tools";
-    const registryTools = getRegistryToolMap(options.toolRegistry ?? createPackagedToolRegistry());
+    const registryTools = getRegistryToolMap(options.toolRegistry);
     const normalized = normalizeToolsConfig(input);
     const diagnostics = [];
+    // Tool-id and provider checks need a registry to check against, and every
+    // collector below returns early without one. Say so: this package no longer
+    // falls back to a packaged registry, so a caller that used to get id
+    // validation for free now gets none, and a silent downgrade from "your ids are
+    // valid" to "nobody looked" is the kind of change that surfaces as a typo
+    // reaching a learner.
+    const hasConfiguredTools = Object.values(normalized.placement).some((ids) => ids.length > 0) ||
+        Object.keys(normalized.providers).length > 0 ||
+        (normalized.policy.allowed?.length ?? 0) > 0 ||
+        (normalized.policy.blocked?.length ?? 0) > 0;
+    if (registryTools.size === 0 && hasConfiguredTools) {
+        diagnostics.push(createDiagnostic({
+            code: "tools.registryUnavailable",
+            severity: "warning",
+            path: "tools",
+            message: 'No tool registry was supplied, so tool ids, placement levels and provider config were not validated. Pass `toolRegistry` — for the packaged capability set, `createPackagedToolRegistry()` from "@pie-players/pie-default-tool-loaders".',
+        }));
+    }
     const hasRemovedTtsKey = Object.hasOwn(normalized.providers, "tts");
     const nextProviders = {
         ...(normalized.providers || {}),
@@ -233,8 +264,17 @@ export function normalizeAndValidateToolsConfig(input, options = {}) {
     if (strictness === "warn") {
         emitWarnings(diagnostics, source);
     }
-    if (strictness === "error" && diagnostics.length > 0) {
-        throwValidationError(diagnostics, source);
+    // Severity decides what `strictness: "error"` rejects. Every diagnostic this
+    // function raised was `"error"` until `tools.registryUnavailable`, which
+    // reports that validation could not run rather than that the config is wrong —
+    // throwing on it would turn "no registry supplied" from a host's existing,
+    // working setup into a construction failure.
+    const blocking = diagnostics.filter((entry) => entry.severity === "error");
+    if (strictness === "error" && blocking.length > 0) {
+        throwValidationError(blocking, source);
+    }
+    if (strictness === "error" && blocking.length === 0) {
+        emitWarnings(diagnostics, source);
     }
     return {
         config: nextConfig,

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

@@ -7,6 +7,8 @@
  * Part of PIE Assessment Toolkit.
  */
 import { segmentSentences as segmentTextToSentences } from "./text-segmentation.js";
+const NATIVE_START_TIMEOUT_MS = 5_000;
+const VOICE_INVENTORY_TIMEOUT_MS = 2_000;
 const normalizeLanguageCode = (value) => String(value || "")
     .trim()
     .toLowerCase();
@@ -16,17 +18,18 @@ const browserLanguage = () => {
         : "";
     return normalizeLanguageCode(navigatorLanguage || "en-US");
 };
-const findBrowserVoice = (voices, preferredName) => {
-    if (preferredName) {
-        const explicit = voices.find((voice) => voice.name === preferredName);
-        if (explicit)
-            return explicit;
+const findBrowserVoice = (voices, preferredVoice) => {
+    if (preferredVoice) {
+        return (voices.find((voice) => voice.voiceURI === preferredVoice) ||
+            voices.find((voice) => voice.name === preferredVoice) ||
+            null);
     }
     const language = browserLanguage();
     const languagePrefix = language.split("-")[0] || "en";
     const matchesLanguage = (voice) => {
         const voiceLanguage = normalizeLanguageCode(voice.lang);
-        return voiceLanguage === language || voiceLanguage.startsWith(`${languagePrefix}-`);
+        return (voiceLanguage === language ||
+            voiceLanguage.startsWith(`${languagePrefix}-`));
     };
     const ranked = [
         (voice) => voice.localService && matchesLanguage(voice),
@@ -94,9 +97,98 @@ class BrowserTTSProviderImpl {
     _isPlaying = false;
     _isPaused = false;
     speakRunId = 0;
+    settlePendingVoiceWait = null;
+    settlePendingChunk = null;
+    onPlaybackStart = undefined;
     constructor(config) {
         this.config = config;
     }
+    waitForBrowserVoices(runId, configuredVoice) {
+        return new Promise((resolve, reject) => {
+            const synth = speechSynthesis;
+            const canUseEventTarget = typeof synth.addEventListener === "function" &&
+                typeof synth.removeEventListener === "function";
+            const previousHandler = canUseEventTarget ? null : synth.onvoiceschanged;
+            let settled = false;
+            let timeout = null;
+            let pendingSettlement = null;
+            const cleanup = () => {
+                if (timeout !== null) {
+                    clearTimeout(timeout);
+                    timeout = null;
+                }
+                if (canUseEventTarget) {
+                    synth.removeEventListener("voiceschanged", onVoicesChanged);
+                }
+                else if (synth.onvoiceschanged === propertyHandler) {
+                    synth.onvoiceschanged = previousHandler;
+                }
+                if (pendingSettlement &&
+                    this.settlePendingVoiceWait === pendingSettlement) {
+                    this.settlePendingVoiceWait = null;
+                }
+            };
+            const finish = (voicesAvailable, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(voicesAvailable);
+                }
+            };
+            const inspectVoiceInventory = () => {
+                if (runId !== this.speakRunId) {
+                    finish(false);
+                    return;
+                }
+                if (synth.getVoices().length > 0)
+                    finish(true);
+            };
+            const onVoicesChanged = () => inspectVoiceInventory();
+            const propertyHandler = (event) => {
+                try {
+                    previousHandler?.call(synth, event);
+                }
+                finally {
+                    inspectVoiceInventory();
+                }
+            };
+            pendingSettlement = () => finish(false);
+            this.settlePendingVoiceWait = pendingSettlement;
+            timeout = setTimeout(() => finish(false, new Error(`Configured browser voice "${configuredVoice}" could not be resolved because the browser did not publish its voice inventory within ${VOICE_INVENTORY_TIMEOUT_MS / 1_000} seconds.`)), VOICE_INVENTORY_TIMEOUT_MS);
+            if (canUseEventTarget) {
+                synth.addEventListener("voiceschanged", onVoicesChanged);
+            }
+            else {
+                synth.onvoiceschanged = propertyHandler;
+            }
+            // Close the getVoices()/listener-registration race without polling.
+            inspectVoiceInventory();
+        });
+    }
+    async resolveBrowserVoice(runId) {
+        const configuredVoice = typeof this.config?.voice === "string" ? this.config.voice.trim() : "";
+        let voices = speechSynthesis.getVoices();
+        if (configuredVoice && voices.length === 0) {
+            const voicesAvailable = await this.waitForBrowserVoices(runId, configuredVoice);
+            if (!voicesAvailable || runId !== this.speakRunId) {
+                return { shouldContinue: false, voice: null };
+            }
+            voices = speechSynthesis.getVoices();
+        }
+        if (runId !== this.speakRunId) {
+            return { shouldContinue: false, voice: null };
+        }
+        const voice = findBrowserVoice(voices, configuredVoice || undefined);
+        if (configuredVoice && !voice) {
+            throw new Error(`Configured browser voice "${configuredVoice}" is unavailable. Select a voice exposed by this browser using its voiceURI or name.`);
+        }
+        return { shouldContinue: true, voice };
+    }
     async speak(text) {
         if (!this.config) {
             throw new Error("TTS not initialized");
@@ -104,12 +196,15 @@ class BrowserTTSProviderImpl {
         // Invalidate any in-flight run and cancel current utterance.
         this.stop();
         const runId = this.speakRunId;
+        const voiceResolution = await this.resolveBrowserVoice(runId);
+        if (!voiceResolution.shouldContinue)
+            return;
         const chunks = this.splitIntoChunks(text);
         for (const chunk of chunks) {
             if (runId !== this.speakRunId) {
                 break;
             }
-            const shouldContinue = await this.speakChunk(chunk.text, chunk.offset, runId);
+            const shouldContinue = await this.speakChunk(chunk.text, chunk.offset, runId, voiceResolution.voice);
             if (!shouldContinue) {
                 break;
             }
@@ -121,6 +216,9 @@ class BrowserTTSProviderImpl {
         }
         this.stop();
         const runId = this.speakRunId;
+        const voiceResolution = await this.resolveBrowserVoice(runId);
+        if (!voiceResolution.shouldContinue)
+            return;
         for (const segment of segments) {
             if (runId !== this.speakRunId)
                 break;
@@ -128,7 +226,7 @@ class BrowserTTSProviderImpl {
             for (const chunk of chunks) {
                 if (runId !== this.speakRunId)
                     break;
-                const shouldContinue = await this.speakChunk(chunk.text, segment.startOffset + chunk.offset, runId);
+                const shouldContinue = await this.speakChunk(chunk.text, segment.startOffset + chunk.offset, runId, voiceResolution.voice);
                 if (!shouldContinue)
                     break;
             }
@@ -213,7 +311,7 @@ class BrowserTTSProviderImpl {
         const match = slice.match(/^\s*([^\s]+)/);
         return match?.[1]?.length || 1;
     }
-    async speakChunk(chunkText, chunkOffset, runId) {
+    async speakChunk(chunkText, chunkOffset, runId, voice) {
         return new Promise((resolve, reject) => {
             if (runId !== this.speakRunId) {
                 resolve(false);
@@ -222,47 +320,99 @@ class BrowserTTSProviderImpl {
             const utterance = new SpeechSynthesisUtterance(chunkText);
             this.utterance = utterance;
             // Apply config
-            const voice = findBrowserVoice(speechSynthesis.getVoices(), this.config?.voice);
             if (voice && shouldAssignBrowserVoice(voice))
                 utterance.voice = voice;
             if (this.config?.rate)
                 utterance.rate = this.config.rate;
             if (this.config?.pitch)
                 utterance.pitch = this.config.pitch;
+            let didStart = false;
+            let settled = false;
+            let startTimeout = null;
+            let pendingSettlement = null;
             const clearOwnedUtterance = () => {
                 if (this.utterance === utterance) {
                     this.utterance = null;
                 }
             };
+            const clearStartTimeout = () => {
+                if (startTimeout !== null) {
+                    clearTimeout(startTimeout);
+                    startTimeout = null;
+                }
+            };
+            const detachHandlers = () => {
+                utterance.onstart = null;
+                utterance.onend = null;
+                utterance.onerror = null;
+                utterance.onpause = null;
+                utterance.onresume = null;
+                utterance.onboundary = null;
+            };
+            const settle = (shouldContinue, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearStartTimeout();
+                detachHandlers();
+                clearOwnedUtterance();
+                if (pendingSettlement &&
+                    this.settlePendingChunk === pendingSettlement) {
+                    this.settlePendingChunk = null;
+                }
+                if (runId === this.speakRunId) {
+                    this._isPlaying = false;
+                    this._isPaused = false;
+                }
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(shouldContinue);
+                }
+            };
+            const browserEngineStartError = (reason) => new Error(reason === "ended"
+                ? "Browser speech synthesis ended before audio started. The browser speech engine may be unavailable or stuck; try another voice or restart the browser."
+                : `Browser speech synthesis did not start within ${NATIVE_START_TIMEOUT_MS / 1_000} seconds. The browser speech engine may be unavailable or stuck; try another voice or restart the browser.`);
+            pendingSettlement = () => settle(false);
+            this.settlePendingChunk = pendingSettlement;
             utterance.onstart = () => {
-                if (runId !== this.speakRunId)
+                if (runId !== this.speakRunId) {
+                    settle(false);
                     return;
+                }
+                didStart = true;
+                clearStartTimeout();
                 this._isPlaying = true;
                 this._isPaused = false;
+                try {
+                    this.onPlaybackStart?.();
+                }
+                catch (error) {
+                    console.error("Browser TTS playback-start callback failed", error);
+                }
             };
             utterance.onend = () => {
-                clearOwnedUtterance();
                 if (runId !== this.speakRunId) {
-                    resolve(false);
+                    settle(false);
                     return;
                 }
-                this._isPlaying = false;
-                this._isPaused = false;
-                resolve(true);
+                if (!didStart) {
+                    settle(false, browserEngineStartError("ended"));
+                    return;
+                }
+                settle(true);
             };
             utterance.onerror = (event) => {
-                clearOwnedUtterance();
                 if (runId !== this.speakRunId) {
-                    resolve(false);
+                    settle(false);
                     return;
                 }
-                this._isPlaying = false;
-                this._isPaused = false;
                 if (event.error === "interrupted" || event.error === "canceled") {
-                    resolve(false);
+                    settle(false);
                     return;
                 }
-                reject(new Error(`Speech synthesis error: ${event.error}`));
+                settle(false, new Error(`Speech synthesis error: ${event.error}`));
             };
             utterance.onpause = () => {
                 if (runId !== this.speakRunId)
@@ -299,7 +449,20 @@ class BrowserTTSProviderImpl {
                 console.log("[BrowserProvider] Calling onWordBoundary with word:", word, "at position:", absoluteBoundaryStart);
                 this.onWordBoundary(word, absoluteBoundaryStart, wordLength);
             };
-            speechSynthesis.speak(utterance);
+            startTimeout = setTimeout(() => {
+                if (settled || didStart || runId !== this.speakRunId)
+                    return;
+                settle(false, browserEngineStartError("timedOut"));
+                speechSynthesis.cancel();
+            }, NATIVE_START_TIMEOUT_MS);
+            try {
+                speechSynthesis.speak(utterance);
+            }
+            catch (error) {
+                settle(false, error instanceof Error
+                    ? error
+                    : new Error("Browser speech synthesis failed to queue speech"));
+            }
         });
     }
     pause() {
@@ -313,8 +476,12 @@ class BrowserTTSProviderImpl {
         }
     }
     stop() {
+        const utterance = this.utterance;
+        const shouldCancel = this._isPlaying || utterance !== null;
         this.speakRunId += 1;
-        if (this._isPlaying || this.utterance) {
+        this.settlePendingVoiceWait?.();
+        this.settlePendingChunk?.();
+        if (shouldCancel) {
             speechSynthesis.cancel();
         }
         this.utterance = null;