@supersuit/artifacts 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 `@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.12.0 (2026-09-28)
+
+**Say a comment instead of typing it.** The comment card has a microphone. While you speak, a
+browser with speech recognition (Chrome, Edge, Safari) fills the box live; when you stop, a host
+that configured transcription replaces it with a better transcript unless you already edited it.
+With neither, the recording is kept and the box stays yours to type in. Memos cap at 3 minutes.
+The recording travels with the comment and plays back from the pin, the thread and `/responses`.
+
+- Host config: `transcribe?: Transcriber`, with `deepgramTranscriber(key)` (Nova-3) and
+  `openaiTranscriber(key, model?)` from `./artifacts`. The key never reaches the browser and never
+  appears in an error.
+- New handler `TRANSCRIBE` (`POST /api/artifacts/<id>/transcribe`): 404 when the host passed no
+  transcriber, so the reader falls back to the browser; only readers who may write comments, or
+  signed-in readers on their own notes; 20 per reader per page per hour.
+- Recordings upload through the existing `UPLOAD` route with a signed PUT (`audio` in the body),
+  under `comments/` or `personal/<hashed reader>/`; a comment may only name a `comments/` path and
+  a note only its own reader's. Playback is by signed URL (`audioUrl` on rows). Reader audio has
+  its own allowlist (webm, m4a, mp3, ogg; iPhone `audio/mp4` is stored as `.m4a`).
+- Anonymous personal memos stay in the browser (IndexedDB) and move to the account on sign-in.
+- The privacy test now covers personal audio: no publisher route returns it or its URL.
+- DETECTOR: a comment card with no microphone.
+- REMEDY: bump; add `app/api/artifacts/[id]/transcribe/route.ts` delegating to `TRANSCRIBE`;
+  pass `transcribe` to get server transcripts; the bucket's CORS must allow `PUT` from the site
+  origin with `content-type`, `cache-control` and `x-goog-content-length-range`.
+- Tests: adapters against a stubbed fetch, the transcribe route (404, rate limit, refusal),
+  upload path guards, the recorder (live transcript, host transcript vs an edited box, no-support
+  path, the 3-minute cap, device-only memos), the extended privacy test. All key rules
+  mutation-checked.
+
 ## 0.11.1 (2026-09-28)
 
 **The comment controls draw in the page's colours.** The comment overlay is portalled onto

package/README.md

@@ -446,6 +446,46 @@ export function DELETE(request: NextRequest, ctx: Ctx) { return artifacts.PERSON
 Without `personal`, every reader's notes stay on their device. Without `state`, no page takes
 shared comments.
 
+### Voice memos
+
+Every comment card has a Record button where the browser can record (Chrome records
+`audio/webm`, iPhone Safari `audio/mp4`, stored as `.m4a`). Where the browser has speech
+recognition, the words appear in the box as the reader speaks. A memo stops at three minutes.
+
+Recordings go up through the same `uploads/<name>` route the publisher uses, to
+`<page>/comments/<memo>.<ext>` or, for a signed-in reader's personal note,
+`<page>/personal/<dir>/<memo>.<ext>`. They are never made public: playback is a signed URL
+issued beside the comment or note it belongs to. That needs the four audio methods
+`createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`, `audioUrl`); a host
+with its own `ArtifactAssets` and none of them keeps memos on the reader's device. On a bucket
+with bucket-wide public read, a recording is readable by anyone holding its path (the paths are
+unguessable); keep the bucket per-object public to have the signed-URL guarantee.
+
+To transcribe on the server, pass `transcribe` and add the route. The key stays on the server;
+without `transcribe` the route answers 404 and readers keep the browser's live transcript (or an
+empty box). 20 transcriptions per reader per page per hour.
+
+```ts
+import { deepgramTranscriber } from '@supersuit/artifacts/artifacts'
+export const artifacts = createArtifactRoutes({
+  // ...
+  transcribe: process.env.DEEPGRAM_API_KEY ? deepgramTranscriber(process.env.DEEPGRAM_API_KEY) : undefined,
+  // or openaiTranscriber(key, 'gpt-4o-mini-transcribe')
+})
+```
+
+```ts
+// app/api/artifacts/[id]/transcribe/route.ts
+import type { NextRequest } from 'next/server'
+import { artifacts } from '@/lib/artifacts'
+type Ctx = { params: Promise<{ id: string }> }
+export function POST(request: NextRequest, ctx: Ctx) { return artifacts.TRANSCRIBE(request, ctx) }
+```
+
+The bucket also needs CORS allowing `PUT` from the site's origin with the `content-type`,
+`cache-control` and `x-goog-content-length-range` headers, since the reader's browser uploads
+directly.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,

package/lib/artifacts/assets.d.ts

@@ -14,6 +14,17 @@ export interface ArtifactAssets {
     }>;
     /** After a signed upload: make it readable and return its URL, or null if nothing arrived. */
     finishUpload?(id: string, name: string, digest: string): Promise<string | null>;
+    /** A signed URL a reader PUTs one recording to, at most MAX_AUDIO_BYTES. */
+    signAudioUpload?(id: string, path: string, contentType: string): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+    }>;
+    /** After the PUT: the stored size, or null if nothing arrived. */
+    audioSize?(id: string, path: string): Promise<number | null>;
+    /** The recording's bytes, for the transcriber; null when there is none. */
+    readAudio?(id: string, path: string): Promise<Buffer | null>;
+    /** A signed URL to play the recording, valid for about an hour. */
+    audioUrl?(id: string, path: string): Promise<string>;
 }
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export declare const ASSET_DIGEST: RegExp;

package/lib/artifacts/assets.js

@@ -3,6 +3,7 @@
 // publisher shelled out to gsutil against the maintainer's bucket, which no other operator
 // could do, so every operator gets the same door: PUT bytes with their key, get a URL back.
 import { createHash } from 'node:crypto';
+import { MAX_AUDIO_BYTES } from './audio.js';
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export const ASSET_DIGEST = /^[0-9a-f]{8}$/;
 const CACHE_CONTROL = 'public, max-age=31536000, immutable';
@@ -96,5 +97,39 @@ export function createArtifactAssets(bucket, prefix) {
             }
             return `https://storage.googleapis.com/${bucket.name}/${key}`;
         },
+        // The size cap rides in the signature (`x-goog-content-length-range`), so the bucket itself
+        // refuses an oversize body; the browser must send the returned headers verbatim.
+        async signAudioUpload(id, path, contentType) {
+            const range = `0,${MAX_AUDIO_BYTES}`;
+            const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600', 'x-goog-content-length-range': range };
+            const [uploadUrl] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({
+                version: 'v4',
+                action: 'write',
+                expires: Date.now() + 15 * 60 * 1000,
+                contentType,
+                extensionHeaders: { 'cache-control': headers['cache-control'], 'x-goog-content-length-range': range },
+            });
+            return { uploadUrl, headers };
+        },
+        async audioSize(id, path) {
+            const file = bucket.file(`${clean}/${id}/${path}`);
+            const [there] = await file.exists();
+            if (!there)
+                return null;
+            const [meta] = await file.getMetadata();
+            return Number(meta.size ?? 0);
+        },
+        async readAudio(id, path) {
+            const file = bucket.file(`${clean}/${id}/${path}`);
+            const [there] = await file.exists();
+            if (!there)
+                return null;
+            const [bytes] = await file.download();
+            return bytes;
+        },
+        async audioUrl(id, path) {
+            const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            return url;
+        },
     };
 }

package/lib/artifacts/audio.d.ts

@@ -0,0 +1,21 @@
+/** Extension -> the type it is stored and transcribed as. */
+export declare const AUDIO_TYPES: Record<string, string>;
+/** The type without parameters: `audio/webm;codecs=opus` -> `audio/webm`. */
+export declare const baseMime: (mime: string) => string;
+/** The extension a recording of this type is stored under, or null when a page does not take it. */
+export declare function audioExtFor(mime: string): string | null;
+/** The type of a stored recording, from its path's extension; null when it is not one. */
+export declare function audioTypeFor(path: string): string | null;
+/** A memo is capped at 3 minutes in the recorder, a bit under 3 MB at voice bitrate; this is the
+ *  ceiling the upload and the transcriber enforce whatever the browser sent. */
+export declare const MAX_AUDIO_BYTES: number;
+export declare const MAX_MEMO_MS: number;
+/** A memo's file name: a random id the browser draws, and the extension of its type. */
+export declare const MEMO_NAME: RegExp;
+/** Where a shared comment's recording lives under its page. */
+export declare const commentAudioPath: (name: string) => string;
+export declare const isCommentAudioPath: (p: unknown) => p is string;
+/** A signed-in reader's personal-note recording, under a directory only their uid derives
+ *  (`personalAudioDir` in personal-store.ts). Anything else is not theirs. */
+export declare const personalAudioPath: (dir: string, name: string) => string;
+export declare const isPersonalAudioPath: (p: unknown, dir: string) => p is string;

package/lib/artifacts/audio.js

@@ -0,0 +1,43 @@
+// Voice memos: which recordings a page takes, and what each one is called. Pure, so the reader's
+// browser, the routes and the transcribers all agree on one table.
+//
+// Chrome records `audio/webm` (with a codec suffix), iPhone Safari records `audio/mp4`. Both have
+// to survive the whole trip: the recorder's choice, the upload allowlist, the stored extension,
+// and the Content-Type the transcription service is told. `.m4a`, never `.mp4`, for mp4 audio:
+// the publisher's `.mp4` is a video, and a transcriber that detects by file name needs to know
+// this one is audio.
+/** Extension -> the type it is stored and transcribed as. */
+export const AUDIO_TYPES = {
+    webm: 'audio/webm',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+};
+/** The type without parameters: `audio/webm;codecs=opus` -> `audio/webm`. */
+export const baseMime = (mime) => mime.split(';')[0].trim().toLowerCase();
+/** The extension a recording of this type is stored under, or null when a page does not take it. */
+export function audioExtFor(mime) {
+    const base = baseMime(mime);
+    for (const [ext, type] of Object.entries(AUDIO_TYPES))
+        if (type === base)
+            return ext;
+    return null;
+}
+/** The type of a stored recording, from its path's extension; null when it is not one. */
+export function audioTypeFor(path) {
+    const ext = path.split('.').pop()?.toLowerCase() ?? '';
+    return Object.hasOwn(AUDIO_TYPES, ext) ? AUDIO_TYPES[ext] : null;
+}
+/** A memo is capped at 3 minutes in the recorder, a bit under 3 MB at voice bitrate; this is the
+ *  ceiling the upload and the transcriber enforce whatever the browser sent. */
+export const MAX_AUDIO_BYTES = 4 * 1024 * 1024;
+export const MAX_MEMO_MS = 3 * 60 * 1000;
+/** A memo's file name: a random id the browser draws, and the extension of its type. */
+export const MEMO_NAME = /^[A-Za-z0-9_-]{16,64}\.(webm|m4a|mp3|ogg)$/;
+/** Where a shared comment's recording lives under its page. */
+export const commentAudioPath = (name) => `comments/${name}`;
+export const isCommentAudioPath = (p) => typeof p === 'string' && p.startsWith('comments/') && MEMO_NAME.test(p.slice('comments/'.length));
+/** A signed-in reader's personal-note recording, under a directory only their uid derives
+ *  (`personalAudioDir` in personal-store.ts). Anything else is not theirs. */
+export const personalAudioPath = (dir, name) => `personal/${dir}/${name}`;
+export const isPersonalAudioPath = (p, dir) => typeof p === 'string' && p.startsWith(`personal/${dir}/`) && MEMO_NAME.test(p.slice(`personal/${dir}/`.length));

package/lib/artifacts/index.d.ts

@@ -13,4 +13,6 @@ export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type S
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.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';
-export { createPersonalStore, createMemoryPersonalStore, validatePersonal, MAX_PERSONAL_PER_READER, type PersonalStore, type PersonalNote, type PersonalNoteValue } from './personal-store.js';
+export { createPersonalStore, createMemoryPersonalStore, validatePersonal, personalAudioDir, MAX_PERSONAL_PER_READER, type PersonalStore, type PersonalNote, type PersonalNoteValue } from './personal-store.js';
+export { deepgramTranscriber, openaiTranscriber, type Transcriber } from './transcribe.js';
+export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';

package/lib/artifacts/index.js

@@ -13,4 +13,6 @@ export { stateView, responsesOf, responsesCsv } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.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';
-export { createPersonalStore, createMemoryPersonalStore, validatePersonal, MAX_PERSONAL_PER_READER } from './personal-store.js';
+export { createPersonalStore, createMemoryPersonalStore, validatePersonal, personalAudioDir, MAX_PERSONAL_PER_READER } from './personal-store.js';
+export { deepgramTranscriber, openaiTranscriber } from './transcribe.js';
+export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';

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

@@ -8,6 +8,10 @@ export type PersonalNote = {
     updatedAt?: string;
 };
 export declare const MAX_PERSONAL_PER_READER = 500;
+/** The directory a signed-in reader's voice-note recordings live in under a page: derived from
+ *  their uid, so a path names its owner without spelling out an account id, and a route can tell
+ *  in one comparison whether a recording is the asker's own. */
+export declare const personalAudioDir: (readerUid: string) => string;
 export interface PersonalStore {
     list(artifactId: string, readerUid: string): Promise<PersonalNote[]>;
     add(artifactId: string, readerUid: string, value: PersonalNoteValue): Promise<PersonalNote | {

package/lib/artifacts/personal-store.js

@@ -12,9 +12,13 @@
 // `base` is the artifacts collection path (`tenants/<id>/artifacts`), the same base the readers
 // store uses, so each tenant's notes sit beside its own pages. A reader who is not signed in keeps
 // notes on their device instead (reader/device-notes.ts): those never reach any server at all.
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { validateComment } from './comments.js';
 export const MAX_PERSONAL_PER_READER = 500;
+/** The directory a signed-in reader's voice-note recordings live in under a page: derived from
+ *  their uid, so a path names its owner without spelling out an account id, and a route can tell
+ *  in one comparison whether a recording is the asker's own. */
+export const personalAudioDir = (readerUid) => createHash('sha256').update(`personal-audio|${readerUid}`).digest('hex').slice(0, 24);
 /** A personal note is a comment with no thread: nobody else can see it to reply. */
 export function validatePersonal(v) {
     if (v && typeof v === 'object' && 'parent' in v)

package/lib/artifacts/transcribe.d.ts

@@ -0,0 +1,8 @@
+/** A finished recording in, the transcript out; null when the service could not produce one. */
+export type Transcriber = (audio: Blob, mime: string) => Promise<{
+    text: string;
+} | null>;
+/** Deepgram Nova-3: the raw recording as the body, its type as Content-Type. */
+export declare function deepgramTranscriber(key: string): Transcriber;
+/** OpenAI's transcription endpoint: a multipart form, the file named so the format is detected. */
+export declare function openaiTranscriber(key: string, model?: string): Transcriber;

package/lib/artifacts/transcribe.js

@@ -0,0 +1,56 @@
+// Transcription: the host decides, the browser is the floor.
+//
+// A host that has a key for a transcription service passes `transcribe` to createArtifactRoutes,
+// and the reader's finished voice memo is sent there from the server, so the key never reaches a
+// browser. Without it the transcribe route answers 404 and the reader keeps whatever the browser
+// transcribed live (or an empty box). The two adapters below are ready to pass as they are.
+//
+// THE KEY NEVER LEAVES THIS FILE. An adapter answers null on any failure and never throws: a
+// thrown error travels into logs and error bodies, and a service that echoes the credential back
+// in its own error text (some do) would carry the key with it. Nothing here reads a response body
+// on a failure, and nothing here puts the key anywhere but the Authorization header.
+import { audioExtFor, baseMime } from './audio.js';
+// Under the route's own 30-second budget, so a slow service ends in a clean null, not a timeout.
+const TIMEOUT_MS = 25_000;
+async function post(url, init) {
+    try {
+        const r = await fetch(url, { ...init, signal: AbortSignal.timeout(TIMEOUT_MS) });
+        if (!r.ok)
+            return null;
+        return await r.json();
+    }
+    catch {
+        return null;
+    }
+}
+const textOf = (t) => (typeof t === 'string' ? { text: t.trim() } : null);
+/** Deepgram Nova-3: the raw recording as the body, its type as Content-Type. */
+export function deepgramTranscriber(key) {
+    return async (audio, mime) => {
+        if (!key)
+            return null;
+        const body = await post('https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true', {
+            method: 'POST',
+            headers: { Authorization: `Token ${key}`, 'Content-Type': baseMime(mime) },
+            body: audio,
+        });
+        return textOf(body?.results?.channels?.[0]?.alternatives?.[0]?.transcript);
+    };
+}
+/** OpenAI's transcription endpoint: a multipart form, the file named so the format is detected. */
+export function openaiTranscriber(key, model = 'gpt-4o-mini-transcribe') {
+    return async (audio, mime) => {
+        const ext = audioExtFor(mime);
+        if (!key || !ext)
+            return null;
+        const form = new FormData();
+        form.append('file', new File([audio], `memo.${ext}`, { type: baseMime(mime) }));
+        form.append('model', model);
+        const body = await post('https://api.openai.com/v1/audio/transcriptions', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${key}` },
+            body: form,
+        });
+        return textOf(body?.text);
+    };
+}

package/lib/reader/comment-card.d.ts

@@ -1,8 +1,19 @@
-import { type CommentsMode } from '../artifacts/comments.js';
+import { type CommentValue, type CommentsMode } from '../artifacts/comments.js';
+import { type VoiceHost, type VoiceMemo, type VoiceScope } from './voice-recorder.js';
+/** A memo as the card hands it to be saved: the recording, where it was already uploaded (if it
+ *  was, and for which kind), and where the words in the box came from. */
+export type SavedMemo = {
+    memo: VoiceMemo;
+    uploaded: {
+        scope: VoiceScope;
+        path: string;
+    } | null;
+    transcript?: CommentValue['transcript'];
+};
 /** The warning, word for word. `They` is fixed copy: the card never guesses a pronoun. */
 export declare function warningLine(ownerName: string, mode: CommentsMode): string;
 export declare const DEVICE_LINE = "Saved on this device. Sign in to keep it everywhere.";
-export declare function CommentCard({ ownerName, mode, canShare, signedIn, quote, initial, accent, signIn, onSave, onCancel, }: {
+export declare function CommentCard({ ownerName, mode, canShare, signedIn, quote, initial, accent, signIn, voice, onSave, onCancel, }: {
     ownerName: string;
     mode: CommentsMode;
     canShare: boolean;
@@ -12,7 +23,9 @@ export declare function CommentCard({ ownerName, mode, canShare, signedIn, quote
     initial?: string;
     accent?: string;
     signIn?: string | null;
+    /** The page's voice routes. Null: a memo is kept but never uploaded or transcribed here. */
+    voice?: VoiceHost | null;
     /** Resolves to an error to show, or null when saved. */
-    onSave: (body: string, share: boolean) => Promise<string | null>;
+    onSave: (body: string, share: boolean, memo?: SavedMemo) => Promise<string | null>;
     onCancel: () => void;
 }): import("react").JSX.Element;

package/lib/reader/comment-card.js

@@ -5,8 +5,13 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // owner will never see, shown every time, because the moment it matters is the moment someone is
 // about to write something they meant for the owner. When they can share, a switch picks Share
 // (the default) or Just for me.
-import { useState } from 'react';
+//
+// A voice memo (voice-recorder.tsx) writes into the same box: the browser's live transcript while
+// you speak, then the host's transcript when the recording stops, unless you have edited the box
+// since, in which case your words win. With neither, the memo is kept and the box stays empty.
+import { useRef, useState } from 'react';
 import { MAX_COMMENT_CHARS } from '../artifacts/comments.js';
+import { VoiceRecorder } from './voice-recorder.js';
 /** The warning, word for word. `They` is fixed copy: the card never guesses a pronoun. */
 export function warningLine(ownerName, mode) {
     const why = mode === 'off'
@@ -15,22 +20,52 @@ export function warningLine(ownerName, mode) {
     return `Only you will see this. ${why}, so this is a personal note. They won't see it.`;
 }
 export const DEVICE_LINE = 'Saved on this device. Sign in to keep it everywhere.';
-export function CommentCard({ ownerName, mode, canShare, signedIn, quote, initial = '', accent = 'currentColor', signIn, onSave, onCancel, }) {
+export function CommentCard({ ownerName, mode, canShare, signedIn, quote, initial = '', accent = 'currentColor', signIn, voice = null, onSave, onCancel, }) {
     const [text, setText] = useState(initial);
     const [share, setShare] = useState(canShare);
     const [busy, setBusy] = useState(false);
     const [error, setError] = useState(null);
+    const [memo, setMemo] = useState(null);
+    const [transcript, setTranscript] = useState(undefined);
+    const [status, setStatus] = useState(null);
+    // Refs, because the host's transcript arrives after an await and must see the box as it is then.
+    const base = useRef('');
+    const edited = useRef(false);
+    const uploaded = useRef(null);
     const personal = !canShare || !share;
+    // Where a memo goes: a shared comment, the reader's account, or (neither) this device only.
+    const scope = () => (canShare && share ? 'comment' : signedIn ? 'personal' : null);
+    const recorded = async (m) => {
+        setMemo(m);
+        uploaded.current = null;
+        edited.current = false;
+        const where = scope();
+        if (!voice || !where)
+            return;
+        setStatus('Transcribing');
+        const path = await voice.upload(m, where);
+        if (path) {
+            uploaded.current = { scope: where, path };
+            const heard = await voice.transcribe(path);
+            if (heard && !edited.current) {
+                setText(base.current ? `${base.current} ${heard}` : heard);
+                setTranscript('host');
+            }
+        }
+        setStatus(null);
+    };
     const submit = async (e) => {
         e?.preventDefault();
         const body = text.trim();
-        if (!body || busy)
+        if ((!body && !memo) || busy)
             return;
         setBusy(true);
-        const err = await onSave(body, canShare && share);
+        const err = memo
+            ? await onSave(body, canShare && share, { memo, uploaded: uploaded.current, ...(body && transcript ? { transcript } : {}) })
+            : await onSave(body, canShare && share);
         setBusy(false);
         setError(err);
     };
-    return (_jsxs("form", { "data-comment-card": true, "data-comment-ui": true, "data-nospeak": true, onSubmit: submit, className: "w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-left font-sans text-sm text-[color:var(--a-strong)] shadow-xl", children: [!canShare ? (_jsx("p", { "data-comment-warning": true, role: "note", className: "mb-2 rounded-lg border px-3 py-2 text-[13px] leading-snug", style: { borderColor: accent }, children: warningLine(ownerName, mode) })) : null, quote ? _jsx("p", { className: "mb-2 line-clamp-3 border-l-2 pl-2 text-[13px] italic opacity-75", style: { borderColor: accent }, children: quote }) : null, _jsx("textarea", { value: text, autoFocus: true, onChange: (e) => setText(e.target.value), onKeyDown: (e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey))
-                    void submit(); }, maxLength: MAX_COMMENT_CHARS, rows: 3, "aria-label": personal ? 'A personal note' : `A comment for ${ownerName}`, placeholder: personal ? 'A note for yourself' : `A comment for ${ownerName}`, className: "w-full rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-ground,transparent)] p-2 text-[15px]" }), canShare ? (_jsxs("fieldset", { className: "mt-2 flex flex-wrap gap-x-4 gap-y-1 text-[13px]", children: [_jsx("legend", { className: "sr-only", children: "Who sees this" }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("input", { type: "radio", name: "comment-share", "data-comment-share": "share", checked: share, onChange: () => setShare(true) }), `Share with ${ownerName}`] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("input", { type: "radio", name: "comment-share", "data-comment-share": "mine", checked: !share, onChange: () => setShare(false) }), "Just for me"] })] })) : null, personal && !signedIn ? (_jsx("p", { "data-comment-device": true, className: "mt-2 text-xs opacity-70", children: signIn ? _jsxs(_Fragment, { children: ["Saved on this device. ", _jsx("a", { href: signIn, className: "underline", children: "Sign in to keep it everywhere." })] }) : DEVICE_LINE })) : null, error ? _jsx("p", { role: "alert", className: "mt-2 text-xs text-amber-500", children: error }) : null, _jsxs("div", { className: "mt-3 flex items-center gap-3", children: [_jsx("button", { type: "submit", "data-comment-save": true, disabled: busy || !text.trim(), className: "rounded-full px-4 py-1 text-sm font-medium disabled:opacity-40", style: { background: accent, color: 'var(--a-on-accent, #111)' }, children: personal ? 'Save note' : 'Comment' }), _jsx("button", { type: "button", onClick: onCancel, className: "text-sm opacity-70 hover:opacity-100", children: "Cancel" })] })] }));
+    return (_jsxs("form", { "data-comment-card": true, "data-comment-ui": true, "data-nospeak": true, onSubmit: submit, className: "w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-left font-sans text-sm text-[color:var(--a-strong)] shadow-xl", children: [!canShare ? (_jsx("p", { "data-comment-warning": true, role: "note", className: "mb-2 rounded-lg border px-3 py-2 text-[13px] leading-snug", style: { borderColor: accent }, children: warningLine(ownerName, mode) })) : null, quote ? _jsx("p", { className: "mb-2 line-clamp-3 border-l-2 pl-2 text-[13px] italic opacity-75", style: { borderColor: accent }, children: quote }) : null, _jsx("textarea", { value: text, autoFocus: true, onChange: (e) => { setText(e.target.value); edited.current = true; setTranscript('typed'); }, onKeyDown: (e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey))
+                    void submit(); }, maxLength: MAX_COMMENT_CHARS, rows: 3, "aria-label": personal ? 'A personal note' : `A comment for ${ownerName}`, placeholder: personal ? 'A note for yourself' : `A comment for ${ownerName}`, className: "w-full rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-ground,transparent)] p-2 text-[15px]" }), _jsx(VoiceRecorder, { accent: accent, onStart: () => { base.current = text.trim(); setMemo(null); setTranscript(undefined); setError(null); }, onLive: (heard) => { setText(base.current ? `${base.current} ${heard}` : heard); setTranscript('browser'); }, onStop: (m) => void recorded(m), onError: setError }), memo ? (_jsxs("p", { "data-voice-kept": true, className: "m-0 mt-1 text-xs opacity-70", children: [status ?? 'Recording kept with this comment.', _jsx("button", { type: "button", "data-voice-discard": true, className: "ml-2 underline", onClick: () => { setMemo(null); uploaded.current = null; }, children: "Discard recording" })] })) : null, canShare ? (_jsxs("fieldset", { className: "mt-2 flex flex-wrap gap-x-4 gap-y-1 text-[13px]", children: [_jsx("legend", { className: "sr-only", children: "Who sees this" }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("input", { type: "radio", name: "comment-share", "data-comment-share": "share", checked: share, onChange: () => setShare(true) }), `Share with ${ownerName}`] }), _jsxs("label", { className: "flex items-center gap-1.5", children: [_jsx("input", { type: "radio", name: "comment-share", "data-comment-share": "mine", checked: !share, onChange: () => setShare(false) }), "Just for me"] })] })) : null, personal && !signedIn ? (_jsx("p", { "data-comment-device": true, className: "mt-2 text-xs opacity-70", children: signIn ? _jsxs(_Fragment, { children: ["Saved on this device. ", _jsx("a", { href: signIn, className: "underline", children: "Sign in to keep it everywhere." })] }) : DEVICE_LINE })) : null, error ? _jsx("p", { role: "alert", className: "mt-2 text-xs text-amber-500", children: error }) : null, _jsxs("div", { className: "mt-3 flex items-center gap-3", children: [_jsx("button", { type: "submit", "data-comment-save": true, disabled: busy || (!text.trim() && !memo), className: "rounded-full px-4 py-1 text-sm font-medium disabled:opacity-40", style: { background: accent, color: 'var(--a-on-accent, #111)' }, children: personal ? 'Save note' : 'Comment' }), _jsx("button", { type: "button", onClick: onCancel, className: "text-sm opacity-70 hover:opacity-100", children: "Cancel" })] })] }));
 }

package/lib/reader/comment-layer.d.ts

@@ -1,5 +1,7 @@
 import { type CommentsMode } from '../artifacts/comments.js';
-export declare function CommentLayer({ artifactId, rootId, ownerName, comments, canShare, signedIn, isOwner, version, accent, ground, signIn, }: {
+import { type VoiceHost } from './voice-recorder.js';
+import { type DeviceAudio } from './device-audio.js';
+export declare function CommentLayer({ artifactId, rootId, ownerName, comments, canShare, signedIn, isOwner, version, accent, ground, signIn, voice, audioStore, }: {
     artifactId: string;
     /** The element holding the page's prose, the same root the read-aloud lights. */
     rootId: string;
@@ -14,4 +16,8 @@ export declare function CommentLayer({ artifactId, rootId, ownerName, comments,
     accent: string;
     ground: string;
     signIn?: string | null;
+    /** The page's voice routes; defaults to this page's own. Tests pass a stub. */
+    voice?: VoiceHost;
+    /** Where an anonymous reader's recordings live; defaults to this browser's IndexedDB. */
+    audioStore?: DeviceAudio;
 }): import("react").JSX.Element;