@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

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+
@@ -52,57 +50,63 @@ export interface Annotation {
     timestamp: number;
 }
 export declare class HighlightCoordinator implements HighlightCoordinatorApi {
-    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();
+    /**
+     * 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;
     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
      * 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;
     /**
@@ -193,25 +197,10 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
         color: HighlightColor;
         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().
-     */
-    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
      *
@@ -220,11 +209,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;
 }