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

package/dist/runtime/shell-scope.js

@@ -0,0 +1,188 @@
+import { ContextProvider, } from "@pie-players/pie-context";
+import { assessmentToolkitRegionScopeContext, assessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
+import { catalogSourceSignature, } from "../services/catalog-owner.js";
+import { PIE_INTERNAL_CONTENT_LOADED_EVENT } from "./registration-events.js";
+import { createShellRegistrationDispatcher, shellEventTarget, } from "./shell-registration.js";
+import { connectHostRuntimeContext, dispatchCrossBoundaryEvent, } from "./tool-host-contract.js";
+/**
+ * The newest events kept until a runtime answers; an older one is dropped. A
+ * scope in plain mode sends only load and error events, a section shell its
+ * session events too.
+ */
+const MAX_HELD_SHELL_EVENTS = 50;
+function provide(host, context, value) {
+    const provider = new ContextProvider(host, { context, initialValue: value });
+    provider.connect();
+    return { provider, value };
+}
+function republish(provided, value, same) {
+    if (same(provided.value, value))
+        return;
+    provided.value = value;
+    provided.provider.setValue(value);
+}
+const sameItem = (a, b, kind) => {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.id !== b.id)
+        return false;
+    const catalogs = catalogSourceSignature(a, kind);
+    return (catalogs !== null &&
+        catalogs === catalogSourceSignature(b, kind));
+};
+const sameShellContext = (a, b) => a.kind === b.kind &&
+    a.itemId === b.itemId &&
+    a.canonicalItemId === b.canonicalItemId &&
+    a.contentKind === b.contentKind &&
+    a.regionPolicy === b.regionPolicy &&
+    a.scopeElement === b.scopeElement &&
+    sameItem(a.item, b.item, a.kind);
+const sameRegionScope = (a, b) => a.scopeElement === b.scopeElement &&
+    a.ttsHighlightTargetResolver === b.ttsHighlightTargetResolver;
+const setAttributeIfChanged = (host, name, value) => {
+    if (host.getAttribute(name) !== value)
+        host.setAttribute(name, value);
+};
+/**
+ * A shell's publication of its content: the identity, as the shell context the
+ * tools inside it read, the region they act on, as the region scope, and the
+ * content itself, registered with the runtime, which files its accessibility
+ * catalogs under it. The section player's item and passage shells and
+ * `<pie-item-scope>` all publish through this, so a tool resolves its target
+ * and its catalogs the same way inside any of them.
+ *
+ * Content republished unchanged arrives as a new object, the composition being
+ * deep reactive state, so items compare by id and catalogs, the measure the
+ * registration applies.
+ *
+ * The registration waits for the runtime the shell sits in to answer through
+ * `assessmentToolkitHostRuntimeContext`, and carries that runtime's id, which
+ * the runtime claims it by. A shell mounted before its toolkit, which a host
+ * composing the elements itself can do, would otherwise register with no one
+ * listening, and nothing replays a registration. The document's context root
+ * replays the request instead, once the toolkit's provider connects. A
+ * different runtime answering later, a nearer toolkit taking over, moves the
+ * registration: the old runtime is told to unregister by its id, and the new
+ * one gets the registration and the content's last load, which only the old
+ * one heard.
+ */
+export function createShellScope() {
+    const registration = createShellRegistrationDispatcher();
+    const contextVersion = Date.now();
+    let host = null;
+    let shell = null;
+    let region = null;
+    let stopFindingRuntime = null;
+    let runtime = null;
+    let identity = null;
+    let held = [];
+    let loaded = null;
+    const syncRegistration = () => {
+        if (runtime !== null)
+            registration.sync(identity, runtime);
+    };
+    function send(type, detail) {
+        if (type === PIE_INTERNAL_CONTENT_LOADED_EVENT)
+            loaded = detail;
+        if (host && runtime !== null) {
+            dispatchCrossBoundaryEvent(shellEventTarget(host, runtime), type, {
+                ...detail,
+                runtimeId: runtime.runtimeId,
+            });
+            return;
+        }
+        held.push({ type, detail });
+        if (held.length > MAX_HELD_SHELL_EVENTS)
+            held.shift();
+    }
+    // The subscription re-answers whenever the runtime republishes its context,
+    // so only a different id means anything here.
+    function onRuntime(value) {
+        if (value.runtimeId === runtime?.runtimeId)
+            return;
+        const moved = runtime !== null;
+        runtime = { runtimeId: value.runtimeId, eventTarget: value.eventTarget };
+        syncRegistration();
+        const pending = held;
+        held = [];
+        for (const event of pending)
+            send(event.type, event.detail);
+        if (moved && loaded)
+            send(PIE_INTERNAL_CONTENT_LOADED_EVENT, loaded);
+    }
+    function disconnect() {
+        for (const provided of [shell, region])
+            provided?.provider.disconnect();
+        stopFindingRuntime?.();
+        stopFindingRuntime = null;
+        runtime = null;
+        held = [];
+        loaded = null;
+        identity = null;
+        shell = null;
+        region = null;
+        host = null;
+    }
+    function publish(state) {
+        if (!state) {
+            registration.sync(null);
+            disconnect();
+            return;
+        }
+        if (state.host !== host)
+            disconnect();
+        host = state.host;
+        const canonicalItemId = state.canonicalItemId || state.itemId;
+        const regionPolicy = state.regionPolicy || "default";
+        const scopeElement = state.scopeElement || state.host;
+        const shellValue = {
+            kind: state.kind,
+            itemId: state.itemId,
+            canonicalItemId,
+            contentKind: state.contentKind,
+            regionPolicy,
+            scopeElement,
+            item: state.item ?? null,
+            contextVersion,
+        };
+        if (shell)
+            republish(shell, shellValue, sameShellContext);
+        else
+            shell = provide(host, assessmentToolkitShellContext, shellValue);
+        const regionValue = {
+            scopeElement,
+            ttsHighlightTargetResolver: state.ttsHighlightTargetResolver ?? null,
+        };
+        if (region)
+            republish(region, regionValue, sameRegionScope);
+        else
+            region = provide(host, assessmentToolkitRegionScopeContext, regionValue);
+        setAttributeIfChanged(host, "data-item-id", state.itemId);
+        setAttributeIfChanged(host, "data-canonical-item-id", canonicalItemId);
+        setAttributeIfChanged(host, "data-pie-shell-root", state.kind);
+        setAttributeIfChanged(host, "data-region-policy", regionPolicy);
+        const previousIdentity = identity;
+        identity = state.itemId
+            ? {
+                kind: state.kind,
+                host,
+                itemId: state.itemId,
+                canonicalItemId,
+                contentKind: state.contentKind,
+                item: state.item ?? null,
+                settings: state.settings ?? null,
+            }
+            : null;
+        if (previousIdentity &&
+            (previousIdentity.itemId !== identity?.itemId ||
+                previousIdentity.canonicalItemId !== identity?.canonicalItemId)) {
+            loaded = null;
+        }
+        // Answers at once when the runtime is already there.
+        stopFindingRuntime ??= connectHostRuntimeContext(host, onRuntime);
+        syncRegistration();
+    }
+    return { publish, retire: registration.retire, disconnect, send };
+}

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

@@ -1,5 +1,6 @@
-import type { UnknownContext } from "@pie-players/pie-context";
-import { type RegionScopeContextListener, type RuntimeContextListener, type ShellContextListener } from "../context/runtime-context-consumer.js";
+import { type AssessmentToolkitHostRuntimeContext, type AssessmentToolkitRegionScopeContext, type AssessmentToolkitRuntimeContext, type AssessmentToolkitShellContext } from "../context/assessment-toolkit-context.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.
@@ -11,19 +12,36 @@ export declare function createCrossBoundaryEvent<T>(name: string, detail: T, ini
 export declare function dispatchCrossBoundaryEvent<T>(target: EventTarget, name: string, detail: T, init?: Partial<BaseEventInit>): boolean;
 /**
  * Shared runtime-context connection contract for tools and shells.
- * Uses retry + provider announcements so late providers are tolerated.
+ * A provider that connects after the tool answers it through the document's
+ * context root.
  */
-export declare function connectToolRuntimeContext(host: HTMLElement, onValue: RuntimeContextListener): () => void;
+export declare function connectToolRuntimeContext(host: HTMLElement, onValue: (value: AssessmentToolkitRuntimeContext) => void): () => void;
 /**
  * Shared shell-context connection contract for tools needing item/passage scope.
  */
-export declare function connectToolShellContext(host: HTMLElement, onValue: ShellContextListener): () => void;
+export declare function connectToolShellContext(host: HTMLElement, onValue: (value: AssessmentToolkitShellContext) => void): () => void;
 /**
  * Shared region-scope context contract for tools targeting content subregions.
  */
-export declare function connectToolRegionScopeContext(host: HTMLElement, onValue: RegionScopeContextListener): () => void;
-/**
- * Guard utility: narrows unknown context payloads when needed by callers.
- */
-export declare function isContextValueDefined<T extends UnknownContext>(value: unknown): value is T["__context__"];
+export declare function connectToolRegionScopeContext(host: HTMLElement, onValue: (value: AssessmentToolkitRegionScopeContext) => void): () => void;
+/** Connects a shell or toolkit element to the host runtime context above it. */
+export declare function connectHostRuntimeContext(host: HTMLElement, onValue: (value: AssessmentToolkitHostRuntimeContext) => void): () => 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;
 export {};

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

@@ -1,4 +1,5 @@
-import { connectAssessmentToolkitRegionScopeContext, connectAssessmentToolkitRuntimeContext, connectAssessmentToolkitShellContext, } from "../context/runtime-context-consumer.js";
+import { connectContextWithRetry } from "@pie-players/pie-context";
+import { assessmentToolkitHostRuntimeContext, assessmentToolkitRegionScopeContext, assessmentToolkitRuntimeContext, assessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
 const CROSS_BOUNDARY_EVENT_INIT = {
     bubbles: true,
     composed: true,
@@ -22,26 +23,46 @@ export function dispatchCrossBoundaryEvent(target, name, detail, init = {}) {
 }
 /**
  * Shared runtime-context connection contract for tools and shells.
- * Uses retry + provider announcements so late providers are tolerated.
+ * A provider that connects after the tool answers it through the document's
+ * context root.
  */
 export function connectToolRuntimeContext(host, onValue) {
-    return connectAssessmentToolkitRuntimeContext(host, onValue);
+    return connectContextWithRetry(host, assessmentToolkitRuntimeContext, onValue);
 }
 /**
  * Shared shell-context connection contract for tools needing item/passage scope.
  */
 export function connectToolShellContext(host, onValue) {
-    return connectAssessmentToolkitShellContext(host, onValue);
+    return connectContextWithRetry(host, assessmentToolkitShellContext, onValue);
 }
 /**
  * Shared region-scope context contract for tools targeting content subregions.
  */
 export function connectToolRegionScopeContext(host, onValue) {
-    return connectAssessmentToolkitRegionScopeContext(host, onValue);
+    return connectContextWithRetry(host, assessmentToolkitRegionScopeContext, onValue);
 }
-/**
- * Guard utility: narrows unknown context payloads when needed by callers.
- */
-export function isContextValueDefined(value) {
-    return value !== null && value !== undefined;
+/** Connects a shell or toolkit element to the host runtime context above it. */
+export function connectHostRuntimeContext(host, onValue) {
+    return connectContextWithRetry(host, assessmentToolkitHostRuntimeContext, 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,
+    };
 }

package/dist/runtime/unclaimed-registration-watch.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A toolkit stops every registration it claims, so one that reaches the
+ * document went unclaimed: its item's catalogs are not filed and it does not
+ * count toward its section's loading. Installed from a toolkit's host at
+ * connect, once per document across every copy of the toolkit.
+ */
+export declare function watchForUnclaimedRegistrations(doc: Document | null | undefined): void;

package/dist/runtime/unclaimed-registration-watch.js

@@ -0,0 +1,23 @@
+import { warnOncePerDocument } from "./page-warnings.js";
+import { PIE_REGISTER_EVENT, } from "./registration-events.js";
+/**
+ * A toolkit stops every registration it claims, so one that reaches the
+ * document went unclaimed: its item's catalogs are not filed and it does not
+ * count toward its section's loading. Installed from a toolkit's host at
+ * connect, once per document across every copy of the toolkit.
+ */
+export function watchForUnclaimedRegistrations(doc) {
+    if (!doc)
+        return;
+    const slot = Symbol.for("pie.assessmentToolkit.unclaimedRegistrationWatch");
+    const slots = doc;
+    if (slots[slot])
+        return;
+    slots[slot] = true;
+    doc.addEventListener(PIE_REGISTER_EVENT, (event) => {
+        const detail = event
+            .detail;
+        const itemId = typeof detail?.itemId === "string" ? detail.itemId : "";
+        warnOncePerDocument(doc, "unclaimedRegistration", `[pie-assessment-toolkit] Item "${itemId}" registered, but no toolkit claimed the registration, so its accessibility catalogs are not filed and it does not count toward its section's loading. Render its shell or scope inside the <pie-assessment-toolkit> that answered it. Reported once per page.`);
+    });
+}

package/dist/services/ElementToolStateStore.d.ts

@@ -25,7 +25,9 @@ export declare class ElementToolStateStore {
     private onStateChange;
     /**
      * Generates a globally unique element ID by combining assessment, section, item, and element IDs.
-     * Format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`
+     * Format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`, each part with
+     * `%` written as `%25` and `:` as `%3A`, so an id containing `:` round-trips
+     * and cannot collide with another split of the same characters.
      *
      * @example
      * getGlobalElementId('demo-assessment', 'section-1', 'q1', 'mc1')
@@ -48,7 +50,7 @@ export declare class ElementToolStateStore {
      * @param toolId Tool identifier (e.g., 'answerEliminator', 'flagging')
      * @param state Tool-specific state object
      */
-    setState(globalElementId: string, toolId: string, state: any): void;
+    setState(globalElementId: string, toolId: string, state: unknown): void;
     /**
      * Gets tool state for a specific element.
      *
@@ -56,29 +58,30 @@ export declare class ElementToolStateStore {
      * @param toolId Tool identifier
      * @returns Tool state or undefined if not found
      */
-    getState(globalElementId: string, toolId: string): any | undefined;
+    getState(globalElementId: string, toolId: string): unknown;
     /**
      * Gets all tool states for a specific element.
      *
      * @param globalElementId Composite key identifying the element
      * @returns Object with tool states keyed by toolId
      */
-    getElementState(globalElementId: string): Record<string, any>;
+    getElementState(globalElementId: string): Record<string, unknown>;
     /**
      * Gets all tool states for all elements.
      * Used for persistence and debugging.
      *
      * @returns Nested object: { globalElementId: { toolId: state } }
      */
-    getAllState(): Record<string, Record<string, any>>;
+    getAllState(): Record<string, Record<string, unknown>>;
     /**
      * Subscribes to state changes.
-     * Callback is invoked whenever any element's tool state changes.
+     * Callback is invoked whenever any element's tool state changes, including
+     * a `loadState` restore, with a copy of the state that it may keep.
      *
      * @param callback Function to call on state changes
      * @returns Unsubscribe function
      */
-    subscribe(callback: (state: Map<string, Map<string, any>>) => void): () => void;
+    subscribe(callback: (state: Map<string, Map<string, unknown>>) => void): () => void;
     private _notifyListeners;
     /**
      * Sets a callback to be invoked on state changes for persistence integration.
@@ -86,15 +89,16 @@ export declare class ElementToolStateStore {
      *
      * @param callback Function to call with serialized state on changes
      */
-    setOnStateChange(callback: (state: Record<string, Record<string, any>>) => void): void;
+    setOnStateChange(callback: (state: Record<string, Record<string, unknown>>) => void): void;
     private _notifyStateChange;
     /**
      * Loads tool state from serialized format.
-     * Used to restore state from localStorage or server.
+     * Used to restore state from localStorage or server. Subscribers are
+     * notified; the persistence callback is not, so a restore never writes back.
      *
      * @param state Serialized state object
      */
-    loadState(state: Record<string, Record<string, any>>): void;
+    loadState(state: Record<string, Record<string, unknown>>): void;
     /**
      * Clears all tool state for a specific element.
      *

package/dist/services/ElementToolStateStore.js

@@ -13,20 +13,30 @@
  * - Optional persistence callback integration
  * - Generic solution for any tool
  */
+function escapeIdPart(part) {
+    return part.replace(/%/g, "%25").replace(/:/g, "%3A");
+}
+function unescapeIdPart(part) {
+    return part.replace(/%(25|3A)/g, (_, code) => (code === "25" ? "%" : ":"));
+}
 export class ElementToolStateStore {
     elementStates = new Map();
     listeners = new Set();
     onStateChange = null;
     /**
      * Generates a globally unique element ID by combining assessment, section, item, and element IDs.
-     * Format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`
+     * Format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`, each part with
+     * `%` written as `%25` and `:` as `%3A`, so an id containing `:` round-trips
+     * and cannot collide with another split of the same characters.
      *
      * @example
      * getGlobalElementId('demo-assessment', 'section-1', 'q1', 'mc1')
      * // Returns: "demo-assessment:section-1:q1:mc1"
      */
     getGlobalElementId(assessmentId, sectionId, itemId, elementId) {
-        return `${assessmentId}:${sectionId}:${itemId}:${elementId}`;
+        return [assessmentId, sectionId, itemId, elementId]
+            .map(escapeIdPart)
+            .join(":");
     }
     /**
      * Parses a global element ID into its component parts.
@@ -39,12 +49,8 @@ export class ElementToolStateStore {
         const parts = globalElementId.split(":");
         if (parts.length !== 4)
             return null;
-        return {
-            assessmentId: parts[0],
-            sectionId: parts[1],
-            itemId: parts[2],
-            elementId: parts[3],
-        };
+        const [assessmentId, sectionId, itemId, elementId] = parts.map(unescapeIdPart);
+        return { assessmentId, sectionId, itemId, elementId };
     }
     /**
      * Sets tool state for a specific element.
@@ -101,7 +107,8 @@ export class ElementToolStateStore {
     }
     /**
      * Subscribes to state changes.
-     * Callback is invoked whenever any element's tool state changes.
+     * Callback is invoked whenever any element's tool state changes, including
+     * a `loadState` restore, with a copy of the state that it may keep.
      *
      * @param callback Function to call on state changes
      * @returns Unsubscribe function
@@ -111,8 +118,19 @@ export class ElementToolStateStore {
         return () => this.listeners.delete(callback);
     }
     _notifyListeners() {
+        if (this.listeners.size === 0)
+            return;
+        const snapshot = new Map([...this.elementStates].map(([key, toolStates]) => [
+            key,
+            new Map(toolStates),
+        ]));
         for (const listener of this.listeners) {
-            listener(this.elementStates);
+            try {
+                listener(snapshot);
+            }
+            catch (error) {
+                console.warn("[ElementToolStateStore] listener failed:", error);
+            }
         }
     }
     /**
@@ -125,13 +143,19 @@ export class ElementToolStateStore {
         this.onStateChange = callback;
     }
     _notifyStateChange() {
-        if (this.onStateChange) {
+        if (!this.onStateChange)
+            return;
+        try {
             this.onStateChange(this.getAllState());
         }
+        catch (error) {
+            console.warn("[ElementToolStateStore] state-change callback failed:", error);
+        }
     }
     /**
      * Loads tool state from serialized format.
-     * Used to restore state from localStorage or server.
+     * Used to restore state from localStorage or server. Subscribers are
+     * notified; the persistence callback is not, so a restore never writes back.
      *
      * @param state Serialized state object
      */
@@ -174,7 +198,7 @@ export class ElementToolStateStore {
      * @param sectionId Section identifier
      */
     clearSection(assessmentId, sectionId) {
-        const prefix = `${assessmentId}:${sectionId}:`;
+        const prefix = `${escapeIdPart(assessmentId)}:${escapeIdPart(sectionId)}:`;
         const keysToDelete = [];
         for (const key of this.elementStates.keys()) {
             if (key.startsWith(prefix)) {

package/dist/services/HighlightCoordinator.d.ts

@@ -51,53 +51,50 @@ 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 ttsWordRanges;
+    private ttsSentenceRanges;
     private ttsWordElementHighlights;
     private ttsSentenceElementHighlights;
     private annotations;
-    private colorHighlights;
+    private ttsStyleSource;
     private nextAnnotationId;
     private supported;
     private rangeSerializer;
     private themeObserver;
-    private explicitTTSColorOverride;
-    constructor(config?: HighlightCoordinatorConfig);
+    constructor();
     private setupThemeObservation;
     private parseColor;
     private relativeLuminance;
     private contrastRatio;
     private blend;
     private resolveAdaptiveTTSStyle;
-    private applyAdaptiveTTSStyle;
     /**
-     * Initialize CSS Custom Highlights
+     * Adapt the TTS colors to `sourceEl`, the element being highlighted. Without
+     * one, to the element highlighted last on the page while it stays connected,
+     * else to the document.
      */
+    private applyAdaptiveTTSStyle;
+    /** Register the shared highlights, unless another coordinator already did. */
     private initializeHighlights;
     /**
      * Register CSS styles for highlights
      */
     private registerStyles;
     /**
-     * Highlight a word for TTS (temporary)
+     * Highlight the word being read (temporary), replacing the previous one.
+     * Every range paints, so a word split across inline elements highlights
+     * whole. A range that covers elements also marks the replaced elements in it
+     * (svg, img, canvas), which a CSS range cannot paint.
      *
-     * @param textNode Text node containing the word
-     * @param startOffset Start position in text node
-     * @param endOffset End position in text node
+     * @param ranges The word's ranges: one per tree it spans
      */
-    highlightTTSWord(textNode: Text, startOffset: number, endOffset: number): void;
+    highlightTTSWord(ranges: Range[]): void;
     /**
      * Highlight a single element as the active TTS word (temporary).
      *
-     * Unlike {@link highlightTTSWord} (which paints a CSS range over a text node)
-     * this marks the element itself via `data-pie-tts-word-element`. It is used
+     * Unlike {@link highlightTTSWord} (which paints CSS ranges over text) this
+     * marks the element itself via `data-pie-tts-word-element`. It is used
      * for atomic targets that have no direct text node to range over — most
      * notably MathJax CHTML tokens (e.g. `<mjx-mi><mjx-c/></mjx-mi>`, whose glyph
      * lives in a font-driven pseudo-element a CSS range cannot paint) and
@@ -200,10 +197,8 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
         timestamp?: number;
     }>, root?: Element): number;
     /**
-     * Highlight a text range (interface method)
-     *
-     * Generic method that adapts to the specific highlight type.
-     * For more control, use the specific methods like highlightTTSWord().
+     * Highlight a range as the given type: the TTS types paint as
+     * {@link highlightTTSWord} and {@link highlightTTSSentence} do.
      */
     highlightRange(range: Range, type: HighlightType, color?: HighlightColor): void;
     /**
@@ -226,11 +221,10 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
      */
     updateTTSHighlightStyle(color: string, opacity: number): void;
     /**
-     * Cleanup this coordinator's highlights and observer.
+     * Remove this coordinator's ranges and stop its observer.
      *
-     * The stylesheet is process-global and shared by every live coordinator, so
-     * removing it here would break a replacement or sibling coordinator. Keep the
-     * single bounded style element installed for the lifetime of the document.
+     * The stylesheet and the registered highlights are page-wide and shared by
+     * every live coordinator, so they stay installed for the document's lifetime.
      */
     destroy(): void;
 }