@supersuit/artifacts 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.26.0
+
+**Read-along that leaves the reader in charge.** A tap on any word started the audio, and while it
+played the page scrolled back to the lit word every time it left the screen, pulling a reader who
+had scrolled ahead back to the voice.
+
+- A tap on a word while the audio is paused shows a small **Play from here** bar beside the word
+  (it moves with the page, closes with × or Escape); pressing it plays from that word. A tap while
+  it plays jumps straight there.
+- The page follows the voice until the reader scrolls on their own (wheel, touch, or a scrolling
+  key: arrows, Page Up/Down, Home, End, space outside a text field). It then stays where they are,
+  and a floating **Back to the voice** button scrolls back to the lit word and resumes following.
+  Pressing play, or tapping a word while it plays, also resumes following.
+- New export `isUserScrollKey`.
+- DETECTOR: on a narrated page, pause and tap a word. Audio starting at once means 0.25.0 or
+  earlier.
+- REMEDY: update the dependency. No config change.
+- Tests: `artifact-reader-controls.test.tsx` (offer when paused and play from the word; jump when
+  playing; scrolling while playing releases the page and the button brings it back; scrolling while
+  paused changes nothing; the scroll keys). `test:packed` green.
+
 ## 0.25.0
 
 **A page can play a Supersuit Session demo inline: the ```simulator block.** A book or guide that

package/lib/reader/artifact-reader.d.ts

@@ -15,6 +15,9 @@ export declare function seekableWord(target: Element | null): HTMLSpanElement |
 /** The word to light at `now`, or -1. Nothing lights until narration has started: the first
  *  word begins at 0, so an untouched page would otherwise sit with its first word highlighted. */
 export declare function litWordIndex(words: WordTiming[], now: number, started: boolean): number;
+/** Whether a key press is the reader scrolling the page themselves. Space scrolls only outside a
+ *  field that takes text. */
+export declare function isUserScrollKey(key: string, target: EventTarget | null): boolean;
 export declare function ArtifactReader({ src, words, rootId, label, accent, ground, }: {
     src: string;
     words: WordTiming[];

package/lib/reader/artifact-reader.js

@@ -1,10 +1,13 @@
 'use client';
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // Speechify-style read-along for a published artifact. The narration was generated
 // from the same rendered text this page shows (see lib/artifacts/narration.ts), so
 // the highlighter walks the DOM in reading order, wraps each word, and aligns that
 // sequence to the word timings by normalized token, resyncing within a short window
-// when the two disagree. Click a word to seek; the bar at the bottom plays and paces.
+// when the two disagree. Tap a word while it plays to jump there; tap one while it is paused and a
+// small bar offers to play from it, so reading and tapping never starts the audio by surprise. While
+// it plays the page follows the voice, until the reader scrolls on their own: then it leaves them
+// where they are and shows a button that brings them back to the voice.
 import { useEffect, useRef, useState } from 'react';
 import { nextRate, PlayerBar } from './player-bar.js';
 const SKIP = '[data-nospeak], [data-artifact-links], pre, [data-footnotes], sup, img, style, script';
@@ -130,6 +133,17 @@ function fmt(t) {
     const s = Math.floor(t % 60);
     return `${m}:${s.toString().padStart(2, '0')}`;
 }
+const SCROLL_KEYS = new Set(['ArrowDown', 'ArrowUp', 'PageDown', 'PageUp', 'Home', 'End', ' ']);
+/** Whether a key press is the reader scrolling the page themselves. Space scrolls only outside a
+ *  field that takes text. */
+export function isUserScrollKey(key, target) {
+    if (!SCROLL_KEYS.has(key))
+        return false;
+    const el = target;
+    if (el && (el.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName ?? '')))
+        return false;
+    return true;
+}
 export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
     const narrator = label;
     const audioRef = useRef(null);
@@ -141,6 +155,15 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
     const [t, setT] = useState(0);
     const [dur, setDur] = useState(0);
     const [rate, setRate] = useState(1);
+    // Whether the page follows the voice. A reader scrolling on their own turns it off; the button
+    // that appears, a word tapped while playing, or pressing play turns it back on.
+    const [following, setFollowing] = useState(true);
+    const followingRef = useRef(true);
+    const playingRef = useRef(false);
+    const follow = (on) => { followingRef.current = on; setFollowing(on); };
+    // The Play from here bar, beside the word a paused reader tapped, in page coordinates so it
+    // stays with the word when they scroll.
+    const [offer, setOffer] = useState(null);
     useEffect(() => {
         const root = document.getElementById(rootId);
         if (!root)
@@ -154,12 +177,50 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
             const idx = mapRef.current.indexOf(el);
             if (idx === -1 || !audioRef.current)
                 return;
-            audioRef.current.currentTime = words[idx].s;
-            void audioRef.current.play();
+            if (playingRef.current) {
+                audioRef.current.currentTime = words[idx].s;
+                follow(true);
+                setOffer(null);
+                return;
+            }
+            const r = el.getBoundingClientRect();
+            setOffer({ idx, top: r.bottom + window.scrollY + 6, left: Math.max(8, r.left + window.scrollX) });
         };
         root.addEventListener('click', onClick);
         return () => root.removeEventListener('click', onClick);
     }, [rootId, words]);
+    // The reader scrolling on their own, while it plays, stops the page following the voice.
+    useEffect(() => {
+        const mine = () => { if (playingRef.current && followingRef.current)
+            follow(false); };
+        const onKey = (e) => { if (isUserScrollKey(e.key, e.target))
+            mine(); };
+        const onEsc = (e) => { if (e.key === 'Escape')
+            setOffer(null); };
+        window.addEventListener('wheel', mine, { passive: true });
+        window.addEventListener('touchmove', mine, { passive: true });
+        window.addEventListener('keydown', onKey);
+        window.addEventListener('keydown', onEsc);
+        return () => {
+            window.removeEventListener('wheel', mine);
+            window.removeEventListener('touchmove', mine);
+            window.removeEventListener('keydown', onKey);
+            window.removeEventListener('keydown', onEsc);
+        };
+    }, []);
+    const playFrom = (idx) => {
+        const a = audioRef.current;
+        if (!a)
+            return;
+        a.currentTime = words[idx].s;
+        follow(true);
+        setOffer(null);
+        void a.play();
+    };
+    const backToVoice = () => {
+        follow(true);
+        litRef.current?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    };
     useEffect(() => {
         const a = audioRef.current;
         if (!a)
@@ -174,7 +235,7 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
                 litRef.current?.classList.remove('artifact-word-lit');
                 el?.classList.add('artifact-word-lit');
                 litRef.current = el;
-                if (el && playing) {
+                if (el && playing && followingRef.current) {
                     const r = el.getBoundingClientRect();
                     if (r.top < 80 || r.bottom > window.innerHeight - 140) {
                         el.scrollIntoView({ block: 'center', behavior: 'smooth' });
@@ -197,10 +258,13 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
     };
     return (_jsxs(_Fragment, { children: [_jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => {
                     startedRef.current = true;
+                    playingRef.current = true;
                     setPlaying(true);
+                    setOffer(null);
+                    follow(true);
                 }, onSeeking: () => {
                     startedRef.current = true;
-                }, onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx(PlayerBar, { playing: playing, onToggle: toggle, label: narrator, accent: accent, ground: ground, value: t, max: dur, step: 0.1, onSeek: (v) => {
+                }, onPause: () => { playingRef.current = false; setPlaying(false); }, onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), offer ? (_jsxs("div", { "data-nospeak": true, className: "absolute z-50 flex items-center gap-1 rounded-full border px-1 py-1 text-sm shadow-lg", style: { top: offer.top, left: offer.left, background: ground, borderColor: accent }, children: [_jsx("button", { type: "button", "data-play-from-here": true, onClick: () => playFrom(offer.idx), className: "rounded-full px-3 py-1 font-medium", style: { background: accent, color: ground }, children: "\u25B6 Play from here" }), _jsx("button", { type: "button", "aria-label": "Close", onClick: () => setOffer(null), className: "px-2 opacity-70", children: "\u00D7" })] })) : null, playing && !following ? (_jsx("button", { type: "button", "data-follow-voice": true, "data-nospeak": true, onClick: backToVoice, className: "fixed left-1/2 z-50 -translate-x-1/2 rounded-full px-4 py-2 text-sm font-medium shadow-lg", style: { bottom: 'calc(env(safe-area-inset-bottom, 0px) + 5.5rem)', background: accent, color: ground }, children: "Back to the voice" })) : null, _jsx(PlayerBar, { playing: playing, onToggle: toggle, label: narrator, accent: accent, ground: ground, value: t, max: dur, step: 0.1, onSeek: (v) => {
                     if (audioRef.current)
                         audioRef.current.currentTime = v;
                 }, progress: `${fmt(t)} / ${fmt(dur)}`, rate: rate, onRate: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",