@supersuit/artifacts 0.10.0 → 0.11.0

package/lib/reader/comment-layer.js

@@ -0,0 +1,384 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Comments on any part of a page, Figma style. Select text and a "Comment" chip appears; hold and
+// drag over anything that is not text (an image, a table, the gap between paragraphs) and a box
+// draws. Either opens the card (comment-card.tsx), which says before anything is typed whether
+// the owner will ever read it.
+//
+// Two kinds, kept apart all the way down:
+//   SHARED   the `comments` slot on the state API; filled pins in the page's accent.
+//   PERSONAL the reader's own notes: /personal when signed in, else this device only
+//            (device-notes.ts); hollow pins marked "only you". Never on the state API.
+//
+// Pins sit in the margin beside a quote, or on the box drawn. A comment whose quote or block is gone
+// from this version is listed under "Comments on earlier versions" after the article, with its
+// quote, the way the notes widget sets aside notes on a renamed heading. Replies are one level
+// deep and only on shared comments. Everything drawn here is data-nospeak and data-comment-ui, so
+// the read-aloud never reads it and the text index never counts it.
+//
+// Rendered empty on the server and on the first client render so the markup always hydrates; the
+// overlay is portalled onto document.body so its coordinates are page coordinates.
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+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 { 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';
+const LONG_PRESS_MS = 400;
+const DRAG_PX = 8;
+/** Where a drag never starts a box: controls, and anything that is somebody's words. */
+const NOT_FOR_BOXES = 'a, button, input, textarea, select, audio, video[controls], summary, label, [data-comment-ui], [data-note-toggle], [data-heading-notes], [data-artifact-notes], .artifact-defined-term, .artifact-word';
+function isTextTarget(el) {
+    if (el.closest(NOT_FOR_BOXES))
+        return true;
+    for (const c of Array.from(el.childNodes))
+        if (c.nodeType === Node.TEXT_NODE && c.textContent?.trim())
+            return true;
+    return false;
+}
+function sharedFrom(body) {
+    const slot = body?.slots?.[COMMENTS_SLOT];
+    if (!slot)
+        return [];
+    const rows = new Map();
+    for (const r of Array.isArray(slot.mine) ? slot.mine : [])
+        rows.set(String(r.id), { ...r, mine: true });
+    for (const r of Array.isArray(slot.shared) ? slot.shared : [])
+        rows.set(String(r.id), r);
+    const out = [];
+    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 ?? '') });
+    }
+    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 stateUrl = `/api/artifacts/${artifactId}/state`;
+    const personalUrl = `/api/artifacts/${artifactId}/personal`;
+    const [mounted, setMounted] = useState(false);
+    const [shared, setShared] = useState([]);
+    const [serverNotes, setServerNotes] = useState([]);
+    const [device, setDevice] = useState([]);
+    const [onServer, setOnServer] = useState(signedIn);
+    const [showPins, setShowPins] = useState(true);
+    const [panel, setPanel] = useState(false);
+    const [chip, setChip] = useState(null);
+    const [draft, setDraft] = useState(null);
+    const [thread, setThread] = useState(null);
+    const [drag, setDrag] = useState(null);
+    const [tick, setTick] = useState(0);
+    const call = useCallback(async (url, init) => {
+        try {
+            const r = await fetch(url, { credentials: 'same-origin', cache: 'no-store', ...init });
+            return { status: r.status, body: (await r.json().catch(() => ({}))) };
+        }
+        catch {
+            return { status: 0, body: { error: 'that did not reach the page; try again' } };
+        }
+    }, []);
+    const refreshDevice = useCallback(() => setDevice(personalFrom(deviceNotes(artifactId), 'device')), [artifactId]);
+    useEffect(() => {
+        setMounted(true);
+        refreshDevice();
+        let live = true;
+        if (comments !== 'off') {
+            void call(stateUrl).then((r) => { if (live && r.status === 200)
+                setShared(sharedFrom(r.body)); });
+        }
+        if (signedIn) {
+            void (async () => {
+                const r = await call(personalUrl);
+                if (!live)
+                    return;
+                if (r.status !== 200) {
+                    setOnServer(false);
+                    return;
+                }
+                let notes = r.body.notes ?? [];
+                // Notes kept on this device before signing in move to the account, then leave the device.
+                for (const n of deviceNotes(artifactId)) {
+                    const m = await call(personalUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ value: n.value }) });
+                    if (m.status !== 200)
+                        break;
+                    notes = m.body.notes ?? notes;
+                    removeDeviceNote(artifactId, n.id);
+                }
+                if (!live)
+                    return;
+                setServerNotes(personalFrom(notes, 'server'));
+                refreshDevice();
+            })();
+        }
+        const relayout = () => setTick((t) => t + 1);
+        window.addEventListener('resize', relayout);
+        const root = document.getElementById(rootId);
+        const ro = typeof ResizeObserver !== 'undefined' && root ? new ResizeObserver(relayout) : null;
+        if (ro && root)
+            ro.observe(root);
+        return () => { live = false; window.removeEventListener('resize', relayout); ro?.disconnect(); };
+    }, [artifactId, comments, signedIn, stateUrl, personalUrl, rootId, call, refreshDevice]);
+    // Text selection inside the page shows the Comment chip.
+    useEffect(() => {
+        const root = document.getElementById(rootId);
+        if (!root)
+            return;
+        const check = () => {
+            const sel = document.getSelection();
+            if (!sel || sel.isCollapsed || !sel.rangeCount)
+                return setChip(null);
+            const r = sel.getRangeAt(0);
+            const common = r.commonAncestorContainer;
+            if (!root.contains(common) || (common instanceof Element ? common : common.parentElement)?.closest('[data-comment-ui]'))
+                return setChip(null);
+            const idx = indexText(root);
+            let s = offsetAt(idx, r.startContainer, r.startOffset);
+            let e = offsetAt(idx, r.endContainer, r.endOffset);
+            if (s === null || e === null)
+                return setChip(null);
+            while (s < e && /\s/.test(idx.text[s]))
+                s++;
+            while (e > s && /\s/.test(idx.text[e - 1]))
+                e--;
+            if (e <= s)
+                return setChip(null);
+            e = Math.min(e, s + MAX_QUOTE_CHARS);
+            const anchor = textAnchorFrom(idx.text, s, e, headingAt(root, idx, s));
+            const rect = typeof r.getBoundingClientRect === 'function' ? r.getBoundingClientRect() : null;
+            setChip({ anchor, quote: anchor.quote, x: (rect?.right ?? 0) + window.scrollX, y: (rect?.bottom ?? 0) + window.scrollY + 6 });
+        };
+        let timer;
+        // Phones adjust a selection with handles and fire no mouseup; settle on selectionchange instead.
+        const settle = () => { clearTimeout(timer); timer = setTimeout(check, 350); };
+        root.addEventListener('mouseup', check);
+        root.addEventListener('keyup', check);
+        document.addEventListener('selectionchange', settle);
+        return () => { clearTimeout(timer); root.removeEventListener('mouseup', check); root.removeEventListener('keyup', check); document.removeEventListener('selectionchange', settle); };
+    }, [rootId]);
+    // Hold and drag over anything that is not text draws a box. A mouse starts after 8px of travel;
+    // a finger after a 400 ms long-press, so an ordinary swipe still scrolls.
+    const dragRef = useRef(null);
+    useEffect(() => {
+        const root = document.getElementById(rootId);
+        if (!root)
+            return;
+        const down = (e) => {
+            if (e.button !== 0 || !(e.target instanceof Element) || isTextTarget(e.target))
+                return;
+            const d = { x: e.clientX, y: e.clientY, armed: e.pointerType !== 'touch', drawing: false };
+            if (e.pointerType === 'touch')
+                d.timer = setTimeout(() => { d.armed = true; navigator.vibrate?.(10); }, LONG_PRESS_MS);
+            else
+                e.preventDefault();
+            dragRef.current = d;
+        };
+        const move = (e) => {
+            const d = dragRef.current;
+            if (!d)
+                return;
+            const far = Math.hypot(e.clientX - d.x, e.clientY - d.y) > DRAG_PX;
+            if (!d.armed) {
+                if (far) {
+                    clearTimeout(d.timer);
+                    dragRef.current = null;
+                }
+                return;
+            }
+            if (!d.drawing && !far)
+                return;
+            d.drawing = true;
+            setDrag({ x1: d.x, y1: d.y, x2: e.clientX, y2: e.clientY });
+        };
+        const up = (e) => {
+            const d = dragRef.current;
+            dragRef.current = null;
+            if (!d)
+                return;
+            clearTimeout(d.timer);
+            setDrag(null);
+            if (!d.drawing)
+                return;
+            const box = { left: Math.min(d.x, e.clientX), right: Math.max(d.x, e.clientX), top: Math.min(d.y, e.clientY), bottom: Math.max(d.y, e.clientY) };
+            // The box belongs to the block it covers most, so a drag across a gap still lands somewhere.
+            let best = null;
+            for (const el of root.querySelectorAll('[data-block]')) {
+                const b = el.getBoundingClientRect();
+                const area = Math.max(0, Math.min(box.right, b.right) - Math.max(box.left, b.left)) * Math.max(0, Math.min(box.bottom, b.bottom) - Math.max(box.top, b.top));
+                if (area > 0 && (!best || area > best.area))
+                    best = { el, area };
+            }
+            if (!best)
+                return;
+            const anchor = regionFrom(best.el.getBoundingClientRect(), { x: d.x, y: d.y }, { x: e.clientX, y: e.clientY }, best.el.dataset.block);
+            if (anchor) {
+                setChip(null);
+                setDraft({ anchor, x: box.right + window.scrollX, y: box.bottom + window.scrollY + 6 });
+            }
+        };
+        // While a finger is drawing, the page must not scroll under it.
+        const touchmove = (e) => { if (dragRef.current?.armed)
+            e.preventDefault(); };
+        const noImageDrag = (e) => { if (dragRef.current)
+            e.preventDefault(); };
+        root.addEventListener('pointerdown', down);
+        window.addEventListener('pointermove', move);
+        window.addEventListener('pointerup', up);
+        window.addEventListener('pointercancel', up);
+        root.addEventListener('touchmove', touchmove, { passive: false });
+        root.addEventListener('dragstart', noImageDrag);
+        return () => {
+            root.removeEventListener('pointerdown', down);
+            window.removeEventListener('pointermove', move);
+            window.removeEventListener('pointerup', up);
+            window.removeEventListener('pointercancel', up);
+            root.removeEventListener('touchmove', touchmove);
+            root.removeEventListener('dragstart', noImageDrag);
+        };
+    }, [rootId]);
+    const items = useMemo(() => [...shared, ...serverNotes, ...device], [shared, serverNotes, device]);
+    const tops = useMemo(() => items.filter((i) => !i.value.parent || !items.some((p) => p.id === i.value.parent)), [items]);
+    // Where each top-level comment sits on this version, or that it is on an earlier one.
+    const layout = useMemo(() => {
+        const placed = [];
+        const earlier = [];
+        if (!mounted)
+            return { placed, earlier };
+        const root = document.getElementById(rootId);
+        if (!root)
+            return { placed, earlier: tops };
+        const idx = indexText(root);
+        const col = (root.querySelector('article') ?? root).getBoundingClientRect();
+        const margin = Math.min(col.right + window.scrollX + 8, window.scrollX + (window.innerWidth || col.right + 40) - 32);
+        for (const item of tops) {
+            const at = item.value.parent ? null : placeAnchor(root, idx, item.value.anchor);
+            if (!at) {
+                earlier.push(item);
+                continue;
+            }
+            const b = boxOf(at);
+            if (at.kind === 'text')
+                placed.push({ item, left: margin, top: b.top });
+            else
+                placed.push({ item, left: b.left + b.width - 12, top: b.top - 12, box: b });
+        }
+        // Pins on the same line stack instead of hiding one another.
+        placed.sort((a, b) => a.top - b.top || a.left - b.left);
+        for (let i = 1; i < placed.length; i++) {
+            const p = placed[i - 1];
+            if (Math.abs(placed[i].left - p.left) < 20 && placed[i].top - p.top < 26)
+                placed[i].top = p.top + 26;
+        }
+        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 };
+        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)
+                return typeof r.body.error === 'string' ? r.body.error : 'that did not save; try again';
+            setShared(sharedFrom(r.body));
+        }
+        else if (signedIn && onServer) {
+            const r = await call(personalUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ value }) });
+            if (r.status === 200)
+                setServerNotes(personalFrom(r.body.notes ?? [], 'server'));
+            else if (r.body.device === true) {
+                setOnServer(false);
+                addDeviceNote(artifactId, value);
+                refreshDevice();
+            }
+            else
+                return typeof r.body.error === 'string' ? r.body.error : 'that did not save; try again';
+        }
+        else {
+            addDeviceNote(artifactId, value);
+            refreshDevice();
+        }
+        document.getSelection()?.removeAllRanges();
+        setDraft(null);
+        return null;
+    };
+    const remove = async (item) => {
+        if (item.where === 'device') {
+            removeDeviceNote(artifactId, item.id);
+            refreshDevice();
+        }
+        else if (item.kind === 'personal') {
+            const r = await call(`${personalUrl}?entry=${encodeURIComponent(item.id)}`, { method: 'DELETE' });
+            if (r.status === 200)
+                setServerNotes(personalFrom(r.body.notes ?? [], 'server'));
+        }
+        else {
+            const r = await call(stateUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ slot: COMMENTS_SLOT, op: 'remove', entry: item.id }) });
+            if (r.status === 200)
+                setShared(sharedFrom(r.body));
+        }
+        if (thread === item.id)
+            setThread(null);
+    };
+    const edit = async (item, body) => {
+        const value = { ...item.value, body };
+        if (item.where === 'device') {
+            replaceDeviceNote(artifactId, item.id, value);
+            refreshDevice();
+            return null;
+        }
+        const r = item.kind === 'personal'
+            ? await call(personalUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ entry: item.id, value }) })
+            : await call(stateUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ slot: COMMENTS_SLOT, op: 'replace', entry: item.id, value }) });
+        if (r.status !== 200)
+            return typeof r.body.error === 'string' ? r.body.error : 'that did not save; try again';
+        if (item.kind === 'personal')
+            setServerNotes(personalFrom(r.body.notes ?? [], 'server'));
+        else
+            setShared(sharedFrom(r.body));
+        return null;
+    };
+    const reply = async (parent, body) => {
+        const value = { anchor: parent.value.anchor, body, version, parent: parent.id };
+        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)
+            return typeof r.body.error === 'string' ? r.body.error : 'that did not save; try again';
+        setShared(sharedFrom(r.body));
+        return null;
+    };
+    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;
+    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 }) {
+    const personal = item.kind === 'personal';
+    return (_jsx("button", { type: "button", "data-comment-pin": item.kind, "data-comment-id": item.id, onClick: onOpen, "aria-label": personal ? 'Your personal note (only you)' : `Comment by ${item.name}`, className: "absolute z-30 flex h-6 min-w-6 items-center justify-center gap-1 rounded-full border-2 px-1.5 text-[10px] font-semibold shadow", style: { left, top, borderColor: accent, background: personal ? ground : accent, color: personal ? accent : 'var(--a-on-accent, #111)' }, children: personal ? _jsx("span", { children: "only you" }) : _jsx("span", { "aria-hidden": true, children: "\u25CF" }) }));
+}
+function Floating({ x, y, children }) {
+    // Kept inside the screen on a phone, where the margin a pin sits in may be the screen's edge.
+    const width = typeof window === 'undefined' ? 360 : Math.min(360, window.innerWidth - 16);
+    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 }) {
+    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
+                ? _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 }) {
+    const [editing, setEditing] = useState(false);
+    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] })] }));
+}
+function InlineForm({ label, initial = '', accent = 'currentColor', onSubmit, onCancel }) {
+    const [text, setText] = useState(initial);
+    const [error, setError] = useState(null);
+    return (_jsxs("form", { className: "mt-2", onSubmit: async (e) => { e.preventDefault(); if (text.trim())
+            setError(await onSubmit(text.trim())); }, children: [_jsx("textarea", { value: text, autoFocus: true, rows: 2, onChange: (e) => setText(e.target.value), "aria-label": label, className: "w-full rounded-lg border border-[color:var(--a-line)] bg-transparent p-2 text-[15px]" }), error ? _jsx("p", { role: "alert", className: "text-xs text-amber-500", children: error }) : null, _jsxs("div", { className: "mt-1 flex gap-3 text-xs", children: [_jsx("button", { type: "submit", disabled: !text.trim(), className: "rounded-full px-3 py-0.5 font-medium disabled:opacity-40", style: { background: accent, color: 'var(--a-on-accent, #111)' }, children: label }), _jsx("button", { type: "button", onClick: onCancel, className: "opacity-70", children: "Cancel" })] })] }));
+}

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

@@ -0,0 +1,45 @@
+import { type Anchor, type RegionAnchor } from '../artifacts/anchor.js';
+export type TextIndex = {
+    text: string;
+    nodes: {
+        node: Text;
+        start: number;
+    }[];
+};
+/** Every text node under the root, in order, joined. Word spans the read-aloud wraps around the
+ *  words keep the same text, so the string is the same before and after they are drawn. */
+export declare function indexText(root: HTMLElement): TextIndex;
+/** The offset in the index of a selection boundary (a text node and an offset in it, or an element
+ *  and a child index). Null when the boundary is not under the indexed root. */
+export declare function offsetAt(idx: TextIndex, container: Node, offset: number): number | null;
+/** A Range over [start, end) of the index. */
+export declare function rangeOf(idx: TextIndex, start: number, end: number): Range | null;
+/** The slug of the last heading at or before an offset: the section a quote sat under. */
+export declare function headingAt(root: HTMLElement, idx: TextIndex, offset: number): string | undefined;
+export type Placement = {
+    kind: 'text';
+    range: Range;
+} | {
+    kind: 'region';
+    block: HTMLElement;
+    anchor: RegionAnchor;
+};
+/** Where an anchor is on this page now, or null: the comment is then on an earlier version. */
+export declare function placeAnchor(root: HTMLElement, idx: TextIndex, a: Anchor): Placement | null;
+type Box = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** Page coordinates (scroll included) of a placement: a text quote's first line, or the drawn box. */
+export declare function boxOf(p: Placement): Box;
+/** A box dragged over a block, as fractions of that block, clamped inside it. */
+export declare function regionFrom(block: DOMRect, a: {
+    x: number;
+    y: number;
+}, b: {
+    x: number;
+    y: number;
+}, id: string): RegionAnchor | null;
+export {};

package/lib/reader/comment-place.js

@@ -0,0 +1,117 @@
+// Between the page in the browser and a comment's anchor: the page's text as one string (so a
+// selection becomes a text-quote anchor and an anchor becomes a Range again), and where on the
+// screen each anchor sits. DOM only, no React, so the layer and its tests share it.
+import { findText } from '../artifacts/anchor.js';
+/** Text that is on the page but not the page's prose: the notes widget, hidden definition copy,
+ *  and anything the comment layer itself draws. */
+const SKIP = 'script, style, [data-heading-notes], [data-artifact-notes], .artifact-defined-note, [data-comment-ui]';
+/** Every text node under the root, in order, joined. Word spans the read-aloud wraps around the
+ *  words keep the same text, so the string is the same before and after they are drawn. */
+export function indexText(root) {
+    const nodes = [];
+    let text = '';
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+        acceptNode: (n) => (n.parentElement?.closest(SKIP) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT),
+    });
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+        nodes.push({ node: n, start: text.length });
+        text += n.data;
+    }
+    return { text, nodes };
+}
+/** The offset in the index of a selection boundary (a text node and an offset in it, or an element
+ *  and a child index). Null when the boundary is not under the indexed root. */
+export function offsetAt(idx, container, offset) {
+    const direct = idx.nodes.find((n) => n.node === container);
+    if (direct)
+        return direct.start + Math.min(offset, direct.node.data.length);
+    const at = document.createRange();
+    try {
+        at.setStart(container, offset);
+    }
+    catch {
+        return null;
+    }
+    at.collapse(true);
+    let pos = null;
+    for (const { node, start } of idx.nodes) {
+        // A text node wholly before the boundary counts in full; the first one after it stops the count.
+        if (at.comparePoint(node, node.data.length) <= 0)
+            pos = start + node.data.length;
+        else {
+            pos ??= start;
+            break;
+        }
+    }
+    return pos;
+}
+/** A Range over [start, end) of the index. */
+export function rangeOf(idx, start, end) {
+    const locate = (i, isEnd) => {
+        for (const { node, start: s } of idx.nodes) {
+            const e = s + node.data.length;
+            if (i < e || (isEnd && i === e))
+                return { node, off: i - s };
+        }
+        return null;
+    };
+    const a = locate(start, false);
+    const b = locate(end, true);
+    if (!a || !b)
+        return null;
+    const r = document.createRange();
+    r.setStart(a.node, a.off);
+    r.setEnd(b.node, b.off);
+    return r;
+}
+/** The slug of the last heading at or before an offset: the section a quote sat under. */
+export function headingAt(root, idx, offset) {
+    let slug;
+    for (const h of root.querySelectorAll('h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]')) {
+        const at = offsetAt(idx, h, 0);
+        if (at !== null && at <= offset)
+            slug = h.id;
+    }
+    return slug;
+}
+/** Where an anchor is on this page now, or null: the comment is then on an earlier version. */
+export function placeAnchor(root, idx, a) {
+    if (a.kind === 'text') {
+        const at = findText(idx.text, a);
+        const range = at ? rangeOf(idx, at.start, at.end) : null;
+        return range ? { kind: 'text', range } : null;
+    }
+    const block = root.querySelector(`[data-block="${a.block}"]`);
+    return block ? { kind: 'region', block, anchor: a } : null;
+}
+const pageBox = (r) => ({ left: r.left + window.scrollX, top: r.top + window.scrollY, width: r.width, height: r.height });
+/** Page coordinates (scroll included) of a placement: a text quote's first line, or the drawn box. */
+export function boxOf(p) {
+    if (p.kind === 'text') {
+        // jsdom has no Range geometry; a browser always does.
+        const rects = typeof p.range.getClientRects === 'function' ? Array.from(p.range.getClientRects()) : [];
+        const first = rects.find((r) => r.width || r.height) ?? p.range.startContainer.parentElement?.getBoundingClientRect();
+        return pageBox(first ?? { left: 0, top: 0, width: 0, height: 0 });
+    }
+    const b = p.block.getBoundingClientRect();
+    return pageBox({ left: b.left + p.anchor.x * b.width, top: b.top + p.anchor.y * b.height, width: p.anchor.w * b.width, height: p.anchor.h * b.height });
+}
+/** A box dragged over a block, as fractions of that block, clamped inside it. */
+export function regionFrom(block, a, b, id) {
+    if (!block.width || !block.height)
+        return null;
+    const clamp = (v) => Math.min(1, Math.max(0, v));
+    const x1 = clamp((Math.min(a.x, b.x) - block.left) / block.width);
+    const x2 = clamp((Math.max(a.x, b.x) - block.left) / block.width);
+    const y1 = clamp((Math.min(a.y, b.y) - block.top) / block.height);
+    const y2 = clamp((Math.max(a.y, b.y) - block.top) / block.height);
+    if (x2 - x1 <= 0 || y2 - y1 <= 0)
+        return null;
+    // Rounded at the edges and measured between them, so x + w never rounds past the block's edge.
+    const r4 = (v) => Math.round(v * 10000) / 10000;
+    const w = r4(x2) - r4(x1);
+    const h = r4(y2) - r4(y1);
+    if (w <= 0 || h <= 0)
+        return null;
+    return { kind: 'region', block: id, x: r4(x1), y: r4(y1), w, h };
+}

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

@@ -0,0 +1,6 @@
+import type { PersonalNote, PersonalNoteValue } from '../artifacts/personal-store.js';
+export declare const deviceNotesKey: (artifactId: string) => string;
+export declare const deviceNotes: (artifactId: string) => PersonalNote[];
+export declare function addDeviceNote(artifactId: string, value: PersonalNoteValue): PersonalNote;
+export declare function replaceDeviceNote(artifactId: string, id: string, value: PersonalNoteValue): void;
+export declare function removeDeviceNote(artifactId: string, id: string): void;

package/lib/reader/device-notes.js

@@ -0,0 +1,35 @@
+export const deviceNotesKey = (artifactId) => `artifact-notes:${location.host}:${artifactId}`;
+function read(artifactId) {
+    try {
+        const raw = JSON.parse(window.localStorage.getItem(deviceNotesKey(artifactId)) ?? '[]');
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((n) => !!n && typeof n === 'object' && typeof n.id === 'string' && typeof n.at === 'string' && !!n.value && typeof n.value === 'object');
+    }
+    catch {
+        return [];
+    }
+}
+function write(artifactId, notes) {
+    try {
+        if (notes.length)
+            window.localStorage.setItem(deviceNotesKey(artifactId), JSON.stringify(notes));
+        else
+            window.localStorage.removeItem(deviceNotesKey(artifactId));
+    }
+    catch {
+        // Storage full or blocked (a private window): the note is lost with the tab, and nothing breaks.
+    }
+}
+export const deviceNotes = (artifactId) => read(artifactId);
+export function addDeviceNote(artifactId, value) {
+    const n = { id: `d-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`, value, at: new Date().toISOString() };
+    write(artifactId, [...read(artifactId), n]);
+    return n;
+}
+export function replaceDeviceNote(artifactId, id, value) {
+    write(artifactId, read(artifactId).map((n) => (n.id === id ? { ...n, value, updatedAt: new Date().toISOString() } : n)));
+}
+export function removeDeviceNote(artifactId, id) {
+    write(artifactId, read(artifactId).filter((n) => n.id !== id));
+}

package/lib/reader/index.d.ts

@@ -2,3 +2,7 @@ export { ArtifactReader, wrapWords, seekableWord, litWordIndex, type WordTiming
 export { BrowserReader } from './browser-reader.js';
 export { PlayerBar } from './player-bar.js';
 export { planSentences, wordAt, sentenceOf, fromWord, MAX_SENTENCE_WORDS, type Sentence } from './speech-plan.js';
+export { CommentLayer } from './comment-layer.js';
+export { CommentCard, warningLine, DEVICE_LINE } from './comment-card.js';
+export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDeviceNote } from './device-notes.js';
+export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom, type TextIndex, type Placement } from './comment-place.js';

package/lib/reader/index.js

@@ -4,3 +4,7 @@ export { ArtifactReader, wrapWords, seekableWord, litWordIndex } from './artifac
 export { BrowserReader } from './browser-reader.js';
 export { PlayerBar } from './player-bar.js';
 export { planSentences, wordAt, sentenceOf, fromWord, MAX_SENTENCE_WORDS } from './speech-plan.js';
+export { CommentLayer } from './comment-layer.js';
+export { CommentCard, warningLine, DEVICE_LINE } from './comment-card.js';
+export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDeviceNote } from './device-notes.js';
+export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom } from './comment-place.js';