@supersuit/artifacts 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 `@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
+wanted to show a session had to send readers away to another site.
+
+```simulator
+scenario: diane-meeting-prep
+caption: Step into the hour before Diane's first meeting. Press Start.
+height: 760px            # optional, default 720px
+```
+
+- Same syntax as the Superskills book's reader, so one block works in both. `scenario` is
+  lowercase letters, digits and dashes; `caption` is required; `height` is `NNNpx`. A malformed
+  block is refused at publish with the line, like a checklist.
+- The HOST names the demo: new `ArtifactRoutesConfig.simulatorEmbed` (an https embed page, e.g.
+  `https://example.com/simulator/embed`). The block draws as a lazy-loaded frame on
+  `<embed>?scenario=<id>&timeline=off`, with the caption under it. No default: a host without a
+  demo draws the caption alone, never the block's source as code.
+- New exports `parseSimulatorFence`, `simulatorSrc`, `SimulatorBlock`; `ArtifactMarkdown` takes
+  `simulator?: { embed }`.
+- DETECTOR: publish a page with a ```simulator block. A code block showing `scenario:` means the
+  host is on 0.24.0 or earlier, or has not set `simulatorEmbed`.
+- REMEDY: update the dependency and set `simulatorEmbed` in the host's routes config.
+- Tests: `simulator.test.ts` (parse, defaults, refusals with lines, https-only embed),
+  `widgets.test.ts` (refused at publish, passes when well formed), `render.test.tsx` (frame when the
+  host names a demo, caption only when not, never a code block). `test:packed` green.
+
 ## 0.24.0
 
 **A reader is asked for their name when they comment, so the owner can credit the feedback.**

package/lib/artifacts/index.d.ts

@@ -13,6 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor, type StateStore, type StateEntry, type Writer } from './state-store.js';
 export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
+export { parseSimulatorFence, simulatorSrc, type SimulatorBlock } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence, type ChecklistBlock, type ChecklistItem, type ChecklistValue } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment, type CommentsMode, type CommentsVisible, type CommentValue } from './comments.js';

package/lib/artifacts/index.js

@@ -13,6 +13,7 @@ export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeCh
 export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
 export { stateView, responsesOf, responsesCsv } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
+export { parseSimulatorFence, simulatorSrc } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment } from './comments.js';

package/lib/artifacts/render.d.ts

@@ -4,6 +4,9 @@ import { type Heading } from './widgets.js';
 import { type Definition } from './definitions.js';
 export declare function isReachableHref(href: unknown): href is string;
 export declare function artifactUrlTransform(url: string): string;
+type SimulatorCtx = {
+    embed: string;
+};
 /** A pack's figure resolver (BrandPack.figure). */
 export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps> | undefined;
 /** The page's top-level sections: every heading among the body's top-level blocks at the
@@ -11,7 +14,7 @@ export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps>
 export declare function sectionOutline(markdown: string, headings?: Heading[]): SectionOutline[];
 /** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
  *  page carries a ```notes block. */
-export declare function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, }: {
+export declare function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, }: {
     markdown: string;
     /** The page a ```checklist keeps its ticks under, and whether its Send can reach the owner
      *  (a host that keeps answers, on a page that declares the slot). On a page whose checklists
@@ -33,4 +36,7 @@ export declare function ArtifactMarkdown({ markdown, notes, checklist, definitio
     };
     /** Terms to define inline (front matter `definitions:`): the first occurrence of each is underlined. */
     definitions?: Definition[];
+    /** The host's Supersuit Session demo, for ```simulator blocks. Without it a block shows its caption only. */
+    simulator?: SimulatorCtx;
 }): import("react").JSX.Element;
+export {};

package/lib/artifacts/render.js

@@ -16,6 +16,7 @@ import { unified } from 'unified';
 import { blocksOf, checklistSyncs, checklistsOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { Checklist } from '../widgets/checklist.js';
+import { parseSimulatorFence, simulatorSrc } from './simulator.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
@@ -94,6 +95,15 @@ function InlineAudio({ src, label }) {
     const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
+/** A ```simulator block: the demo in a frame when the host has one, its caption alone when it does
+ *  not, and nothing when the block does not parse (a page published before validation existed). */
+function SimulatorFence({ source, ctx }) {
+    const r = parseSimulatorFence(source.replace(/\n$/, ''), 0);
+    if (!r.ok)
+        return null;
+    const src = ctx ? simulatorSrc(ctx.embed, r.block.scenario) : null;
+    return (_jsxs("figure", { "data-artifact-simulator": true, className: "my-8", children: [src ? (_jsx("iframe", { src: src, title: r.block.caption, loading: "lazy", allow: "microphone; autoplay; fullscreen", className: "block w-full rounded-xl border border-[color:var(--a-line)]", style: { height: r.block.height, border: 0 } })) : null, _jsx("figcaption", { className: "mt-2 text-sm opacity-80", children: r.block.caption })] }));
+}
 /** The one image a paragraph holds and nothing else (whitespace aside), or null. */
 function soleImage(node) {
     const kids = (node?.children ?? []).filter((c) => !(c.type === 'text' && !c.value?.trim()));
@@ -122,7 +132,7 @@ function ChecklistFence({ line, ctx }) {
         return null;
     return (_jsx(Checklist, { items: c.items.map((it) => ({ id: it.id, title: checklistMarkdown(it.text, true), description: it.description ? checklistMarkdown(it.description, false) : null })), artifactId: ctx.artifactId, send: ctx.send && ctx.artifactId && !ctx.sync ? c.send : undefined, sync: ctx.sync && !!ctx.artifactId, owner: ctx.owner, accent: ctx.accent }));
 }
-function baseComponents(block, figure, checklists) {
+function baseComponents(block, figure, checklists, simulator) {
     return {
         p: ({ node, children }) => {
             // An image alone in its paragraph that the pack draws itself replaces the paragraph, so the
@@ -162,6 +172,8 @@ function baseComponents(block, figure, checklists) {
             // answers) it draws nothing: its settings are not prose and never shown as code.
             if (lang === 'notes')
                 return null;
+            if (lang === 'simulator')
+                return _jsx(SimulatorFence, { source: textOf(children), ctx: simulator });
             if (!className) {
                 return _jsx("code", { className: "rounded bg-[color:var(--a-surface-strong)] px-1.5 py-0.5 text-[0.9em] text-[color:var(--a-strong)]", children: children });
             }
@@ -171,7 +183,7 @@ function baseComponents(block, figure, checklists) {
             // A links fence renders its own block; do not wrap it in <pre>.
             const inner = Array.isArray(children) ? children[0] : children;
             const cls = inner?.props?.className ?? '';
-            if (/language-(links|notes|checklist)/.test(cls))
+            if (/language-(links|notes|checklist|simulator)/.test(cls))
                 return _jsx(_Fragment, { children: children });
             return (_jsx("pre", { ...block(node), "data-artifact-code": true, 
                 // whitespace-pre-wrap, because a fence here usually holds PROSE meant to be pasted
@@ -204,20 +216,20 @@ const HEADING_CLASS = {
 };
 /** Components for any page: every heading gets its slug as an id, the one headingsOf derived,
  *  so a contents link and a note both land on it. */
-function pageComponents(headings, block, figure, checklists) {
+function pageComponents(headings, block, figure, checklists, simulator) {
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function Heading({ node, children }) {
         const Tag = `h${depth}`;
         const h = byLine.get(node?.position?.start.line ?? -1);
         return _jsx(Tag, { id: h?.slug, ...block(node), className: HEADING_CLASS[depth], children: children });
     };
-    return { ...baseComponents(block, figure, checklists), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
+    return { ...baseComponents(block, figure, checklists, simulator), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
 }
 /** Components for a page with a notes block: every heading gets its slug as an id, a note
  *  control, and its notes after it. The heading is found by its source line, so the slug is the
  *  one headingsOf derived, the same one a note stores. */
-function notesComponents(headings, block, figure, checklists) {
-    const components = baseComponents(block, figure, checklists);
+function notesComponents(headings, block, figure, checklists, simulator) {
+    const components = baseComponents(block, figure, checklists, simulator);
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function NotedHeading({ node, children }) {
         const Tag = `h${depth}`;
@@ -296,7 +308,7 @@ const DEFINED_TERM_CSS = '.artifact-defined-term{text-decoration-line:underline;
     'clip:rect(0,0,0,0);white-space:nowrap;border:0}';
 /** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
  *  page carries a ```notes block. */
-export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, }) {
+export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, }) {
     const on = !!notes && hasNotesWidget(markdown);
     const headings = headingsOf(markdown);
     const blocks = blocksOf(markdown);
@@ -313,7 +325,7 @@ export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Sect
         // page whose checklists sync, that same slot is the shared set, so it turns sync on instead.
         ? { byLine: lists, artifactId: checklist?.artifactId, send: !!checklist?.send, sync: !!checklist?.send && checklistSyncs(lists.values()), owner: checklist?.owner, accent: checklist?.accent }
         : undefined;
-    const components = on ? notesComponents(headings, block, figure, checklists) : pageComponents(headings, block, figure, checklists);
+    const components = on ? notesComponents(headings, block, figure, checklists, simulator) : pageComponents(headings, block, figure, checklists, simulator);
     if (outline.length)
         components.section = sectionComponent(Section, outline, block);
     const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, urlTransform: artifactUrlTransform, children: markdown }));

package/lib/artifacts/simulator.d.ts

@@ -0,0 +1,17 @@
+export type SimulatorBlock = {
+    scenario: string;
+    caption: string;
+    height: string;
+};
+/** Parses a simulator fence's body. `line` is the line the fence opens on, so every error names
+ *  the line the author sees. */
+export declare function parseSimulatorFence(value: string, line: number): {
+    ok: true;
+    block: SimulatorBlock;
+} | {
+    ok: false;
+    error: string;
+};
+/** The address the player loads: the host's embed page, the scenario, the timeline off. Null for
+ *  an embed address that is not https, so a misconfigured host frames nothing. */
+export declare function simulatorSrc(embed: string, scenario: string): string | null;

package/lib/artifacts/simulator.js

@@ -0,0 +1,59 @@
+// The ```simulator fence: a Supersuit Session demo played inline on the page. The block names a
+// scenario and a caption; the HOST names the demo's embed page (ArtifactRoutesConfig.simulatorEmbed),
+// so this public package points at nobody's service by default, and a host without a demo draws
+// the caption alone rather than the block's source as code.
+//
+//   ```simulator
+//   scenario: diane-meeting-prep
+//   caption: Step into the hour before Diane's first meeting. Press Start.
+//   height: 760px            # optional, default 720px
+//   ```
+//
+// The same syntax the Superskills book's reader takes, so one block works in both.
+const SCENARIO = /^[a-z0-9-]+$/;
+const HEIGHT = /^\d{3,4}px$/;
+const KEYS = ['scenario', 'caption', 'height'];
+/** Parses a simulator fence's body. `line` is the line the fence opens on, so every error names
+ *  the line the author sees. */
+export function parseSimulatorFence(value, line) {
+    const got = {};
+    const rows = value ? value.split('\n') : [];
+    for (let i = 0; i < rows.length; i++) {
+        const raw = rows[i].trim();
+        if (!raw || raw.startsWith('#'))
+            continue;
+        const at = line + 1 + i;
+        const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(raw);
+        if (!m)
+            return { ok: false, error: `line ${at}: the simulator block takes lines like "scenario: <id>"` };
+        const key = m[1];
+        if (!KEYS.includes(key))
+            return { ok: false, error: `line ${at}: the simulator block has an unknown key: ${m[1]}` };
+        got[key] = { v: m[2].replace(/\s+#.*$/, '').trim(), at };
+    }
+    if (!got.scenario)
+        return { ok: false, error: `line ${line}: the simulator block needs a scenario` };
+    if (!SCENARIO.test(got.scenario.v))
+        return { ok: false, error: `line ${got.scenario.at}: a simulator scenario is lowercase letters, digits and dashes` };
+    if (!got.caption?.v)
+        return { ok: false, error: `line ${line}: the simulator block needs a caption, the line a reader sees under the demo` };
+    if (got.height && !HEIGHT.test(got.height.v))
+        return { ok: false, error: `line ${got.height.at}: a simulator height is a number of pixels, like 760px` };
+    return { ok: true, block: { scenario: got.scenario.v, caption: got.caption.v, height: got.height?.v ?? '720px' } };
+}
+/** The address the player loads: the host's embed page, the scenario, the timeline off. Null for
+ *  an embed address that is not https, so a misconfigured host frames nothing. */
+export function simulatorSrc(embed, scenario) {
+    let u;
+    try {
+        u = new URL(embed);
+    }
+    catch {
+        return null;
+    }
+    if (u.protocol !== 'https:')
+        return null;
+    u.searchParams.set('scenario', scenario);
+    u.searchParams.set('timeline', 'off');
+    return u.toString();
+}

package/lib/artifacts/widgets.js

@@ -16,6 +16,7 @@ import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import { blockId } from './anchor.js';
 import { MAX_NOTE_CHARS, NOTES_SLOT } from './notes-place.js';
+import { parseSimulatorFence } from './simulator.js';
 import { CHECKLIST_SLOT, assignChecklistIds, parseChecklistFence } from './checklist.js';
 export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes } from './notes-place.js';
 /** Widgets the design names and this version does not draw yet. A fence using one is refused at
@@ -100,6 +101,13 @@ export function scanWidgets(body, offset) {
         }
         notes = w;
     }
+    for (const f of fences) {
+        if (f.lang !== 'simulator')
+            continue;
+        const r = parseSimulatorFence(f.value, (f.position?.start.line ?? 1) + offset);
+        if (!r.ok)
+            return r;
+    }
     const lists = scanChecklists(fences, offset);
     if (!lists.ok)
         return lists;

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/lib/routes/artifacts.d.ts

@@ -27,6 +27,10 @@ export type ArtifactRoutesConfig = {
     packFor?: (artifact: ArtifactRecord) => BrandPack | undefined;
     /** The host that serves a 200, e.g. https://artifacts.example.com. No trailing slash. */
     siteUrl: string;
+    /** The embed page of this host's Supersuit Session demo (an https URL, e.g.
+     *  https://example.com/simulator/embed), for ```simulator blocks. Without it a block shows its
+     *  caption only. No default: this package points at nobody's service. */
+    simulatorEmbed?: string;
     /** Read at request time, so a rotated key needs no rebuild. */
     publishKey: () => string | undefined;
     /** Verifies publisher passes (`p1`, see artifacts/publisher.ts): a signed, hour-long stand-in

package/lib/routes/artifacts.js

@@ -303,7 +303,7 @@ export function createArtifactRoutes(config) {
         const title = v.title ?? a.title;
         const summary = v.summary ?? a.summary;
         const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader }) {
@@ -328,7 +328,7 @@ export function createArtifactRoutes(config) {
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), meta] }));
                         return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
-                                checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) }));
+                                checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined }) }));
                     })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.24.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",