@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

package/dist/services/AccessibilityCatalogResolver.d.ts

@@ -55,25 +55,17 @@ export type CatalogType = "spoken" | "sign-language" | "transcript" | "braille"
 /**
  * The catalog types PIE names, plus the rule for the ones it does not.
  *
- * The type above stays open on purpose: QTI treats the support vocabulary as
- * extensible, and closing it here would reject content PIE has no reason to
- * reject and could not usefully validate anyway, since catalogs arrive as
- * authored JSON rather than through this type. Keeping it open cost something
- * though — the named literals were documentation only, so a card written
- * `"spokn"` was a perfectly valid `CatalogType` that no reader would ever ask
- * for, and it failed by being invisible rather than by failing. That is what
- * `isKnownCatalogType` and the warnings below are for: the openness stays, the
- * silence does not.
+ * `CatalogType` stays open because QTI treats the support vocabulary as
+ * extensible, and catalogs arrive as authored JSON this type never validates.
+ * The trade: a card written `"spokn"` is a valid `CatalogType` no reader asks
+ * for, so `isKnownCatalogType` and the warnings below report it.
  */
 export declare const KNOWN_CATALOG_TYPES: ReadonlySet<string>;
 export declare function isKnownCatalogType(type: string): boolean;
 /**
- * Which of a card's two content slots it fills.
- *
- * Not a new field on the card and not a second discriminant: the card already
- * says which form it is by carrying `content` or `payload`, and the
- * exactly-one-of invariant is what makes that unambiguous. This names the
- * distinction so a lookup can ask for one.
+ * Which of a card's two content slots it fills. The card says so by carrying
+ * `content` or `payload`, and the exactly-one-of invariant makes that
+ * unambiguous; this type names the distinction so a lookup can ask for one.
  */
 export type CatalogCardForm = "content" | "payload";
 export declare const catalogCardForm: (card: CatalogCard) => CatalogCardForm;
@@ -93,17 +85,15 @@ export interface CatalogLookupOptions {
      * Preferred content form, when one catalog type legitimately has both on the
      * same node.
      *
-     * The case this exists for is a `spoken` node carrying both a reading script
-     * and a recording of it — which is APIP's authoring pattern and what QTI 3's
-     * migration guidance tells you to keep, the script doubling as the source the
-     * audio was generated from and as the fallback when it cannot play. Before
-     * this, both resolution rungs took the first card matching type and language,
-     * so whichever of the two was written second in the array was unreachable and
-     * nothing said so.
+     * The case is a `spoken` node carrying both a reading script and a recording
+     * of it, which is APIP's authoring pattern and what QTI 3's migration
+     * guidance keeps: the script is the source the audio was generated from and
+     * the fallback when it cannot play. Without a form, a lookup returns the
+     * first card matching type and language.
      *
      * A preference, not a filter: if the requested form is not present, the other
-     * one is still returned. Callers that cannot use a form must check what they
-     * got, exactly as they already must for a card of a type they did not expect.
+     * one is still returned. Callers that cannot use a form check what they got,
+     * as they do for a card of a type they did not expect.
      */
     form?: CatalogCardForm;
 }
@@ -241,9 +231,11 @@ export declare class AccessibilityCatalogResolver {
      */
     hasCatalog(catalogId: string): boolean;
     /**
-     * Get alternative content for a catalog identifier
+     * Get alternative content for a catalog identifier.
      *
-     * Priority: Item-level catalogs take precedence over assessment-level
+     * With a `context`, the catalog registered for exactly that owner comes
+     * first, then the one compatible scoped catalog (several are ambiguous and
+     * resolve to null). Item-level catalogs come next, then assessment-level.
      */
     getAlternative(catalogId: string, options: CatalogLookupOptions): ResolvedCatalog | null;
     private resolveCard;
@@ -264,11 +256,9 @@ export declare class AccessibilityCatalogResolver {
      * Get all available alternatives for a catalog identifier
      *
      * Every card goes through `resolveCard`, the same projection `getAlternative`
-     * uses, so enumeration cannot describe a card differently from the resolution
-     * that renders it. It was hand-rolled here once and drifted immediately: the
-     * `signLanguage` alias was folded in on the resolution path only, so a card
-     * that arrived under the alias rendered correctly and was still reported as
-     * carrying no payload by anything asking what alternates exist.
+     * uses, so enumeration describes a card exactly as the resolution that
+     * renders it. A hand-rolled copy here drifted: the `signLanguage` alias was
+     * folded in on the resolution path only.
      */
     getAllAlternatives(catalogId: string): ResolvedCatalog[];
     /**

package/dist/services/AccessibilityCatalogResolver.js

@@ -4,15 +4,10 @@ import { sanitizeSsmlString } from "./SSMLExtractor.js";
 /**
  * The catalog types PIE names, plus the rule for the ones it does not.
  *
- * The type above stays open on purpose: QTI treats the support vocabulary as
- * extensible, and closing it here would reject content PIE has no reason to
- * reject and could not usefully validate anyway, since catalogs arrive as
- * authored JSON rather than through this type. Keeping it open cost something
- * though — the named literals were documentation only, so a card written
- * `"spokn"` was a perfectly valid `CatalogType` that no reader would ever ask
- * for, and it failed by being invisible rather than by failing. That is what
- * `isKnownCatalogType` and the warnings below are for: the openness stays, the
- * silence does not.
+ * `CatalogType` stays open because QTI treats the support vocabulary as
+ * extensible, and catalogs arrive as authored JSON this type never validates.
+ * The trade: a card written `"spokn"` is a valid `CatalogType` no reader asks
+ * for, so `isKnownCatalogType` and the warnings below report it.
  */
 export const KNOWN_CATALOG_TYPES = new Set([
     "spoken",
@@ -336,9 +331,11 @@ export class AccessibilityCatalogResolver {
             Array.from(this.scopedCatalogs.values()).some((owner) => owner.catalogs.has(catalogId)));
     }
     /**
-     * Get alternative content for a catalog identifier
+     * Get alternative content for a catalog identifier.
      *
-     * Priority: Item-level catalogs take precedence over assessment-level
+     * With a `context`, the catalog registered for exactly that owner comes
+     * first, then the one compatible scoped catalog (several are ambiguous and
+     * resolve to null). Item-level catalogs come next, then assessment-level.
      */
     getAlternative(catalogId, options) {
         // A typo on this side is as silent as one on a card: the lookup simply finds
@@ -513,10 +510,10 @@ export class AccessibilityCatalogResolver {
         }
         return false;
     }
-    // The single funnel every registration path runs through — the constructor and
-    // `addItemCatalogs` by way of `indexCatalogs`, and `registerCatalogs`
-    // directly — which is why the unknown-type report lives here rather than at
-    // each entry point.
+    // The single funnel every registration path runs through (the constructor and
+    // `addItemCatalogs` by way of `indexCatalogs`, `registerCatalogs` and
+    // `registerOwner` by way of `insertScopedCatalogs`), so the unknown-type
+    // report lives here.
     sanitizeCatalogs(catalogs) {
         return catalogs.map((catalog) => ({
             ...catalog,
@@ -541,11 +538,10 @@ export class AccessibilityCatalogResolver {
         // Language rungs, most specific first: the requested language, then the
         // default language, then any.
         //
-        // Each requested tag expands into its RFC 4647 lookup sequence, so `es-MX`
-        // tries `es-mx` and then `es` before falling through to the default. Matching
-        // was `===`, which made a POSIX `es_ES` card — what the Learnosity transform
-        // emits — unreachable for an `es-ES` request except through the final
-        // no-constraint rung, i.e. by accident.
+        // Each requested tag expands into its RFC 4647 lookup sequence over
+        // normalized tags, so `es-MX` tries `es-mx` and then `es` before falling
+        // through to the default, and a POSIX `es_ES` card (what the Learnosity
+        // transform emits) matches an `es-ES` request on its own rung.
         const languageRungs = [];
         const pushLookupRungs = (tag) => {
             for (const step of languageTagLookupSequence(tag)) {
@@ -563,18 +559,16 @@ export class AccessibilityCatalogResolver {
             const candidates = catalog.cards.filter((card) => card.catalog === type && matchesLanguage(card));
             if (candidates.length === 0)
                 continue;
-            // Form is preferred inside a language rung and never across them: a
-            // recording in the requested language beats a script in that language,
-            // but a script in the requested language beats a recording in another
-            // one. Getting this backwards would answer a Spanish lookup with English
-            // audio, which is worse than answering it with Spanish text.
+            // Language outranks form: form is preferred inside a language rung and
+            // never across them, so a Spanish lookup preferring a recording gets a
+            // Spanish recording first, then Spanish text, and never English audio
+            // ahead of either.
             if (form) {
                 const preferred = candidates.find((card) => catalogCardForm(card) === form);
                 if (preferred)
                     return preferred;
             }
-            // No preference expressed, or the preferred form is absent: first match,
-            // which is what every caller got before form preference existed.
+            // No preference, or the preferred form is absent: the first match.
             return candidates[0];
         }
         return null;
@@ -583,25 +577,20 @@ export class AccessibilityCatalogResolver {
      * Get all available alternatives for a catalog identifier
      *
      * Every card goes through `resolveCard`, the same projection `getAlternative`
-     * uses, so enumeration cannot describe a card differently from the resolution
-     * that renders it. It was hand-rolled here once and drifted immediately: the
-     * `signLanguage` alias was folded in on the resolution path only, so a card
-     * that arrived under the alias rendered correctly and was still reported as
-     * carrying no payload by anything asking what alternates exist.
+     * uses, so enumeration describes a card exactly as the resolution that
+     * renders it. A hand-rolled copy here drifted: the `signLanguage` alias was
+     * folded in on the resolution path only.
      */
     getAllAlternatives(catalogId) {
         const results = [];
-        // Type, language *and* form: one catalog identifier legitimately carries
-        // several cards of the same type in different languages, and also a script
-        // and a recording of the same type in the *same* language. Keying on type
-        // and language alone dropped the second of those on the floor, so anything
-        // asking what alternates exist under-reported them.
+        // Keyed on type, language and form: one catalog identifier can carry cards
+        // of one type in several languages, and a script and a recording of one
+        // type in the same language.
         const claimed = new Set();
         const add = (card, source) => {
             // The language part is normalized, so a POSIX `es_ES` card and a BCP-47
-            // `es-ES` card collapse to one entry here exactly as they now collapse on
-            // the resolution path. Keying on the raw string would report two
-            // alternates where resolution can only ever return one.
+            // `es-ES` card collapse to one entry, as on the resolution path, which
+            // only ever returns one of them.
             const key = `${card.catalog}|${normalizeLanguageTag(card.language)}|${catalogCardForm(card)}`;
             if (claimed.has(key))
                 return;
@@ -646,7 +635,6 @@ export class AccessibilityCatalogResolver {
     getStatistics() {
         const allTypes = new Set();
         const allLanguages = new Set();
-        // Collect from assessment catalogs
         for (const catalog of this.assessmentCatalogs.values()) {
             for (const card of catalog.cards) {
                 allTypes.add(card.catalog);
@@ -654,7 +642,6 @@ export class AccessibilityCatalogResolver {
                     allLanguages.add(card.language);
             }
         }
-        // Collect from item catalogs
         for (const catalog of this.itemCatalogs.values()) {
             for (const card of catalog.cards) {
                 allTypes.add(card.catalog);

package/dist/services/ElementToolStateStore.d.ts

@@ -1,21 +1,22 @@
 /**
- * ElementToolStateStore - Manages element-level ephemeral tool state
+ * ElementToolStateStore: ephemeral UI tool state (answer eliminations, flags and
+ * the like), kept out of the session data sent to the server for scoring.
  *
- * Provides centralized storage for UI tool state (answer eliminations, flags, etc.)
- * that should NOT be sent to the server for scoring. Each element is uniquely identified
- * across the entire assessment using composite keys.
- *
- * Key features:
- * - Element-level granularity (not item-level)
- * - Composite keys for global uniqueness: `assessmentId:sectionId:itemId:elementId`
- * - Cross-section state persistence
- * - Reactive subscriptions
- * - Optional persistence callback integration
- * - Generic solution for any tool
+ * State is keyed by a composite global element id,
+ * `assessmentId:sectionId:attemptId:itemId:elementId`, unique across the
+ * assessment and per attempt: two attempts at one section never share a key.
+ * Subscribers see every change, and an optional persistence callback
+ * (`setOnStateChange`) receives the serialized state.
+ */
+/**
+ * The parts of a global element id. `attemptId` is `""` when the host names no
+ * attempt. A tool whose state belongs to an item or a section rather than to
+ * one element leaves `elementId`, and for a section `itemId`, as `""`.
  */
 export interface ElementIdComponents {
     assessmentId: string;
     sectionId: string;
+    attemptId: string;
     itemId: string;
     elementId: string;
 }
@@ -24,70 +25,51 @@ export declare class ElementToolStateStore {
     private listeners;
     private onStateChange;
     /**
-     * Generates a globally unique element ID by combining assessment, section, item, and element IDs.
-     * 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.
+     * Generates a globally unique element ID from its parts.
+     * Format: `${assessmentId}:${sectionId}:${attemptId}:${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: 'demo-assessment', sectionId: 'section-1',
+     *   attemptId: 'attempt-1', itemId: 'q1', elementId: 'mc1' })
+     * // Returns: "demo-assessment:section-1:attempt-1:q1:mc1"
      */
-    getGlobalElementId(assessmentId: string, sectionId: string, itemId: string, elementId: string): string;
+    getGlobalElementId(parts: ElementIdComponents): string;
     /**
      * Parses a global element ID into its component parts.
      *
      * @example
-     * parseGlobalElementId('demo-assessment:section-1:q1:mc1')
-     * // Returns: { assessmentId: 'demo-assessment', sectionId: 'section-1', itemId: 'q1', elementId: 'mc1' }
+     * parseGlobalElementId('demo-assessment:section-1:attempt-1:q1:mc1')
+     * // Returns: { assessmentId: 'demo-assessment', sectionId: 'section-1',
+     * //   attemptId: 'attempt-1', itemId: 'q1', elementId: 'mc1' }
      */
     parseGlobalElementId(globalElementId: string): ElementIdComponents | null;
     /**
      * Sets tool state for a specific element.
      * Notifies all subscribers and triggers persistence callback.
-     *
-     * @param globalElementId Composite key identifying the element
-     * @param toolId Tool identifier (e.g., 'answerEliminator', 'flagging')
-     * @param state Tool-specific state object
      */
     setState(globalElementId: string, toolId: string, state: unknown): void;
-    /**
-     * Gets tool state for a specific element.
-     *
-     * @param globalElementId Composite key identifying the element
-     * @param toolId Tool identifier
-     * @returns Tool state or undefined if not found
-     */
+    /** One tool's state for an element, or `undefined` when none is set. */
     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
-     */
+    /** Every tool's state for an element, keyed by toolId. */
     getElementState(globalElementId: string): Record<string, unknown>;
     /**
-     * Gets all tool states for all elements.
-     * Used for persistence and debugging.
-     *
-     * @returns Nested object: { globalElementId: { toolId: state } }
+     * All state as `{ globalElementId: { toolId: state } }`, for persistence and
+     * debugging.
      */
     getAllState(): Record<string, Record<string, unknown>>;
     /**
      * Subscribes to 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
+     * a `loadState` restore, with a copy of the state that it may keep. Returns
+     * the unsubscribe function.
      */
     subscribe(callback: (state: Map<string, Map<string, unknown>>) => void): () => void;
     private _notifyListeners;
     /**
      * Sets a callback to be invoked on state changes for persistence integration.
      * Used by demo/app layer to persist tool state to localStorage or server.
-     *
-     * @param callback Function to call with serialized state on changes
      */
     setOnStateChange(callback: (state: Record<string, Record<string, unknown>>) => void): void;
     private _notifyStateChange;
@@ -95,29 +77,18 @@ export declare class ElementToolStateStore {
      * Loads tool state from serialized format.
      * 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, unknown>>): void;
-    /**
-     * Clears all tool state for a specific element.
-     *
-     * @param globalElementId Composite key identifying the element
-     */
+    /** Clears all tool state for a specific element. */
     clearElement(globalElementId: string): void;
     /**
      * Clears state for a specific tool across all elements.
      * Useful when disabling a tool globally.
-     *
-     * @param toolId Tool identifier
      */
     clearTool(toolId: string): void;
     /**
-     * Clears all tool state for a specific section.
+     * Clears all tool state for a specific section, across its attempts.
      * Useful when unmounting/disposing a section.
-     *
-     * @param assessmentId Assessment identifier
-     * @param sectionId Section identifier
      */
     clearSection(assessmentId: string, sectionId: string): void;
     /**

package/dist/services/ElementToolStateStore.js

@@ -1,18 +1,20 @@
 /**
- * ElementToolStateStore - Manages element-level ephemeral tool state
+ * ElementToolStateStore: ephemeral UI tool state (answer eliminations, flags and
+ * the like), kept out of the session data sent to the server for scoring.
  *
- * Provides centralized storage for UI tool state (answer eliminations, flags, etc.)
- * that should NOT be sent to the server for scoring. Each element is uniquely identified
- * across the entire assessment using composite keys.
- *
- * Key features:
- * - Element-level granularity (not item-level)
- * - Composite keys for global uniqueness: `assessmentId:sectionId:itemId:elementId`
- * - Cross-section state persistence
- * - Reactive subscriptions
- * - Optional persistence callback integration
- * - Generic solution for any tool
+ * State is keyed by a composite global element id,
+ * `assessmentId:sectionId:attemptId:itemId:elementId`, unique across the
+ * assessment and per attempt: two attempts at one section never share a key.
+ * Subscribers see every change, and an optional persistence callback
+ * (`setOnStateChange`) receives the serialized state.
  */
+const ID_PARTS = [
+    "assessmentId",
+    "sectionId",
+    "attemptId",
+    "itemId",
+    "elementId",
+];
 function escapeIdPart(part) {
     return part.replace(/%/g, "%25").replace(/:/g, "%3A");
 }
@@ -24,41 +26,37 @@ export class ElementToolStateStore {
     listeners = new Set();
     onStateChange = null;
     /**
-     * Generates a globally unique element ID by combining assessment, section, item, and element IDs.
-     * 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.
+     * Generates a globally unique element ID from its parts.
+     * Format: `${assessmentId}:${sectionId}:${attemptId}:${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: 'demo-assessment', sectionId: 'section-1',
+     *   attemptId: 'attempt-1', itemId: 'q1', elementId: 'mc1' })
+     * // Returns: "demo-assessment:section-1:attempt-1:q1:mc1"
      */
-    getGlobalElementId(assessmentId, sectionId, itemId, elementId) {
-        return [assessmentId, sectionId, itemId, elementId]
-            .map(escapeIdPart)
-            .join(":");
+    getGlobalElementId(parts) {
+        return ID_PARTS.map((name) => escapeIdPart(parts[name])).join(":");
     }
     /**
      * Parses a global element ID into its component parts.
      *
      * @example
-     * parseGlobalElementId('demo-assessment:section-1:q1:mc1')
-     * // Returns: { assessmentId: 'demo-assessment', sectionId: 'section-1', itemId: 'q1', elementId: 'mc1' }
+     * parseGlobalElementId('demo-assessment:section-1:attempt-1:q1:mc1')
+     * // Returns: { assessmentId: 'demo-assessment', sectionId: 'section-1',
+     * //   attemptId: 'attempt-1', itemId: 'q1', elementId: 'mc1' }
      */
     parseGlobalElementId(globalElementId) {
         const parts = globalElementId.split(":");
-        if (parts.length !== 4)
+        if (parts.length !== ID_PARTS.length)
             return null;
-        const [assessmentId, sectionId, itemId, elementId] = parts.map(unescapeIdPart);
-        return { assessmentId, sectionId, itemId, elementId };
+        const [assessmentId, sectionId, attemptId, itemId, elementId] = parts.map(unescapeIdPart);
+        return { assessmentId, sectionId, attemptId, itemId, elementId };
     }
     /**
      * Sets tool state for a specific element.
      * Notifies all subscribers and triggers persistence callback.
-     *
-     * @param globalElementId Composite key identifying the element
-     * @param toolId Tool identifier (e.g., 'answerEliminator', 'flagging')
-     * @param state Tool-specific state object
      */
     setState(globalElementId, toolId, state) {
         let elementState = this.elementStates.get(globalElementId);
@@ -70,22 +68,11 @@ export class ElementToolStateStore {
         this._notifyListeners();
         this._notifyStateChange();
     }
-    /**
-     * Gets tool state for a specific element.
-     *
-     * @param globalElementId Composite key identifying the element
-     * @param toolId Tool identifier
-     * @returns Tool state or undefined if not found
-     */
+    /** One tool's state for an element, or `undefined` when none is set. */
     getState(globalElementId, toolId) {
         return this.elementStates.get(globalElementId)?.get(toolId);
     }
-    /**
-     * Gets all tool states for a specific element.
-     *
-     * @param globalElementId Composite key identifying the element
-     * @returns Object with tool states keyed by toolId
-     */
+    /** Every tool's state for an element, keyed by toolId. */
     getElementState(globalElementId) {
         const elementState = this.elementStates.get(globalElementId);
         if (!elementState)
@@ -93,10 +80,8 @@ export class ElementToolStateStore {
         return Object.fromEntries(elementState.entries());
     }
     /**
-     * Gets all tool states for all elements.
-     * Used for persistence and debugging.
-     *
-     * @returns Nested object: { globalElementId: { toolId: state } }
+     * All state as `{ globalElementId: { toolId: state } }`, for persistence and
+     * debugging.
      */
     getAllState() {
         const result = {};
@@ -108,10 +93,8 @@ export class ElementToolStateStore {
     /**
      * Subscribes to 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
+     * a `loadState` restore, with a copy of the state that it may keep. Returns
+     * the unsubscribe function.
      */
     subscribe(callback) {
         this.listeners.add(callback);
@@ -136,8 +119,6 @@ export class ElementToolStateStore {
     /**
      * Sets a callback to be invoked on state changes for persistence integration.
      * Used by demo/app layer to persist tool state to localStorage or server.
-     *
-     * @param callback Function to call with serialized state on changes
      */
     setOnStateChange(callback) {
         this.onStateChange = callback;
@@ -156,8 +137,6 @@ export class ElementToolStateStore {
      * Loads tool state from serialized format.
      * 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) {
         this.elementStates.clear();
@@ -167,11 +146,7 @@ export class ElementToolStateStore {
         }
         this._notifyListeners();
     }
-    /**
-     * Clears all tool state for a specific element.
-     *
-     * @param globalElementId Composite key identifying the element
-     */
+    /** Clears all tool state for a specific element. */
     clearElement(globalElementId) {
         this.elementStates.delete(globalElementId);
         this._notifyListeners();
@@ -180,8 +155,6 @@ export class ElementToolStateStore {
     /**
      * Clears state for a specific tool across all elements.
      * Useful when disabling a tool globally.
-     *
-     * @param toolId Tool identifier
      */
     clearTool(toolId) {
         for (const elementState of this.elementStates.values()) {
@@ -191,11 +164,8 @@ export class ElementToolStateStore {
         this._notifyStateChange();
     }
     /**
-     * Clears all tool state for a specific section.
+     * Clears all tool state for a specific section, across its attempts.
      * Useful when unmounting/disposing a section.
-     *
-     * @param assessmentId Assessment identifier
-     * @param sectionId Section identifier
      */
     clearSection(assessmentId, sectionId) {
         const prefix = `${escapeIdPart(assessmentId)}:${escapeIdPart(sectionId)}:`;

package/dist/services/HighlightCoordinator.d.ts

@@ -11,8 +11,6 @@
  * - Configurable colors and styles
  * - Annotation persistence via RangeSerializer
  *
- * Part of PIE Assessment Toolkit.
- *
  * Browser Support:
  * - Chrome/Edge 105+
  * - Safari 17.2+
@@ -63,6 +61,11 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
     private rangeSerializer;
     private themeObserver;
     constructor();
+    /**
+     * Re-adapt the TTS colors when the page's theme moves: on the document
+     * element, on a `<pie-theme>` host, and when a `<pie-theme>` mounts, which
+     * themes its target as it connects.
+     */
     private setupThemeObservation;
     private parseColor;
     private relativeLuminance;
@@ -100,12 +103,10 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
      * lives in a font-driven pseudo-element a CSS range cannot paint) and
      * whole-expression fallbacks.
      *
-     * The supplied element is painted exactly; we deliberately do NOT walk up to
-     * a containing `<math>` / `<mjx-container>`. That escalation is what made
-     * MathJax-rendered math highlight as a full block while native MathML tracked
-     * per-token: a resolved single token must paint as a token, and only a
-     * genuine expression fallback (where the element already is the container)
-     * should paint the whole expression.
+     * The supplied element is painted exactly, with no walk up to a containing
+     * `<math>` / `<mjx-container>`: a resolved token paints as a token, and only
+     * an expression fallback, where the element already is the container, paints
+     * the whole expression.
      */
     highlightTTSWordElement(element: Element): void;
     /**
@@ -196,23 +197,10 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
         color: HighlightColor;
         timestamp?: number;
     }>, root?: Element): number;
-    /**
-     * 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;
-    /**
-     * Clear highlights of a specific type (interface method)
-     */
-    clearHighlights(type: HighlightType): void;
     /**
      * Clear all highlights (interface method)
      */
     clearAll(): void;
-    /**
-     * Check if CSS Highlight API is supported (interface method)
-     */
-    isSupported(): boolean;
     /**
      * Update TTS highlight style dynamically
      *