@supersuit/artifacts 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 `@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.18.0 (2026-09-29)
+
+**No page is ever read by the browser's own voice, and a page can turn its audio off.** 0.10.0
+made a page with no recorded narration read itself with `speechSynthesis`, which on a phone is
+Safari's built-in voice. The operator heard it on a letter going to a partner: *"NEVER PUT
+DEFAULT SAFARI VOICE DICTATION. ALWAYS KOKORO OR IF I WANT TO SPEND MONEY 11LABS."* A page is
+now read by the audio recorded at publish, or it has no player at all.
+
+And *"add ability to disable audio"*: `voice: none` on a republish removes the page's stored
+narration, timings and hash, so the player goes too. Before this, an update merged fields, so a
+recording survived every republish that did not mention it and there was no way to take it off.
+
+- Removed: `BrowserReader`, `planSentences`, `wordAt`, `sentenceOf`, `fromWord`,
+  `MAX_SENTENCE_WORDS` from `./reader`. Nothing in a host should have mounted them directly.
+- DETECTOR: an un-narrated page that shows a player bar, or any `speechSynthesis` in `lib/`.
+- REMEDY: bump. To silence a page, republish it with `voice: none` (a publisher that sends it;
+  Freedom's publish-artifact does from the release after this).
+- Tests: route GUARDs that an un-narrated page, and one whose timings fail, mount no reader; store
+  tests that audio survives a silent republish and `voice: none` clears it; `check-packed` fails if
+  the tarball carries `speechSynthesis` or the fixture page mounts a player. The default-pages
+  golden was regenerated on purpose: the only change is the removed browser-reader element.
+
 ## 0.17.0 (2026-09-29)
 
 **A host can accept a signed, hour-long publisher pass wherever it accepts the publish key.** A

package/README.md

@@ -154,7 +154,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `audience` | Free text stored with the page, never shown |
 | `id` | Republish in place instead of minting a new page |
 | `cover` | An image URL (absolute or site-relative) used as the unfurl image instead of the share card |
-| `voice`, `narration`, `timings`, `narrationHash` | Read-aloud: the audio and word timings a publisher generated. Absent (or the timings will not load), the page is read by the browser's own voice instead, lighting the same words; a browser with no `speechSynthesis` shows no player |
+| `voice`, `narration`, `timings`, `narrationHash` | Read-aloud: the audio and word timings a publisher generated (Kokoro by default, ElevenLabs on request). Absent, or the timings will not load, the page has no player: it is never read by the browser's own voice. `voice: none` turns audio off and removes any recording the page already had |
 | `password` | Shuts the body behind a door (below) |
 | `access` | `freedom`, `invite` or `public`: a confidential page (below) |
 | `theme` | `light`, `dark` or `system` (follow the reader's device). Overrides the brand pack's mode for this page |

package/lib/artifacts/store.js

@@ -126,7 +126,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.to ? { to: input.meta.to } : {}),
         ...(input.meta.audience ? { audience: input.meta.audience } : {}),
         ...(input.meta.cover ? { cover: input.meta.cover } : {}),
-        ...(input.meta.voice ? { voice: input.meta.voice } : {}),
+        ...(input.meta.voice && input.meta.voice !== 'none' ? { voice: input.meta.voice } : {}),
         ...(input.meta.narration ? { narration: input.meta.narration } : {}),
         ...(input.meta.timings ? { timings: input.meta.timings } : {}),
         ...(input.meta.narrationHash ? { narrationHash: input.meta.narrationHash } : {}),
@@ -190,8 +190,13 @@ async function saveArtifact(col, input) {
             ...(input.meta.comments ? {} : { comments: FieldValue.delete() }),
             ...(input.meta.commentsVisible ? {} : { commentsVisible: FieldValue.delete() }),
         };
+        // `voice: none` is the page declaring it has no audio. An update merges, so the recording it
+        // had would otherwise survive every republish; clear it on purpose, and the player goes with it.
+        const audio = input.meta.voice === 'none'
+            ? { voice: FieldValue.delete(), narration: FieldValue.delete(), timings: FieldValue.delete(), narrationHash: FieldValue.delete() }
+            : {};
         await ref.update({
-            ...fields, ...password, ...subtitle, ...to, ...access, ...state, ...look, markdown: input.markdown, version: next,
+            ...fields, ...password, ...subtitle, ...to, ...access, ...state, ...look, ...audio, markdown: input.markdown, version: next,
             // `updatedAt` is when this version went live; finishing its own publish does not move it.
             ...(fresh || input.markdown !== existing.markdown ? { updatedAt: now } : {}),
             note: nextNote ?? FieldValue.delete(),

package/lib/reader/index.d.ts

@@ -1,7 +1,5 @@
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex, type WordTiming } from './artifact-reader.js';
-export { BrowserReader } from './browser-reader.js';
 export { PlayerBar } from './player-bar.js';
-export { planSentences, wordAt, sentenceOf, fromWord, MAX_SENTENCE_WORDS, type Sentence } from './speech-plan.js';
 export { CommentLayer } from './comment-layer.js';
 export { CommentCard, warningLine, DEVICE_LINE } from './comment-card.js';
 export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDeviceNote } from './device-notes.js';

package/lib/reader/index.js

@@ -1,9 +1,7 @@
-// The `./reader` entry: both readers and the bar they share. Each component module carries its
+// The `./reader` entry: the reader and the bar it uses. Each component module carries its
 // own 'use client'; this barrel is plain re-exports so it can be imported from either side.
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex } from './artifact-reader.js';
-export { BrowserReader } from './browser-reader.js';
 export { PlayerBar } from './player-bar.js';
-export { planSentences, wordAt, sentenceOf, fromWord, MAX_SENTENCE_WORDS } from './speech-plan.js';
 export { CommentLayer } from './comment-layer.js';
 export { CommentCard, warningLine, DEVICE_LINE } from './comment-card.js';
 export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDeviceNote } from './device-notes.js';

package/lib/routes/artifacts.js

@@ -17,7 +17,6 @@ import { themedPack } from '../brand/theme.js';
 import { showToc, tocOf, TocInline, TocRail } from '../artifacts/toc.js';
 import { renderShareCard } from '../brand/share-card.js';
 import { ArtifactReader } from '../reader/artifact-reader.js';
-import { BrowserReader } from '../reader/browser-reader.js';
 import { CommentLayer } from '../reader/comment-layer.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
 import { UpdatedTime } from '../reader/updated-time.js';
@@ -262,9 +261,9 @@ export function createArtifactRoutes(config) {
                         const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { a: a, n: n, at: a.updatedAt, history: await historyOf(a.id) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         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, Section: pack.Section, figure: pack.figure }) }));
-                    })() }), _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 })) : (
-                // No recorded narration, or its timings would not load: the browser reads the page.
-                _jsx(BrowserReader, { rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground }))] }));
+                    })() }), _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. */] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in

package/package.json

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

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

@@ -1,8 +0,0 @@
-export declare const BROWSER_READER_LABEL = "Read aloud by your browser";
-export declare function BrowserReader({ rootId, label, accent, ground, }: {
-    rootId: string;
-    /** The line under the play button. */
-    label?: string;
-    accent: string;
-    ground: string;
-}): import("react").JSX.Element;

package/lib/reader/browser-reader.js

@@ -1,171 +0,0 @@
-'use client';
-import { jsx as _jsx } from "react/jsx-runtime";
-// Read-along for a page with no recorded narration: the browser's own voice (speechSynthesis)
-// reads the same word spans the recorded reader lights, and its word-boundary events light them.
-// It sounds worse than a recorded narrator and sends nothing anywhere.
-//
-// One utterance per sentence (see speech-plan.ts). Safari's boundary charIndex drifts on long
-// passages; every new utterance restarts it at zero against offsets we know, so a drift cannot
-// outlast the sentence it began in. Every utterance carries the generation it was spoken in, and
-// an event from an older generation (a sentence cancelled by a click, a seek or a speed change,
-// whose end or error the engine still reports) is ignored.
-//
-// The mount is rendered hidden and empty on the server and on the first client render, so the
-// markup always hydrates; it shows only once the browser is known to have speechSynthesis. It
-// never carries data-artifact-player while hidden, because the popovers measure that element to
-// keep clear of the bar, and a hidden element measures as the whole screen.
-import { useEffect, useRef, useState } from 'react';
-import { BLOCK, seekableWord, wrapWords } from './artifact-reader.js';
-import { nextRate, PlayerBar } from './player-bar.js';
-import { fromWord, planSentences, wordAt } from './speech-plan.js';
-export const BROWSER_READER_LABEL = 'Read aloud by your browser';
-function spokenWords(spans) {
-    const words = [];
-    const starts = new Set();
-    let prevBlock = null;
-    spans.forEach((span, i) => {
-        // Punctuation glued on across an element edge ("**bold**.") is a tail, not a word; it is
-        // spoken with the word it follows, which is also what lets it end a sentence.
-        const tail = span.nextSibling instanceof HTMLElement && span.nextSibling.classList.contains('artifact-word-tail') ? span.nextSibling.textContent ?? '' : '';
-        words.push((span.textContent ?? '') + tail);
-        const block = span.closest(BLOCK);
-        if (i > 0 && block !== prevBlock)
-            starts.add(i);
-        prevBlock = block;
-    });
-    return { words, starts };
-}
-export function BrowserReader({ rootId, label = BROWSER_READER_LABEL, accent, ground, }) {
-    const [ready, setReady] = useState(false);
-    const [playing, setPlaying] = useState(false);
-    const [current, setCurrent] = useState(-1);
-    const [count, setCount] = useState(0);
-    const [rate, setRate] = useState(1);
-    const spansRef = useRef([]);
-    const planRef = useRef([]);
-    const genRef = useRef(0);
-    const rateRef = useRef(1);
-    const currentRef = useRef(-1);
-    const playingRef = useRef(false);
-    // True from the first play until the page is finished: pause and resume act on a live queue.
-    const startedRef = useRef(false);
-    const litRef = useRef(null);
-    const setPlay = (p) => {
-        playingRef.current = p;
-        setPlaying(p);
-    };
-    const light = (i) => {
-        const el = i >= 0 ? spansRef.current[i] ?? null : null;
-        if (el !== litRef.current) {
-            litRef.current?.classList.remove('artifact-word-lit');
-            el?.classList.add('artifact-word-lit');
-            litRef.current = el;
-            if (el && playingRef.current) {
-                const r = el.getBoundingClientRect();
-                if (r.top < 80 || r.bottom > window.innerHeight - 140)
-                    el.scrollIntoView?.({ block: 'center', behavior: 'smooth' });
-            }
-        }
-        currentRef.current = i;
-        setCurrent(i);
-    };
-    const finish = () => {
-        startedRef.current = false;
-        setPlay(false);
-        light(-1);
-    };
-    const speak = (s, gen) => {
-        const synth = window.speechSynthesis;
-        const u = new SpeechSynthesisUtterance(s.text);
-        u.rate = rateRef.current;
-        u.onboundary = (e) => {
-            if (gen !== genRef.current || e.name !== 'word')
-                return;
-            light(wordAt(s, e.charIndex));
-        };
-        u.onend = () => {
-            if (gen !== genRef.current)
-                return;
-            const next = s.first + s.offsets.length;
-            if (next < spansRef.current.length)
-                speak(fromWord(planRef.current, next), gen);
-            else
-                finish();
-        };
-        u.onerror = () => {
-            if (gen === genRef.current)
-                finish();
-        };
-        // Light the sentence's first word now: some engines send no boundary events at all, and the
-        // page should still show where it is.
-        light(s.first);
-        synth.speak(u);
-    };
-    /** Cancel whatever is speaking and read from word `i` on. */
-    const speakFrom = (i) => {
-        if (!planRef.current.length)
-            return;
-        const synth = window.speechSynthesis;
-        const gen = ++genRef.current;
-        synth.cancel();
-        // An engine paused before the cancel stays paused for the next utterance in some browsers.
-        synth.resume();
-        startedRef.current = true;
-        setPlay(true);
-        speak(fromWord(planRef.current, Math.max(0, Math.min(i, spansRef.current.length - 1))), gen);
-    };
-    const speakFromRef = useRef(speakFrom);
-    speakFromRef.current = speakFrom;
-    useEffect(() => {
-        if (typeof window === 'undefined' || !('speechSynthesis' in window))
-            return;
-        const root = document.getElementById(rootId);
-        if (!root)
-            return;
-        const spans = wrapWords(root);
-        if (!spans.length)
-            return;
-        const { words, starts } = spokenWords(spans);
-        spansRef.current = spans;
-        planRef.current = planSentences(words, starts);
-        setCount(spans.length);
-        setReady(true);
-        const onClick = (e) => {
-            const el = seekableWord(e.target);
-            if (!el)
-                return;
-            const idx = spansRef.current.indexOf(el);
-            if (idx !== -1)
-                speakFromRef.current(idx);
-        };
-        root.addEventListener('click', onClick);
-        return () => {
-            root.removeEventListener('click', onClick);
-            genRef.current++;
-            window.speechSynthesis.cancel();
-        };
-    }, [rootId]);
-    const toggle = () => {
-        const synth = window.speechSynthesis;
-        if (!startedRef.current)
-            speakFrom(0);
-        else if (playingRef.current) {
-            synth.pause();
-            setPlay(false);
-        }
-        else {
-            synth.resume();
-            setPlay(true);
-        }
-    };
-    if (!ready)
-        return _jsx("div", { "data-artifact-reader": "browser", hidden: true });
-    return (_jsx("div", { "data-artifact-reader": "browser", children: _jsx(PlayerBar, { playing: playing, onToggle: toggle, label: label, accent: accent, ground: ground, value: Math.max(current, 0), max: Math.max(count - 1, 0), step: 1, onSeek: (v) => speakFrom(v), progress: `${current + 1} / ${count}`, rate: rate, onRate: () => {
-                const r = nextRate(rateRef.current);
-                rateRef.current = r;
-                setRate(r);
-                // The engine fixes the rate when an utterance starts, so restart at the current word.
-                if (startedRef.current && playingRef.current)
-                    speakFrom(Math.max(currentRef.current, 0));
-            } }) }));
-}

package/lib/reader/speech-plan.d.ts

@@ -1,20 +0,0 @@
-export type Sentence = {
-    /** The words joined by single spaces: exactly what is handed to the speech engine. */
-    text: string;
-    /** Index of the sentence's first word in the page's word list. */
-    first: number;
-    /** offsets[i] is the char offset, inside `text`, of word `first + i`. */
-    offsets: number[];
-};
-export declare const MAX_SENTENCE_WORDS = 60;
-/** Split a page's words into sentences. `starts` holds word indexes that begin a new block
- *  (a heading, a paragraph, a list item), which always begin a new sentence. */
-export declare function planSentences(words: string[], starts?: ReadonlySet<number>): Sentence[];
-/** The absolute word index a boundary event's `charIndex` falls in: the last word whose offset
- *  is at or before it. */
-export declare function wordAt(s: Sentence, charIndex: number): number;
-/** The index of the sentence holding `wordIndex`. */
-export declare function sentenceOf(plan: Sentence[], wordIndex: number): number;
-/** The sentence holding `wordIndex`, cut so it starts AT that word, with offsets rebased to the
- *  cut text. What is spoken when a reader clicks a word in the middle of a sentence. */
-export declare function fromWord(plan: Sentence[], wordIndex: number): Sentence;

package/lib/reader/speech-plan.js

@@ -1,67 +0,0 @@
-// How the browser read-aloud splits a page into utterances, and maps a speech engine's
-// word-boundary events back to the page's word spans. Pure, so it is tested without a browser.
-//
-// One utterance per sentence is the drift bound: Safari's boundary charIndex wanders on long
-// passages, and every new utterance restarts it at zero against a sentence whose word offsets
-// are known. The cap keeps a page with no punctuation (a list, a table) from becoming one long
-// utterance, which is also where Chrome is known to stop speaking part-way.
-export const MAX_SENTENCE_WORDS = 60;
-// A word ends a sentence when it ends in . ! ? or :, optionally followed by closing quotes or
-// brackets. "10:30" and "example.com" do not, because the punctuation is not at the end.
-const ENDS_SENTENCE = /[.!?:]["'”’)\]]*$/;
-/** Split a page's words into sentences. `starts` holds word indexes that begin a new block
- *  (a heading, a paragraph, a list item), which always begin a new sentence. */
-export function planSentences(words, starts) {
-    const plan = [];
-    let cur = null;
-    for (let i = 0; i < words.length; i++) {
-        if (cur && (cur.offsets.length >= MAX_SENTENCE_WORDS || starts?.has(i))) {
-            plan.push(cur);
-            cur = null;
-        }
-        if (!cur)
-            cur = { text: '', first: i, offsets: [] };
-        if (cur.offsets.length)
-            cur.text += ' ';
-        cur.offsets.push(cur.text.length);
-        cur.text += words[i];
-        if (ENDS_SENTENCE.test(words[i])) {
-            plan.push(cur);
-            cur = null;
-        }
-    }
-    if (cur)
-        plan.push(cur);
-    return plan;
-}
-/** The absolute word index a boundary event's `charIndex` falls in: the last word whose offset
- *  is at or before it. */
-export function wordAt(s, charIndex) {
-    let i = 0;
-    for (let k = 0; k < s.offsets.length; k++) {
-        if (s.offsets[k] <= charIndex)
-            i = k;
-        else
-            break;
-    }
-    return s.first + i;
-}
-/** The index of the sentence holding `wordIndex`. */
-export function sentenceOf(plan, wordIndex) {
-    let idx = 0;
-    for (let k = 0; k < plan.length; k++) {
-        if (plan[k].first <= wordIndex)
-            idx = k;
-        else
-            break;
-    }
-    return idx;
-}
-/** The sentence holding `wordIndex`, cut so it starts AT that word, with offsets rebased to the
- *  cut text. What is spoken when a reader clicks a word in the middle of a sentence. */
-export function fromWord(plan, wordIndex) {
-    const s = plan[sentenceOf(plan, wordIndex)];
-    const k = Math.max(0, Math.min(wordIndex - s.first, s.offsets.length - 1));
-    const base = s.offsets[k];
-    return { text: s.text.slice(base), first: s.first + k, offsets: s.offsets.slice(k).map((o) => o - base) };
-}