@supersuit/artifacts 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -3,6 +3,88 @@
 `@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.44.0
+
+**Voice notes with their own words, lit as they are spoken.** An audio line followed directly by a
+` ```transcript ` fence of timed words (`<start> <end> <word>` per line, a blank line for a new
+paragraph) now draws one card in the page's brand: the caption, a play button and a seek line
+instead of the native bar, and the transcript beneath, where the word being spoken carries the
+narration's highlight, words already said read normally and words to come are muted. Tapping a word
+plays from there. Additive: a page with no transcript fence renders byte for byte as 0.43.0.
+
+- Publish refuses, with the line in the file: a malformed transcript line, an end before its start,
+  a start before the word above, an empty fence, a name after `transcript`, and a transcript with no
+  audio line directly above it.
+- The card is `data-nospeak` (the narration already skips images and fences), keeps
+  `data-artifact-media` on its `<audio>` for play tracking and the audio line's comment anchor, and
+  plays on iPhone with `preload="none"`, `playsinline` and no autoplay. Starting a note pauses any
+  other audio on the page.
+- The karaoke primitives moved to `src/reader/karaoke.ts` and are shared by the narration and the
+  voice note: `litWordIndex` (same behaviour, still exported from `./reader`), new `begunCount`, and
+  one highlight rule.
+- New bin `supersuit-transcript-fence <audio>`: runs a local transcriber already on the machine
+  (`mlx_whisper`, else `whisper`) with word timestamps and prints the fence. The package carries no
+  transcriber. New exports from `./artifacts`: `parseTranscriptFence`, `scanVoiceNotes`,
+  `transcriptFenceFromWords`, `wordsFromWhisperJson`, `isAudioSrc`, `TRANSCRIPT_LANG`,
+  `MAX_TRANSCRIPT_WORDS`.
+
+DETECTOR: a page whose body already holds a ` ```transcript ` fence (it rendered as a code block)
+now publishes only when that fence parses and sits under an audio line: `rg -n '^```transcript' <pages>`.
+A host whose Tailwind build does not scan this package's `lib/` would draw the card unstyled; the
+existing widgets need the same scan.
+
+REMEDY: none for most hosts; bump. A page that used `transcript` as a plain code label renames the
+fence (```text).
+
+Tests: `src/artifacts/voice-note.test.ts` (grammar, publish refusals with line numbers, comment
+anchors, fence writer, whisper JSON), `src/widgets/voice-note.test.tsx` (the card's markup, iPhone
+attributes, an audio line without a transcript byte-identical to 0.43.0, lighting, tap to seek,
+seek before load).
+
+## 0.43.0
+
+**A comment's id per reader in `/views`, the comments feed for one page, and a limit on new browsers
+through a group link.** A consumer that keeps a local copy of a page's comments could not tell exactly
+which ones it lacked: `/views` listed each reader's comments as `{ at, text }` with no id, and
+`GET /api/comments` is the whole host's feed. Everything here is additive; a caller that ignores the
+new fields and the new parameter sees 0.42.0.
+
+- `GET /api/artifacts/<id>/views`: each comment gains `id` (the entry id the feed calls `entryId`) and
+  `parent` (the entry id it replies to, or null). Under `comment_name: required` every browser on a
+  group link is still listed under the link, each with its own id. Publisher replies stay out.
+- `GET /api/comments?artifact=<page id>`: only that page's rows, read from that page's entries rather
+  than a scan of the host. `since`, `open`, `cursor` and `more` work over that page's comments. A value
+  that is not a page id is a 400; a well-formed id with no page is an empty feed. Without the parameter
+  the feed is unchanged.
+- On a `comment_name: required` page, the first stored note of each new browser through one group
+  link (a reader key with no entry on the page yet, with or without an `artifact_anon` cookie) is
+  counted against the anonymous write limit, keyed by the link, and answers
+  `429 { error: "too many new readers through this link; try again in a minute" }` past 30 a minute.
+  Counted after validation, so a refused request spends nothing. A browser's later notes, a named link
+  and a page without the line are not counted.
+- `summarizeViews` (a public export) takes comments with `id` and `parent` OPTIONAL: a caller passing
+  `{ readerKey, at, text }` compiles and runs as before, and gets `id: null, parent: null` on each item.
+- README: the `id` and `parent` shapes, the `artifact` parameter, and the note that removing
+  `comment_name: required` later turns a group link back into one shared reader and hides every
+  per-browser note from its writer.
+
+DETECTOR: a consumer that reads `comments[]` from `/views` and rebuilds each item field by field, or
+that rejects unknown keys, meets two new ones: `rg -n "\.comments" <your consumer>`. A consumer that
+paged the host-wide feed to find one page's comments can ask for that page alone. A group link handed
+to a crowd that arrives all at once (more than 30 new browsers writing inside a minute) now sees 429 for
+the rest of that minute. A caller already sending a stray `artifact=` parameter on the feed, ignored
+until now, gets a filtered feed, or a 400 if it is not a page id.
+
+REMEDY: read `id` and `parent` where present and tolerate them where not; add `&artifact=<id>` to a
+per-page poll. Nothing is needed for the limit: the same people write again the next minute.
+
+Tests: `src/routes/comment-ids.test.tsx` (ids equal the feed's `entryId`; a reply's `parent`; two
+browsers on one group link under the link with distinct ids; no publisher reply; `artifact=` returns
+one page's rows and composes with `since` and `open=1`; paging 300 comments of one page among 450 in
+pages of 200 never returns another page's row; the unfiltered feed unchanged; a malformed id is 400
+and an unknown page is empty; the limit trips for cookieless writes through one link, not for a
+returning browser, a named link or a page without the line). Every test builds its own stores.
+
 ## 0.42.0
 
 **One page can say who sees its version number and past versions: `history: everyone | admins` in

package/README.md

@@ -620,6 +620,62 @@ visibility: shared   # optional: private | shared
   can leave or read notes; the banner, watermark and print refusal are unchanged. On a public
   page with `writers: signed-in`, the control offers sign-in through `signInOrigin`.
 
+## Voice notes with their words (`transcript`)
+
+An audio line in a page (`![caption](note.m4a)`, or `.mp3`) plays as a clip with the native
+player. Put a `transcript` fence **directly under it** and it becomes a voice note: one card in the
+page's brand with the caption, a play button and a seek line, and the speaker's own words beneath,
+lit one at a time as they are spoken. Words already said read normally, the word being said carries
+the narration's highlight, and the words still to come are a little muted. Tapping a word plays
+from there.
+
+````markdown
+![Robin, to the family](hello.m4a)
+
+```transcript
+0.00 0.62 Hello!
+0.80 1.10 I
+1.10 1.30 hope
+
+2.00 2.40 Love,
+2.40 2.90 Robin
+```
+````
+
+- **One word per line: its start and end in seconds, then the word as it should read.** A phrase
+  timed together is one line; any script works. **A blank line starts a new paragraph.**
+- **The audio stays plain image syntax**, so the publisher uploads a local file as it does any clip
+  (including under `media: private`) and needs no change. The words travel inside the page.
+- **Refused at publish, naming the line in the file:** a line that is not `<start> <end> <word>`, a
+  word that ends before it starts, a word that starts before the word above it, an empty fence, a
+  name after `transcript`, and a `transcript` fence with no audio line directly above it (a second
+  fence under one note included).
+- **The page's narration skips it** (the card is `data-nospeak`, and the narration text never reads
+  images or fences): a reader hears the speaker, never a robot reading the speaker.
+- **On a phone:** nothing is fetched until play (`preload="none"`), no autoplay, `playsinline`. A
+  tapped word before the clip has loaded seeks once its metadata arrives. Starting a note pauses any
+  other audio on the page, the narration included.
+- **Play tracking is unchanged:** the `<audio>` keeps `data-artifact-media`, so a play counts like
+  any clip. The note keeps the audio line's comment anchor.
+- An audio line **without** a transcript fence renders exactly as before.
+
+**Making the fence** (never by hand): `supersuit-transcript-fence` ships with the package and runs
+a transcriber already on your machine, locally, with word timestamps: `mlx_whisper` (Apple Silicon,
+`pip install mlx-whisper`), else openai-whisper's `whisper`. The package itself carries no
+transcriber.
+
+```bash
+npx -p @supersuit/artifacts supersuit-transcript-fence hello.m4a > fence.md
+# --language zh   the spoken language, when auto-detect guesses wrong
+# --gap 1.5       seconds of silence that start a new paragraph (default 1.5)
+# --model <name>  the whisper model (default mlx-community/whisper-large-v3-turbo)
+# --body          the lines only, without the ``` fence
+```
+
+Paste it under the audio line, then correct any word (a name, a phrase in another language)
+and keep its two times. `transcriptFenceFromWords` and `wordsFromWhisperJson` (from
+`@supersuit/artifacts/artifacts`) do the same from code.
+
 ## Comments and personal notes
 
 Every page takes comments pinned to any part of it. A reader selects text (a **Comment** chip
@@ -851,6 +907,19 @@ Authorization: Bearer <publish key>
                                        quote, region, body, transcript, audioUrl, at, resolved, link } ] }
 ```
 
+**One page's feed (0.43.0).** `&artifact=<page id>` returns only that page's rows. `since`, `open`,
+`cursor` and `more` behave as above, over that page's comments alone, so a caller paging one page
+reaches its end without reading another page's rows. The feed is read from that page's own entries,
+not from a scan of the host. A value that is not a page id is a `400` ("artifact must be a page id,
+like abcd2345"); a well-formed id with no page, or no comments, answers an empty feed
+(`{ now, comments: [], cursor: null, more: false }`), as an empty host does. Without the parameter
+the feed is what it was.
+
+```
+GET /api/comments?since=2026-09-28T12:00:00Z&artifact=abcd2345&open=1
+Authorization: Bearer <publish key>
+```
+
 Oldest first, at most 200, strictly after `since` (an ISO 8601 time with a zone; anything else is
 a 400). `name` is null for an anonymous reader; `reader` is `{ rid, label }` for a comment left through a per-reader link, else null; `by` is the name its writer typed, else null; `publisher` is true for a reply written through the reply route; `quote` is the text the comment is pinned to, or
 null for a box (`region: true`); `parent` is the comment a reply answers; `audioUrl` is a signed
@@ -911,7 +980,7 @@ Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `
 |---|---|---|
 | `GET /api/artifacts/<id>/recipients` | publish key | Every reader, with the working link for each |
 | `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group?, closes? }], revoke?: [rid] or '*', expires?: ISO time or null, closes?: { rids: [rid] or '*', at: ISO time or null } }`. `add` answers each new reader's link; `expires: null` is Keep; `closes` sets, moves or clears a reader's feedback window |
-| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. Each comment is `{ id, parent, at, text }` (see Comment ids in /views). A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
 | `POST /api/artifacts/<id>/seen` | the page itself (public) | The reader's own signal, below |
 
 Config, both on `createArtifactRoutes`: `recipients` (a store from `createRecipientsStore(db, '<collection path>')`, or `memoryRecipientsStore()` in tests) and `recipientSecret`, a function returning the signing secret, read on every request. A secret shorter than 32 characters is treated as unset: per-reader pages stay shut and the routes answer 404 or 501. Signing with an empty secret throws.
@@ -978,6 +1047,35 @@ the one shared reader (`r:<rid>`) and are shown to no browser afterwards. A name
 reader either way. The feedback window, the feed's `reader: { rid, label }` and the `/views` line
 stay per link: every browser on a group link shares them.
 
+### Comment ids in `/views` (0.43.0)
+
+Each comment in a reader's `comments` array carries the entry id the comments feed calls
+`entryId`, and the id of the comment it replies to:
+
+```json
+{ "rid": "abcdefghijkl", "label": "Anyone with the link", "group": true, "comments": [
+  { "id": "kq3vN8xTz2LwPd5mRa", "parent": null, "at": "2026-10-11T10:01:00.000Z", "text": "Which river?" },
+  { "id": "Jm7cHy4bQe9sUf1xWk", "parent": "kq3vN8xTz2LwPd5mRa", "at": "2026-10-11T10:04:00.000Z", "text": "The north one." } ] }
+```
+
+`at` and `text` are as before. Under `comment_name: required` the notes of every browser on a
+group link are listed under that link's row, each with its own `id`. The publisher's replies are not
+listed. A caller that keeps a local copy of a page's comments compares these ids with
+`GET /api/comments?artifact=<id>` to see exactly which ones it lacks.
+
+**Limit on new browsers.** On a page with `comment_name: required`, the first stored note of each new
+browser through one group link is counted against that link, per minute, on the anonymous write limit
+(30). A browser is new when its reader key has no entry on the page yet, whether or not it arrived with
+an `artifact_anon` cookie. Past the limit the state route answers
+`429 { error: "too many new readers through this link; try again in a minute" }`. Only a stored note is
+counted: a request refused for a missing name, a closed window or a malformed body spends nothing. A
+browser's later notes, a named link and a page without the line are never counted. "Note" here means
+any stored entry in any slot, and a browser that removes its only entry and writes again is new again.
+
+**Removing the line later.** Taking `comment_name: required` off a page turns its group link back into
+one shared reader, and every note left per browser stops being shown to its writer: the notes stay with
+the publisher, under their per-browser keys.
+
 ## Broadcasts (`template: broadcast`)
 
 A broadcast is its own page kind, not a document with extra flags. It is one message sent to several people, each through their own link, and it renders as one card: the sender's words at the top, then the media in the order the words put it (a video with sound and controls, photos, a voice note's player, link cards), then that person's own note. None of the document's furniture: no table of contents, no version line, no read-along, and no page menu for a reader.

package/lib/artifacts/index.d.ts

@@ -27,3 +27,4 @@ export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
 export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.js';
+export { parseTranscriptFence, scanVoiceNotes, transcriptFenceFromWords, wordsFromWhisperJson, isAudioSrc, TRANSCRIPT_LANG, MAX_TRANSCRIPT_WORDS, type TranscriptParagraphs, type TimedWord, type VoiceNoteBlock } from './voice-note.js';

package/lib/artifacts/index.js

@@ -27,3 +27,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';
 export { migrateMemosToPrivate, MEMO_KEY } from './migrate-memos.js';
+export { parseTranscriptFence, scanVoiceNotes, transcriptFenceFromWords, wordsFromWhisperJson, isAudioSrc, TRANSCRIPT_LANG, MAX_TRANSCRIPT_WORDS } from './voice-note.js';

package/lib/artifacts/recipients-store.d.ts

@@ -38,6 +38,8 @@ export type RecipientSummary = {
     plays: number;
     devices: number;
     comments: {
+        id: string | null;
+        parent: string | null;
         at: string;
         text: string;
     }[];
@@ -78,6 +80,8 @@ export declare function createRecipientsStore(db: Firestore, base: string): Reci
 /** One line per reader (never the owner), in the order they were added. */
 export declare function summarizeViews(rec: RecipientsRecord, views: ViewDoc[], comments: {
     readerKey: string;
+    id?: string | null;
+    parent?: string | null;
     at: string;
     text: string;
 }[]): RecipientSummary[];

package/lib/artifacts/recipients-store.js

@@ -179,7 +179,7 @@ export function summarizeViews(rec, views, comments) {
             activeSeconds: mine.reduce((n, v) => n + v.activeSeconds, 0),
             plays: mine.reduce((n, v) => n + Object.values(v.plays).reduce((a, b) => a + b, 0), 0),
             devices: new Set(mine.map((v) => v.device)).size,
-            comments: comments.filter((c) => ridOfReaderKey(c.readerKey) === r.rid).map((c) => ({ at: c.at, text: c.text })),
+            comments: comments.filter((c) => ridOfReaderKey(c.readerKey) === r.rid).map((c) => ({ id: c.id ?? null, parent: c.parent ?? null, at: c.at, text: c.text })),
         };
     });
 }

package/lib/artifacts/render.js

@@ -6,6 +6,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 //   ```links   one "url | note" per line, rendered as link cards
 //   ```checklist   items a reader ticks, kept in their browser (widgets/checklist.tsx)
 //   > [!note] / > [!warning]   a callout instead of a blockquote
+//   ```transcript   right under an audio line: a voice note whose words light up as spoken (voice-note.ts)
 // A checklist's item text and descriptions are markdown drawn by the same safe renderer: raw
 // HTML escaped, links only where a reader can follow them, no images.
 import { Children, isValidElement } from 'react';
@@ -22,6 +23,8 @@ import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
 import { remarkDefinitions } from './definitions.js';
+import { AUDIO_SRC, remarkVoiceNotes, TRANSCRIPT_LANG } from './voice-note.js';
+import { VoiceNote } from '../widgets/voice-note.js';
 // Every colour is a theme variable (brand/theme.ts), so a page follows its light, dark or system mode.
 const GOLD = 'var(--a-accent)';
 function hostOf(url) {
@@ -78,7 +81,7 @@ const VIDEO = /\.mp4(?:[?#].*)?$/i;
 /** `![caption](x.mp3)` is a clip the reader plays: an annotated conversation, a voice note, a
  *  quote heard rather than read. Native controls, and `preload="none"` so a page of clips fetches
  *  nothing until one is pressed. The alt is its caption, shown above the player. */
-const AUDIO = /\.(mp3|m4a)(?:[?#].*)?$/i;
+const AUDIO = AUDIO_SRC;
 /** The stored file's name, for play tracking: the last path segment before any query. */
 const mediaName = (src) => {
     const last = src.split(/[?#]/)[0].split('/').pop() ?? '';
@@ -161,8 +164,17 @@ 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, embeds) {
+function baseComponents(block, figure, checklists, embeds, voiceNotes) {
     return {
+        // A voice note (remarkVoiceNotes): the audio line and its transcript, drawn as one keepsake.
+        div: ({ node, ...props }) => {
+            const at = props['data-artifact-voicenote-at'];
+            const v = at === undefined ? undefined : voiceNotes?.[Number(at)];
+            // Any other div (a section body, a definition) is drawn as it would be with no override.
+            if (!v)
+                return _jsx("div", { ...props });
+            return _jsx(VoiceNote, { src: artifactUrlTransform(v.src), label: v.label, media: mediaName(v.src), paragraphs: v.paragraphs, block: block(node) });
+        },
         p: ({ node, children }) => {
             // An image alone in its paragraph that the pack draws itself replaces the paragraph, so the
             // pack's figure may hold block content (a <p> cannot) and still carry the comment anchor.
@@ -201,6 +213,9 @@ function baseComponents(block, figure, checklists, embeds) {
             // answers) it draws nothing: its settings are not prose and never shown as code.
             if (lang === 'notes')
                 return null;
+            // A transcript not under an audio line draws nothing (publish refuses one; an old page may hold it).
+            if (lang === TRANSCRIPT_LANG)
+                return null;
             if (lang === 'simulator' || lang === 'messages')
                 return _jsx(EmbedFence, { kind: lang, source: textOf(children), ctx: embeds?.[lang] });
             if (!className) {
@@ -212,7 +227,7 @@ function baseComponents(block, figure, checklists, embeds) {
             // 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|simulator|messages)/.test(cls))
+            if (/language-(links|notes|checklist|simulator|messages|transcript)/.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
@@ -245,20 +260,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, embeds) {
+function pageComponents(headings, block, figure, checklists, embeds, voiceNotes) {
     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, embeds), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
+    return { ...baseComponents(block, figure, checklists, embeds, voiceNotes), 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, embeds) {
-    const components = baseComponents(block, figure, checklists, embeds);
+function notesComponents(headings, block, figure, checklists, embeds, voiceNotes) {
+    const components = baseComponents(block, figure, checklists, embeds, voiceNotes);
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function NotedHeading({ node, children }) {
         const Tag = `h${depth}`;
@@ -348,14 +363,17 @@ export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Sect
     };
     const defined = definitions?.length ? definitions : null;
     const outline = Section ? sectionOutline(markdown, headings) : [];
-    const plugins = [remarkGfm, ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
+    // Voice notes first, so a section groups the note node the pair became.
+    const voiceNotes = [];
+    const voiced = /^ {0,3}(`{3,}|~{3,})\s*transcript\b/m.test(markdown);
+    const plugins = [remarkGfm, ...(voiced ? [remarkVoiceNotes(voiceNotes)] : []), ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
     const lists = /^ {0,3}(`{3,}|~{3,})\s*checklist\b/m.test(markdown) ? checklistsOf(markdown) : null;
     const checklists = lists
         // `send` from the host means it keeps answers and the page declared the `checklist` slot; on a
         // 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, embeds) : pageComponents(headings, block, figure, checklists, embeds);
+    const components = on ? notesComponents(headings, block, figure, checklists, embeds, voiceNotes) : pageComponents(headings, block, figure, checklists, embeds, voiceNotes);
     if (outline.length)
         components.section = sectionComponent(Section, outline, block);
     const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, urlTransform: artifactUrlTransform, children: markdown }));

package/lib/artifacts/voice-note.d.ts

@@ -0,0 +1,55 @@
+import type { Root, RootContent, Image } from 'mdast';
+import type { WordTiming } from '../reader/karaoke.js';
+export declare const TRANSCRIPT_LANG = "transcript";
+/** `![caption](x.mp3)` / `.m4a` is a clip the reader plays. */
+export declare const AUDIO_SRC: RegExp;
+export declare const isAudioSrc: (src: unknown) => src is string;
+/** A page this long is a book, not a voice note. */
+export declare const MAX_TRANSCRIPT_WORDS = 20000;
+export type TranscriptParagraphs = WordTiming[][];
+/** Parses a transcript fence's body. `line` is the line the fence opens on in the file, so every
+ *  error names the line the author sees in their editor. */
+export declare function parseTranscriptFence(value: string, line: number): {
+    ok: true;
+    paragraphs: TranscriptParagraphs;
+} | {
+    ok: false;
+    error: string;
+};
+/** The audio image a paragraph holds and nothing else (whitespace aside), or null. */
+export declare function soleAudio(n: RootContent | undefined): Image | null;
+/** The publish-time check: every transcript fence parses, takes no name, and sits directly under
+ *  an audio line. `offset` is how many lines of the file sit above the body. */
+export declare function scanVoiceNotes(tree: Root, offset: number): {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    error: string;
+};
+/** What the renderer draws for one voice note. */
+export type VoiceNoteBlock = {
+    src: string;
+    label: string;
+    paragraphs: TranscriptParagraphs;
+};
+/** Replaces each audio line + transcript pair with one node the renderer draws as a voice note,
+ *  keeping the audio line's position so its comment anchor (blocksOf) is unchanged. A pair that
+ *  does not parse is left alone: the audio plays as before and the fence draws nothing. `found`
+ *  collects the notes; the node carries its index. */
+export declare function remarkVoiceNotes(found: VoiceNoteBlock[]): () => (tree: Root) => void;
+/** A word as a transcriber reports it (mlx_whisper / openai-whisper `word_timestamps`). */
+export type TimedWord = {
+    word: string;
+    start: number;
+    end: number;
+};
+/** The body of a transcript fence for a list of timed words: one word per line, and a blank line
+ *  wherever the speaker paused at least `paragraphGap` seconds. Times never run backwards, so the
+ *  result always passes the publish check. Correct a word's spelling afterwards; keep its times. */
+export declare function transcriptFenceFromWords(words: TimedWord[], opts?: {
+    paragraphGap?: number;
+}): string;
+/** The timed words in a whisper JSON result (`segments[].words[]`, written by `mlx_whisper` or
+ *  `whisper` with word timestamps on). Anything else in the file is ignored. */
+export declare function wordsFromWhisperJson(json: unknown): TimedWord[];

package/lib/artifacts/voice-note.js

@@ -0,0 +1,161 @@
+export const TRANSCRIPT_LANG = 'transcript';
+/** `![caption](x.mp3)` / `.m4a` is a clip the reader plays. */
+export const AUDIO_SRC = /\.(mp3|m4a)(?:[?#].*)?$/i;
+export const isAudioSrc = (src) => typeof src === 'string' && AUDIO_SRC.test(src);
+/** A page this long is a book, not a voice note. */
+export const MAX_TRANSCRIPT_WORDS = 20000;
+const ROW = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s+(\S.*)$/;
+const GRAMMAR = 'a transcript line is "<start> <end> <word>" in seconds, like "1.10 1.30 hope"';
+/** Parses a transcript fence's body. `line` is the line the fence opens on in the file, so every
+ *  error names the line the author sees in their editor. */
+export function parseTranscriptFence(value, line) {
+    const paragraphs = [];
+    let current = [];
+    let prev = null;
+    let count = 0;
+    const rows = value.split('\n');
+    for (let i = 0; i < rows.length; i++) {
+        const raw = rows[i].trim();
+        const at = line + 1 + i;
+        if (!raw) {
+            if (current.length)
+                paragraphs.push(current);
+            current = [];
+            continue;
+        }
+        const m = ROW.exec(raw);
+        if (!m)
+            return { ok: false, error: `line ${at}: ${GRAMMAR}` };
+        const s = Number(m[1]);
+        const e = Number(m[2]);
+        if (e < s)
+            return { ok: false, error: `line ${at}: this word ends before it starts (${m[1]} to ${m[2]})` };
+        if (prev && s < prev.s)
+            return { ok: false, error: `line ${at}: this word starts at ${m[1]}, before the word above it (${prev.s}); words go in the order they are spoken` };
+        if (++count > MAX_TRANSCRIPT_WORDS)
+            return { ok: false, error: `line ${at}: a transcript takes at most ${MAX_TRANSCRIPT_WORDS} words` };
+        prev = { w: m[3].trim(), s, e };
+        current.push(prev);
+    }
+    if (current.length)
+        paragraphs.push(current);
+    if (!count)
+        return { ok: false, error: `line ${line}: this transcript has no words; ${GRAMMAR}` };
+    return { ok: true, paragraphs };
+}
+/** The audio image a paragraph holds and nothing else (whitespace aside), or null. */
+export function soleAudio(n) {
+    if (!n || n.type !== 'paragraph')
+        return null;
+    const kids = n.children.filter((c) => !(c.type === 'text' && !c.value.trim()));
+    return kids.length === 1 && kids[0].type === 'image' && isAudioSrc(kids[0].url) ? kids[0] : null;
+}
+const isParent = (n) => !!n && typeof n === 'object' && Array.isArray(n.children);
+/** Visits every transcript fence with the sibling right above it, at any depth. */
+function eachTranscript(tree, visit) {
+    const walk = (p) => {
+        p.children.forEach((n, i) => {
+            if (n.type === 'code' && n.lang === TRANSCRIPT_LANG)
+                visit(n, p.children[i - 1]);
+            else if (isParent(n) && n.type !== 'paragraph' && n.type !== 'heading')
+                walk(n);
+        });
+    };
+    walk(tree);
+}
+/** The publish-time check: every transcript fence parses, takes no name, and sits directly under
+ *  an audio line. `offset` is how many lines of the file sit above the body. */
+export function scanVoiceNotes(tree, offset) {
+    let error = null;
+    let count = 0;
+    eachTranscript(tree, (fence, above) => {
+        if (error)
+            return;
+        const line = (fence.position?.start.line ?? 1) + offset;
+        if (fence.meta?.trim()) {
+            error = `line ${line}: the transcript block takes no name`;
+            return;
+        }
+        if (!soleAudio(above)) {
+            error = `line ${line}: a transcript belongs directly under its voice note: put an audio line like ![caption](note.m4a) right above it`;
+            return;
+        }
+        const r = parseTranscriptFence(fence.value, line);
+        if (!r.ok) {
+            error = r.error;
+            return;
+        }
+        count++;
+    });
+    return error ? { ok: false, error } : { ok: true, count };
+}
+/** Replaces each audio line + transcript pair with one node the renderer draws as a voice note,
+ *  keeping the audio line's position so its comment anchor (blocksOf) is unchanged. A pair that
+ *  does not parse is left alone: the audio plays as before and the fence draws nothing. `found`
+ *  collects the notes; the node carries its index. */
+export function remarkVoiceNotes(found) {
+    return () => (tree) => {
+        const walk = (p) => {
+            const out = [];
+            for (const n of p.children) {
+                const above = out[out.length - 1];
+                const audio = n.type === 'code' && n.lang === TRANSCRIPT_LANG && !n.meta?.trim() ? soleAudio(above) : null;
+                const r = audio ? parseTranscriptFence(n.value, 0) : null;
+                if (audio && r?.ok) {
+                    found.push({ src: audio.url, label: audio.alt ?? '', paragraphs: r.paragraphs });
+                    out[out.length - 1] = {
+                        type: 'artifactVoiceNote',
+                        position: above.position,
+                        data: { hName: 'div', hProperties: { dataArtifactVoicenoteAt: String(found.length - 1) } },
+                        children: [],
+                    };
+                    continue;
+                }
+                if (isParent(n) && n.type !== 'paragraph' && n.type !== 'heading')
+                    walk(n);
+                out.push(n);
+            }
+            p.children = out;
+        };
+        walk(tree);
+    };
+}
+/** The body of a transcript fence for a list of timed words: one word per line, and a blank line
+ *  wherever the speaker paused at least `paragraphGap` seconds. Times never run backwards, so the
+ *  result always passes the publish check. Correct a word's spelling afterwards; keep its times. */
+export function transcriptFenceFromWords(words, opts = {}) {
+    const gap = opts.paragraphGap ?? 1.5;
+    const lines = [];
+    let prev = null;
+    for (const w of words) {
+        const text = w.word.replace(/\s+/g, ' ').trim();
+        if (!text)
+            continue;
+        const start = Math.max(0, prev ? Math.max(w.start, prev.start) : w.start);
+        const end = Math.max(start, w.end);
+        if (prev && start - prev.end >= gap)
+            lines.push('');
+        lines.push(`${start.toFixed(2)} ${end.toFixed(2)} ${text}`);
+        prev = { start, end };
+    }
+    return lines.length ? lines.join('\n') + '\n' : '';
+}
+/** The timed words in a whisper JSON result (`segments[].words[]`, written by `mlx_whisper` or
+ *  `whisper` with word timestamps on). Anything else in the file is ignored. */
+export function wordsFromWhisperJson(json) {
+    const segments = json?.segments;
+    if (!Array.isArray(segments))
+        return [];
+    const out = [];
+    for (const seg of segments) {
+        const words = seg?.words;
+        if (!Array.isArray(words))
+            continue;
+        for (const w of words) {
+            const { word, start, end } = (w ?? {});
+            if (typeof word === 'string' && typeof start === 'number' && typeof end === 'number')
+                out.push({ word, start, end });
+        }
+    }
+    return out;
+}

package/lib/artifacts/widgets.js

@@ -17,6 +17,7 @@ import remarkGfm from 'remark-gfm';
 import { blockId } from './anchor.js';
 import { MAX_NOTE_CHARS, NOTES_SLOT } from './notes-place.js';
 import { isEmbedKind, parseEmbedFence } from './simulator.js';
+import { scanVoiceNotes, TRANSCRIPT_LANG } from './voice-note.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
@@ -70,7 +71,8 @@ export function headingsOf(markdown) {
  *  (the front matter), so every error names the line the author sees in their editor. */
 export function scanWidgets(body, offset) {
     const fences = [];
-    walk(parse(body).children, (n) => { if (n.type === 'code')
+    const tree = parse(body);
+    walk(tree.children, (n) => { if (n.type === 'code')
         fences.push(n); });
     let notes = null;
     for (const f of fences) {
@@ -108,6 +110,9 @@ export function scanWidgets(body, offset) {
         if (!r.ok)
             return r;
     }
+    const voiced = scanVoiceNotes(tree, offset);
+    if (!voiced.ok)
+        return voiced;
     const lists = scanChecklists(fences, offset);
     if (!lists.ok)
         return lists;
@@ -287,7 +292,7 @@ export function blocksOf(markdown) {
             content = plain(n);
         }
         else if (n.type === 'code') {
-            if (n.lang === 'links' || n.lang === NOTES_SLOT || n.lang === 'checklist')
+            if (n.lang === 'links' || n.lang === NOTES_SLOT || n.lang === 'checklist' || n.lang === TRANSCRIPT_LANG)
                 continue;
             kind = 'code';
             content = n.value;

package/lib/cli/transcript-fence.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli/transcript-fence.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Turns a recording into the ```transcript fence a voice note needs, so nobody times words by
+// hand. The package carries no transcriber: this runs one already on the machine, locally,
+// `mlx_whisper` (Apple Silicon: `pip install mlx-whisper`) or else openai-whisper's `whisper`,
+// with word timestamps on, and prints the fence to paste under the audio line.
+//
+//   npx -p @supersuit/artifacts supersuit-transcript-fence note.m4a [--language en] [--model M] [--gap 1.5] [--body]
+//
+// Correct any word afterwards (a name, a phrase in another language); keep its two times.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, readdirSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { transcriptFenceFromWords, wordsFromWhisperJson } from '../artifacts/voice-note.js';
+const USAGE = 'usage: supersuit-transcript-fence <audio file> [--language en] [--model <whisper model>] [--gap <seconds>] [--body]';
+function arg(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function has(cmd) {
+    return spawnSync('sh', ['-c', `command -v ${cmd}`], { stdio: 'ignore' }).status === 0;
+}
+function main(argv) {
+    const args = argv.slice(2);
+    const file = args.find((a, i) => !a.startsWith('--') && !['--language', '--model', '--gap'].includes(args[i - 1]));
+    if (!file || args.includes('--help')) {
+        process.stderr.write(USAGE + '\n');
+        return file ? 0 : 2;
+    }
+    const path = resolve(file);
+    if (!existsSync(path)) {
+        process.stderr.write(`no such file: ${path}\n`);
+        return 2;
+    }
+    const language = arg(args, '--language');
+    const gap = Number(arg(args, '--gap') ?? 1.5);
+    const out = mkdtempSync(join(tmpdir(), 'transcript-fence-'));
+    try {
+        let r;
+        if (has('mlx_whisper')) {
+            const model = arg(args, '--model') ?? 'mlx-community/whisper-large-v3-turbo';
+            r = spawnSync('mlx_whisper', [path, '--word-timestamps', 'True', '-f', 'json', '-o', out, '--model', model, ...(language ? ['--language', language] : [])], { stdio: ['ignore', 'ignore', 'inherit'] });
+        }
+        else if (has('whisper')) {
+            const model = arg(args, '--model') ?? 'turbo';
+            r = spawnSync('whisper', [path, '--word_timestamps', 'True', '--output_format', 'json', '--output_dir', out, '--model', model, ...(language ? ['--language', language] : [])], { stdio: ['ignore', 'ignore', 'inherit'] });
+        }
+        else {
+            process.stderr.write('no local transcriber found: install mlx-whisper (pip install mlx-whisper, Apple Silicon) or openai-whisper (pip install openai-whisper)\n');
+            return 3;
+        }
+        if (r.status !== 0) {
+            process.stderr.write(`the transcriber exited ${r.status}\n`);
+            return 1;
+        }
+        const json = readdirSync(out).find((f) => f.endsWith('.json'));
+        if (!json) {
+            process.stderr.write('the transcriber wrote no JSON\n');
+            return 1;
+        }
+        const body = transcriptFenceFromWords(wordsFromWhisperJson(JSON.parse(readFileSync(join(out, json), 'utf8'))), { paragraphGap: gap });
+        if (!body) {
+            process.stderr.write('the transcriber heard no words\n');
+            return 1;
+        }
+        process.stdout.write(args.includes('--body') ? body : '```transcript\n' + body + '```\n');
+        return 0;
+    }
+    finally {
+        rmSync(out, { recursive: true, force: true });
+    }
+}
+process.exitCode = main(process.argv);

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

@@ -1,8 +1,5 @@
-export type WordTiming = {
-    w: string;
-    s: number;
-    e: number;
-};
+import { litWordIndex, type WordTiming } from './karaoke.js';
+export { litWordIndex, type WordTiming };
 /** The elements that hold a run of text; a word whose block differs from the previous word's
  *  starts a new sentence in the browser read-aloud. */
 export declare const BLOCK = "p, li, td, th, h1, h2, h3, h4, h5, h6, blockquote, aside, dt, dd, figcaption, div";
@@ -12,9 +9,6 @@ export declare function wrapWords(root: HTMLElement): HTMLSpanElement[];
 /** The karaoke word a click lands on, or null. A defined term is a control that opens its
  *  definition, so a tap on it must never seek or start the narration. */
 export declare function seekableWord(target: Element | null): HTMLSpanElement | null;
-/** 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;

package/lib/reader/artifact-reader.js

@@ -10,6 +10,8 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // where they are and shows a button that brings them back to the voice.
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { nextRate, PlayerBar } from './player-bar.js';
+import { litWordIndex } from './karaoke.js';
+export { litWordIndex };
 const SKIP = '[data-nospeak], [data-artifact-links], pre, [data-footnotes], sup, img, style, script';
 /** The elements that hold a run of text; a word whose block differs from the previous word's
  *  starts a new sentence in the browser read-aloud. */
@@ -109,25 +111,6 @@ function align(spans, words) {
     }
     return out;
 }
-/** 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 function litWordIndex(words, now, started) {
-    if (!started)
-        return -1;
-    let lo = 0;
-    let hi = words.length - 1;
-    let idx = -1;
-    while (lo <= hi) {
-        const mid = (lo + hi) >> 1;
-        if (words[mid].s <= now) {
-            idx = mid;
-            lo = mid + 1;
-        }
-        else
-            hi = mid - 1;
-    }
-    return idx >= 0 && now <= words[idx].e + 0.25 ? idx : -1;
-}
 function fmt(t) {
     const m = Math.floor(t / 60);
     const s = Math.floor(t % 60);

package/lib/reader/index.d.ts

@@ -1,4 +1,5 @@
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex, type WordTiming } from './artifact-reader.js';
+export { begunCount } from './karaoke.js';
 export { PlayerBar } from './player-bar.js';
 export { QuietView } from './quiet-view.js';
 export { CommentLayer } from './comment-layer.js';

package/lib/reader/index.js

@@ -1,6 +1,7 @@
 // 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 { begunCount } from './karaoke.js';
 export { PlayerBar } from './player-bar.js';
 export { QuietView } from './quiet-view.js';
 export { CommentLayer } from './comment-layer.js';

package/lib/reader/karaoke.d.ts

@@ -0,0 +1,13 @@
+export type WordTiming = {
+    w: string;
+    s: number;
+    e: number;
+};
+/** 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;
+/** How many words have begun by `now`: the rest are still to come. A pause between words keeps
+ *  the count, so the words already said never fall back to muted in a silence. */
+export declare function begunCount(words: WordTiming[], now: number): number;
+/** The highlight on the word being spoken, in the page's accent. */
+export declare const litDeclarations: (accent: string) => string;

package/lib/reader/karaoke.js

@@ -0,0 +1,33 @@
+// The karaoke primitives the page's narration and a voice note share: which word is being spoken
+// at a time, how many words have begun, and the one highlight both draw. Pure and server-safe.
+/** The last word that has begun by `now`, or -1. Words are sorted by start. */
+function lastBegun(words, now) {
+    let lo = 0;
+    let hi = words.length - 1;
+    let idx = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (words[mid].s <= now) {
+            idx = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return idx;
+}
+/** 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 function litWordIndex(words, now, started) {
+    if (!started)
+        return -1;
+    const idx = lastBegun(words, now);
+    return idx >= 0 && now <= words[idx].e + 0.25 ? idx : -1;
+}
+/** How many words have begun by `now`: the rest are still to come. A pause between words keeps
+ *  the count, so the words already said never fall back to muted in a silence. */
+export function begunCount(words, now) {
+    return lastBegun(words, now) + 1;
+}
+/** The highlight on the word being spoken, in the page's accent. */
+export const litDeclarations = (accent) => `background: color-mix(in srgb, ${accent} 35%, transparent); color: var(--a-strong, #fff);`;

package/lib/reader/player-bar.js

@@ -8,11 +8,12 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // button, the seek line, the progress and the speed. The speed button has a FIXED width wide enough
 // for its longest label ("1.25x"), so stepping 1x -> 1.25x -> 2x never resizes it and never shifts
 // the seek line beside it (Gary: "the bottom bar speed dial shouldn't cause reflow when clicked").
+import { litDeclarations } from './karaoke.js';
 export function PlayerBar({ playing, onToggle, accent, ground, value, max, step, onSeek, progress, rate, onRate, }) {
     return (_jsxs(_Fragment, { children: [_jsx("style", { children: `
         .artifact-word { border-radius: 3px; transition: background-color 120ms; }
         .artifact-word:hover { background: var(--a-surface-strong, rgba(255,255,255,0.08)); cursor: pointer; }
-        .artifact-word-lit { background: color-mix(in srgb, ${accent} 35%, transparent); color: var(--a-strong, #fff); }
+        .artifact-word-lit { ${litDeclarations(accent)} }
       ` }), _jsx("div", { "data-artifact-player": true, className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: onToggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsx("div", { className: "min-w-0 flex-1", children: _jsx("input", { type: "range", min: 0, max: max || 0, step: step, value: Math.min(value, max || 0), onChange: (e) => onSeek(Number(e.target.value)), "aria-label": "Seek", className: "block w-full", style: { accentColor: accent } }) }), _jsx("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: progress }), _jsxs("button", { type: "button", onClick: onRate, "data-artifact-rate": true, className: "w-14 shrink-0 whitespace-nowrap rounded border border-[color:var(--a-line-strong)] py-1 text-center text-xs tabular-nums text-[color:var(--a-body)]", "aria-label": `Playback speed, ${rate}x`, children: [rate, "x"] })] }) }), _jsx("div", { className: "h-20", "aria-hidden": true })] }));
 }
 /** The speeds the speed button steps through, in order, wrapping back to the first. */

package/lib/routes/recipients-routes.js

@@ -136,7 +136,7 @@ export function createRecipientsRoutes(given) {
         // A page nobody has been added to yet has no readers, which is an answer and not a missing page.
         const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
         const entries = ctx.state ? await ctx.state.entries(id) : [];
-        const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, at: e.at, text: String(e.value?.body ?? '') }));
+        const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, id: e.id, parent: typeof e.value?.parent === 'string' ? e.value.parent : null, at: e.at, text: String(e.value?.body ?? '') }));
         return json({ id, expireAt: rec.expireAt, keep: rec.keep, recipients: summarizeViews(rec, await ctx.recipients.views(id), comments) });
     }
     /** Reader text goes with the page: every comment and answer on it, whoever wrote it. */

package/lib/routes/state-routes.js

@@ -5,7 +5,8 @@
 //   GET  /api/artifacts/<id>/responses  publish key; every answer with who (?format=csv)
 //   DELETE /api/artifacts/<id>/responses?reader=<key>  publish key; one reader's answers
 //   GET  /api/comments?since=<ISO>      publish key; every shared comment on any page after a time
-//                                       (&open=1: leave out threads that are resolved)
+//                                       (&open=1: leave out threads that are resolved;
+//                                       &artifact=<id>: only that page's comments)
 //   POST /api/artifacts/<id>/resolve    publish key, or the owner or an admin signed in; resolve or
 //                                       reopen one comment thread { entry, resolved?, note?, by? }
 //
@@ -368,6 +369,16 @@ export function createStateRoutes(ctx) {
                 if (!replacing)
                     return json({ error: 'this page is not taking more answers here' }, 409);
             }
+            // A group link under `comment_name: required` makes each browser its own reader, so one link
+            // could start any number of them. The FIRST STORED write of a reader key the page has not seen
+            // is counted against the link, whether it came with a cookie or not (any 24 characters pass as
+            // one), and only here, after validation, so a refused request spends nothing. A key that
+            // already has an entry is never counted again.
+            if (recipient?.perBrowser && !(await ctx.state.entries(id)).some((e) => e.readerKey === writer.key)) {
+                const n = await ctx.state.countAnonWrite(id, `gl.${recipient.rid}`, Math.floor(Date.now() / 60000));
+                if (n > ANON_WRITES_PER_MINUTE)
+                    return json({ error: 'too many new readers through this link; try again in a minute' }, 429);
+            }
             const r = op === 'set'
                 ? await ctx.state.set({ artifactId: id, slot, writer, value })
                 : await ctx.state.append({ artifactId: id, slot, writer, value });
@@ -424,10 +435,17 @@ export function createStateRoutes(ctx) {
         const openOnly = openParam === '1' || openParam === 'true';
         if (!ctx.state)
             return json({ error: 'this host keeps no answers' }, 501);
-        if (!ctx.state.slotSince)
+        // One page's feed (0.43.0): read that page's entries alone, so a caller paging a single page
+        // never reads, or is handed, another page's comments.
+        const only = req.nextUrl.searchParams.get('artifact');
+        if (only !== null && !ARTIFACT_ID_RE.test(only))
+            return json({ error: 'artifact must be a page id, like abcd2345' }, 400);
+        if (only === null && !ctx.state.slotSince)
             return json({ error: 'this host cannot list comments by time' }, 501);
         const now = new Date().toISOString();
-        const entries = await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
+        const entries = only !== null
+            ? (await ctx.state.entries(only)).filter((e) => e.slot === COMMENTS_SLOT && e.at > since).sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id)).slice(0, FEED_MAX)
+            : await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
         const pages = new Map();
         const pageOf = (id) => { if (!pages.has(id))
             pages.set(id, ctx.store.get(id)); return pages.get(id); };

package/lib/widgets/voice-note.d.ts

@@ -0,0 +1,10 @@
+import { type WordTiming } from '../reader/karaoke.js';
+export declare function VoiceNote({ src, label, media, paragraphs, block }: {
+    src: string;
+    label: string;
+    /** The stored file's name, for play tracking. */
+    media: string;
+    paragraphs: WordTiming[][];
+    /** The comment anchor the audio line carried. */
+    block?: Record<string, string>;
+}): import("react").JSX.Element;

package/lib/widgets/voice-note.js

@@ -0,0 +1,125 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A voice note in the reader's browser: a recording tucked into the page like a note in a letter.
+// The caption, a play button and a seek line drawn in the page's brand (never the native bar), and
+// the speaker's own words beneath, lit one at a time as they are spoken: words already said read
+// normally, the word being said carries the same highlight as the page's narration (karaoke.ts),
+// and the words to come are a little muted. Tapping a word plays from there.
+//
+// The whole note is data-nospeak, so the page's own narration skips it: a reader hears the person,
+// never a robot reading the person. The words are server-rendered, so the transcript reads as text
+// before anything loads; only the lighting needs the browser.
+//
+// iPhone Safari: no autoplay, `preload="none"` (nothing fetched until play), `playsinline`. A seek
+// asked for before the clip has loaded waits for its metadata, since Safari drops it otherwise.
+// `data-artifact-media` stays on the <audio>, so play tracking counts it like any clip.
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { begunCount, litDeclarations, litWordIndex } from '../reader/karaoke.js';
+const CSS = '[data-artifact-voicenote] .vn-word{border-radius:3px;cursor:pointer;transition:background-color 120ms,opacity 200ms;-webkit-tap-highlight-color:transparent}' +
+    '[data-artifact-voicenote] .vn-word:hover{background:var(--a-surface-strong,rgba(127,127,127,0.12))}' +
+    '[data-artifact-voicenote] .vn-word.vn-ahead{opacity:0.5}' +
+    `[data-artifact-voicenote] .vn-word.vn-word-lit{${litDeclarations('var(--a-accent)')}opacity:1}` +
+    '[data-artifact-voicenote] input[type=range]{accent-color:var(--a-accent)}' +
+    '[data-artifact-voicenote] button:focus-visible,[data-artifact-voicenote] input:focus-visible{outline:2px solid var(--a-accent);outline-offset:2px}';
+function fmt(t) {
+    const s = Math.max(0, Math.floor(t));
+    return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
+}
+export function VoiceNote({ src, label, media, paragraphs, block }) {
+    const audioRef = useRef(null);
+    const rootRef = useRef(null);
+    const words = useMemo(() => paragraphs.flat(), [paragraphs]);
+    const spans = useRef([]);
+    const shown = useRef({ lit: -1, begun: -1 });
+    const [playing, setPlaying] = useState(false);
+    const [started, setStarted] = useState(false);
+    const startedRef = useRef(false);
+    const [t, setT] = useState(0);
+    const [duration, setDuration] = useState(0);
+    const total = duration || words[words.length - 1]?.e || 0;
+    /** Light the word at the audio's current time; touch only the spans whose state changed. */
+    const sync = () => {
+        const a = audioRef.current;
+        if (!a)
+            return;
+        const now = a.currentTime;
+        setT(now);
+        if (!startedRef.current)
+            return;
+        const lit = litWordIndex(words, now, true);
+        const begun = a.ended ? words.length : begunCount(words, now);
+        const was = shown.current;
+        if (lit === was.lit && begun === was.begun)
+            return;
+        if (was.lit !== lit) {
+            spans.current[was.lit]?.classList.remove('vn-word-lit');
+            spans.current[lit]?.classList.add('vn-word-lit');
+        }
+        const from = Math.max(0, Math.min(begun, was.begun < 0 ? 0 : was.begun));
+        const to = was.begun < 0 ? spans.current.length : Math.max(begun, was.begun);
+        for (let i = from; i < to; i++)
+            spans.current[i]?.classList.toggle('vn-ahead', i >= begun);
+        shown.current = { lit, begun };
+    };
+    const start = () => {
+        if (startedRef.current)
+            return;
+        startedRef.current = true;
+        setStarted(true);
+    };
+    // While it plays, follow the voice every frame; Safari's timeupdate alone is four times a second.
+    useEffect(() => {
+        if (!playing)
+            return;
+        let raf = 0;
+        const tick = () => {
+            sync();
+            raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(raf);
+    });
+    const play = () => {
+        const a = audioRef.current;
+        if (!a)
+            return;
+        start();
+        // One voice at a time: the narration or another note stops when this one starts.
+        for (const other of Array.from(document.querySelectorAll('audio')))
+            if (other !== a && !other.paused)
+                other.pause();
+        void a.play()?.catch?.(() => setPlaying(false));
+    };
+    const toggle = () => {
+        const a = audioRef.current;
+        if (!a)
+            return;
+        if (a.paused)
+            play();
+        else
+            a.pause();
+    };
+    const seekTo = (s) => {
+        const a = audioRef.current;
+        if (!a)
+            return;
+        start();
+        const go = () => {
+            a.currentTime = s;
+            sync();
+        };
+        if (a.readyState >= 1)
+            go();
+        else
+            a.addEventListener('loadedmetadata', go, { once: true });
+    };
+    let k = 0;
+    spans.current = [];
+    return (_jsxs("div", { ...block, ref: rootRef, "data-nospeak": true, "data-artifact-voicenote": true, ...(started ? { 'data-started': '' } : {}), className: "my-8 rounded-xl border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-5 pb-5 pt-4 shadow-sm", children: [_jsx("style", { children: CSS }), _jsx("audio", { ref: audioRef, src: src, preload: "none", playsInline: true, "data-artifact-media": media, onPlay: () => { start(); setPlaying(true); }, onPause: () => { setPlaying(false); sync(); }, onEnded: () => { setPlaying(false); sync(); }, onTimeUpdate: sync, onSeeked: sync, onLoadedMetadata: (e) => { const d = e.currentTarget.duration; if (Number.isFinite(d))
+                    setDuration(d); }, onDurationChange: (e) => { const d = e.currentTarget.duration; if (Number.isFinite(d))
+                    setDuration(d); } }), _jsx("span", { className: "block text-[11px] uppercase tracking-[0.2em] text-[color:var(--a-accent)]", children: "Voice note" }), label ? _jsx("span", { className: "mt-1 block font-serif text-lg italic text-[color:var(--a-strong)]", children: label }) : null, _jsxs("div", { className: "mt-3 flex items-center gap-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": `${playing ? 'Pause' : 'Play'} voice note${label ? `: ${label}` : ''}`, className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full bg-[color:var(--a-accent)] text-[color:var(--a-on-accent)]", children: playing ? (_jsxs("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsx("input", { type: "range", "aria-label": "Seek", min: 0, max: total || 1, step: 0.01, value: Math.min(t, total || 1), onChange: (e) => seekTo(Number(e.currentTarget.value)), className: "min-w-0 flex-1" }), _jsxs("span", { className: "shrink-0 font-mono text-xs tabular-nums text-[color:var(--a-muted)]", children: [fmt(t), " / ", fmt(total)] })] }), _jsx("div", { className: "mt-4 leading-relaxed text-[color:var(--a-body)]", children: paragraphs.map((p, pi) => (_jsx("p", { "data-vn-paragraph": true, className: "my-2", children: p.map((w, wi) => {
+                        const i = k++;
+                        return (_jsxs("span", { children: [wi ? ' ' : null, _jsx("span", { ref: (el) => { if (el)
+                                        spans.current[i] = el; }, className: "vn-word", onClick: () => { seekTo(w.s); play(); }, children: w.w })] }, wi));
+                    }) }, pi))) })] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.42.0",
+  "version": "0.44.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",
@@ -20,6 +20,9 @@
   ],
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "bin": {
+    "supersuit-transcript-fence": "lib/cli/transcript-fence.js"
+  },
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",