@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.74

package/dist/runtime/adapter/SectionEngineAdapter.d.ts

@@ -39,9 +39,9 @@
  * `scripts/check-engine-core-purity.mjs` enforce the core's purity;
  * the adapter follows the same constraint by convention so it stays
  * usable from non-Svelte hosts (Node tests, Storybook, or future
- * non-Svelte consumers). `bun run check:custom-elements` already
- * blocks `.svelte` imports in published `dist`; adding a Svelte
- * dependency here would also leak through that gate.
+ * non-Svelte consumers). `bun run check:custom-elements:dist`
+ * already blocks `.svelte` imports in published `dist`; adding a
+ * Svelte dependency here would also leak through that gate.
  */
 import type { FrameworkErrorReporter } from "../../services/framework-error-bus.js";
 import { SectionEngineCore } from "../core/SectionEngineCore.js";

package/dist/runtime/adapter/SectionEngineAdapter.js

@@ -39,9 +39,9 @@
  * `scripts/check-engine-core-purity.mjs` enforce the core's purity;
  * the adapter follows the same constraint by convention so it stays
  * usable from non-Svelte hosts (Node tests, Storybook, or future
- * non-Svelte consumers). `bun run check:custom-elements` already
- * blocks `.svelte` imports in published `dist`; adding a Svelte
- * dependency here would also leak through that gate.
+ * non-Svelte consumers). `bun run check:custom-elements:dist`
+ * already blocks `.svelte` imports in published `dist`; adding a
+ * Svelte dependency here would also leak through that gate.
  */
 import { SectionEngineCore } from "../core/SectionEngineCore.js";
 import { createCoordinatorBridge, } from "./coordinator-bridge.js";

package/dist/runtime/registration-events.d.ts

@@ -1,3 +1,4 @@
+import type { SessionCommitReason } from "@pie-players/pie-players-shared/pie";
 import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
 export declare const PIE_REGISTER_EVENT = "pie-register";
 export declare const PIE_UNREGISTER_EVENT = "pie-unregister";
@@ -21,6 +22,8 @@ export interface ItemSessionChangedDetail {
     canonicalItemId?: string;
     session: unknown;
     sourceRuntimeId?: string;
+    /** Set when the change is a commit at a teardown, navigation or page-hidden seam. */
+    sessionCommitReason?: SessionCommitReason;
 }
 export interface InternalItemSessionChangedDetail {
     itemId: string;

package/dist/runtime/section-runtime-engine-host-context.d.ts

@@ -62,15 +62,9 @@ export declare const sectionRuntimeEngineHostContext: {
 };
 export type SectionRuntimeEngineHostContextListener = (value: SectionRuntimeEngineHostContextValue) => void;
 /**
- * Connect a DOM host to the cross-CE engine context with the same
- * provider-retry semantics used elsewhere in the toolkit (initial
- * synchronous request + `context-provider` re-request + 50 ms polling
- * fallback up to 200 attempts ≈ 10 s).
- *
- * The retry mirrors the existing
- * `connectAssessmentToolkitHostRuntimeContext` infrastructure so the
- * timing characteristics of cross-CE handshakes stay consistent across
- * the toolkit's contexts.
+ * Connect a DOM host to the cross-CE engine context through
+ * `connectContextWithRetry`, the provider-retry the toolkit's other
+ * contexts use.
  *
  * Returns a cleanup function that disconnects the consumer and clears
  * the retry interval. Standalone toolkits naturally exhaust the retry

package/dist/runtime/section-runtime-engine-host-context.js

@@ -35,7 +35,7 @@
  * breaking change. Adding optional fields to the value shape is
  * allowed; required fields are not.
  */
-import { ContextConsumer, createContext, } from "@pie-players/pie-context";
+import { connectContextWithRetry, createContext, } from "@pie-players/pie-context";
 /**
  * `pie-context` context key for the cross-CE engine bridge. Uses a
  * `Symbol.for(...)` registry key so providers and consumers in
@@ -43,15 +43,9 @@ import { ContextConsumer, createContext, } from "@pie-players/pie-context";
  */
 export const sectionRuntimeEngineHostContext = createContext(Symbol.for("pie.sectionRuntimeEngineHostContext"));
 /**
- * Connect a DOM host to the cross-CE engine context with the same
- * provider-retry semantics used elsewhere in the toolkit (initial
- * synchronous request + `context-provider` re-request + 50 ms polling
- * fallback up to 200 attempts ≈ 10 s).
- *
- * The retry mirrors the existing
- * `connectAssessmentToolkitHostRuntimeContext` infrastructure so the
- * timing characteristics of cross-CE handshakes stay consistent across
- * the toolkit's contexts.
+ * Connect a DOM host to the cross-CE engine context through
+ * `connectContextWithRetry`, the provider-retry the toolkit's other
+ * contexts use.
  *
  * Returns a cleanup function that disconnects the consumer and clears
  * the retry interval. Standalone toolkits naturally exhaust the retry
@@ -59,37 +53,5 @@ export const sectionRuntimeEngineHostContext = createContext(Symbol.for("pie.sec
  * engine — that is by design and is not an error.
  */
 export function connectSectionRuntimeEngineHostContext(host, onValue) {
-    let hasValue = false;
-    const consumer = new ContextConsumer(host, {
-        context: sectionRuntimeEngineHostContext,
-        subscribe: true,
-        onValue: (value) => {
-            hasValue = true;
-            onValue(value);
-        },
-    });
-    consumer.connect();
-    const onContextProvider = (event) => {
-        if (event.context !==
-            sectionRuntimeEngineHostContext) {
-            return;
-        }
-        consumer.requestValue();
-    };
-    host.addEventListener("context-provider", onContextProvider);
-    let attempts = 0;
-    const maxAttempts = 200;
-    const retryTimer = globalThis.setInterval(() => {
-        if (hasValue || attempts >= maxAttempts) {
-            globalThis.clearInterval(retryTimer);
-            return;
-        }
-        attempts += 1;
-        consumer.requestValue();
-    }, 50);
-    return () => {
-        globalThis.clearInterval(retryTimer);
-        host.removeEventListener("context-provider", onContextProvider);
-        consumer.disconnect();
-    };
+    return connectContextWithRetry(host, sectionRuntimeEngineHostContext, onValue);
 }

package/dist/runtime/tool-host-contract.d.ts

@@ -1,5 +1,7 @@
 import type { UnknownContext } from "@pie-players/pie-context";
 import { type RegionScopeContextListener, type RuntimeContextListener, type ShellContextListener } from "../context/runtime-context-consumer.js";
+import type { ZIndexLayer } from "../services/ToolCoordinator.js";
+import type { ToolCoordinatorApi } from "../services/interfaces.js";
 type BaseEventInit = Pick<EventInit, "bubbles" | "composed" | "cancelable">;
 /**
  * Contract helper for all toolkit/tool events that must cross custom-element boundaries.
@@ -22,6 +24,24 @@ export declare function connectToolShellContext(host: HTMLElement, onValue: Shel
  * Shared region-scope context contract for tools targeting content subregions.
  */
 export declare function connectToolRegionScopeContext(host: HTMLElement, onValue: RegionScopeContextListener): () => void;
+/** A tool's registration with the coordinator in its runtime context. */
+export interface ToolCoordinatorRegistration {
+    /**
+     * Registers `toolId` with `coordinator`, first unregistering it from the
+     * coordinator or id it was registered under. The coordinator arrives through
+     * a republished runtime context, so a new instance can replace the old one
+     * mid-session; a one-shot registration would leave z-index, `bringToFront`
+     * and visibility-restore bound to the dead one. Call it from an effect on
+     * both; it does nothing until both are set, or when neither changed.
+     */
+    sync(coordinator: ToolCoordinatorApi | null | undefined, toolId: string | null | undefined): void;
+    /**
+     * Unregisters from the coordinator the registration was made against, which
+     * is not necessarily the one currently in context.
+     */
+    release(): void;
+}
+export declare function createToolCoordinatorRegistration(name: string, layer: ZIndexLayer): ToolCoordinatorRegistration;
 /**
  * Guard utility: narrows unknown context payloads when needed by callers.
  */

package/dist/runtime/tool-host-contract.js

@@ -39,6 +39,27 @@ export function connectToolShellContext(host, onValue) {
 export function connectToolRegionScopeContext(host, onValue) {
     return connectAssessmentToolkitRegionScopeContext(host, onValue);
 }
+export function createToolCoordinatorRegistration(name, layer) {
+    let registered = null;
+    function release() {
+        registered?.coordinator.unregisterTool(registered.toolId);
+        registered = null;
+    }
+    return {
+        sync(coordinator, toolId) {
+            if (!coordinator || !toolId)
+                return;
+            if (registered?.coordinator === coordinator &&
+                registered.toolId === toolId) {
+                return;
+            }
+            release();
+            coordinator.registerTool(toolId, name, undefined, layer);
+            registered = { coordinator, toolId };
+        },
+        release,
+    };
+}
 /**
  * Guard utility: narrows unknown context payloads when needed by callers.
  */

package/dist/services/HighlightCoordinator.d.ts

@@ -51,13 +51,7 @@ export interface Annotation {
     color: HighlightColor;
     timestamp: number;
 }
-/**
- * Configuration for HighlightCoordinator
- * Currently empty but allows future extension without breaking changes
- */
-export type HighlightCoordinatorConfig = Record<string, never>;
 export declare class HighlightCoordinator implements HighlightCoordinatorApi {
-    private config;
     private ttsWordHighlight;
     private ttsSentenceHighlight;
     private ttsWordElementHighlights;
@@ -69,7 +63,7 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
     private rangeSerializer;
     private themeObserver;
     private explicitTTSColorOverride;
-    constructor(config?: HighlightCoordinatorConfig);
+    constructor();
     private setupThemeObservation;
     private parseColor;
     private relativeLuminance;

package/dist/services/HighlightCoordinator.js

@@ -43,7 +43,6 @@ export var HighlightColor;
     HighlightColor["UNDERLINE"] = "underline";
 })(HighlightColor || (HighlightColor = {}));
 export class HighlightCoordinator {
-    config;
     ttsWordHighlight = null;
     ttsSentenceHighlight = null;
     ttsWordElementHighlights = new Set();
@@ -56,8 +55,7 @@ export class HighlightCoordinator {
     rangeSerializer;
     themeObserver = null;
     explicitTTSColorOverride = null;
-    constructor(config = {}) {
-        this.config = config;
+    constructor() {
         this.rangeSerializer = new RangeSerializer();
         // SSR guard
         if (typeof CSS === "undefined" || !("highlights" in CSS)) {

package/dist/services/TTSService.d.ts

@@ -66,7 +66,6 @@ export declare class TTSService {
     private playbackChunks;
     private activeRecordedAudio;
     private sentenceHighlightSegments;
-    private currentSeekSegmentIndex;
     private activeSentenceStartOffset;
     private playbackStartDeferredRunId;
     private pendingPlaybackStartHighlights;
@@ -171,6 +170,11 @@ export declare class TTSService {
     private isElementHidden;
     private getBoundaryStrength;
     private getBoundaryAnchor;
+    /**
+     * `textOffset` is where `normalizedText` starts in the element's visible text:
+     * boundaries are collected over the whole element, and a selection speaks only
+     * part of it.
+     */
     private createSpeechPlan;
     private collectSpeechPlanBoundaries;
     private createNodeStartOffsets;
@@ -182,6 +186,11 @@ export declare class TTSService {
     private createSeekSegmentsFromSpeechChunks;
     private getCurrentSeekSegmentIndex;
     private speakWithPlan;
+    /**
+     * `startOffset` indexes the spoken text; the position map indexes the whole
+     * content element, which for a selection starts `activeWordBoundaryOffset`
+     * characters earlier.
+     */
     private highlightSentenceSegment;
     private getSegmentIndexForOffset;
     private highlightSentenceForOffset;
@@ -252,6 +261,11 @@ export declare class TTSService {
      *
      * @param range DOM Range to speak
      */
+    /**
+     * The selected part of `root`'s normalized visible text and where it starts, or
+     * null when the map is unavailable or holds no selected character.
+     */
+    private selectMappedRangeText;
     speakRange(range: Range, options?: {
         contentRoot?: Element | null;
     }): Promise<void>;

package/dist/services/TTSService.js

@@ -15,7 +15,7 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import { applyMediaFragment, enforceMediaFragment } from "./catalog-media.js";
+import { applyMediaFragment, enforceMediaFragment, } from "@pie-players/pie-players-shared/media";
 import { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
 import { resolveSpokenAudioMedia, } from "./spoken-audio-cards.js";
 import { BrowserTTSProvider } from "./tts/browser-provider.js";
@@ -95,7 +95,6 @@ export class TTSService {
     // chunk loop on a run that has already been superseded.
     activeRecordedAudio = null;
     sentenceHighlightSegments = [];
-    currentSeekSegmentIndex = 0;
     activeSentenceStartOffset = null;
     playbackStartDeferredRunId = null;
     pendingPlaybackStartHighlights = [];
@@ -675,9 +674,21 @@ export class TTSService {
             units: this.getStructuralPauseProfile().units[strength],
         };
     }
-    createSpeechPlan(contentElement, normalizedText) {
+    /**
+     * `textOffset` is where `normalizedText` starts in the element's visible text:
+     * boundaries are collected over the whole element, and a selection speaks only
+     * part of it.
+     */
+    createSpeechPlan(contentElement, normalizedText, textOffset = 0) {
         const boundaries = this.collectSpeechPlanBoundaries(contentElement, normalizedText);
-        return this.createSpeechPlanSegments(normalizedText, boundaries);
+        if (textOffset === 0) {
+            return this.createSpeechPlanSegments(normalizedText, boundaries);
+        }
+        const shifted = new Map();
+        for (const [point, units] of boundaries) {
+            shifted.set(point - textOffset, units);
+        }
+        return this.createSpeechPlanSegments(normalizedText, shifted);
     }
     collectSpeechPlanBoundaries(contentElement, normalizedText) {
         const boundaries = new Map();
@@ -858,7 +869,6 @@ export class TTSService {
                 originalOnWordBoundary?.(word, position, length);
                 if (Number.isFinite(position)) {
                     this.currentBoundaryOffset = position;
-                    this.currentSeekSegmentIndex = this.getCurrentSeekSegmentIndex();
                 }
             };
             try {
@@ -878,10 +888,6 @@ export class TTSService {
         for (const segment of segments) {
             if (runId !== this.speakRunId)
                 return;
-            const seekIndex = this.seekSegments.findIndex((candidate) => candidate.startOffset === segment.startOffset);
-            if (seekIndex >= 0) {
-                this.currentSeekSegmentIndex = seekIndex;
-            }
             this.currentBoundaryOffset = segment.startOffset;
             if (shouldTrackSentenceProgress) {
                 this.runWhenPlaybackStarts(runId, () => {
@@ -895,14 +901,20 @@ export class TTSService {
             }
         }
     }
+    /**
+     * `startOffset` indexes the spoken text; the position map indexes the whole
+     * content element, which for a selection starts `activeWordBoundaryOffset`
+     * characters earlier.
+     */
     highlightSentenceSegment(startOffset, text) {
         if (!this.highlightCoordinator || typeof document === "undefined")
             return;
         const length = text.trimEnd().length;
         if (length <= 0)
             return;
-        const start = this.normalizedToDOM.get(startOffset);
-        const end = this.normalizedToDOM.get(startOffset + length - 1);
+        const mapStart = startOffset + this.activeWordBoundaryOffset;
+        const start = this.normalizedToDOM.get(mapStart);
+        const end = this.normalizedToDOM.get(mapStart + length - 1);
         if (!start || !end)
             return;
         const range = document.createRange();
@@ -1030,7 +1042,7 @@ export class TTSService {
                 : hasExplicitBreaks || !speechMatchesVisibleText
                     ? []
                     : shouldUsePlan && this.currentContentElement
-                        ? this.createSpeechPlan(this.currentContentElement, normalizedText)
+                        ? this.createSpeechPlan(this.currentContentElement, normalizedText, options?.wordBoundaryOffset || 0)
                         : this.createSeekSegmentsFromText(highlightText);
             this.sentenceHighlightSegments = hasExplicitBreaks
                 ? []
@@ -1520,7 +1532,6 @@ export class TTSService {
         this.lastError = null;
         this.currentBoundaryOffset = 0;
         this.playbackChunks = [];
-        this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
     }
     prepareHighlightsForSpeak(args) {
@@ -1559,8 +1570,9 @@ export class TTSService {
         // or ServerTTSProvider time-scaled onWordBoundary).
         this.provider.onWordBoundary = (word, charIndex, length) => {
             const wordLength = length || word.length;
-            const globalIndex = charIndex + this.currentBoundaryOffset + args.wordBoundaryOffset;
-            this.highlightSentenceForOffset(globalIndex);
+            const spokenIndex = charIndex + this.currentBoundaryOffset;
+            const globalIndex = spokenIndex + args.wordBoundaryOffset;
+            this.highlightSentenceForOffset(spokenIndex);
             const highlightRange = this.findHighlightRange(globalIndex, wordLength);
             if (highlightRange && this.highlightCoordinator) {
                 const highlightText = highlightRange.node.textContent?.substring(highlightRange.start, highlightRange.end) || "";
@@ -1907,7 +1919,6 @@ export class TTSService {
             for (let index = 0; index < args.speechChunks.length; index++) {
                 if (args.runId !== this.speakRunId)
                     return;
-                this.currentSeekSegmentIndex = index;
                 const segment = this.seekSegments[index];
                 if (segment) {
                     this.currentBoundaryOffset = segment.startOffset;
@@ -1947,7 +1958,6 @@ export class TTSService {
         this.seekSegments = [];
         this.playbackChunks = [];
         this.sentenceHighlightSegments = [];
-        this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
     }
     /**
@@ -1958,6 +1968,42 @@ export class TTSService {
      *
      * @param range DOM Range to speak
      */
+    /**
+     * The selected part of `root`'s normalized visible text and where it starts, or
+     * null when the map is unavailable or holds no selected character.
+     */
+    selectMappedRangeText(range, root) {
+        if (typeof range.comparePoint !== "function")
+            return null;
+        const { text: rootText, map } = collectVisibleTextAndMap(root, this.getTextProcessingOptions());
+        let start = -1;
+        let end = -1;
+        for (const [index, { node, offset }] of map) {
+            if (index >= rootText.length)
+                continue;
+            let inside = false;
+            try {
+                inside =
+                    range.comparePoint(node, offset) === 0 &&
+                        range.comparePoint(node, Math.min(offset + 1, node.length)) === 0;
+            }
+            catch {
+                inside = false;
+            }
+            if (!inside)
+                continue;
+            if (start === -1 || index < start)
+                start = index;
+            if (index > end)
+                end = index;
+        }
+        if (start === -1)
+            return null;
+        const raw = rootText.slice(start, end + 1);
+        const leading = raw.length - raw.trimStart().length;
+        const text = raw.trim();
+        return text ? { text, offset: start + leading } : null;
+    }
     async speakRange(range, options) {
         if (!this.provider) {
             throw new Error("TTS service not initialized");
@@ -1983,28 +2029,38 @@ export class TTSService {
         if (!root)
             return;
         const selected = collectRangeTextForSpeech(range, root);
-        const text = selected.text.trim();
-        if (!text) {
+        const selectedText = selected.text.trim();
+        if (!selectedText) {
             if (selected.filtered) {
                 console.warn("[tts] every part of the selection is either hidden or marked not-to-be-spoken; nothing was spoken.");
             }
             return;
         }
-        // Calculate the offset of the range start within the root element. Filtered
-        // the same way as the speech itself: the offset indexes into the highlight
-        // text, which comes from the exclusion-aware collectors, so counting
-        // characters here that never reach that text would shift every highlight
-        // after the excluded node.
-        const beforeRange = document.createRange();
-        beforeRange.selectNodeContents(root);
-        beforeRange.setEnd(range.startContainer, range.startOffset);
-        const textBeforeRange = collectRangeTextForSpeech(beforeRange, root).text;
-        const normalizedTextBeforeRange = normalizeTextForSpeech(textBeforeRange);
-        const offset = normalizedTextBeforeRange.length +
-            (/\s$/.test(textBeforeRange) && normalizedTextBeforeRange ? 1 : 0);
+        // The spoken text and its offset come from the root's visible-text map, which
+        // the highlight position map and the structural speech plan index too. Joined
+        // from raw text nodes instead, a selection loses the space the map inserts
+        // between blocks, and every offset after that boundary drifts.
+        const mapped = this.selectMappedRangeText(range, root);
+        let text = selectedText;
+        let offset = mapped?.offset ?? 0;
+        if (mapped) {
+            text = mapped.text;
+        }
+        else {
+            // Filtered the same way as the speech itself: the offset indexes into the
+            // highlight text, which comes from the exclusion-aware collectors.
+            const beforeRange = document.createRange();
+            beforeRange.selectNodeContents(root);
+            beforeRange.setEnd(range.startContainer, range.startOffset);
+            const textBeforeRange = collectRangeTextForSpeech(beforeRange, root).text;
+            const normalizedTextBeforeRange = normalizeTextForSpeech(textBeforeRange);
+            offset =
+                normalizedTextBeforeRange.length +
+                    (/\s$/.test(textBeforeRange) && normalizedTextBeforeRange ? 1 : 0);
+        }
         this.debugLog("[TTSService] speakRange offset calculation:", {
             selectedText: text,
-            textBeforeRange: textBeforeRange.substring(0, 100),
+            mapped: !!mapped,
             offset,
             rootTag: root.tagName,
         });
@@ -2058,7 +2114,6 @@ export class TTSService {
         this.cancelRecordedAudio();
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
-        this.currentSeekSegmentIndex = safeTargetIndex;
         const runId = ++this.speakRunId;
         const restartSegments = this.seekSegments.slice(safeTargetIndex);
         this.highlightCoordinator?.clearTTS();
@@ -2079,7 +2134,6 @@ export class TTSService {
                     if (runId !== this.speakRunId)
                         return;
                     const absoluteIndex = safeTargetIndex + index;
-                    this.currentSeekSegmentIndex = absoluteIndex;
                     const segment = this.seekSegments[absoluteIndex];
                     if (segment) {
                         this.currentBoundaryOffset = segment.startOffset;
@@ -2222,7 +2276,6 @@ export class TTSService {
         this.seekSegments = [];
         this.playbackChunks = [];
         this.sentenceHighlightSegments = [];
-        this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
         this.activePlaybackRate = null;
     }

package/dist/services/ToolCoordinator.d.ts

@@ -23,13 +23,7 @@ export declare enum ZIndexLayer {
     CONTROL = 3000,// Drag handles, resize controls (3000-3999)
     HIGHLIGHT = 4000
 }
-/**
- * Configuration for ToolCoordinator
- * Currently empty but allows future extension without breaking changes
- */
-export type ToolCoordinatorConfig = Record<string, never>;
 export declare class ToolCoordinator implements ToolCoordinatorApi {
-    private config;
     private tools;
     private layerCounters;
     private listeners;
@@ -42,7 +36,7 @@ export declare class ToolCoordinator implements ToolCoordinatorApi {
      * Cleared on genuine teardown via {@link releaseTool}.
      */
     private visibilityState;
-    constructor(config?: ToolCoordinatorConfig);
+    constructor();
     /**
      * Subscribe to tool state changes
      * Returns unsubscribe function

package/dist/services/ToolCoordinator.js

@@ -26,7 +26,6 @@ export var ZIndexLayer;
     ZIndexLayer[ZIndexLayer["HIGHLIGHT"] = 4000] = "HIGHLIGHT";
 })(ZIndexLayer || (ZIndexLayer = {}));
 export class ToolCoordinator {
-    config;
     tools = new Map();
     layerCounters = new Map();
     listeners = new Set();
@@ -39,8 +38,7 @@ export class ToolCoordinator {
      * Cleared on genuine teardown via {@link releaseTool}.
      */
     visibilityState = new Map();
-    constructor(config = {}) {
-        this.config = config;
+    constructor() {
         // Initialize layer counters
         this.layerCounters.set(ZIndexLayer.BASE, 0);
         this.layerCounters.set(ZIndexLayer.TOOL, 0);

package/dist/services/ToolRegistry.d.ts

@@ -24,8 +24,8 @@ export interface ToolToolbarButtonDefinition {
     toolId: string;
     label: string;
     /**
-     * Optional to match what the renderers already do: `ToolButton.svelte` and
-     * `ItemToolBar.svelte` both guard on `button.icon`, and `ToolbarItem.icon` is
+     * Optional to match what the renderer already does: `ItemToolBar.svelte`
+     * guards on `button.icon`, and `ToolbarItem.icon` is
      * already optional, so requiring it here claimed a guarantee nothing relied
      * on. A registration that renders a button still has to declare an icon —
      * `assertToolRegistrationShape` enforces that.
@@ -216,6 +216,15 @@ export interface ToolProviderDescriptor {
     getAuthFetcher?: (config: ToolRuntimeConfig | undefined) => (() => Promise<Record<string, unknown>>) | undefined;
     lazy?: boolean;
 }
+/**
+ * The id a registration's provider registers under for one tool config: the
+ * descriptor's answer, then the config's `provider.id`, then the tool id. `null`
+ * when the registration carries no provider.
+ *
+ * The coordinator registers providers under this id and the section player looks
+ * for them in a host-supplied coordinator by it, so the two resolve it one way.
+ */
+export declare function resolveToolProviderId(registration: Pick<ToolRegistration, "toolId" | "provider">, config: ToolRuntimeConfig | undefined): string | null;
 export interface ToolToolbarRenderResult {
     toolId: string;
     elements?: ToolRenderElement[];
@@ -230,12 +239,10 @@ export interface ToolToolbarRenderResult {
  * falls back to `name` rather than rendering the key, so a catalog gap degrades
  * to English instead of to `tools.something.name` on a toolbar button.
  *
- * Both display resolvers live here so the toolbars, the settings panels and the
- * PNP debugger cannot each invent their own precedence.
+ * It lives here so the toolbars, the settings panels and the PNP debugger
+ * cannot each invent their own precedence.
  */
 export declare function resolveToolRegistrationName(registration: Pick<ToolRegistration, "name" | "nameKey">, i18n?: I18nProvider): string;
-/** A registration's description in the interface locale. See the name resolver. */
-export declare function resolveToolRegistrationDescription(registration: Pick<ToolRegistration, "description" | "descriptionKey">, i18n?: I18nProvider): string;
 export type ToolActivation = "toolbar-toggle" | "selection-gateway" | "region";
 export type ToolSingletonScope = "section";
 /**

package/dist/services/ToolRegistry.js

@@ -6,6 +6,22 @@
  */
 import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
 import { normalizeToolAlias } from "./tools-config-normalizer.js";
+/**
+ * The id a registration's provider registers under for one tool config: the
+ * descriptor's answer, then the config's `provider.id`, then the tool id. `null`
+ * when the registration carries no provider.
+ *
+ * The coordinator registers providers under this id and the section player looks
+ * for them in a host-supplied coordinator by it, so the two resolve it one way.
+ */
+export function resolveToolProviderId(registration, config) {
+    const descriptor = registration.provider;
+    if (!descriptor)
+        return null;
+    return (descriptor.getProviderId?.(config) ??
+        config?.provider?.id ??
+        registration.toolId);
+}
 /**
  * A registration's display name in the interface locale.
  *
@@ -13,16 +29,12 @@ import { normalizeToolAlias } from "./tools-config-normalizer.js";
  * falls back to `name` rather than rendering the key, so a catalog gap degrades
  * to English instead of to `tools.something.name` on a toolbar button.
  *
- * Both display resolvers live here so the toolbars, the settings panels and the
- * PNP debugger cannot each invent their own precedence.
+ * It lives here so the toolbars, the settings panels and the PNP debugger
+ * cannot each invent their own precedence.
  */
 export function resolveToolRegistrationName(registration, i18n) {
     return resolveKeyedString(registration.name, registration.nameKey, i18n);
 }
-/** A registration's description in the interface locale. See the name resolver. */
-export function resolveToolRegistrationDescription(registration, i18n) {
-    return resolveKeyedString(registration.description, registration.descriptionKey, i18n);
-}
 function resolveKeyedString(source, key, i18n) {
     if (!key || !i18n)
         return source;
@@ -50,7 +62,7 @@ function assertNonEmptyString(value, fieldName) {
 }
 // Defence-in-depth: reject obvious XSS payloads in tool-registered icon
 // markup at registration time. Runtime rendering still runs each icon
-// through DOMPurify (see `ToolIcon.svelte`), but surfacing the problem
+// through DOMPurify (`sanitizeSvgIcon` in `ItemToolBar.svelte`), but surfacing the problem
 // early produces a clearer error for tool authors than "the icon silently
 // disappeared after sanitization".
 const SCRIPTABLE_ICON_PATTERNS = [