blume 2.0.3 → 2.1.0

package/src/components/layout/NarrationPlayer.astro

@@ -0,0 +1,1085 @@
+---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { NARRATION_SPEEDS } from "../../narration/player.ts";
+import type { NarrationCues } from "../../narration/script.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  /** Where generated clips are served (`/blume-narration/audio/`), when a provider generates them. */
+  audioBase?: string;
+  /** Strings in the content's language: the spoken cues come from here. */
+  cues?: UIStrings["narration"];
+  /** The content's language, for sentence splitting and the browser voice. */
+  lang: string;
+  /** This page's manifest URL, when a provider generates clips. */
+  manifest?: string;
+  /** The player's labels, in the page's language. */
+  strings?: UIStrings["narration"];
+}
+
+const { audioBase, cues, lang, manifest, strings } = Astro.props;
+// Merged per key over English, like PageFeedback, so a partial pack still
+// resolves every label.
+const s = { ...EN_UI.narration, ...strings };
+const c = { ...EN_UI.narration, ...cues };
+const cueMap: NarrationCues = {
+  danger: c.cueDanger,
+  info: c.cueInfo,
+  note: c.cueNote,
+  section: c.cueSection,
+  step: c.cueStep,
+  success: c.cueSuccess,
+  tab: c.cueTab,
+  tip: c.cueTip,
+  warning: c.cueWarning,
+};
+
+const iconButton =
+  "inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
+---
+
+{/* Stays hidden until the script has read the page: pages too short to
+    narrate, and browsers with no voice for the language, never show it. The
+    root is a direct child of the article so it can stay pinned under the
+    header while the article scrolls. It's also the container the controls
+    are sized against, so they're laid out at the full width while the pill
+    grows to it. */}
+<div
+  class="@container not-prose z-30 mt-5 mb-6 hidden"
+  data-audio-base={audioBase}
+  data-blume-narration="skip"
+  data-blume-narration-player
+  data-cues={JSON.stringify(cueMap)}
+  data-lang={lang}
+  data-manifest={manifest}
+  data-minutes={s.minutes}
+>
+  {/* One pill for both states: it fits the start button, and widens to the
+      article for the controls while one fades into the other. */}
+  <div
+    class="relative flex h-9 w-fit max-w-full items-center rounded-full border border-border bg-background text-foreground transition-colors"
+    data-narration-shell
+  >
+    <button
+      class="inline-flex h-full cursor-pointer items-center gap-2 whitespace-nowrap rounded-full px-3.5 text-sm"
+      data-narration-start
+      type="button"
+    >
+      <Icon name="headphones" size={16} />
+      <span>{s.label}</span>
+      <span class="text-muted-foreground tabular-nums" data-narration-duration></span>
+    </button>
+    <div
+      aria-label={s.label}
+      class="absolute inset-y-0 start-0 flex w-[calc(100cqw-2px)] items-center gap-0.5 px-[3px]"
+      data-narration-controls
+      role="group"
+    >
+      <button
+        aria-label={s.pause}
+        class={iconButton}
+        data-label-pause={s.pause}
+        data-label-play={s.play}
+        data-narration-toggle
+        type="button"
+      >
+        <span data-narration-icon-pause><Icon name="pause" size={16} /></span>
+        <span class="hidden" data-narration-icon-play><Icon name="play" size={16} /></span>
+      </button>
+      <button aria-label={s.previous} class={iconButton} data-narration-previous type="button">
+        <Icon name="skip-back" size={16} />
+      </button>
+      <button aria-label={s.next} class={iconButton} data-narration-next type="button">
+        <Icon name="skip-forward" size={16} />
+      </button>
+      <input
+        aria-label={s.progress}
+        class="mx-1.5 h-4 min-w-12 flex-1 cursor-pointer appearance-none bg-transparent"
+        data-narration-seek
+        max="0"
+        min="0"
+        step="1"
+        type="range"
+        value="0"
+      />
+      {/* A narrow pill drops the readout; the seek bar still shows progress. */}
+      <span class="px-1 text-muted-foreground text-xs tabular-nums @max-sm:hidden" data-narration-time></span>
+      <span class="relative inline-flex shrink-0 items-center">
+        <select
+          aria-label={s.speed}
+          class="h-7 cursor-pointer appearance-none rounded-full bg-background ps-2.5 pe-6 text-foreground text-xs transition-colors hover:bg-muted"
+          data-narration-speed
+        >
+          {NARRATION_SPEEDS.map((speed) => <option selected={speed === 1} value={String(speed)}>{speed}×</option>)}
+        </select>
+        <Icon class="pointer-events-none absolute end-2 text-muted-foreground" name="chevron-down" size={12} />
+      </span>
+      <button
+        class="hidden h-7 shrink-0 cursor-pointer items-center gap-1.5 rounded-full px-2 text-accent text-xs transition-colors hover:bg-muted"
+        data-narration-follow
+        type="button"
+      >
+        <Icon name="locate-fixed" size={14} />
+        <span class="@max-sm:sr-only">{s.follow}</span>
+      </button>
+      <button aria-label={s.stop} class={iconButton} data-narration-stop type="button">
+        <Icon name="x" size={16} />
+      </button>
+    </div>
+  </div>
+  <p class="mt-2 hidden text-muted-foreground text-sm" data-narration-error role="status">
+    {s.error}
+  </p>
+</div>
+
+<style is:global>
+  /* The sentence being read. The Custom Highlight API paints it without
+     touching the DOM, so selection, search, and copy are unaffected. */
+  ::highlight(blume-narration) {
+    background-color: color-mix(in oklab, var(--blume-accent) 24%, transparent);
+  }
+  /* While playing, the pill spans the article and stays pinned under the
+     header as the article scrolls. */
+  [data-blume-narration-player].is-playing {
+    position: sticky;
+    top: 4.75rem;
+  }
+  [data-blume-narration-player].is-playing [data-narration-shell] {
+    width: 100%;
+  }
+  [data-blume-narration-player]:not(.is-playing) [data-narration-shell]:hover {
+    border-color: color-mix(in oklab, var(--blume-foreground) 40%, transparent);
+  }
+  /* The seek bar: a thin track filled with the accent up to the thumb.
+     Firefox fills it natively; elsewhere the fill is a gradient stopping at
+     the thumb's center, which the script keeps in --narration-progress. */
+  [data-narration-seek] {
+    --narration-fill: var(--blume-accent);
+    --narration-rail: color-mix(in oklab, var(--blume-foreground) 14%, transparent);
+    --narration-direction: to right;
+  }
+  [data-narration-seek]:dir(rtl) {
+    --narration-direction: to left;
+  }
+  [data-narration-seek]::-webkit-slider-runnable-track {
+    height: 4px;
+    border-radius: 9999px;
+    background: linear-gradient(
+      var(--narration-direction),
+      var(--narration-fill) calc(6px + (100% - 12px) * var(--narration-progress, 0)),
+      var(--narration-rail) 0
+    );
+  }
+  [data-narration-seek]::-webkit-slider-thumb {
+    appearance: none;
+    width: 12px;
+    height: 12px;
+    margin-top: -4px;
+    border: 0;
+    border-radius: 9999px;
+    background: var(--narration-fill);
+  }
+  [data-narration-seek]::-moz-range-track {
+    height: 4px;
+    border-radius: 9999px;
+    background: var(--narration-rail);
+  }
+  [data-narration-seek]::-moz-range-progress {
+    height: 4px;
+    border-radius: 9999px;
+    background: var(--narration-fill);
+  }
+  [data-narration-seek]::-moz-range-thumb {
+    width: 12px;
+    height: 12px;
+    border: 0;
+    border-radius: 9999px;
+    background: var(--narration-fill);
+  }
+  /* Focus rings the thumb, not the whole bar. */
+  [data-narration-seek]:focus-visible {
+    outline: none;
+  }
+  [data-narration-seek]:focus-visible::-webkit-slider-thumb {
+    box-shadow:
+      0 0 0 2px var(--blume-background),
+      0 0 0 4px var(--blume-accent);
+  }
+  [data-narration-seek]:focus-visible::-moz-range-thumb {
+    box-shadow:
+      0 0 0 2px var(--blume-background),
+      0 0 0 4px var(--blume-accent);
+  }
+  /* Whichever of the start button and the controls isn't in use is invisible,
+     and out of the tab order. */
+  [data-narration-start],
+  [data-narration-controls] {
+    opacity: 0;
+    visibility: hidden;
+  }
+  [data-blume-narration-player]:not(.is-playing) [data-narration-start],
+  [data-blume-narration-player].is-playing [data-narration-controls] {
+    opacity: 1;
+    visibility: visible;
+  }
+  /* The one leaving fades out first; the one arriving is visible (so it can
+     take focus) at once, and fades in as the pill resizes. */
+  @media (prefers-reduced-motion: no-preference) {
+    [data-narration-start],
+    [data-narration-controls] {
+      transition:
+        opacity 120ms ease,
+        visibility 0s linear 120ms;
+    }
+    [data-blume-narration-player]:not(.is-playing) [data-narration-start],
+    [data-blume-narration-player].is-playing [data-narration-controls] {
+      transition:
+        opacity 180ms ease 100ms,
+        visibility 0s;
+    }
+  }
+</style>
+
+<script>
+  import {
+    followScroll,
+    isInView,
+    parseSpeed,
+    pickVoice,
+    progressAt,
+    progressLabel,
+    progressTotal,
+    seekKeyTarget,
+    spokenFraction,
+    stepAtProgress,
+    stepsFromManifest,
+    stepsFromSegments,
+  } from "../../narration/player.ts";
+  import type { NarrationStep } from "../../narration/player.ts";
+  import {
+    alignBlocks,
+    extractNarration,
+    isNarratable,
+    isNarrationCues,
+    isNarrationManifest,
+    narrationLength,
+    narrationMinutes,
+    segmentNarration,
+  } from "../../narration/script.ts";
+  import type {
+    NarrationExtract,
+    NarrationTree,
+  } from "../../narration/script.ts";
+  import { track } from "./analytics-client.ts";
+
+  const HIGHLIGHT = "blume-narration";
+  const SPEED_KEY = "blume-narration-speed";
+  // How long a scroll the player started is ignored by the "reader scrolled
+  // away" check: a smooth scroll fires scroll events until it settles.
+  const OWN_SCROLL_MS = 900;
+  // The pill widening to the controls, or narrowing back to the button.
+  const MORPH_MS = 320;
+  const MORPH_EASING = "cubic-bezier(0.32, 0.72, 0, 1)";
+  // How long after the click the reading starts, so the pill has finished
+  // widening before the first sentence sounds.
+  const START_DELAY_MS = 500;
+
+  const domTree: NarrationTree<Node> = {
+    attr: (node, name) =>
+      node instanceof Element ? node.getAttribute(name) : null,
+    children: (node) => Array.from(node.childNodes),
+    tag: (node) => (node instanceof Element ? node.localName : null),
+    text: (node) =>
+      node.nodeType === Node.TEXT_NODE ? (node.nodeValue ?? "") : null,
+  };
+
+  interface TabsElement extends HTMLElement {
+    activate: (index: number, sync: boolean, updateHash: boolean) => void;
+  }
+
+  const isTabsElement = (element: Element | null): element is TabsElement =>
+    element !== null &&
+    "activate" in element &&
+    typeof element.activate === "function";
+
+  const synth: SpeechSynthesis | null =
+    "speechSynthesis" in window ? window.speechSynthesis : null;
+
+  // Chrome fills the voice list asynchronously; wait for it once per page
+  // load, but not forever (some Linux builds never fire `voiceschanged`).
+  let voicesLoading: Promise<SpeechSynthesisVoice[]> | null = null;
+  const loadVoices = (): Promise<SpeechSynthesisVoice[]> => {
+    voicesLoading ??= new Promise((resolve) => {
+      if (!synth) {
+        resolve([]);
+        return;
+      }
+      const ready = synth.getVoices();
+      if (ready.length > 0) {
+        resolve(ready);
+        return;
+      }
+      const done = () => {
+        synth.removeEventListener("voiceschanged", done);
+        resolve(synth.getVoices());
+      };
+      synth.addEventListener("voiceschanged", done);
+      setTimeout(done, 1500);
+    });
+    return voicesLoading;
+  };
+
+  const readSpeed = (): number => {
+    try {
+      return parseSpeed(localStorage.getItem(SPEED_KEY));
+    } catch {
+      return 1;
+    }
+  };
+
+  const writeSpeed = (speed: number): void => {
+    try {
+      localStorage.setItem(SPEED_KEY, String(speed));
+    } catch {
+      // Storage blocked: the speed just isn't remembered.
+    }
+  };
+
+  const reducedMotion = (): boolean =>
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const setHighlight = (range: Range | null): void => {
+    if (!("highlights" in CSS)) {
+      return;
+    }
+    if (range) {
+      CSS.highlights.set(HIGHLIGHT, new Highlight(range));
+    } else {
+      CSS.highlights.delete(HIGHLIGHT);
+    }
+  };
+
+  const wait = (ms: number): Promise<void> =>
+    new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+
+  const required = <T extends Element>(root: Element, selector: string): T => {
+    const element = root.querySelector<T>(selector);
+    if (!element) {
+      throw new Error(`Narration player is missing ${selector}`);
+    }
+    return element;
+  };
+
+  class Player {
+    readonly #root: HTMLElement;
+    readonly #article: HTMLElement;
+    readonly #lang: string;
+    readonly #manifestUrl: string | null;
+    readonly #audioBase: string | null;
+    readonly #shell: HTMLElement;
+    readonly #start: HTMLButtonElement;
+    readonly #controls: HTMLElement;
+    readonly #toggle: HTMLButtonElement;
+    readonly #seek: HTMLInputElement;
+    readonly #time: HTMLElement;
+    readonly #speedSelect: HTMLSelectElement;
+    readonly #follow: HTMLButtonElement;
+    readonly #error: HTMLElement;
+    readonly #listeners = new AbortController();
+    #extract: NarrationExtract<Node> | null = null;
+    #steps: NarrationStep[] = [];
+    #ranges = new Map<number, Range | null>();
+    #index = 0;
+    #engine: "audio" | "browser" = "browser";
+    #voice: SpeechSynthesisVoice | null = null;
+    #audio: HTMLAudioElement | null = null;
+    #preload: HTMLAudioElement | null = null;
+    #speed = readSpeed();
+    #started = false;
+    #playing = false;
+    // Started, and waiting for the pill to widen before reading.
+    #pending = false;
+    #following = true;
+    #ownScrollUntil = 0;
+    #morphing: Animation | null = null;
+    // Bumped by every start, so a start the reader stopped (or restarted)
+    // while it loaded never begins reading.
+    #session = 0;
+    // What's sounding the current step, and when a browser voice began it:
+    // the readout moves through a sentence from these.
+    #source: "clip" | "voice" | null = null;
+    #spokenAt: number | null = null;
+    #frame = 0;
+    #scrubbing = false;
+    // Bumped whenever playback moves or stops, so a late `ended`/`end` from
+    // the clip or utterance it replaced can't advance the new one.
+    #token = 0;
+
+    constructor(root: HTMLElement, article: HTMLElement) {
+      this.#root = root;
+      this.#article = article;
+      this.#lang = root.dataset.lang || document.documentElement.lang || "en";
+      this.#manifestUrl = root.dataset.manifest || null;
+      this.#audioBase = root.dataset.audioBase || null;
+      this.#shell = required(root, "[data-narration-shell]");
+      this.#start = required(root, "[data-narration-start]");
+      this.#controls = required(root, "[data-narration-controls]");
+      this.#toggle = required(root, "[data-narration-toggle]");
+      this.#seek = required(root, "[data-narration-seek]");
+      this.#time = required(root, "[data-narration-time]");
+      this.#speedSelect = required(root, "[data-narration-speed]");
+      this.#follow = required(root, "[data-narration-follow]");
+      this.#error = required(root, "[data-narration-error]");
+    }
+
+    /** Read the page, and show the player if it has something to narrate. */
+    async init(): Promise<void> {
+      let cues: unknown;
+      try {
+        cues = JSON.parse(this.#root.dataset.cues ?? "");
+      } catch {
+        return;
+      }
+      if (!isNarrationCues(cues)) {
+        return;
+      }
+      const extract = extractNarration(this.#article, domTree, cues);
+      if (!isNarratable(extract)) {
+        return;
+      }
+      this.#extract = extract;
+      // Browser voices are the fallback everywhere, and the only engine when
+      // no clips were generated: with none for the language, don't offer
+      // narration at all.
+      if (this.#manifestUrl && this.#audioBase) {
+        void loadVoices().then((voices) => {
+          this.#voice = pickVoice(voices, this.#lang);
+        });
+      } else {
+        this.#voice = pickVoice(await loadVoices(), this.#lang);
+        if (!this.#voice) {
+          return;
+        }
+      }
+      if (this.#listeners.signal.aborted) {
+        return;
+      }
+      const minutes = narrationMinutes(narrationLength(extract), this.#lang);
+      const label = (this.#root.dataset.minutes ?? "{n} min").replaceAll(
+        "{n}",
+        String(minutes)
+      );
+      required(this.#root, "[data-narration-duration]").textContent =
+        `· ${label}`;
+      this.#speedSelect.value = String(this.#speed);
+      this.#wire();
+      this.#root.classList.remove("hidden");
+    }
+
+    destroy(): void {
+      this.stop();
+      this.#listeners.abort();
+      this.#audio = null;
+      this.#preload = null;
+    }
+
+    #wire(): void {
+      const { signal } = this.#listeners;
+      this.#start.addEventListener("click", () => void this.#begin(), {
+        signal,
+      });
+      this.#toggle.addEventListener(
+        "click",
+        () => (this.#playing || this.#pending ? this.#pause() : this.#resume()),
+        { signal }
+      );
+      required(this.#root, "[data-narration-previous]").addEventListener(
+        "click",
+        () => this.#play(this.#index - 1),
+        { signal }
+      );
+      required(this.#root, "[data-narration-next]").addEventListener(
+        "click",
+        () => this.#play(this.#index + 1),
+        { signal }
+      );
+      // The bar is measured in characters: dragging or clicking it plays the
+      // sentence under the thumb, and the arrow keys move a sentence at a time.
+      this.#seek.addEventListener(
+        "input",
+        () => {
+          const target = stepAtProgress(this.#steps, Number(this.#seek.value));
+          if (target === this.#index) {
+            this.#renderProgress();
+          } else {
+            this.#play(target);
+          }
+        },
+        { signal }
+      );
+      this.#seek.addEventListener(
+        "keydown",
+        (event) => {
+          const target = seekKeyTarget(
+            event.key,
+            this.#index,
+            this.#steps.length,
+            getComputedStyle(this.#seek).direction === "rtl"
+          );
+          if (target !== null) {
+            event.preventDefault();
+            this.#play(target);
+          }
+        },
+        { signal }
+      );
+      this.#seek.addEventListener(
+        "pointerdown",
+        () => {
+          this.#scrubbing = true;
+        },
+        { signal }
+      );
+      const release = () => {
+        if (this.#scrubbing) {
+          this.#scrubbing = false;
+          this.#renderProgress();
+        }
+      };
+      window.addEventListener("pointerup", release, { signal });
+      window.addEventListener("pointercancel", release, { signal });
+      this.#speedSelect.addEventListener(
+        "change",
+        () => this.#setSpeed(Number(this.#speedSelect.value)),
+        { signal }
+      );
+      this.#follow.addEventListener(
+        "click",
+        () => {
+          this.#setFollowing(true);
+          this.#followTo(this.#rangeAt(this.#index), true);
+        },
+        { signal }
+      );
+      required(this.#root, "[data-narration-stop]").addEventListener(
+        "click",
+        () => this.stop(),
+        { signal }
+      );
+      window.addEventListener("scroll", () => this.#onScroll(), {
+        passive: true,
+        signal,
+      });
+    }
+
+    async #begin(): Promise<void> {
+      this.#started = true;
+      this.#session += 1;
+      const session = this.#session;
+      const current = () => this.#started && session === this.#session;
+      this.#pending = true;
+      this.#render();
+      const widened = this.#morph(true) ? wait(START_DELAY_MS) : null;
+      this.#error.classList.add("hidden");
+      // The start button just disappeared under focus; hand it to the
+      // play/pause button so a keyboard reader keeps their place.
+      this.#toggle.focus();
+      this.#steps = await this.#loadSteps();
+      if (!current()) {
+        return;
+      }
+      if (this.#steps.length === 0) {
+        this.stop();
+        this.#error.classList.remove("hidden");
+        return;
+      }
+      this.#seek.max = String(progressTotal(this.#steps));
+      this.#index = 0;
+      this.#render();
+      track("narration_play", { engine: this.#engine, path: location.pathname });
+      await widened;
+      // Pausing, seeking, or skipping in the meantime already decided.
+      if (!(current() && this.#pending)) {
+        return;
+      }
+      this.#play(0);
+    }
+
+    // The generated clips when the build wrote them for this page, else the
+    // page read sentence by sentence with a browser voice.
+    async #loadSteps(): Promise<NarrationStep[]> {
+      const extract = this.#extract;
+      if (!extract) {
+        return [];
+      }
+      if (this.#manifestUrl && this.#audioBase) {
+        try {
+          const response = await fetch(this.#manifestUrl);
+          if (response.ok) {
+            const manifest: unknown = await response.json();
+            if (isNarrationManifest(manifest)) {
+              this.#engine = "audio";
+              const aligned = alignBlocks(
+                manifest.blocks,
+                extract.blocks.map((block) => block.text)
+              );
+              return stepsFromManifest(manifest, aligned, this.#audioBase);
+            }
+          }
+        } catch {
+          // No clips reachable: fall through to browser voices.
+        }
+      }
+      this.#voice ??= pickVoice(await loadVoices(), this.#lang);
+      if (!this.#voice) {
+        return [];
+      }
+      this.#engine = "browser";
+      return stepsFromSegments(segmentNarration(extract, this.#lang));
+    }
+
+    #play(target: number): void {
+      if (!this.#started || this.#steps.length === 0) {
+        return;
+      }
+      this.#pending = false;
+      this.#halt();
+      if (target >= this.#steps.length) {
+        track("narration_complete", { path: location.pathname });
+        this.stop();
+        return;
+      }
+      const index = Math.max(0, target);
+      const step = this.#steps[index];
+      if (!step) {
+        return;
+      }
+      this.#index = index;
+      this.#playing = true;
+      this.#tick();
+      const token = this.#token;
+      const range = this.#rangeAt(index);
+      this.#reveal(range);
+      setHighlight(range);
+      this.#followTo(range, false);
+      this.#render();
+      if (step.audio && this.#engine === "audio") {
+        this.#playClip(step, step.audio, token);
+      } else {
+        this.#speak(step, token);
+      }
+    }
+
+    #playClip(step: NarrationStep, src: string, token: number): void {
+      // One element for every clip: once a click has let it play, iOS lets it
+      // keep playing new sources without another gesture.
+      this.#audio ??= new Audio();
+      const audio = this.#audio;
+      this.#source = "clip";
+      audio.src = src;
+      audio.playbackRate = this.#speed;
+      audio.onended = () => {
+        if (token === this.#token) {
+          this.#play(this.#index + 1);
+        }
+      };
+      // A clip that won't load is read by a browser voice instead, if any.
+      audio.onerror = () => {
+        if (token === this.#token) {
+          this.#speak(step, token);
+        }
+      };
+      audio.play().catch(() => {
+        if (token === this.#token) {
+          this.#speak(step, token);
+        }
+      });
+      this.#preloadClip(this.#index + 1);
+    }
+
+    #preloadClip(index: number): void {
+      const next = this.#steps[index]?.audio;
+      if (!next) {
+        return;
+      }
+      this.#preload ??= new Audio();
+      this.#preload.preload = "auto";
+      this.#preload.src = next;
+    }
+
+    #speak(step: NarrationStep, token: number): void {
+      const voice = this.#voice;
+      if (!(synth && voice)) {
+        this.stop();
+        this.#error.classList.remove("hidden");
+        return;
+      }
+      const utterance = new SpeechSynthesisUtterance(step.text);
+      utterance.voice = voice;
+      utterance.lang = voice.lang;
+      utterance.rate = this.#speed;
+      this.#source = "voice";
+      this.#spokenAt = null;
+      utterance.onstart = () => {
+        if (token === this.#token) {
+          this.#spokenAt = performance.now();
+        }
+      };
+      utterance.onend = () => {
+        if (token === this.#token) {
+          this.#play(this.#index + 1);
+        }
+      };
+      utterance.onerror = (event) => {
+        // Cancelling (pause, skip, stop) reports an error too; only a real
+        // failure moves on to the next sentence.
+        if (
+          token !== this.#token ||
+          event.error === "interrupted" ||
+          event.error === "canceled"
+        ) {
+          return;
+        }
+        this.#play(this.#index + 1);
+      };
+      synth.cancel();
+      synth.resume();
+      synth.speak(utterance);
+    }
+
+    // Stop whatever is sounding and orphan its callbacks.
+    #halt(): void {
+      this.#token += 1;
+      this.#playing = false;
+      // A stopped browser voice starts its sentence over.
+      this.#spokenAt = null;
+      if (this.#audio) {
+        this.#audio.onended = null;
+        this.#audio.onerror = null;
+        this.#audio.pause();
+      }
+      // Also silences a browser voice standing in for a clip that failed.
+      synth?.cancel();
+    }
+
+    #pause(): void {
+      this.#pending = false;
+      // A clip pauses in place and resumes mid-sentence; a browser voice has
+      // no reliable pause across engines, so it restarts the sentence.
+      if (this.#engine === "audio" && this.#audio && !this.#audio.paused) {
+        this.#audio.pause();
+        this.#playing = false;
+      } else {
+        this.#halt();
+      }
+      this.#render();
+    }
+
+    #resume(): void {
+      const audio = this.#audio;
+      if (
+        this.#engine === "audio" &&
+        audio &&
+        audio.currentTime > 0 &&
+        !audio.ended &&
+        audio.onended
+      ) {
+        this.#playing = true;
+        audio.playbackRate = this.#speed;
+        void audio.play();
+        this.#tick();
+        this.#render();
+        return;
+      }
+      this.#play(this.#index);
+    }
+
+    stop(): void {
+      const hadFocus = this.#controls.contains(document.activeElement);
+      this.#halt();
+      this.#started = false;
+      this.#pending = false;
+      this.#index = 0;
+      setHighlight(null);
+      this.#setFollowing(true);
+      this.#source = null;
+      this.#render();
+      this.#morph(false);
+      if (hadFocus) {
+        this.#start.focus();
+      }
+    }
+
+    // Swap the start button and the controls, animating the pill's width
+    // from where it is now (mid-animation, if it was already moving) to where
+    // the new state puts it. The animation leaves no inline width behind, so
+    // the pill keeps fitting its button, or the article, as the page resizes.
+    // Returns whether it animated.
+    #morph(playing: boolean): boolean {
+      const from = this.#shell.getBoundingClientRect().width;
+      this.#morphing?.cancel();
+      this.#root.classList.toggle("is-playing", playing);
+      const to = this.#shell.getBoundingClientRect().width;
+      if (from === to || reducedMotion()) {
+        return false;
+      }
+      // Clipped only while it moves, so focus rings aren't cut off at rest.
+      this.#shell.style.overflow = "hidden";
+      const animation = this.#shell.animate(
+        { width: [`${from}px`, `${to}px`] },
+        { duration: MORPH_MS, easing: MORPH_EASING }
+      );
+      this.#morphing = animation;
+      const settle = () => {
+        if (this.#morphing === animation) {
+          this.#morphing = null;
+          this.#shell.style.overflow = "";
+        }
+      };
+      animation.addEventListener("finish", settle);
+      animation.addEventListener("cancel", settle);
+      return true;
+    }
+
+    #setSpeed(speed: number): void {
+      this.#speed = speed;
+      writeSpeed(speed);
+      if (this.#audio) {
+        this.#audio.playbackRate = speed;
+      }
+      // A browser voice can't change rate mid-utterance: restart the sentence.
+      if (this.#playing && this.#engine === "browser") {
+        this.#play(this.#index);
+        return;
+      }
+      this.#render();
+    }
+
+    #render(): void {
+      const playing = this.#playing || this.#pending;
+      const label = playing
+        ? this.#toggle.dataset.labelPause
+        : this.#toggle.dataset.labelPlay;
+      this.#toggle.setAttribute("aria-label", label ?? "");
+      required(this.#toggle, "[data-narration-icon-pause]").classList.toggle(
+        "hidden",
+        !playing
+      );
+      required(this.#toggle, "[data-narration-icon-play]").classList.toggle(
+        "hidden",
+        playing
+      );
+      this.#renderProgress();
+    }
+
+    // How far through the current step playback is: a clip reports its own
+    // time, a browser voice is estimated from when it started the sentence.
+    #fraction(): number {
+      const audio = this.#audio;
+      if (this.#source === "clip" && audio && audio.duration > 0) {
+        return Number.isFinite(audio.duration)
+          ? audio.currentTime / audio.duration
+          : 0;
+      }
+      const step = this.#steps[this.#index];
+      if (this.#source === "voice" && step && this.#spokenAt !== null) {
+        return spokenFraction(
+          step.text.length,
+          performance.now() - this.#spokenAt,
+          this.#speed,
+          this.#lang
+        );
+      }
+      return 0;
+    }
+
+    #renderProgress(): void {
+      const position = progressAt(this.#steps, this.#index, this.#fraction());
+      // While the reader drags the thumb, the bar shows where they are.
+      const shown = this.#scrubbing
+        ? Number(this.#seek.value)
+        : Math.round(position);
+      if (!this.#scrubbing) {
+        this.#seek.value = String(shown);
+      }
+      const total = Number(this.#seek.max);
+      this.#seek.style.setProperty(
+        "--narration-progress",
+        String(total > 0 ? shown / total : 0)
+      );
+      const label = progressLabel(
+        this.#steps,
+        position,
+        this.#speed,
+        this.#lang
+      );
+      if (this.#time.textContent !== label) {
+        this.#time.textContent = label;
+        this.#seek.setAttribute("aria-valuetext", label);
+      }
+    }
+
+    // Move the bar and readout every frame while reading, and stop once it
+    // pauses or stops.
+    #tick(): void {
+      if (this.#frame !== 0) {
+        return;
+      }
+      const frame = () => {
+        this.#frame = 0;
+        if (!this.#playing) {
+          return;
+        }
+        this.#renderProgress();
+        this.#frame = requestAnimationFrame(frame);
+      };
+      this.#frame = requestAnimationFrame(frame);
+    }
+
+    #rangeAt(index: number): Range | null {
+      if (this.#ranges.has(index)) {
+        return this.#ranges.get(index) ?? null;
+      }
+      const step = this.#steps[index];
+      const block = step ? this.#extract?.blocks[step.block] : undefined;
+      let range: Range | null = null;
+      if (step && block && step.end > step.start) {
+        const startNode = block.nodes[block.nodeOf[step.start] ?? -1];
+        const endNode = block.nodes[block.nodeOf[step.end - 1] ?? -1];
+        const startOffset = block.offsetOf[step.start];
+        const endOffset = block.offsetOf[step.end - 1];
+        if (
+          startNode &&
+          endNode &&
+          startOffset !== undefined &&
+          endOffset !== undefined &&
+          startNode.isConnected
+        ) {
+          range = document.createRange();
+          try {
+            range.setStart(startNode, startOffset);
+            range.setEnd(endNode, endOffset + 1);
+          } catch {
+            range = null;
+          }
+        }
+      }
+      this.#ranges.set(index, range);
+      return range;
+    }
+
+    // Open a collapsed section, or switch to a hidden tab, holding the
+    // sentence about to be read, so the highlight lands on visible text.
+    #reveal(range: Range | null): void {
+      let element = range?.startContainer.parentElement ?? null;
+      while (element && element !== this.#article) {
+        if (element instanceof HTMLDetailsElement && !element.open) {
+          element.open = true;
+        }
+        if (
+          element.hasAttribute("data-blume-tab-panel") &&
+          element.getClientRects().length === 0
+        ) {
+          const tabs = element.closest("blume-tabs");
+          if (isTabsElement(tabs)) {
+            const panels = Array.from(
+              tabs.querySelectorAll("[data-blume-tab-panel]")
+            ).filter((panel) => panel.closest("blume-tabs") === tabs);
+            const position = panels.indexOf(element);
+            if (position !== -1) {
+              tabs.activate(position, false, false);
+            }
+          }
+        }
+        element = element.parentElement;
+      }
+    }
+
+    // Everything above this line is covered: the header and the pinned player.
+    #inset(): number {
+      return Math.max(64, this.#root.getBoundingClientRect().bottom);
+    }
+
+    #followTo(range: Range | null, force: boolean): void {
+      if (!(range && (this.#following || force))) {
+        return;
+      }
+      const rect = range.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        return;
+      }
+      const delta = followScroll(rect, this.#inset(), window.innerHeight);
+      if (delta === 0) {
+        return;
+      }
+      this.#ownScrollUntil = performance.now() + OWN_SCROLL_MS;
+      window.scrollBy({
+        behavior: reducedMotion() ? "auto" : "smooth",
+        top: delta,
+      });
+    }
+
+    // Scrolling away from the sentence stops the page from following it
+    // (the audio carries on); scrolling back to it picks following up again.
+    #onScroll(): void {
+      if (!this.#started || performance.now() < this.#ownScrollUntil) {
+        return;
+      }
+      const range = this.#rangeAt(this.#index);
+      if (!range) {
+        return;
+      }
+      const inView = isInView(
+        range.getBoundingClientRect(),
+        this.#inset(),
+        window.innerHeight
+      );
+      this.#setFollowing(inView);
+    }
+
+    #setFollowing(following: boolean): void {
+      this.#following = following;
+      this.#follow.classList.toggle("hidden", following);
+      this.#follow.classList.toggle("inline-flex", !following);
+    }
+  }
+
+  let active: Player | null = null;
+
+  const mount = (): void => {
+    active?.destroy();
+    active = null;
+    const root = document.querySelector<HTMLElement>(
+      "[data-blume-narration-player]"
+    );
+    const article = root?.closest("article");
+    if (!(root && article instanceof HTMLElement)) {
+      return;
+    }
+    const player = new Player(root, article);
+    active = player;
+    // Reading the page waits for an idle moment so it never delays the
+    // page's own first paint.
+    const run = () => {
+      if (active === player) {
+        void player.init();
+      }
+    };
+    if ("requestIdleCallback" in window) {
+      window.requestIdleCallback(run, { timeout: 1500 });
+    } else {
+      setTimeout(run, 200);
+    }
+  };
+
+  mount();
+  // Opening another page stops the narration.
+  document.addEventListener("astro:before-swap", () => {
+    active?.destroy();
+    active = null;
+  });
+  document.addEventListener("astro:after-swap", mount);
+</script>