@supersuit/artifacts 0.11.0 → 0.12.0

package/lib/reader/comment-layer.js

@@ -23,6 +23,10 @@ import { createPortal } from 'react-dom';
 import { MAX_QUOTE_CHARS, textAnchorFrom } from '../artifacts/anchor.js';
 import { COMMENTS_SLOT } from '../artifacts/comments.js';
 import { CommentCard } from './comment-card.js';
+import { AudioPlay, hostVoice, newMemoId } from './voice-recorder.js';
+import { deviceAudio as defaultDeviceAudio, isDeviceAudio } from './device-audio.js';
+import { audioExtFor } from '../artifacts/audio.js';
+import { themeVarsAround } from './theme-vars.js';
 import { addDeviceNote, deviceNotes, removeDeviceNote, replaceDeviceNote } from './device-notes.js';
 import { boxOf, headingAt, indexText, offsetAt, placeAnchor, regionFrom } from './comment-place.js';
 const isValue = (v) => !!v && typeof v === 'object' && typeof v.body === 'string' && !!v.anchor && typeof v.anchor === 'object';
@@ -51,12 +55,20 @@ function sharedFrom(body) {
     for (const r of rows.values()) {
         if (!isValue(r.value))
             continue;
-        out.push({ id: String(r.id), kind: 'shared', where: 'server', value: r.value, name: r.mine === true ? 'You' : typeof r.name === 'string' ? r.name : 'a reader', mine: r.mine === true, at: String(r.at ?? '') });
+        out.push({
+            id: String(r.id), kind: 'shared', where: 'server', value: r.value, name: r.mine === true ? 'You' : typeof r.name === 'string' ? r.name : 'a reader', mine: r.mine === true, at: String(r.at ?? ''),
+            ...(typeof r.audioUrl === 'string' ? { audioUrl: r.audioUrl } : {}),
+        });
     }
     return out.sort((a, b) => a.at.localeCompare(b.at));
 }
-const personalFrom = (notes, where) => notes.filter((n) => isValue(n.value)).map((n) => ({ id: n.id, kind: 'personal', where, value: n.value, name: 'You', mine: true, at: n.at }));
-export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare, signedIn, isOwner, version, accent, ground, signIn, }) {
+const personalFrom = (notes, where) => notes.filter((n) => isValue(n.value)).map((n) => ({
+    id: n.id, kind: 'personal', where, value: n.value, name: 'You', mine: true, at: n.at,
+    ...(typeof n.audioUrl === 'string' ? { audioUrl: n.audioUrl } : {}),
+}));
+export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare, signedIn, isOwner, version, accent, ground, signIn, voice, audioStore, }) {
+    const host = useMemo(() => voice ?? hostVoice(artifactId), [voice, artifactId]);
+    const audioDb = useMemo(() => audioStore ?? defaultDeviceAudio, [audioStore]);
     const stateUrl = `/api/artifacts/${artifactId}/state`;
     const personalUrl = `/api/artifacts/${artifactId}/personal`;
     const [mounted, setMounted] = useState(false);
@@ -71,6 +83,7 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     const [thread, setThread] = useState(null);
     const [drag, setDrag] = useState(null);
     const [tick, setTick] = useState(0);
+    const [theme, setTheme] = useState({});
     const call = useCallback(async (url, init) => {
         try {
             const r = await fetch(url, { credentials: 'same-origin', cache: 'no-store', ...init });
@@ -81,6 +94,14 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
         }
     }, []);
     const refreshDevice = useCallback(() => setDevice(personalFrom(deviceNotes(artifactId), 'device')), [artifactId]);
+    // The theme the overlay carries, re-read when a `system` page flips between light and dark.
+    useEffect(() => {
+        const read = () => setTheme(themeVarsAround(document.getElementById(rootId)));
+        read();
+        const mq = typeof window.matchMedia === 'function' ? window.matchMedia('(prefers-color-scheme: dark)') : null;
+        mq?.addEventListener?.('change', read);
+        return () => mq?.removeEventListener?.('change', read);
+    }, [rootId]);
     useEffect(() => {
         setMounted(true);
         refreshDevice();
@@ -100,12 +121,34 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
                 }
                 let notes = r.body.notes ?? [];
                 // Notes kept on this device before signing in move to the account, then leave the device.
+                // A recording kept on the device goes up to the account first, then the note names it there.
                 for (const n of deviceNotes(artifactId)) {
-                    const m = await call(personalUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ value: n.value }) });
+                    const value = { ...n.value };
+                    const key = isDeviceAudio(value.audio) ? value.audio : null;
+                    if (key) {
+                        const blob = await audioDb.get(key);
+                        const path = blob ? await host.upload({ blob, mime: blob.type }, 'personal') : null;
+                        if (blob && !path)
+                            break;
+                        if (path)
+                            value.audio = path;
+                        else {
+                            // The recording is gone from this device: keep the words, or nothing is left to keep.
+                            delete value.audio;
+                            delete value.transcript;
+                            if (!value.body.trim()) {
+                                removeDeviceNote(artifactId, n.id);
+                                continue;
+                            }
+                        }
+                    }
+                    const m = await call(personalUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ value }) });
                     if (m.status !== 200)
                         break;
                     notes = m.body.notes ?? notes;
                     removeDeviceNote(artifactId, n.id);
+                    if (key)
+                        await audioDb.remove(key);
                 }
                 if (!live)
                     return;
@@ -120,7 +163,7 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
         if (ro && root)
             ro.observe(root);
         return () => { live = false; window.removeEventListener('resize', relayout); ro?.disconnect(); };
-    }, [artifactId, comments, signedIn, stateUrl, personalUrl, rootId, call, refreshDevice]);
+    }, [artifactId, comments, signedIn, stateUrl, personalUrl, rootId, call, refreshDevice, host, audioDb]);
     // Text selection inside the page shows the Comment chip.
     useEffect(() => {
         const root = document.getElementById(rootId);
@@ -274,8 +317,26 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
         return { placed, earlier };
         // `tick` re-measures after a resize.
     }, [mounted, rootId, tops, tick]); // eslint-disable-line react-hooks/exhaustive-deps
-    const saveNew = async (body, share, d) => {
-        const value = { anchor: d.anchor, body, version };
+    /** The recording's path for where it is being saved: reused when the card already uploaded it
+     *  there, uploaded now when the reader switched between Share and Just for me after recording. */
+    const memoPath = async (m, scope) => m.uploaded?.scope === scope ? m.uploaded.path : host.upload(m.memo, scope);
+    const LOST = 'The recording did not upload. Try again, or discard it and save the text.';
+    const saveNew = async (body, share, d, memo) => {
+        const value = { anchor: d.anchor, body, version, ...(memo?.transcript ? { transcript: memo.transcript } : {}) };
+        const toDevice = !share && !(signedIn && onServer);
+        if (memo && !toDevice) {
+            const path = await memoPath(memo, share ? 'comment' : 'personal');
+            if (!path)
+                return LOST;
+            value.audio = path;
+        }
+        if (memo && toDevice) {
+            // Not signed in: the recording stays in this browser with the note, and never leaves it.
+            const key = `device/${newMemoId()}.${audioExtFor(memo.memo.mime) ?? 'webm'}`;
+            if (!(await audioDb.put(key, memo.memo.blob)))
+                return 'This browser would not keep the recording. Discard it and save the text.';
+            value.audio = key;
+        }
         if (share) {
             const r = await call(stateUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ slot: COMMENTS_SLOT, op: 'append', value }) });
             if (r.status !== 200)
@@ -305,6 +366,8 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     const remove = async (item) => {
         if (item.where === 'device') {
             removeDeviceNote(artifactId, item.id);
+            if (isDeviceAudio(item.value.audio))
+                await audioDb.remove(item.value.audio);
             refreshDevice();
         }
         else if (item.kind === 'personal') {
@@ -349,7 +412,7 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     const open = layout.placed.find((p) => p.item.id === thread);
     const openItem = open?.item ?? layout.earlier.find((i) => i.id === thread);
     const count = tops.length;
-    const overlay = mounted ? (_jsxs("div", { "data-comment-ui": true, "data-nospeak": true, className: "font-sans", children: [showPins ? layout.placed.map(({ item, left, top, box }) => (_jsxs("div", { children: [box ? (_jsx("div", { "data-comment-box": item.id, "aria-hidden": true, className: "pointer-events-none absolute z-30 rounded-md border-2", style: { left: box.left, top: box.top, width: box.width, height: box.height, borderColor: accent, borderStyle: item.kind === 'personal' ? 'dashed' : 'solid', opacity: thread === item.id ? 1 : 0.55 } })) : null, _jsx(Pin, { item: item, left: left, top: top, accent: accent, ground: ground, onOpen: () => setThread(thread === item.id ? null : item.id) })] }, item.id))) : null, chip && !draft ? (_jsx("button", { type: "button", "data-comment-chip": true, className: "absolute z-50 -translate-x-full rounded-full px-3 py-1 text-xs font-medium shadow-lg", style: { left: chip.x, top: chip.y, background: accent, color: 'var(--a-on-accent, #111)' }, onMouseDown: (e) => e.preventDefault(), onClick: () => { setDraft(chip); setChip(null); }, children: "Comment" })) : null, draft ? (_jsx(Floating, { x: draft.x, y: draft.y, children: _jsx(CommentCard, { ownerName: ownerName, mode: comments, canShare: canShare, signedIn: signedIn && onServer, quote: draft.quote, accent: accent, signIn: signIn, onSave: (body, share) => saveNew(body, share, draft), onCancel: () => setDraft(null) }) })) : null, openItem && open ? (_jsx(Floating, { x: open.left + 28, y: open.top, children: _jsx(Thread, { item: openItem, replies: items.filter((i) => i.value.parent === openItem.id), canReply: openItem.kind === 'shared' && canShare, accent: accent, onClose: () => setThread(null), onRemove: remove, onEdit: edit, onReply: reply }) })) : null, drag ? (_jsx("div", { "aria-hidden": true, className: "pointer-events-none fixed z-40 rounded-md border-2 border-dashed", style: { left: Math.min(drag.x1, drag.x2), top: Math.min(drag.y1, drag.y2), width: Math.abs(drag.x2 - drag.x1), height: Math.abs(drag.y2 - drag.y1), borderColor: accent, background: `color-mix(in srgb, ${accent} 12%, transparent)` } })) : null, _jsxs("div", { className: "fixed right-4 z-40 flex flex-col items-end gap-2", style: { bottom: 'calc(env(safe-area-inset-bottom, 0px) + 5.5rem)' }, children: [panel ? (_jsxs("div", { "data-comment-panel": true, className: "w-64 rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-xs text-[color:var(--a-strong)] shadow-xl", children: [_jsx("p", { className: "opacity-80", children: "Select any text, or hold and drag a box over anything, to leave a comment." }), isOwner ? _jsx("p", { "data-comment-owner": true, className: "mt-1 opacity-80", children: "This is your page: you see every comment, with the name of who left it." }) : null, _jsx("button", { type: "button", "data-comment-pins-toggle": true, className: "mt-2 underline", onClick: () => setShowPins((v) => !v), children: showPins ? 'Hide comments' : 'Show comments' })] })) : null, _jsx("button", { type: "button", "data-comment-button": true, "aria-expanded": panel, onClick: () => setPanel((v) => !v), className: "rounded-full border px-3 py-1.5 text-xs font-medium shadow-lg backdrop-blur", style: { borderColor: accent, color: accent, background: `color-mix(in srgb, ${ground} 85%, transparent)` }, children: count ? `Comments · ${count}` : 'Comment' })] })] })) : null;
+    const overlay = mounted ? (_jsxs("div", { "data-comment-ui": true, "data-nospeak": true, className: "font-sans", style: theme, children: [showPins ? layout.placed.map(({ item, left, top, box }) => (_jsxs("div", { children: [box ? (_jsx("div", { "data-comment-box": item.id, "aria-hidden": true, className: "pointer-events-none absolute z-30 rounded-md border-2", style: { left: box.left, top: box.top, width: box.width, height: box.height, borderColor: accent, borderStyle: item.kind === 'personal' ? 'dashed' : 'solid', opacity: thread === item.id ? 1 : 0.55 } })) : null, _jsx(Pin, { item: item, left: left, top: top, accent: accent, ground: ground, onOpen: () => setThread(thread === item.id ? null : item.id) })] }, item.id))) : null, chip && !draft ? (_jsx("button", { type: "button", "data-comment-chip": true, className: "absolute z-50 -translate-x-full rounded-full px-3 py-1 text-xs font-medium shadow-lg", style: { left: chip.x, top: chip.y, background: accent, color: 'var(--a-on-accent, #111)' }, onMouseDown: (e) => e.preventDefault(), onClick: () => { setDraft(chip); setChip(null); }, children: "Comment" })) : null, draft ? (_jsx(Floating, { x: draft.x, y: draft.y, children: _jsx(CommentCard, { ownerName: ownerName, mode: comments, canShare: canShare, signedIn: signedIn && onServer, quote: draft.quote, accent: accent, signIn: signIn, voice: host, onSave: (body, share, memo) => saveNew(body, share, draft, memo), onCancel: () => setDraft(null) }) })) : null, openItem && open ? (_jsx(Floating, { x: open.left + 28, y: open.top, children: _jsx(Thread, { item: openItem, replies: items.filter((i) => i.value.parent === openItem.id), canReply: openItem.kind === 'shared' && canShare, accent: accent, audioDb: audioDb, onClose: () => setThread(null), onRemove: remove, onEdit: edit, onReply: reply }) })) : null, drag ? (_jsx("div", { "aria-hidden": true, className: "pointer-events-none fixed z-40 rounded-md border-2 border-dashed", style: { left: Math.min(drag.x1, drag.x2), top: Math.min(drag.y1, drag.y2), width: Math.abs(drag.x2 - drag.x1), height: Math.abs(drag.y2 - drag.y1), borderColor: accent, background: `color-mix(in srgb, ${accent} 12%, transparent)` } })) : null, _jsxs("div", { className: "fixed right-4 z-40 flex flex-col items-end gap-2", style: { bottom: 'calc(env(safe-area-inset-bottom, 0px) + 5.5rem)' }, children: [panel ? (_jsxs("div", { "data-comment-panel": true, className: "w-64 rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-xs text-[color:var(--a-strong)] shadow-xl", children: [_jsx("p", { className: "opacity-80", children: "Select any text, or hold and drag a box over anything, to leave a comment." }), isOwner ? _jsx("p", { "data-comment-owner": true, className: "mt-1 opacity-80", children: "This is your page: you see every comment, with the name of who left it." }) : null, _jsx("button", { type: "button", "data-comment-pins-toggle": true, className: "mt-2 underline", onClick: () => setShowPins((v) => !v), children: showPins ? 'Hide comments' : 'Show comments' })] })) : null, _jsx("button", { type: "button", "data-comment-button": true, "aria-expanded": panel, onClick: () => setPanel((v) => !v), className: "rounded-full border px-3 py-1.5 text-xs font-medium shadow-lg backdrop-blur", style: { borderColor: accent, color: accent, background: `color-mix(in srgb, ${ground} 85%, transparent)` }, children: count ? `Comments · ${count}` : 'Comment' })] })] })) : null;
     return (_jsxs(_Fragment, { children: [_jsx("span", { hidden: true, "data-comment-layer": comments, "data-comment-can-share": canShare ? 'yes' : 'no' }), mounted && layout.earlier.length ? (_jsxs("section", { "data-comments-earlier": true, "data-comment-ui": true, "data-nospeak": true, className: "mx-auto max-w-2xl px-6 pb-16 text-sm", children: [_jsx("p", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: "Comments on earlier versions" }), _jsx("ul", { className: "m-0 mt-2 grid list-none gap-3 p-0", children: layout.earlier.map((item) => (_jsxs("li", { className: "m-0 border-l-2 py-1 pl-3", style: { borderColor: accent, borderStyle: item.kind === 'personal' ? 'dashed' : 'solid' }, children: [item.value.anchor.kind === 'text' ? _jsxs("span", { className: "block text-[13px] italic opacity-70", children: ["\u201C", item.value.anchor.quote, "\u201D"] }) : _jsx("span", { className: "block text-[13px] italic opacity-70", children: "A box on part of the page that has changed" }), _jsx("span", { className: "block whitespace-pre-wrap text-[15px] text-[color:var(--a-strong)]", children: item.value.body }), _jsxs("span", { className: "block text-xs opacity-60", children: [item.kind === 'personal' ? 'only you' : item.name, ` · version ${item.value.version}`, item.mine ? _jsx("button", { type: "button", onClick: () => void remove(item), className: "ml-2 underline", children: "delete" }) : null] })] }, item.id))) })] })) : null, overlay ? createPortal(overlay, document.body) : null] }));
 }
 function Pin({ item, left, top, accent, ground, onOpen }) {
@@ -362,19 +425,38 @@ function Floating({ x, y, children }) {
     const left = typeof window === 'undefined' ? x : Math.max(window.scrollX + 8, Math.min(x, window.scrollX + window.innerWidth - width - 8));
     return _jsx("div", { className: "absolute z-50", style: { left, top: y }, children: children });
 }
-function Thread({ item, replies, canReply, accent, onClose, onRemove, onEdit, onReply }) {
+function Thread({ item, replies, canReply, accent, audioDb, onClose, onRemove, onEdit, onReply }) {
     const [replying, setReplying] = useState(false);
-    return (_jsxs("div", { "data-comment-thread": true, "data-comment-ui": true, "data-nospeak": true, className: "w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-sm text-[color:var(--a-strong)] shadow-xl", children: [_jsxs("div", { className: "mb-2 flex items-center justify-between text-[11px] uppercase tracking-[0.15em]", style: { color: accent }, children: [_jsx("span", { children: item.kind === 'personal' ? 'Only you' : 'Comment' }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close", className: "opacity-70 hover:opacity-100", children: "\u00D7" })] }), item.value.anchor.kind === 'text' ? _jsx("p", { className: "mb-2 line-clamp-2 border-l-2 pl-2 text-[13px] italic opacity-70", style: { borderColor: accent }, children: item.value.anchor.quote }) : null, _jsx(Entry, { item: item, onRemove: onRemove, onEdit: onEdit }), replies.length ? _jsx("ul", { className: "m-0 mt-2 grid list-none gap-2 border-l pl-3 p-0", children: replies.map((r) => _jsx("li", { className: "m-0", children: _jsx(Entry, { item: r, onRemove: onRemove, onEdit: onEdit }) }, r.id)) }) : null, canReply ? (replying
+    return (_jsxs("div", { "data-comment-thread": true, "data-comment-ui": true, "data-nospeak": true, className: "w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-sm text-[color:var(--a-strong)] shadow-xl", children: [_jsxs("div", { className: "mb-2 flex items-center justify-between text-[11px] uppercase tracking-[0.15em]", style: { color: accent }, children: [_jsx("span", { children: item.kind === 'personal' ? 'Only you' : 'Comment' }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close", className: "opacity-70 hover:opacity-100", children: "\u00D7" })] }), item.value.anchor.kind === 'text' ? _jsx("p", { className: "mb-2 line-clamp-2 border-l-2 pl-2 text-[13px] italic opacity-70", style: { borderColor: accent }, children: item.value.anchor.quote }) : null, _jsx(Entry, { item: item, accent: accent, audioDb: audioDb, onRemove: onRemove, onEdit: onEdit }), replies.length ? _jsx("ul", { className: "m-0 mt-2 grid list-none gap-2 border-l pl-3 p-0", children: replies.map((r) => _jsx("li", { className: "m-0", children: _jsx(Entry, { item: r, accent: accent, audioDb: audioDb, onRemove: onRemove, onEdit: onEdit }) }, r.id)) }) : null, canReply ? (replying
                 ? _jsx(InlineForm, { label: "Reply", accent: accent, onCancel: () => setReplying(false), onSubmit: async (b) => { const e = await onReply(item, b); if (!e)
                         setReplying(false); return e; } })
                 : _jsx("button", { type: "button", "data-comment-reply": true, onClick: () => setReplying(true), className: "mt-2 text-xs underline", children: "Reply" })) : null] }));
 }
-function Entry({ item, onRemove, onEdit }) {
+/** Where a comment's recording plays from: its signed URL, or this browser's copy of a device note's. */
+function useAudioSrc(item, audioDb) {
+    const [local, setLocal] = useState(null);
+    const key = item.where === 'device' && isDeviceAudio(item.value.audio) ? item.value.audio : null;
+    useEffect(() => {
+        if (!key || typeof URL.createObjectURL !== 'function')
+            return;
+        let url = null;
+        let live = true;
+        void audioDb.get(key).then((b) => { if (live && b) {
+            url = URL.createObjectURL(b);
+            setLocal(url);
+        } });
+        return () => { live = false; if (url)
+            URL.revokeObjectURL(url); };
+    }, [key, audioDb]);
+    return item.audioUrl ?? local;
+}
+function Entry({ item, accent, audioDb, onRemove, onEdit }) {
     const [editing, setEditing] = useState(false);
+    const src = useAudioSrc(item, audioDb);
     if (editing)
         return _jsx(InlineForm, { label: "Save", initial: item.value.body, onCancel: () => setEditing(false), onSubmit: async (b) => { const e = await onEdit(item, b); if (!e)
                 setEditing(false); return e; } });
-    return (_jsxs("div", { children: [_jsx("p", { className: "m-0 whitespace-pre-wrap text-[15px]", children: item.value.body }), _jsxs("p", { className: "m-0 text-xs opacity-60", children: [item.kind === 'personal' ? (item.where === 'device' ? 'only you, on this device' : 'only you') : item.name, item.mine ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "data-comment-edit": true, onClick: () => setEditing(true), className: "ml-2 underline", children: "edit" }), _jsx("button", { type: "button", "data-comment-delete": true, onClick: () => void onRemove(item), className: "ml-2 underline", children: "delete" })] })) : null] })] }));
+    return (_jsxs("div", { children: [src ? _jsx(AudioPlay, { src: src, accent: accent }) : null, item.value.body ? _jsx("p", { className: "m-0 whitespace-pre-wrap text-[15px]", children: item.value.body }) : null, _jsxs("p", { className: "m-0 text-xs opacity-60", children: [item.kind === 'personal' ? (item.where === 'device' ? 'only you, on this device' : 'only you') : item.name, item.mine ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "data-comment-edit": true, onClick: () => setEditing(true), className: "ml-2 underline", children: "edit" }), _jsx("button", { type: "button", "data-comment-delete": true, onClick: () => void onRemove(item), className: "ml-2 underline", children: "delete" })] })) : null] })] }));
 }
 function InlineForm({ label, initial = '', accent = 'currentColor', onSubmit, onCancel }) {
     const [text, setText] = useState(initial);

package/lib/reader/device-audio.d.ts

@@ -0,0 +1,7 @@
+export declare const isDeviceAudio: (p: unknown) => p is string;
+export type DeviceAudio = {
+    put(key: string, blob: Blob): Promise<boolean>;
+    get(key: string): Promise<Blob | null>;
+    remove(key: string): Promise<void>;
+};
+export declare const deviceAudio: DeviceAudio;

package/lib/reader/device-audio.js

@@ -0,0 +1,43 @@
+// Recordings on personal notes for a reader who is not signed in: kept in this browser's IndexedDB
+// and nowhere else, like the notes themselves (device-notes.ts). A note names its recording as
+// `device/<memo>.<ext>`; on sign-in the comment layer uploads it to the reader's account and
+// deletes it here. A browser without IndexedDB (or a private window that refuses it) keeps no
+// recording, and nothing breaks: every call answers null or false.
+const DB = 'artifact-voice';
+const STORE = 'memos';
+export const isDeviceAudio = (p) => typeof p === 'string' && p.startsWith('device/');
+function open() {
+    return new Promise((resolve) => {
+        try {
+            if (typeof indexedDB === 'undefined')
+                return resolve(null);
+            const req = indexedDB.open(DB, 1);
+            req.onupgradeneeded = () => { req.result.createObjectStore(STORE); };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => resolve(null);
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+async function run(mode, fn) {
+    const db = await open();
+    if (!db)
+        return null;
+    return new Promise((resolve) => {
+        try {
+            const req = fn(db.transaction(STORE, mode).objectStore(STORE));
+            req.onsuccess = () => resolve(req.result ?? null);
+            req.onerror = () => resolve(null);
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+export const deviceAudio = {
+    put: async (key, blob) => (await run('readwrite', (s) => s.put(blob, key))) !== null,
+    get: async (key) => { const b = await run('readonly', (s) => s.get(key)); return b instanceof Blob ? b : null; },
+    remove: async (key) => { await run('readwrite', (s) => s.delete(key)); },
+};

package/lib/reader/index.d.ts

@@ -6,3 +6,6 @@ export { CommentLayer } from './comment-layer.js';
 export { CommentCard, warningLine, DEVICE_LINE } from './comment-card.js';
 export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDeviceNote } from './device-notes.js';
 export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom, type TextIndex, type Placement } from './comment-place.js';
+export { VoiceRecorder, AudioPlay, hostVoice, pickRecordingType, newMemoId, recognitionCtor, LIVE_LINE, type VoiceHost, type VoiceMemo, type VoiceScope } from './voice-recorder.js';
+export { deviceAudio, isDeviceAudio, type DeviceAudio } from './device-audio.js';
+export { type SavedMemo } from './comment-card.js';

package/lib/reader/index.js

@@ -8,3 +8,5 @@ export { CommentLayer } from './comment-layer.js';
 export { CommentCard, warningLine, DEVICE_LINE } from './comment-card.js';
 export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDeviceNote } from './device-notes.js';
 export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom } from './comment-place.js';
+export { VoiceRecorder, AudioPlay, hostVoice, pickRecordingType, newMemoId, recognitionCtor, LIVE_LINE } from './voice-recorder.js';
+export { deviceAudio, isDeviceAudio } from './device-audio.js';

package/lib/reader/theme-vars.d.ts

@@ -0,0 +1,3 @@
+/** The page's theme variables (`--a-*`) as they resolve around `el`. Computed style covers variables set by a stylesheet (the `system` mode's media
+ *  query); the inline walk covers engines that do not list custom properties in computed style. */
+export declare function themeVarsAround(el: Element | null): Record<string, string>;

package/lib/reader/theme-vars.js

@@ -0,0 +1,33 @@
+// Anything the reader portals onto document.body leaves the wrapper that sets the page's theme,
+// so it has to carry the theme with it. One helper for every portal (comment overlay, definition
+// sheet, version history).
+/** The page's theme variables (`--a-*`) as they resolve around `el`. Computed style covers variables set by a stylesheet (the `system` mode's media
+ *  query); the inline walk covers engines that do not list custom properties in computed style. */
+export function themeVarsAround(el) {
+    const out = {};
+    if (!el)
+        return out;
+    const cs = getComputedStyle(el);
+    for (let i = 0; i < cs.length; i++) {
+        const name = cs[i];
+        if (name.startsWith('--a-')) {
+            const v = cs.getPropertyValue(name).trim();
+            if (v)
+                out[name] = v;
+        }
+    }
+    for (let n = el; n; n = n.parentElement) {
+        const st = n.style;
+        if (!st)
+            continue;
+        for (let i = 0; i < st.length; i++) {
+            const name = st[i];
+            if (name.startsWith('--a-') && !(name in out)) {
+                const v = st.getPropertyValue(name).trim();
+                if (v)
+                    out[name] = v;
+            }
+        }
+    }
+    return out;
+}

package/lib/reader/voice-recorder.d.ts

@@ -0,0 +1,52 @@
+export type VoiceMemo = {
+    blob: Blob;
+    mime: string;
+};
+export type VoiceScope = 'comment' | 'personal';
+/** The page's own voice routes, from the reader's browser. */
+export type VoiceHost = {
+    /** Upload a memo; the stored path, or null when the page could not keep it. */
+    upload(memo: VoiceMemo, scope: VoiceScope): Promise<string | null>;
+    /** The host's transcript of an uploaded memo; null when it has no transcriber (404) or failed. */
+    transcribe(path: string): Promise<string | null>;
+};
+export declare const LIVE_LINE = "Your browser transcribes this as you speak.";
+/** The recording type to ask for: the first this browser supports, else its default. */
+export declare function pickRecordingType(isSupported?: (t: string) => boolean): string | undefined;
+/** A memo's random file id: 22 url-safe characters, drawn in the browser. */
+export declare function newMemoId(): string;
+type Recognition = {
+    continuous: boolean;
+    interimResults: boolean;
+    lang: string;
+    onresult: ((e: {
+        results: ArrayLike<ArrayLike<{
+            transcript: string;
+        }> & {
+            isFinal?: boolean;
+        }>;
+    }) => void) | null;
+    onerror: (() => void) | null;
+    start(): void;
+    stop(): void;
+};
+type RecognitionCtor = new () => Recognition;
+export declare function recognitionCtor(): RecognitionCtor | null;
+/** The page's own routes as a VoiceHost. Every failure is a null, never a throw. */
+export declare function hostVoice(artifactId: string): VoiceHost;
+/** The mic button. Renders nothing where the browser cannot record. */
+export declare function VoiceRecorder({ onStart, onLive, onStop, onError, accent, maxMs }: {
+    onStart?: () => void;
+    /** The live transcript so far, whole, each time it changes. */
+    onLive?: (text: string) => void;
+    onStop: (memo: VoiceMemo) => void;
+    onError?: (message: string) => void;
+    accent?: string;
+    maxMs?: number;
+}): import("react").JSX.Element | null;
+/** A small play control for a saved memo. `src` is a URL (signed, or a blob: URL on the device). */
+export declare function AudioPlay({ src, accent }: {
+    src: string;
+    accent?: string;
+}): import("react").JSX.Element;
+export {};

package/lib/reader/voice-recorder.js

@@ -0,0 +1,213 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Say it instead of typing it. The microphone in the comment card: MediaRecorder for the memo
+// itself, and, where the browser has it, speech recognition writing into the box while you speak.
+//
+// Chrome records audio/webm (opus), iPhone Safari audio/mp4; the first the browser supports is
+// used, else the browser's own default, and a type the page cannot keep is refused before upload.
+// A memo stops itself at three minutes. The host's transcription (if it has one) happens after the
+// recording stops, in the card, through `hostVoice`, which never sees a key: it only calls this
+// page's own routes.
+//
+// Everything here draws with the page's theme variables (--a-*) and the accent it is handed: the
+// card is portalled onto document.body, and a hard-coded colour there is dark text on a dark page.
+import { useEffect, useRef, useState } from 'react';
+import { MAX_MEMO_MS, audioExtFor, baseMime } from '../artifacts/audio.js';
+export const LIVE_LINE = 'Your browser transcribes this as you speak.';
+const SEEN_KEY = 'artifact-voice-live-seen';
+/** The recording type to ask for: the first this browser supports, else its default. */
+export function pickRecordingType(isSupported = (t) => typeof MediaRecorder !== 'undefined' && MediaRecorder.isTypeSupported(t)) {
+    for (const t of ['audio/webm;codecs=opus', 'audio/mp4']) {
+        try {
+            if (isSupported(t))
+                return t;
+        }
+        catch { /* an engine that throws on the question supports neither */ }
+    }
+    return undefined;
+}
+/** A memo's random file id: 22 url-safe characters, drawn in the browser. */
+export function newMemoId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let s = '';
+    for (const b of bytes)
+        s += 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'[b & 63];
+    return s + Date.now().toString(36).slice(-6);
+}
+export function recognitionCtor() {
+    if (typeof window === 'undefined')
+        return null;
+    const w = window;
+    return w.SpeechRecognition ?? w.webkitSpeechRecognition ?? null;
+}
+const canRecord = () => typeof window !== 'undefined' && typeof MediaRecorder !== 'undefined' && !!navigator.mediaDevices?.getUserMedia;
+/** The page's own routes as a VoiceHost. Every failure is a null, never a throw. */
+export function hostVoice(artifactId) {
+    const post = (url, body) => fetch(url, { method: 'POST', credentials: 'same-origin', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    return {
+        async upload(memo, scope) {
+            try {
+                const ext = audioExtFor(memo.mime);
+                if (!ext)
+                    return null;
+                const url = `/api/artifacts/${artifactId}/uploads/${newMemoId()}.${ext}`;
+                const signed = await post(url, { audio: scope });
+                if (signed.status !== 201)
+                    return null;
+                const { uploadUrl, headers } = (await signed.json());
+                const put = await fetch(uploadUrl, { method: 'PUT', headers, body: memo.blob });
+                if (!put.ok)
+                    return null;
+                const done = await post(url, { audio: scope, done: true });
+                return done.status === 201 ? (await done.json()).path : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async transcribe(path) {
+            try {
+                const r = await post(`/api/artifacts/${artifactId}/transcribe`, { asset: path });
+                if (r.status !== 200)
+                    return null;
+                const b = (await r.json());
+                return typeof b.text === 'string' && b.text.trim() ? b.text.trim() : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+const clock = (ms) => { const s = Math.floor(ms / 1000); return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`; };
+/** The mic button. Renders nothing where the browser cannot record. */
+export function VoiceRecorder({ onStart, onLive, onStop, onError, accent = 'currentColor', maxMs = MAX_MEMO_MS }) {
+    const [supported, setSupported] = useState(false);
+    const [live, setLive] = useState(false);
+    const [note, setNote] = useState(false);
+    const [recording, setRecording] = useState(false);
+    const [elapsed, setElapsed] = useState(0);
+    const rec = useRef(null);
+    useEffect(() => {
+        setSupported(canRecord());
+        const has = !!recognitionCtor();
+        setLive(has);
+        try {
+            setNote(has && !window.localStorage.getItem(SEEN_KEY));
+        }
+        catch {
+            setNote(has);
+        }
+        return () => { const r = rec.current; if (r) {
+            clearTimeout(r.timer);
+            clearInterval(r.tick);
+            r.recog?.stop();
+            r.stream.getTracks().forEach((t) => t.stop());
+        } };
+    }, []);
+    const stop = () => {
+        const r = rec.current;
+        if (!r)
+            return;
+        clearTimeout(r.timer);
+        clearInterval(r.tick);
+        try {
+            r.recog?.stop();
+        }
+        catch { /* already stopped */ }
+        if (r.recorder.state !== 'inactive')
+            r.recorder.stop();
+    };
+    const start = async () => {
+        let stream;
+        try {
+            stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        }
+        catch {
+            onError?.('The microphone is blocked. Allow it for this site in your browser, then try again.');
+            return;
+        }
+        const asked = pickRecordingType();
+        let recorder;
+        try {
+            recorder = asked ? new MediaRecorder(stream, { mimeType: asked }) : new MediaRecorder(stream);
+        }
+        catch {
+            stream.getTracks().forEach((t) => t.stop());
+            onError?.('This browser cannot record here.');
+            return;
+        }
+        const chunks = [];
+        recorder.ondataavailable = (e) => { if (e.data && e.data.size)
+            chunks.push(e.data); };
+        recorder.onstop = () => {
+            stream.getTracks().forEach((t) => t.stop());
+            rec.current = null;
+            setRecording(false);
+            const type = recorder.mimeType || asked || chunks[0]?.type || '';
+            if (!audioExtFor(type)) {
+                onError?.('This browser records in a format the page cannot keep.');
+                return;
+            }
+            onStop({ blob: new Blob(chunks, { type: baseMime(type) }), mime: baseMime(type) });
+        };
+        let recog = null;
+        const Ctor = recognitionCtor();
+        if (Ctor) {
+            try {
+                recog = new Ctor();
+                recog.continuous = true;
+                recog.interimResults = true;
+                recog.lang = document.documentElement.lang || navigator.language || 'en-US';
+                recog.onresult = (e) => {
+                    let text = '';
+                    for (let i = 0; i < e.results.length; i++)
+                        text += e.results[i][0]?.transcript ?? '';
+                    onLive?.(text.replace(/\s+/g, ' ').trim());
+                };
+                recog.onerror = () => { };
+                recog.start();
+            }
+            catch {
+                recog = null;
+            }
+            try {
+                window.localStorage.setItem(SEEN_KEY, '1');
+            }
+            catch { /* private window */ }
+        }
+        const began = Date.now();
+        rec.current = {
+            recorder, stream, recog,
+            timer: setTimeout(stop, maxMs),
+            tick: setInterval(() => setElapsed(Date.now() - began), 250),
+        };
+        setElapsed(0);
+        setRecording(true);
+        onStart?.();
+        recorder.start(1000);
+    };
+    if (!supported)
+        return null;
+    return (_jsxs("div", { "data-voice-recorder": true, className: "mt-2 text-[13px] text-[color:var(--a-strong)]", children: [_jsxs("button", { type: "button", "data-voice-mic": true, "aria-pressed": recording, onClick: () => (recording ? stop() : void start()), className: "inline-flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium", style: recording ? { borderColor: accent, background: accent, color: 'var(--a-on-accent, currentColor)' } : { borderColor: accent, color: accent }, children: [_jsx("span", { "aria-hidden": true, children: recording ? '■' : '●' }), recording ? `Stop · ${clock(elapsed)}` : 'Record'] }), live && note ? _jsx("p", { "data-voice-live-note": true, className: "m-0 mt-1 text-xs opacity-70", children: LIVE_LINE }) : null] }));
+}
+/** A small play control for a saved memo. `src` is a URL (signed, or a blob: URL on the device). */
+export function AudioPlay({ src, accent = 'currentColor' }) {
+    const [playing, setPlaying] = useState(false);
+    const el = useRef(null);
+    useEffect(() => () => { el.current?.pause(); }, []);
+    const toggle = () => {
+        if (!el.current) {
+            el.current = new Audio(src);
+            el.current.onended = () => setPlaying(false);
+            el.current.onpause = () => setPlaying(false);
+            el.current.onplay = () => setPlaying(true);
+        }
+        if (el.current.paused)
+            void el.current.play()?.catch?.(() => setPlaying(false));
+        else
+            el.current.pause();
+    };
+    return (_jsxs("button", { type: "button", "data-voice-play": true, onClick: toggle, "aria-label": playing ? 'Pause the recording' : 'Play the recording', className: "mr-2 inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs text-[color:var(--a-strong)]", style: { borderColor: accent }, children: [_jsx("span", { "aria-hidden": true, style: { color: accent }, children: playing ? '❚❚' : '▶' }), playing ? 'Pause' : 'Play'] }));
+}

package/lib/routes/artifacts.d.ts

@@ -7,6 +7,7 @@ import type { BrandPack } from '../brand/pack.js';
 import { type Access } from '../artifacts/reader.js';
 import { type ReadersStore } from '../artifacts/readers-store.js';
 import type { PersonalStore } from '../artifacts/personal-store.js';
+import type { Transcriber } from '../artifacts/transcribe.js';
 export type ArtifactRoutesConfig = {
     store: ArtifactStore;
     /** Where readers' answers live. Without it every state route answers 501. */
@@ -49,6 +50,11 @@ export type ArtifactRoutesConfig = {
      *  its writer's name, whatever `comments_visible:` says. Without it nobody is the owner, and
      *  the publisher reads comments through /responses. */
     ownerEmail?: string;
+    /** Turns a reader's voice memo into text on the server, so the service's key never reaches a
+     *  browser: `deepgramTranscriber(key)` or `openaiTranscriber(key)` from `./artifacts`, or your
+     *  own. Without it the transcribe route answers 404 and readers get the browser's live
+     *  transcript, or an empty box to type into. */
+    transcribe?: Transcriber;
 };
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export declare const ARTIFACT_ID: RegExp;
@@ -152,13 +158,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
             id: string;
             name: string;
         }>;
-    }) => Promise<NextResponse<{
-        error: string;
-    }> | NextResponse<{
-        id: string;
-        name: string;
-        url: string;
-    }>>;
+    }) => Promise<NextResponse<unknown>>;
     SHARE_IMAGE: (_request: NextRequest, { params }: Params) => Promise<Response>;
     ENTER: (request: NextRequest) => Promise<NextResponse<unknown>>;
     LEAVE: (request: NextRequest) => Promise<NextResponse<unknown>>;
@@ -191,5 +191,10 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         access: Access | null;
         views: number;
     }>>;
+    TRANSCRIBE: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
 };
 export {};