@pie-players/pie-assessment-toolkit 0.3.65 → 0.3.67

package/dist/services/TTSService.js

@@ -97,6 +97,13 @@ export class TTSService {
     sentenceHighlightSegments = [];
     currentSeekSegmentIndex = 0;
     activeSentenceStartOffset = null;
+    playbackStartDeferredRunId = null;
+    pendingPlaybackStartHighlights = [];
+    playbackStartBarrierCleanup = null;
+    playbackRateWriteQueue = Promise.resolve();
+    playbackRateRequestId = 0;
+    pendingPlaybackRateRequest = null;
+    activePlaybackRate = null;
     activeHighlightMode = "word";
     lastRenderedRegionTarget = null;
     telemetryReporter = null;
@@ -130,6 +137,61 @@ export class TTSService {
             console.debug(message, detail);
         }
     }
+    clearPlaybackStartBarrier(cleanup = this.playbackStartBarrierCleanup) {
+        cleanup?.();
+        if (this.playbackStartBarrierCleanup === cleanup) {
+            this.playbackStartBarrierCleanup = null;
+        }
+    }
+    notifyPlaybackStarted(runId) {
+        if (this.playbackStartDeferredRunId !== runId ||
+            runId !== this.speakRunId) {
+            return;
+        }
+        this.setState(PlaybackState.PLAYING);
+        const pendingHighlights = this.pendingPlaybackStartHighlights.splice(0);
+        for (const applyHighlight of pendingHighlights) {
+            applyHighlight();
+        }
+    }
+    installPlaybackStartBarrier(runId, hasMediaStartSignal = false) {
+        this.clearPlaybackStartBarrier();
+        const provider = this.provider;
+        const startAwareProvider = provider && "onPlaybackStart" in provider ? provider : null;
+        if (!startAwareProvider && !hasMediaStartSignal)
+            return null;
+        const previousOnPlaybackStart = startAwareProvider?.onPlaybackStart;
+        const onPlaybackStart = () => {
+            try {
+                this.notifyPlaybackStarted(runId);
+            }
+            finally {
+                previousOnPlaybackStart?.();
+            }
+        };
+        if (startAwareProvider) {
+            startAwareProvider.onPlaybackStart = onPlaybackStart;
+        }
+        this.playbackStartDeferredRunId = runId;
+        const cleanup = () => {
+            if (startAwareProvider?.onPlaybackStart === onPlaybackStart) {
+                startAwareProvider.onPlaybackStart = previousOnPlaybackStart;
+            }
+            if (this.playbackStartDeferredRunId === runId) {
+                this.playbackStartDeferredRunId = null;
+                this.pendingPlaybackStartHighlights = [];
+            }
+        };
+        this.playbackStartBarrierCleanup = cleanup;
+        return cleanup;
+    }
+    runWhenPlaybackStarts(runId, callback) {
+        if (this.playbackStartDeferredRunId === runId) {
+            this.pendingPlaybackStartHighlights.push(callback);
+            return;
+        }
+        callback();
+    }
     async emitTelemetry(eventName, payload) {
         try {
             await this.telemetryReporter?.(eventName, payload);
@@ -810,7 +872,9 @@ export class TTSService {
             }
             this.currentBoundaryOffset = segment.startOffset;
             if (shouldTrackSentenceProgress) {
-                this.highlightSentenceSegment(segment.startOffset, segment.text);
+                this.runWhenPlaybackStarts(runId, () => {
+                    this.highlightSentenceSegment(segment.startOffset, segment.text);
+                });
             }
             await this.provider.speak(segment.text);
             const pauseMs = segment.pauseMsAfter ?? 0;
@@ -923,6 +987,8 @@ export class TTSService {
             throw new Error("TTS service not initialized");
         }
         const runId = ++this.speakRunId;
+        this.clearPlaybackStartBarrier();
+        let playbackStartBarrier = null;
         try {
             await this.applyLanguageSettings(options);
             if (runId !== this.speakRunId)
@@ -962,11 +1028,13 @@ export class TTSService {
                     playbackSegments: this.seekSegments,
                 });
             this.setState(PlaybackState.LOADING);
+            playbackStartBarrier = this.installPlaybackStartBarrier(runId, !!this.playbackChunks[0]?.audio);
             this.prepareHighlightsForSpeak({
                 contentToSpeak: highlightText,
                 options,
                 highlightMode,
                 shouldUsePlan,
+                runId,
             });
             if (speechMatchesVisibleText) {
                 this.configureWordBoundaryHighlighting({
@@ -977,7 +1045,10 @@ export class TTSService {
             else {
                 this.clearWordBoundaryHighlighting();
             }
-            this.setState(PlaybackState.PLAYING);
+            if (!playbackStartBarrier) {
+                this.setState(PlaybackState.PLAYING);
+            }
+            this.activePlaybackRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
             await this.executeSpeakPlayback({
                 shouldUsePlan,
                 runId,
@@ -1001,13 +1072,30 @@ export class TTSService {
             this.clearHighlightsAndTracking();
             throw finalError;
         }
+        finally {
+            this.clearPlaybackStartBarrier(playbackStartBarrier);
+        }
     }
     async switchProviderToBrowser(reason, context) {
         if (!this.currentProvider)
             return false;
         const fallbackProvider = new BrowserTTSProvider();
         const previousProviderId = this.currentProvider.providerId;
-        const browserConfig = { ...this.ttsConfig };
+        // Voice identifiers and provider extensions belong to the provider that
+        // rejected initialization. Carry only settings whose meaning is portable
+        // when crossing the provider boundary; otherwise a Polly/Google/SC voice
+        // such as "Joanna" can incorrectly become an explicit Browser voice.
+        const browserConfig = {};
+        if (this.ttsConfig.rate !== undefined) {
+            browserConfig.rate = this.ttsConfig.rate;
+        }
+        if (this.ttsConfig.pitch !== undefined) {
+            browserConfig.pitch = this.ttsConfig.pitch;
+        }
+        if (this.ttsConfig.mathTokenHighlighting !== undefined) {
+            browserConfig.mathTokenHighlighting =
+                this.ttsConfig.mathTokenHighlighting;
+        }
         const operation = context?.operation || "tts-initialize";
         const offendingText = context?.contentToSpeak ?? "";
         const offendingPreview = offendingText
@@ -1431,20 +1519,22 @@ export class TTSService {
             return;
         }
         const initialSegment = this.sentenceHighlightSegments[0] || this.seekSegments[0];
-        if (initialSegment) {
-            this.highlightSentenceSegment(initialSegment.startOffset, initialSegment.text);
-            this.debugLog("[TTSService] Applied initial sentence highlighting");
-        }
-        else {
-            try {
-                const range = document.createRange();
-                range.selectNodeContents(this.currentContentElement);
-                this.paintTTSSentenceRanges([range]);
+        this.runWhenPlaybackStarts(args.runId, () => {
+            if (initialSegment) {
+                this.highlightSentenceSegment(initialSegment.startOffset, initialSegment.text);
+                this.debugLog("[TTSService] Applied initial sentence highlighting");
             }
-            catch {
-                // No-op fallback when DOM range creation fails.
+            else {
+                try {
+                    const range = document.createRange();
+                    range.selectNodeContents(this.currentContentElement);
+                    this.paintTTSSentenceRanges([range]);
+                }
+                catch {
+                    // No-op fallback when DOM range creation fails.
+                }
             }
-        }
+        });
     }
     configureWordBoundaryHighlighting(args) {
         if (!this.provider ||
@@ -1605,6 +1695,16 @@ export class TTSService {
             // fallback, so this cannot recurse.
             if (chunk.plainFallback && runId === this.speakRunId) {
                 this.debugLog("[TTSService] SSML chunk speak failed; retrying plain text", { message: error instanceof Error ? error.message : String(error) });
+                // A recorded-first run can own the start barrier even when its fallback
+                // provider has no formal start signal. Drop the failed recording's queued
+                // highlight and resume that non-start-aware provider's immediate-start lifecycle.
+                if (this.playbackStartDeferredRunId === runId &&
+                    this.provider &&
+                    !("onPlaybackStart" in this.provider)) {
+                    this.pendingPlaybackStartHighlights = [];
+                    this.clearPlaybackStartBarrier();
+                    this.setState(PlaybackState.PLAYING);
+                }
                 await this.speakCatalogChunkOnce(chunk.plainFallback, runId);
                 return;
             }
@@ -1621,7 +1721,7 @@ export class TTSService {
      * would highlight the wrong words confidently rather than the right region
      * vaguely.
      */
-    async playRecordedAudio(media) {
+    async playRecordedAudio(media, onPlaybackStart) {
         if (typeof document === "undefined") {
             throw new Error("[tts] no document available to play recorded audio");
         }
@@ -1632,9 +1732,18 @@ export class TTSService {
         element.playbackRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate || 1));
         await new Promise((resolve, reject) => {
             let endGuard;
+            let didStart = false;
+            let settled = false;
+            const markStarted = () => {
+                if (settled || didStart)
+                    return;
+                didStart = true;
+                onPlaybackStart?.();
+            };
             const cleanup = () => {
                 element.removeEventListener("ended", onEnded);
                 element.removeEventListener("error", onError);
+                element.removeEventListener("playing", markStarted);
                 if (endGuard !== undefined)
                     clearInterval(endGuard);
                 if (this.activeRecordedAudio?.element === element) {
@@ -1642,10 +1751,16 @@ export class TTSService {
                 }
             };
             const onEnded = () => {
+                if (settled)
+                    return;
+                settled = true;
                 cleanup();
                 resolve();
             };
             const onError = () => {
+                if (settled)
+                    return;
+                settled = true;
                 cleanup();
                 reject(new Error(`[tts] recorded audio failed to play: ${source.src}`));
             };
@@ -1655,6 +1770,9 @@ export class TTSService {
             this.activeRecordedAudio = {
                 element,
                 cancel: () => {
+                    if (settled)
+                        return;
+                    settled = true;
                     cleanup();
                     element.pause();
                     resolve();
@@ -1662,6 +1780,7 @@ export class TTSService {
             };
             element.addEventListener("ended", onEnded);
             element.addEventListener("error", onError);
+            element.addEventListener("playing", markStarted);
             // Browsers honour a Media Fragments start offset but are inconsistent
             // about the end bound, so the end is enforced here — the same reason the
             // signing region enforces its own.
@@ -1672,7 +1791,7 @@ export class TTSService {
                         onEnded();
                 }, 100);
             }
-            Promise.resolve(element.play()).catch(onError);
+            Promise.resolve(element.play()).then(markStarted).catch(onError);
         }).finally(() => {
             if (this.activeRecordedAudio?.element === element) {
                 this.activeRecordedAudio = null;
@@ -1693,8 +1812,12 @@ export class TTSService {
             return;
         this.lastRenderedRegionTarget = null;
         if (chunk.audio) {
-            this.highlightCatalogRegion(chunk);
-            await this.playRecordedAudio(chunk.audio);
+            this.runWhenPlaybackStarts(runId, () => {
+                this.highlightCatalogRegion(chunk);
+            });
+            await this.playRecordedAudio(chunk.audio, () => {
+                this.notifyPlaybackStarted(runId);
+            });
             return;
         }
         const contentRoot = chunk.regionElement || chunk.sourceElement || this.currentContentElement;
@@ -1713,12 +1836,14 @@ export class TTSService {
                 mathTokenHighlighting,
             })
             : null;
-        if (highlightPlan && pipelineChunk && chunk.mathAlignment) {
-            this.renderHighlightDecision(highlightPlan.resolveInitial(pipelineChunk.id));
-        }
-        else {
-            this.highlightCatalogRegion(chunk);
-        }
+        this.runWhenPlaybackStarts(runId, () => {
+            if (highlightPlan && pipelineChunk && chunk.mathAlignment) {
+                this.renderHighlightDecision(highlightPlan.resolveInitial(pipelineChunk.id));
+            }
+            else {
+                this.highlightCatalogRegion(chunk);
+            }
+        });
         const canUseChunkBoundaries = chunk.sourceElement &&
             ((chunk.mathAlignment && chunk.mathAlignment.speech.tokens.length > 0) ||
                 (chunk.mathAlignments && chunk.mathAlignments.length > 0) ||
@@ -1805,6 +1930,8 @@ export class TTSService {
         }
     }
     clearHighlightsAndTracking() {
+        this.pendingPlaybackStartHighlights = [];
+        this.activePlaybackRate = null;
         if (this.highlightCoordinator) {
             this.highlightCoordinator.clearTTS();
         }
@@ -1923,13 +2050,21 @@ export class TTSService {
             ? this.playbackChunks.slice(safeTargetIndex)
             : null;
         this.speakRunId += 1;
+        this.clearPlaybackStartBarrier();
         this.cancelRecordedAudio();
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
         this.currentSeekSegmentIndex = safeTargetIndex;
         const runId = ++this.speakRunId;
         const restartSegments = this.seekSegments.slice(safeTargetIndex);
-        this.setState(PlaybackState.PLAYING);
+        this.highlightCoordinator?.clearTTS();
+        this.activeSentenceStartOffset = null;
+        this.setState(PlaybackState.LOADING);
+        const playbackStartBarrier = this.installPlaybackStartBarrier(runId, !!restartChunks?.[0]?.audio);
+        if (!playbackStartBarrier) {
+            this.setState(PlaybackState.PLAYING);
+        }
+        this.activePlaybackRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
         try {
             this.configureWordBoundaryHighlighting({
                 highlightMode: this.activeHighlightMode,
@@ -1968,17 +2103,68 @@ export class TTSService {
             this.highlightTargetResolverProvider = null;
             throw error;
         }
+        finally {
+            this.clearPlaybackStartBarrier(playbackStartBarrier);
+        }
     }
     async setPlaybackRate(rate) {
+        if (!this.provider) {
+            throw new Error("TTSService not initialized. Call initialize() first.");
+        }
         const nextRate = this.normalizePlaybackRate(rate);
-        await this.updateSettings({ rate: nextRate });
-        if (this.state !== PlaybackState.PLAYING ||
-            !this.currentText ||
-            this.seekSegments.length === 0 ||
-            this.hasExplicitBreakSemantics(this.currentText)) {
+        const pendingRequest = this.pendingPlaybackRateRequest;
+        if (pendingRequest?.rate === nextRate) {
+            await pendingRequest.promise;
             return;
         }
-        await this.restartFromSeekIndex(this.getCurrentSeekSegmentIndex());
+        const requestId = ++this.playbackRateRequestId;
+        const settingsWrite = this.playbackRateWriteQueue.then(async () => {
+            const playbackRunId = this.speakRunId;
+            // A newer distinct target supersedes queued work before it mutates either
+            // provider settings or playback. An already-running write cannot be
+            // cancelled, so its post-write generation check still suppresses restart.
+            if (requestId !== this.playbackRateRequestId) {
+                return { didUpdate: false, playbackRunId };
+            }
+            // An omitted rate is the provider-default 1× rate. Re-check inside the
+            // serialized operation so overlapping callers observe the preceding write.
+            const currentRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
+            if (nextRate === currentRate) {
+                return { didUpdate: false, playbackRunId };
+            }
+            await this.updateSettings({ rate: nextRate });
+            return { didUpdate: true, playbackRunId };
+        });
+        this.playbackRateWriteQueue = settingsWrite.then(() => undefined, () => undefined);
+        const operation = settingsWrite.then(async (result) => {
+            if (requestId !== this.playbackRateRequestId ||
+                result.playbackRunId !== this.speakRunId) {
+                return;
+            }
+            const activePlaybackNeedsRate = this.activePlaybackRate !== null &&
+                this.activePlaybackRate !== nextRate;
+            if (!result.didUpdate && !activePlaybackNeedsRate)
+                return;
+            if ((this.state !== PlaybackState.PLAYING &&
+                this.state !== PlaybackState.LOADING) ||
+                !this.currentText ||
+                this.seekSegments.length === 0 ||
+                this.hasExplicitBreakSemantics(this.currentText)) {
+                return;
+            }
+            await this.restartFromSeekIndex(this.getCurrentSeekSegmentIndex());
+        });
+        let trackedOperation;
+        trackedOperation = operation.finally(() => {
+            if (this.pendingPlaybackRateRequest?.promise === trackedOperation) {
+                this.pendingPlaybackRateRequest = null;
+            }
+        });
+        this.pendingPlaybackRateRequest = {
+            rate: nextRate,
+            promise: trackedOperation,
+        };
+        await trackedOperation;
     }
     async seekBy(units) {
         if (!this.provider || !this.currentText)
@@ -2015,6 +2201,7 @@ export class TTSService {
         if (!this.provider)
             return;
         this.speakRunId += 1;
+        this.clearPlaybackStartBarrier();
         this.cancelRecordedAudio();
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
@@ -2036,6 +2223,7 @@ export class TTSService {
         this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
+        this.activePlaybackRate = null;
     }
     /**
      * Request UI-level TTS controls to hand off/deactivate.

package/dist/services/ToolRegistry.d.ts

@@ -4,8 +4,7 @@
  * Central registry for all assessment tools. Manages tool metadata, visibility logic,
  * and button/instance creation. Supports dynamic registration and override by integrators.
  */
-import type { ItemEntity } from "@pie-players/pie-players-shared/types";
-import type { CatalogOwnerContext } from "./AccessibilityCatalogResolver.js";
+import type { CatalogOwnerSnapshot } from "./AccessibilityCatalogResolver.js";
 import type { ToolContext, ToolLevel } from "./tool-context.js";
 import type { ToolComponentOverrides } from "../tools/tool-tag-map.js";
 import type { AccessibilityCatalogResolverApi, ElementToolStateStoreApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi } from "./interfaces.js";
@@ -13,6 +12,13 @@ import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { ToolProviderConfig as ToolRuntimeConfig } from "./tools-config-normalizer.js";
 import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
 export type ToolModuleLoader = () => Promise<unknown>;
+export type ToolRegistryChangeKind = "register" | "override" | "unregister" | "clear" | "component-overrides" | "module-loaders";
+/** A successful mutation to discoverable or rendering registry state. */
+export interface ToolRegistryChangeEvent {
+    kind: ToolRegistryChangeKind;
+    toolIds: readonly string[];
+}
+export type ToolRegistryChangeListener = (event: ToolRegistryChangeEvent) => void;
 export interface ToolToolbarButtonDefinition {
     toolId: string;
     label: string;
@@ -178,8 +184,8 @@ export interface ToolSurfaceServices {
  * `surface` is a host-defined slot name. Core defines none and validates only
  * that a region capability claims at least one, so a host can open a new surface
  * without a change here and a capability can declare which of a host's surfaces
- * it fits. Section-player ships `"content-media"` (the media region on an item
- * or passage card) and `"section-overlay"` (the section-scoped singleton).
+ * it fits. Section-player ships `"content-lead"` and `"content-media"` on item
+ * and passage cards, plus `"section-overlay"` at section scope.
  *
  * `content` carries whatever the capability's own `requiresAuthoredContent`
  * resolved, so the host neither inspects nor names it — it hands back what the
@@ -207,11 +213,23 @@ export interface ToolContentDependencyContext {
     featureId: string;
     /** Feature parameters from the policy decision, if any. */
     parameters?: unknown;
-    catalogResolver: AccessibilityCatalogResolverApi | null;
-    /** Owner scope for catalog lookups, without `modelId`. */
-    ownerContext: CatalogOwnerContext;
-    /** The item in scope, when the host renders per item. */
-    item?: ItemEntity | null;
+    /**
+     * Owner-scoped catalog cards, or `null` when no resolver is available.
+     *
+     * The catalog module has already applied item/passage/model traversal and
+     * registration precedence. A capability interprets its own card type without
+     * reconstructing the owner scope or reading the raw entity.
+     */
+    catalogs: CatalogOwnerSnapshot | null;
+    /**
+     * Whether policy granted one of this capability's support ids.
+     *
+     * `false` reaches `resolve` only for a capability that declares
+     * {@link ToolRegistration.resolvesWithoutGrant}, and it is the signal that the
+     * capability must answer from the content alone. Everything else sees `true`,
+     * because the host asks about eligibility first and stops there.
+     */
+    granted: boolean;
 }
 /**
  * A capability's declaration that it needs authored content to have anything to
@@ -240,8 +258,8 @@ export interface ToolContentDependencyContext {
  * keeps the resolver and the host from knowing which accommodation they are
  * resolving.
  *
- * Resolvable only on a surface the host renders per item or per passage:
- * `ownerContext` names an item model or a passage, never a section, because a DRD
+ * Resolvable only on a surface the host renders per item or per passage. The
+ * owner snapshot represents an item/model or passage, never a section, because a DRD
  * resource pairs with a piece of content and not with a container. A capability
  * declaring one and claiming a section-scoped surface is declined there rather
  * than mounted with no content. `resolve` is also synchronous — a capability whose
@@ -255,9 +273,9 @@ export interface ToolContentDependency {
      * Must be JSON-serializable. A host re-resolves on every policy and catalog
      * signal and compares the answer structurally to decide whether anything moved,
      * because every resolution builds fresh objects and identity would report a
-     * change each time. A `Map`, a function or a DOM node therefore compares equal
-     * to itself across a real change and the capability never hears about it; a
-     * cyclic value throws inside the host's own reconciliation.
+     * change each time. A `Map`, function, DOM node, cyclic value, or other
+     * non-serializable result is rejected for that capability and reported as a
+     * recoverable surface warning instead of escaping into the player.
      */
     resolve(context: ToolContentDependencyContext): unknown | null;
     /**
@@ -339,6 +357,22 @@ export interface ToolRegistration {
      * {@link ToolContentDependency}.
      */
     requiresAuthoredContent?: ToolContentDependency;
+    /**
+     * Ask this capability for its content even when policy granted nothing.
+     *
+     * Only meaningful together with {@link ToolRegistration.requiresAuthoredContent},
+     * and only correct for a capability whose authored content can declare itself
+     * *presentation* rather than an accommodation — content authored to be delivered
+     * that way to everyone, which no profile grants and none revokes. Such a
+     * capability must return `null` from `resolve` when its content is the
+     * accommodation kind and the grant is absent, and the `granted` flag on the
+     * context is how it tells the two apart.
+     *
+     * Without this, "no grant" ends the question before content is consulted, which
+     * is the right default: it is what keeps an accommodation off the item of a
+     * learner with no documented need.
+     */
+    resolvesWithoutGrant?: boolean;
     /**
      * Optional provider registration metadata.
      * When present, ToolkitCoordinator can register provider(s) generically
@@ -393,6 +427,13 @@ export declare class ToolRegistry {
     private moduleLoaders;
     private loadedToolModules;
     private moduleLoadPromises;
+    private changeListeners;
+    private emitChange;
+    /**
+     * Observe successful registry mutations. Delivery is synchronous, listener
+     * failures are isolated, and the returned unsubscribe is idempotent.
+     */
+    onRegistryChange(listener: ToolRegistryChangeListener): () => void;
     /**
      * Normalize a single tool alias to canonical toolId.
      */

package/dist/services/ToolRegistry.js

@@ -93,6 +93,17 @@ function assertToolRegistrationShape(registration) {
     if (isRegion && typeof registration.renderSurface !== "function") {
         throw new Error(`Invalid tool registration "${registration.toolId}": region tools must implement "renderSurface".`);
     }
+    if (registration.resolvesWithoutGrant !== undefined &&
+        typeof registration.resolvesWithoutGrant !== "boolean") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "resolvesWithoutGrant" must be a boolean.`);
+    }
+    if (registration.resolvesWithoutGrant &&
+        !registration.requiresAuthoredContent) {
+        // The flag only decides whether content is consulted without a grant, so on a
+        // capability with no content dependency it reads as "granted to everyone" and
+        // does nothing at all.
+        throw new Error(`Invalid tool registration "${registration.toolId}": "resolvesWithoutGrant" requires "requiresAuthoredContent".`);
+    }
     if (registration.renderSurface !== undefined &&
         typeof registration.renderSurface !== "function") {
         throw new Error(`Invalid tool registration "${registration.toolId}": "renderSurface" must be a function.`);
@@ -157,6 +168,31 @@ export class ToolRegistry {
     moduleLoaders = new Map();
     loadedToolModules = new Set();
     moduleLoadPromises = new Map();
+    changeListeners = new Set();
+    emitChange(event) {
+        for (const listener of this.changeListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.warn("[ToolRegistry] change listener failed:", error);
+            }
+        }
+    }
+    /**
+     * Observe successful registry mutations. Delivery is synchronous, listener
+     * failures are isolated, and the returned unsubscribe is idempotent.
+     */
+    onRegistryChange(listener) {
+        this.changeListeners.add(listener);
+        let subscribed = true;
+        return () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            this.changeListeners.delete(listener);
+        };
+    }
     /**
      * Normalize a single tool alias to canonical toolId.
      */
@@ -190,6 +226,7 @@ export class ToolRegistry {
                 this.pnpIndex.get(pnpId).add(registration.toolId);
             }
         }
+        this.emitChange({ kind: "register", toolIds: [registration.toolId] });
     }
     /**
      * Override an existing tool registration
@@ -219,6 +256,7 @@ export class ToolRegistry {
                 this.pnpIndex.get(pnpId).add(registration.toolId);
             }
         }
+        this.emitChange({ kind: "override", toolIds: [registration.toolId] });
     }
     /**
      * Unregister a tool
@@ -236,6 +274,7 @@ export class ToolRegistry {
             }
         }
         this.tools.delete(toolId);
+        this.emitChange({ kind: "unregister", toolIds: [toolId] });
     }
     /**
      * Get a tool registration by ID
@@ -416,28 +455,43 @@ export class ToolRegistry {
      * Clear all registrations (useful for testing)
      */
     clear() {
+        const toolIds = this.getAllToolIds();
+        if (toolIds.length === 0)
+            return;
         this.tools.clear();
         this.pnpIndex.clear();
+        this.emitChange({ kind: "clear", toolIds });
     }
     /**
      * Configure global component overrides used by tool instance creation.
      */
     setComponentOverrides(overrides) {
+        if (this.componentOverrides === overrides)
+            return;
         this.componentOverrides = overrides;
+        this.emitChange({ kind: "component-overrides", toolIds: [] });
     }
     /**
      * Register lazy module loaders by toolId.
      * Toolbars call ensureToolModuleLoaded(toolId) before instance creation.
      */
     setToolModuleLoaders(loaders) {
-        for (const [toolId, loader] of Object.entries(loaders)) {
-            if (!loader)
-                continue;
+        const entries = Object.entries(loaders).filter((entry) => entry[1] !== undefined);
+        for (const [toolId, loader] of entries) {
             assertNonEmptyString(toolId, "tool module loader id");
             if (typeof loader !== "function") {
                 throw new Error(`Invalid tool module loader for "${toolId}": expected a function.`);
             }
+        }
+        const changedToolIds = [];
+        for (const [toolId, loader] of entries) {
+            if (this.moduleLoaders.get(toolId) === loader)
+                continue;
             this.moduleLoaders.set(toolId, loader);
+            changedToolIds.push(toolId);
+        }
+        if (changedToolIds.length > 0) {
+            this.emitChange({ kind: "module-loaders", toolIds: changedToolIds });
         }
     }
     /**