@supersuit/artifacts 0.9.0 → 0.11.0

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

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

package/lib/reader/index.js

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

package/lib/reader/player-bar.d.ts

@@ -0,0 +1,18 @@
+export declare function PlayerBar({ playing, onToggle, label, accent, ground, value, max, step, onSeek, progress, rate, onRate, }: {
+    playing: boolean;
+    onToggle: () => void;
+    /** The line under the play button. */
+    label: string;
+    accent: string;
+    ground: string;
+    value: number;
+    max: number;
+    step: number;
+    onSeek: (value: number) => void;
+    /** The text at the right of the bar: a time for recorded audio, a word count for the browser. */
+    progress: string;
+    rate: number;
+    onRate: () => void;
+}): import("react").JSX.Element;
+/** The speeds the speed button steps through, in order, wrapping back to 1. */
+export declare function nextRate(rate: number): number;

package/lib/reader/player-bar.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// The bar at the bottom of a page that can be listened to, shared by the recorded-narration
+// reader and the browser read-aloud, so a page looks the same whichever one is speaking. It is
+// pure chrome: each reader owns its engine and hands the bar what to show and what to call.
+export function PlayerBar({ playing, onToggle, label, accent, ground, value, max, step, onSeek, progress, rate, onRate, }) {
+    return (_jsxs(_Fragment, { children: [_jsx("style", { children: `
+        .artifact-word { border-radius: 3px; transition: background-color 120ms; }
+        .artifact-word:hover { background: var(--a-surface-strong, rgba(255,255,255,0.08)); cursor: pointer; }
+        .artifact-word-lit { background: color-mix(in srgb, ${accent} 35%, transparent); color: var(--a-strong, #fff); }
+      ` }), _jsx("div", { "data-artifact-player": true, className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: onToggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: label }), _jsx("input", { type: "range", min: 0, max: max || 0, step: step, value: Math.min(value, max || 0), onChange: (e) => onSeek(Number(e.target.value)), "aria-label": "Seek", className: "mt-1 w-full", style: { accentColor: accent } })] }), _jsx("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: progress }), _jsxs("button", { type: "button", onClick: onRate, className: "shrink-0 rounded border border-[color:var(--a-line-strong)] px-2 py-1 text-xs text-[color:var(--a-body)]", "aria-label": "Playback speed", children: [rate, "x"] })] }) }), _jsx("div", { className: "h-20", "aria-hidden": true })] }));
+}
+/** The speeds the speed button steps through, in order, wrapping back to 1. */
+export function nextRate(rate) {
+    return rate >= 1.5 ? 1 : rate + 0.25;
+}

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

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

package/lib/reader/speech-plan.js

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

package/lib/routes/artifacts.d.ts

@@ -6,10 +6,14 @@ import { type ArtifactAssets } from '../artifacts/assets.js';
 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';
 export type ArtifactRoutesConfig = {
     store: ArtifactStore;
     /** Where readers' answers live. Without it every state route answers 501. */
     state?: StateStore;
+    /** Where signed-in readers' personal notes live. Read ONLY by the reader's own /personal
+     *  handlers, never by any publisher route. Without it every reader's notes stay on their device. */
+    personal?: PersonalStore;
     /** Where uploaded files go. Optional; without it PUT_ASSET answers 501. */
     assets?: ArtifactAssets;
     brand: BrandPack;
@@ -41,6 +45,10 @@ export type ArtifactRoutesConfig = {
      *  `x-forwarded-for`, which is correct on Vercel (it overwrites XFF with the real client IP)
      *  and wrong behind any other proxy that appends rather than replaces; pass this there. */
     clientIp?: (req: NextRequest) => string;
+    /** The page owner's sign-in email. Signed in as them, a page shows every shared comment with
+     *  its writer's name, whatever `comments_visible:` says. Without it nobody is the owner, and
+     *  the publisher reads comments through /responses. */
+    ownerEmail?: string;
 };
 /** 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;
@@ -68,6 +76,21 @@ type VersionProps = VersionParams & {
 export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     dynamic: "force-dynamic";
     maxDuration: number;
+    PERSONAL_GET: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown> | undefined>;
+    PERSONAL_POST: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown> | undefined>;
+    PERSONAL_DELETE: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown> | undefined>;
     STATE_GET: (req: NextRequest, { params }: {
         params: Promise<{
             id: string;

package/lib/routes/artifacts.js

@@ -9,13 +9,16 @@ import { ArtifactMarkdown } from '../artifacts/render.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
 import { cleanNote } from '../artifacts/store.js';
-import { shapeChanges } from '../artifacts/state.js';
+import { effectiveWriters, shapeChanges } from '../artifacts/state.js';
+import { COMMENTS_SLOT } from '../artifacts/comments.js';
 import { ASSET_DIGEST, ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
 import { BrandGround } from '../brand/wrapper.js';
 import { themedPack } from '../brand/theme.js';
 import { showToc, tocOf, TocInline, TocRail } from '../artifacts/toc.js';
 import { renderShareCard } from '../brand/share-card.js';
 import { ArtifactReader } from '../reader/artifact-reader.js';
+import { BrowserReader } from '../reader/browser-reader.js';
+import { CommentLayer } from '../reader/comment-layer.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
 import { UpdatedTime } from '../reader/updated-time.js';
 import { VersionHistory } from '../reader/version-history.js';
@@ -24,6 +27,7 @@ import { FLAG_KINDS, summarize } from '../artifacts/readers-store.js';
 import { AckDoor, ConfidentialBanner, NO_PRINT_CSS, NotAllowedDoor, SignInDoor, Watermark, ackText } from '../artifacts/confidential.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
+import { createPersonalRoutes } from './personal-routes.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export const ARTIFACT_ID = ARTIFACT_ID_RE;
 /** A version number as it appears in a URL: no zero, no leading zero, so each version has one address. */
@@ -45,13 +49,15 @@ export function createArtifactRoutes(config) {
     // The version in the URL is what makes a re-publish show up: every unfurler caches by URL.
     const signInOrigin = config.signInOrigin;
     const owner = config.owner ?? brand.name;
+    const ownerEmail = config.ownerEmail?.trim().toLowerCase();
     const readerSecret = () => config.readerSecret?.();
     const signOutUrl = (id) => `/api/reader/leave?to=${encodeURIComponent(pagePath(id))}`;
     const shareCardUrl = (id, updatedAt) => `${pageUrl(id)}/share.png?v=${encodeURIComponent(updatedAt)}`;
     const stateRoutes = createStateRoutes({
         store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey, pageUrl, signInOrigin, siteUrl,
-        clientIp: config.clientIp,
+        clientIp: config.clientIp, ownerEmail: config.ownerEmail,
     });
+    const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl });
     async function generateMetadata({ params }) {
         const { id } = await params;
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
@@ -105,7 +111,7 @@ export function createArtifactRoutes(config) {
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
         if (!a)
             notFound();
-        const render = (top) => (n === null ? Body(a, { top }) : VersionBody(a, n, { top }));
+        const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top }));
         if (a.access)
             return GatedPage(a, id, render, n);
         // A password shuts the body, never the title: the header stays so the reader knows which
@@ -120,19 +126,23 @@ export function createArtifactRoutes(config) {
         // The same cookie again on the page's state API: a cookie scoped to the page path is never
         // sent to /api/artifacts/<id>/state, so without it a password page could not take answers.
         const unlockLine = (path) => `${unlockCookieName(id)}=${keyHash(id, a.password)}; Path=${path}; Max-Age=31536000; SameSite=Lax; Secure`;
-        // The API copy is set on EVERY open of a page with state:, because the page cannot see it (a
+        // The API copy is set on EVERY open of a page with state: (or on a host keeping personal notes,
+        // which every page takes), because the page cannot see it (a
         // cookie scoped to /api/... never reaches the page path): a reader who unlocked the page
         // before its API cookie existed would otherwise be refused every answer until they reopened
         // the ?key= link.
         const paths = !open || !a.password ? [] : [
             ...(key !== undefined && cookie !== keyHash(id, a.password) ? [pagePath(id)] : []),
-            ...(a.state ? [`/api/artifacts/${id}`] : key !== undefined && cookie !== keyHash(id, a.password) ? [`/api/artifacts/${id}`] : []),
+            ...(a.state || config.personal ? [`/api/artifacts/${id}`] : key !== undefined && cookie !== keyHash(id, a.password) ? [`/api/artifacts/${id}`] : []),
         ];
         const remember = paths.length ? paths.map((p) => `document.cookie=${JSON.stringify(unlockLine(p))}`).join(';') : null;
         if (!open) {
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }), _jsx(ArtifactDoor, { brand: brand, wrongKey: key !== undefined })] }));
         }
-        const page = await render(true);
+        // Who is reading an open page, when they happen to be signed in: their comments follow them.
+        // Only a host that signs readers in can know one; the read never fails the page.
+        const reader = readerSecret() ? verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE).catch(() => undefined)) : null;
+        const page = await render(true, reader);
         if (n === null)
             void store.bumpViews(id);
         return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, page] }));
@@ -142,7 +152,8 @@ export function createArtifactRoutes(config) {
     async function GatedPage(a, id, render, n) {
         const here = n === null ? pageUrl(id) : `${pageUrl(id)}/v/${n}`;
         const readCookie = config.readCookie ?? defaultReadCookie;
-        const reader = verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE));
+        // Only a host that signs readers in can know one; the read never fails the page.
+        const reader = readerSecret() ? verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE).catch(() => undefined)) : null;
         const allow = config.readers && reader ? await config.readers.allowList(id) : [];
         const d = config.readers ? decide(a.access, reader, allow) : { open: false, why: 'signed-out' };
         const header = (_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }));
@@ -158,7 +169,7 @@ export function createArtifactRoutes(config) {
         if (config.readers && !(await config.readers.acknowledged(id, r.email))) {
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [header, _jsx(AckDoor, { brand: brand, name: firstName(r, allow), email: r.email, owner: owner, pageId: id, signOutUrl: signOutUrl(id) })] }));
         }
-        const page = await render(false);
+        const page = await render(false, r);
         if (n === null)
             void store.bumpViews(id);
         return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: NO_PRINT_CSS } }), _jsx(Watermark, { email: r.email }), _jsx("div", { className: "px-6 pt-20 sm:pt-24", children: _jsx(ConfidentialBanner, { name: firstName(r, allow), email: r.email, reason: d.reason, owner: owner, brand: brand, signOutUrl: signOutUrl(id) }) }), page, _jsx(ReaderWatch, { artifactId: id, endpoint: "/api/reader/track", accent: brand.accent })] }));
@@ -189,7 +200,7 @@ export function createArtifactRoutes(config) {
         return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history })] }), _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions })] })] }));
     }
     /** The page itself, shared by open and gated pages. */
-    async function Body(a, { top }) {
+    async function Body(a, { top, reader }) {
         let words = [];
         if (a.narration && a.timings) {
             try {
@@ -202,7 +213,11 @@ export function createArtifactRoutes(config) {
             }
         }
         const toc = showToc(a.markdown, a.toc) ? tocOf(a.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsx(VersionLine, { a: a, n: a.version ?? (a.versions?.length ?? 0) + 1, at: a.updatedAt, history: await historyOf(a.id) })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        // Shared comments need the page to take them AND a host that keeps answers; personal notes need neither.
+        const mode = config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsx(VersionLine, { a: a, n: a.version ?? (a.versions?.length ?? 0) + 1, at: a.updatedAt, history: await historyOf(a.id) })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : (
+                // No recorded narration, or its timings would not load: the browser reads the page.
+                _jsx(BrowserReader, { rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground }))] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in
@@ -493,5 +508,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, ...personalRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/lib/routes/personal-routes.d.ts

@@ -0,0 +1,24 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { type PersonalStore } from '../artifacts/personal-store.js';
+import type { ArtifactStore } from '../artifacts/store.js';
+import type { ReadersStore } from '../artifacts/readers-store.js';
+export type PersonalRoutesContext = {
+    store: ArtifactStore;
+    personal?: PersonalStore;
+    readers?: ReadersStore;
+    readerSecret: () => string | undefined;
+    pageUrl: (id: string) => string;
+    signInOrigin?: string;
+    siteUrl: string;
+};
+type Params = {
+    params: Promise<{
+        id: string;
+    }>;
+};
+export declare function createPersonalRoutes(ctx: PersonalRoutesContext): {
+    PERSONAL_GET: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown> | undefined>;
+    PERSONAL_POST: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown> | undefined>;
+    PERSONAL_DELETE: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown> | undefined>;
+};
+export {};