(null);
const width = useSceneWidth(sceneRef);
- const { state, dispatch, lastAction, onKeyDown } = usePlayer(trace);
+ const [narrating, setNarrating] = useState(false);
+ // A host withdrawing the optional feature also discards consent,
+ // including when it later re-enables the control on this instance.
+ useEffect(() => { if (!narration) setNarrating(false); }, [narration]);
+ const { state, dispatch, lastAction, seekRevision, onKeyDown } = usePlayer(trace, narration && narrating);
const [sound, setSound] = useState(sonification?.enabled ?? false);
const [fullscreen, setFullscreen] = useState(false);
const [fullscreenAvailable, setFullscreenAvailable] = useState(false);
@@ -65,6 +74,12 @@ export function ThroughlinePlayer({
const captionId = useId();
const keyboardHelpId = useId();
const frame = trace.frames[state.step] ?? trace.frames[0];
+ const spokenText = frame ? narrationText(frame, trace, guidance) : "";
+ const voice = useNarration({
+ trace, step: state.step, text: spokenText, seekRevision, speed: state.speed,
+ playing: state.playing, enabled: narration && narrating, setEnabled: setNarrating,
+ dispatch, offered: narration && !!frame,
+ });
useEffect(() => {
const syncFullscreen = () => {
@@ -148,6 +163,7 @@ export function ThroughlinePlayer({
{summary}
+ {voice.error && narration && {voice.error}
}
{fullscreenError && (
{fullscreenError}
@@ -189,6 +205,11 @@ export function ThroughlinePlayer({
setSound((enabled) => !enabled) }
diff --git a/src/react/speech-owner.ts b/src/react/speech-owner.ts
new file mode 100644
index 0000000..c2b52a5
--- /dev/null
+++ b/src/react/speech-owner.ts
@@ -0,0 +1,45 @@
+/**
+ * The Web Speech synthesis queue is browser-global, not component-local.
+ * Coordinate Throughline instances sharing one engine. New narration takes
+ * over; the displaced player is paused and its narration is switched off.
+ *
+ * External scripts can still call speechSynthesis.cancel(). Such calls are
+ * reported by the utterance error handler as interruptions.
+ */
+export interface SpeechOwner {
+ onDisplaced(): void;
+}
+
+const owners = new WeakMap();
+
+export function ownsSpeech(engine: SpeechSynthesis, owner: SpeechOwner): boolean {
+ return owners.get(engine) === owner;
+}
+
+export function acquireSpeech(engine: SpeechSynthesis, owner: SpeechOwner): void {
+ const previous = owners.get(engine);
+ if (previous === owner) return;
+ if (previous) {
+ // Drop ownership BEFORE notifying the old player. Its cleanup must
+ // never cancel the new player's utterance.
+ owners.delete(engine);
+ previous.onDisplaced();
+ // cancel() clears the browser-wide queue, so only the coordinator
+ // may invoke it when replacing an existing Throughline owner.
+ try { engine.cancel(); } catch { /* Let speak() report failure. */ }
+ }
+ owners.set(engine, owner);
+}
+
+/** Give up ownership after a natural completion or error, without canceling
+ * another application's speech queue. */
+export function releaseSpeech(engine: SpeechSynthesis, owner: SpeechOwner): void {
+ if (ownsSpeech(engine, owner)) owners.delete(engine);
+}
+
+/** Stop the current Throughline owner. Never cancel another instance's voice. */
+export function cancelOwnedSpeech(engine: SpeechSynthesis, owner: SpeechOwner): void {
+ if (!ownsSpeech(engine, owner)) return;
+ owners.delete(engine);
+ try { engine.cancel(); } catch { /* Stopping optional audio is best-effort. */ }
+}
diff --git a/src/react/use-narration.ts b/src/react/use-narration.ts
new file mode 100644
index 0000000..1144ff8
--- /dev/null
+++ b/src/react/use-narration.ts
@@ -0,0 +1,211 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { Trace } from "../model.js";
+import type { SeekAction, Speed } from "../seek.js";
+import {
+ acquireSpeech,
+ cancelOwnedSpeech,
+ ownsSpeech,
+ releaseSpeech,
+ type SpeechOwner,
+} from "./speech-owner.js";
+
+type Session = {
+ trace: Trace;
+ step: number;
+ text: string;
+ seekRevision: number;
+ utterance: SpeechSynthesisUtterance;
+ engine: SpeechSynthesis;
+ owner: SpeechOwner;
+ ended: boolean;
+ failed: boolean;
+};
+
+type NarrationInput = {
+ trace: Trace;
+ step: number;
+ text: string;
+ seekRevision: number;
+ speed: Speed;
+ playing: boolean;
+ enabled: boolean;
+ setEnabled: (enabled: boolean) => void;
+ dispatch: (action: SeekAction) => void;
+ offered: boolean;
+};
+
+function speechEngine(): SpeechSynthesis | null {
+ if (typeof window === "undefined" || typeof SpeechSynthesisUtterance === "undefined") return null;
+ return window.speechSynthesis ?? null;
+}
+
+/**
+ * React-only speech clock. Authored-frame identity, text and explicit seek
+ * generations invalidate old utterances. Only a completed current utterance
+ * may dispatch a tick. This controller does not expose speech to the core.
+ */
+export function useNarration({
+ trace, step, text, seekRevision, speed, playing, enabled,
+ setEnabled, dispatch, offered,
+}: NarrationInput): {
+ available: boolean;
+ error: string | null;
+ toggle: () => void;
+} {
+ const [available, setAvailable] = useState(false);
+ const [error, setError] = useState(null);
+ const current = useRef(null);
+ const latest = useRef({
+ trace, step, text, seekRevision, speed, playing, enabled, dispatch, setEnabled,
+ });
+ latest.current = {
+ trace, step, text, seekRevision, speed, playing, enabled, dispatch, setEnabled,
+ };
+ const previous = useRef({ trace, step, text, seekRevision, playing, enabled });
+
+ const stop = useCallback(() => {
+ const voice = current.current;
+ current.current = null;
+ if (!voice) return;
+ // Own cancellations are silent: detach handlers before calling the
+ // global API, which may synchronously report "interrupted".
+ voice.utterance.onend = null;
+ voice.utterance.onerror = null;
+ cancelOwnedSpeech(voice.engine, voice.owner);
+ }, []);
+
+ const start = useCallback(() => {
+ const engine = speechEngine();
+ if (!engine) {
+ setError("Caption narration is unavailable in this browser.");
+ latest.current.dispatch({ type: "pause" });
+ return;
+ }
+ stop();
+ const state = latest.current;
+ if (!state.text) return;
+ try {
+ const utterance = new SpeechSynthesisUtterance(state.text);
+ utterance.rate = state.speed;
+ const session: Session = {
+ trace: state.trace, step: state.step, text: state.text,
+ seekRevision: state.seekRevision, utterance, engine,
+ owner: {
+ onDisplaced: () => {
+ if (current.current !== session) return;
+ // Acquiring another player's voice has already removed
+ // our ownership. Do NOT cancel() here.
+ current.current = null;
+ utterance.onend = null;
+ utterance.onerror = null;
+ session.failed = true;
+ setError("Narration paused: another Throughline player began speaking. Enable narration again to take over.");
+ latest.current.setEnabled(false);
+ latest.current.dispatch({ type: "pause" });
+ },
+ },
+ ended: false, failed: false,
+ };
+ acquireSpeech(engine, session.owner);
+ current.current = session;
+ utterance.onend = () => {
+ if (current.current !== session || session.failed ||
+ !ownsSpeech(session.engine, session.owner)) return;
+ session.ended = true;
+ releaseSpeech(session.engine, session.owner);
+ const next = latest.current;
+ // Updated guidance and same-step seeks invalidate an old
+ // callback even before React has run its effect cleanup.
+ if (next.enabled && next.trace === session.trace &&
+ next.step === session.step && next.text === session.text &&
+ next.seekRevision === session.seekRevision && next.playing) {
+ next.dispatch({ type: "tick" });
+ }
+ };
+ utterance.onerror = (event) => {
+ if (current.current !== session || session.failed) return;
+ // An event that reaches this handler is never our own cancel:
+ // the owned cancellation removed the handlers first.
+ session.ended = true;
+ session.failed = true;
+ releaseSpeech(session.engine, session.owner);
+ setError(
+ "Speech stopped (" + event.error +
+ "). Narration playback is paused. Turn narration off and on to retry.",
+ );
+ latest.current.dispatch({ type: "pause" });
+ };
+ setError(null);
+ if (engine.paused) engine.resume();
+ engine.speak(utterance);
+ } catch {
+ stop();
+ setError("Speech synthesis failed. Narration stopped without advancing the timeline.");
+ latest.current.dispatch({ type: "pause" });
+ }
+ }, [stop]);
+
+ useEffect(() => {
+ setAvailable(offered && Boolean(speechEngine()));
+ }, [offered]);
+
+ // A changed frame, corrected authored guidance, or an explicit seek
+ // (including a seek to the current frame) starts a fresh utterance.
+ useEffect(() => {
+ if (!enabled || !offered) { stop(); return; }
+ const voice = current.current;
+ if (!voice || voice.trace !== trace || voice.step !== step ||
+ voice.text !== text || voice.seekRevision !== seekRevision) {
+ start();
+ }
+ }, [enabled, offered, trace, step, text, seekRevision, start, stop]);
+
+ // The speech clock and the player's Play/Pause control share one state.
+ // Pause/resume only if this instance still owns the global speech queue.
+ useEffect(() => {
+ const old = previous.current;
+ previous.current = { trace, step, text, seekRevision, playing, enabled };
+ if (!enabled || old.trace !== trace || old.step !== step ||
+ old.text !== text || old.seekRevision !== seekRevision ||
+ old.enabled !== enabled || old.playing === playing) return;
+ const voice = current.current;
+ if (!voice) return;
+ if (voice.failed) {
+ if (playing) dispatch({ type: "pause" });
+ return;
+ }
+ if (!playing && !voice.ended) {
+ if (ownsSpeech(voice.engine, voice.owner)) {
+ try { voice.engine.pause(); } catch { /* No timeline mutation. */ }
+ }
+ } else if (playing) {
+ if (voice.ended) {
+ dispatch({ type: "tick" });
+ } else if (ownsSpeech(voice.engine, voice.owner)) {
+ try { voice.engine.resume(); } catch {
+ setError("Speech could not resume.");
+ dispatch({ type: "pause" });
+ }
+ }
+ }
+ }, [trace, step, text, seekRevision, playing, enabled, dispatch]);
+
+ useEffect(() => () => stop(), [stop]);
+
+ const toggle = useCallback(() => {
+ if (latest.current.enabled) {
+ stop();
+ setError(null);
+ setEnabled(false);
+ } else if (speechEngine()) {
+ // Speak within the user gesture, not just the following effect:
+ // browsers may require activation to start the first utterance.
+ setEnabled(true);
+ start();
+ } else {
+ setError("Caption narration is unavailable in this browser.");
+ }
+ }, [setEnabled, start, stop]);
+
+ return { available, error, toggle };
+}
diff --git a/src/react/use-player.ts b/src/react/use-player.ts
index 500d307..06aed3e 100644
--- a/src/react/use-player.ts
+++ b/src/react/use-player.ts
@@ -10,10 +10,12 @@ import {
stepDelayMs,
} from "../seek.js";
-export function usePlayer(trace: Trace): {
+export function usePlayer(trace: Trace, externalClock = false): {
state: SeekState;
dispatch: React.Dispatch;
lastAction: SeekAction | null;
+ /** Increments on every explicit seek, including seeking the current frame. */
+ seekRevision: number;
onKeyDown: React.KeyboardEventHandler;
} {
const [identity, setIdentity] = useState(trace);
@@ -25,8 +27,10 @@ export function usePlayer(trace: Trace): {
// Track how a frame was reached without extending the public seek state.
// Timeline seeks (even an adjacent one) never count as forward playback.
const lastAction = useRef(null);
+ const [seekRevision, bumpSeekRevision] = useState(0);
const dispatch = useCallback>((action) => {
lastAction.current = action;
+ if (action.type === "step") bumpSeekRevision((revision) => revision + 1);
reducerDispatch(action);
}, []);
// Reset during render, before any child can read a stale frame index.
@@ -35,13 +39,13 @@ export function usePlayer(trace: Trace): {
dispatch({ type: "reset", max: Math.max(0, trace.frames.length - 1) });
}
useEffect(() => {
- if (!state.playing) return;
+ if (!state.playing || externalClock) return;
const timer = setInterval(
() => dispatch({ type: "tick" }),
stepDelayMs(BASE_STEP_MS, state.speed),
);
return () => clearInterval(timer);
- }, [state.playing, state.speed]);
+ }, [state.playing, state.speed, externalClock]);
const onKeyDown: React.KeyboardEventHandler = (event) => {
if (event.target !== event.currentTarget) return;
if (["ArrowRight", "ArrowLeft", "Home", "End"].includes(event.key)) {
@@ -58,7 +62,7 @@ export function usePlayer(trace: Trace): {
dispatch({ type: "toggle" });
}
};
- return { state, dispatch, lastAction: lastAction.current, onKeyDown };
+ return { state, dispatch, lastAction: lastAction.current, seekRevision, onKeyDown };
}
export function useSceneWidth(
diff --git a/src/styles/throughline.css b/src/styles/throughline.css
index cbe92f8..3960a22 100644
--- a/src/styles/throughline.css
+++ b/src/styles/throughline.css
@@ -563,7 +563,9 @@
stroke-linecap: round;
stroke-linejoin: round;
}
-.thl-controls .thl-sound[aria-pressed="true"] { color: var(--thl-focus); background: var(--thl-focus-bg); }
+.thl-controls .thl-sound[aria-pressed="true"],
+.thl-controls .thl-narration[aria-pressed="true"] { color: var(--thl-focus); background: var(--thl-focus-bg); }
+.thl-narration-error { margin: 0; font-size: 0.8125rem; color: var(--thl-change); }
.thl-timeline {
appearance: none;
display: block;
@@ -645,6 +647,32 @@
.thl-caption-trailing { gap: 0.375rem; }
.thl-caption-content { max-height: min(12rem, 30vh); }
}
+/* Two optional audio buttons increase the minimum toolbar width. Split
+ only dual-audio players so regular 375px previews keep their compact row.
+ The query uses the player's CONTENT width, not the viewport width. */
+@container (max-width: 360px) {
+ .thl-controls:has(.thl-narration):has(.thl-sound) {
+ grid-template-columns: minmax(0, 1fr);
+ }
+ .thl-controls:has(.thl-narration):has(.thl-sound) .thl-timeline {
+ grid-column: 1; grid-row: 1;
+ }
+ .thl-controls:has(.thl-narration):has(.thl-sound) .thl-transport {
+ grid-column: 1; grid-row: 2;
+ }
+ .thl-controls:has(.thl-narration):has(.thl-sound) .thl-utilities {
+ grid-column: 1; grid-row: 3; justify-content: flex-start;
+ }
+}
+/* Restore the generic narrow-content fallback, independently of optional
+ audio controls. One audio button can also exceed the transport row's
+ available width below 300px; the dual-audio 360px rule remains above. */
+@container (max-width: 300px) {
+ .thl-controls { grid-template-columns: minmax(0, 1fr); }
+ .thl-timeline { grid-column: 1; grid-row: 1; }
+ .thl-transport { grid-column: 1; grid-row: 2; }
+ .thl-utilities { grid-column: 1; grid-row: 3; justify-content: flex-start; }
+}
@keyframes thl-draw { from { stroke-dashoffset: 1; } to { stroke-dashoffset: 0; } }
@keyframes thl-fade { from { opacity: 0; } }
@keyframes thl-flash {