@supersuit/artifacts 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.13.0 (2026-09-28)
+
+**A publisher can hear about new comments, and every comment has a link to itself.**
+
+- `COMMENTS_FEED`: `GET /api/comments?since=<ISO with zone>`, publish key only. Shared comments
+  across the tenant's pages, oldest first, at most 200, `at > since`: `{ now, comments: [{
+  artifactId, title, entryId, parent, name, quote, region, body, transcript, audioUrl, at, link }] }`.
+  `name` null means an anonymous reader. Personal notes never appear (the privacy test calls it).
+  Comments on deleted pages are left out. Callers keep the last row's `at` as their cursor and
+  use `now` only on a first run.
+- Deep link: `/<id>#comment-<entryId>` scrolls to the comment and opens its thread, on load and
+  on `hashchange`; a reply opens its parent's thread; an earlier-versions comment is highlighted.
+- New optional `StateStore.slotSince(slot, after, limit)`; a store without it answers 501.
+- DETECTOR: a host with no `/api/comments` route.
+- REMEDY: bump; add `app/api/comments/route.ts` delegating GET to `COMMENTS_FEED`; create the
+  Firestore composite index on `<base>State` (collection scope): `slot` ascending, `at` ascending.
+- Tests: `comments-feed.test.tsx`, five deep-link tests, the privacy test, and the packed
+  fixture reading a comment back through the feed. Since-exclusivity, the slot filter, the
+  personal-note exclusion, reply-to-parent and the hashchange listener are mutation-checked.
+
 ## 0.12.1 (2026-09-28)
 
 **Tapping into a comment box no longer zooms the page on iPhone.** iOS Safari zooms the page

package/README.md

@@ -80,6 +80,7 @@ The rest, each exporting the named handler(s) from `artifacts`:
 | `app/api/reader/leave/route.ts` | `GET` = `LEAVE` |
 | `app/api/reader/ack/route.ts` | `POST` = `ACK` |
 | `app/api/reader/track/route.ts` | `POST` = `TRACK` |
+| `app/api/comments/route.ts` | `GET` = `COMMENTS_FEED` (see [the comments feed](#the-comments-feed)) |
 
 Pages live at `/<id>` by default. Mounting inside a larger site, pass `pagePrefix: '/a/'` and put
 the page at `app/a/[id]/`. One deployment can serve many sites: build one set of routes per
@@ -486,6 +487,43 @@ The bucket also needs CORS allowing `PUT` from the site's origin with the `conte
 `cache-control` and `x-goog-content-length-range` headers, since the reader's browser uploads
 directly.
 
+### The comments feed
+
+So the publisher hears about a shared comment without opening every page, one route lists every
+shared comment on any of the host's pages after a time. Publish key only; personal notes never
+appear (the privacy test covers this handler like every other).
+
+```
+GET /api/comments?since=2026-09-28T12:00:00Z
+Authorization: Bearer <publish key>
+
+200 { now, comments: [ { artifactId, title, entryId, parent, name, quote, region, body,
+                         transcript, audioUrl, at, link } ] }
+```
+
+Oldest first, at most 200, strictly after `since` (an ISO 8601 time with a zone; anything else is
+a 400). `name` is null for an anonymous reader; `quote` is the text the comment is pinned to, or
+null for a box (`region: true`); `parent` is the comment a reply answers; `audioUrl` is a signed
+URL to the recording, when there is one and the host can sign it. `link` is the page with
+`#comment-<entryId>`: opening it scrolls to the pin and opens its thread (a reply opens its
+parent's; a comment on an earlier version is highlighted in that list). A caller keeps a cursor
+at the last row's `at` and leaves it where it was when nothing came back; `now` is where a first
+run starts, so it does not replay history.
+
+The path sits outside `/api/artifacts/` because `comments` is itself a legal page id there.
+
+```ts
+// app/api/comments/route.ts
+import type { NextRequest } from 'next/server'
+import { artifacts } from '@/lib/artifacts'
+export function GET(request: NextRequest) { return artifacts.COMMENTS_FEED(request) }
+```
+
+On Firestore (`createStateStore`) the query is one range scan over `<base>State` and needs a
+composite index: **`slot` ascending, `at` ascending**, collection scope. Without it Firestore
+refuses the query and the error names a link that creates the index. A host with its own
+`StateStore` implements `slotSince(slot, after, limit)`; without it the feed answers 501.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,

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

@@ -62,6 +62,11 @@ export interface StateStore {
         entryId: string;
         value: unknown;
     }): Promise<StateEntry | null>;
+    /** Every entry in one slot across ALL of this tenant's pages written strictly after `after` (an
+     *  ISO time, compared as the stored `at` string), oldest first, at most `limit`. The comments
+     *  feed reads it. Optional so a host's own store keeps working; without it the feed answers 501.
+     *  The Firestore query needs a composite index on <base>State: slot ASC, at ASC. */
+    slotSince?(slot: string, after: string, limit: number): Promise<StateEntry[]>;
 }
 export declare const readerKeyFor: {
     signedIn: (uid: string) => string;

package/lib/artifacts/state-store.js

@@ -101,6 +101,10 @@ export function createStateStore(db, base) {
             await ref.update({ json: JSON.stringify(value) });
             return { ...e, value };
         },
+        // One indexed range query over the tenant's whole collection: equality on slot, range and
+        // order on at. Needs the composite index (slot ASC, at ASC) on <base>State, or Firestore
+        // refuses the query with FAILED_PRECONDITION and a link that creates it.
+        slotSince: (slot, after, limit) => load(col().where('slot', '==', slot).where('at', '>', after).orderBy('at').limit(limit)),
     };
     return store;
 }
@@ -168,5 +172,10 @@ export function createMemoryStateStore() {
             docs.set(entryId, next);
             return structuredClone(next);
         },
+        slotSince: async (slot, after, limit) => [...docs.values()]
+            .filter((e) => e.slot === slot && e.at > after)
+            .sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id))
+            .slice(0, limit)
+            .map((e) => structuredClone(e)),
     };
 }

package/lib/reader/comment-layer.js

@@ -16,6 +16,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // 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.
 //
+// A link to `#comment-<entryId>` (what the publisher's notification carries) lands on the comment:
+// on load and on every hashchange the pin is scrolled into view and its thread opened; a reply's
+// id opens its parent's thread; a comment on an earlier version is scrolled to and highlighted.
+//
 // 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';
@@ -32,6 +36,9 @@ import { addDeviceNote, deviceNotes, removeDeviceNote, replaceDeviceNote } from
 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 HASH = /^#comment-([A-Za-z0-9_-]{1,128})$/;
+/** The entry id a `#comment-<id>` hash names, or null. */
+const commentHashId = (hash) => HASH.exec(hash)?.[1] ?? null;
 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';
@@ -85,6 +92,11 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     const [drag, setDrag] = useState(null);
     const [tick, setTick] = useState(0);
     const [theme, setTheme] = useState({});
+    /** The comment the address names, until it has been found and shown. */
+    const [target, setTarget] = useState(null);
+    const [highlight, setHighlight] = useState(null);
+    /** A selector to scroll into view once the render that draws it has committed. */
+    const [scrollTo, setScrollTo] = useState(null);
     const call = useCallback(async (url, init) => {
         try {
             const r = await fetch(url, { credentials: 'same-origin', cache: 'no-store', ...init });
@@ -282,6 +294,14 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
             root.removeEventListener('dragstart', noImageDrag);
         };
     }, [rootId]);
+    // The address names a comment: on load, and every time the hash changes while the page is open.
+    useEffect(() => {
+        const read = () => { const id = commentHashId(window.location.hash); if (id)
+            setTarget(id); };
+        read();
+        window.addEventListener('hashchange', read);
+        return () => window.removeEventListener('hashchange', read);
+    }, []);
     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.
@@ -318,6 +338,37 @@ 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
+    // Show the comment the address names once it has loaded: a reply is shown in its parent's thread.
+    // Held until the comments arrive; an id that never arrives (deleted, or not this reader's to see)
+    // simply does nothing.
+    useEffect(() => {
+        if (!target || !mounted)
+            return;
+        const item = items.find((i) => i.id === target);
+        if (!item)
+            return;
+        const parent = item.value.parent ? items.find((i) => i.id === item.value.parent) : undefined;
+        const id = (parent ?? item).id;
+        setTarget(null);
+        if (layout.placed.some((p) => p.item.id === id)) {
+            setShowPins(true);
+            setHighlight(null);
+            setThread(id);
+            setScrollTo(`[data-comment-pin][data-comment-id="${id}"]`);
+        }
+        else if (layout.earlier.some((i) => i.id === id)) {
+            setThread(null);
+            setHighlight(id);
+            setScrollTo(`[data-comment-earlier-id="${id}"]`);
+        }
+    }, [target, mounted, items, layout]);
+    // Effects run after the DOM is committed, so the pin or list item drawn for the target is there.
+    useEffect(() => {
+        if (!scrollTo)
+            return;
+        document.querySelector(scrollTo)?.scrollIntoView?.({ block: 'center', behavior: 'smooth' });
+        setScrollTo(null);
+    }, [scrollTo]);
     /** 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);
@@ -414,7 +465,7 @@ export function CommentLayer({ artifactId, rootId, ownerName, comments, canShare
     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", 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] }));
+    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", { "data-comment-earlier-id": item.id, ...(highlight === item.id ? { 'data-comment-highlight': '' } : {}), className: "m-0 border-l-2 py-1 pl-3", style: { borderColor: accent, borderStyle: item.kind === 'personal' ? 'dashed' : 'solid', ...(highlight === item.id ? { background: `color-mix(in srgb, ${accent} 14%, transparent)` } : {}) }, 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';

package/lib/routes/artifacts.d.ts

@@ -112,6 +112,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
             id: string;
         }>;
     }) => Promise<NextResponse<unknown>>;
+    COMMENTS_FEED: (req: NextRequest) => Promise<NextResponse<unknown>>;
     Page: ({ params, searchParams }: PageProps) => Promise<import("react").JSX.Element>;
     generateMetadata: ({ params }: Params) => Promise<Metadata>;
     VersionPage: ({ params, searchParams }: VersionProps) => Promise<import("react").JSX.Element>;

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

@@ -3,6 +3,12 @@ import { type StateStore } from '../artifacts/state-store.js';
 import type { ArtifactStore } from '../artifacts/store.js';
 import type { ReadersStore } from '../artifacts/readers-store.js';
 export declare const ANON_COOKIE = "artifact_anon";
+/** The most comments one feed answer carries. A caller that gets this many moves its cursor to the
+ *  last row's `at` and asks again. */
+export declare const FEED_MAX = 200;
+/** `since` as the stored `at` form (UTC, milliseconds), or null. A `+` offset left unencoded in a
+ *  query string arrives as a space, so that one spelling is read back as the `+` it was. */
+export declare function feedSince(raw: string | null): string | null;
 /** The id an anonymous writer's rate counter is stored under. An HMAC over the site and the IP,
  *  keyed by the reader secret when the host has one (so the stored value cannot be reversed by
  *  hashing the IPv4 space), else by the site URL. The site is in the message either way, so two
@@ -37,5 +43,6 @@ export declare function createStateRoutes(ctx: StateRoutesContext): {
     STATE_GET: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown> | undefined>;
     STATE_POST: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown> | undefined>;
     RESPONSES: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    COMMENTS_FEED: (req: NextRequest) => Promise<NextResponse<unknown>>;
 };
 export {};

package/lib/routes/state-routes.js

@@ -4,6 +4,7 @@
 //   POST /api/artifacts/<id>/state      { slot, op: set|append|remove|replace, value?, entry? }
 //   GET  /api/artifacts/<id>/responses  publish key; every answer with who (?format=csv)
 //   DELETE /api/artifacts/<id>/responses?reader=<key>  publish key; one reader's answers
+//   GET  /api/comments?since=<ISO>      publish key; every shared comment on any page after a time
 //
 // Who is writing: the grant a gated page already uses, or on a page with `writers: anyone`, an
 // anonymous id in an HttpOnly cookie. When both are present the anonymous answers move to the
@@ -23,6 +24,21 @@ import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js
 export const ANON_COOKIE = 'artifact_anon';
 const ANON_ID = /^[A-Za-z0-9]{24}$/;
 const MAX_BODY = 16 * 1024;
+/** The most comments one feed answer carries. A caller that gets this many moves its cursor to the
+ *  last row's `at` and asks again. */
+export const FEED_MAX = 200;
+// An ISO 8601 time with a zone: 2026-09-28T12:00Z, 2026-09-28T12:00:00.123+02:00. A date alone, or
+// a time with no zone, is refused rather than read in the server's own zone.
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})$/;
+/** `since` as the stored `at` form (UTC, milliseconds), or null. A `+` offset left unencoded in a
+ *  query string arrives as a space, so that one spelling is read back as the `+` it was. */
+export function feedSince(raw) {
+    const v = (raw ?? '').trim().replace(/ (\d{2}:?\d{2})$/, '+$1');
+    if (!ISO_TIME.test(v))
+        return null;
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
 /** The id an anonymous writer's rate counter is stored under. An HMAC over the site and the IP,
  *  keyed by the reader secret when the host has one (so the stored value cannot be reversed by
  *  hashing the IPv4 space), else by the site URL. The site is in the message either way, so two
@@ -295,5 +311,42 @@ export function createStateRoutes(ctx) {
         await withAudioUrls(id, rows.filter((r) => r.slot === COMMENTS_SLOT));
         return json({ id, title: a.title, responses: rows });
     }
-    return { STATE_GET, STATE_POST, RESPONSES };
+    /** GET /api/comments?since=<ISO>: every SHARED comment on any of this host's pages written after
+     *  `since` (exclusive), oldest first, at most FEED_MAX, each with a link that opens it on the
+     *  page. It reads the `comments` slot of the state core only; personal notes live in a store no
+     *  publisher route reads, so they cannot appear here. The publisher's own notifier polls it. */
+    async function COMMENTS_FEED(req) {
+        if (!isPublishAuthed(req, ctx.publishKey()))
+            return json({ error: 'Unauthorized' }, 401);
+        const since = feedSince(req.nextUrl.searchParams.get('since'));
+        if (!since)
+            return json({ error: 'since must be an ISO 8601 time with a zone, like 2026-09-28T12:00:00Z' }, 400);
+        if (!ctx.state)
+            return json({ error: 'this host keeps no answers' }, 501);
+        if (!ctx.state.slotSince)
+            return json({ error: 'this host cannot list comments by time' }, 501);
+        const now = new Date().toISOString();
+        const entries = await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
+        const pages = new Map();
+        const pageOf = (id) => { if (!pages.has(id))
+            pages.set(id, ctx.store.get(id)); return pages.get(id); };
+        const comments = [];
+        for (const e of entries) {
+            const a = await pageOf(e.artifactId);
+            // A page deleted since the comment was left has nowhere for the link to land.
+            if (!a)
+                continue;
+            const v = e.value;
+            const audio = isCommentAudioPath(v.audio) && ctx.audioUrl ? await ctx.audioUrl(e.artifactId, v.audio) : null;
+            comments.push({
+                artifactId: e.artifactId, title: a.title, entryId: e.id, parent: v.parent ?? null,
+                name: e.writer.anonymous ? null : e.writer.name?.trim() || 'a signed-in reader',
+                quote: v.anchor?.kind === 'text' ? v.anchor.quote : null, region: v.anchor?.kind === 'region',
+                body: v.body, transcript: v.transcript ?? null, audioUrl: audio, at: e.at,
+                link: `${ctx.pageUrl(e.artifactId)}#comment-${e.id}`,
+            });
+        }
+        return json({ now, comments });
+    }
+    return { STATE_GET, STATE_POST, RESPONSES, COMMENTS_FEED };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",