@supersuit/artifacts 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 `@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.14.0 (2026-09-28)
+
+**A page can say who it is for.** `to: Isaiah` in front matter reads "For Isaiah" in three
+places: after the kicker on the page (not spoken), in the link preview's title ("For Isaiah:
+<title>", og:title, twitter:title and <title>), and as a line above the title on the share card.
+1 to 60 characters, one line; a republish without it clears it. Past versions keep the name they
+were published with. `audience:` is unchanged: stored, never shown.
+
+- DETECTOR: a page with `to:` whose preview does not name the reader.
+- REMEDY: bump; publishers must forward `to`.
+- Tests: parse and refusals, store round trip and clear-on-omit, the kicker on open, password,
+  gated and version pages, the three metadata titles, the share card markup and PNG, narration
+  leaving the name out. Metadata title, share card prop and clear-on-omit mutation-checked.
+
+## 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
@@ -148,9 +149,10 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `title` (required) | The large line, and the unfurl title |
 | `summary` (required) | The italic teaser under it, and the unfurl description |
 | `subtitle` | A line between the two. A republish without it removes it |
+| `to` | Who the page is for, e.g. `to: Marisol`. Shows as "For Marisol" after the kicker, leads the unfurl title ("For Marisol: <title>") and gets its own line on the share card. Never read aloud, and not an access control. One line, 1 to 60 characters; a republish without it removes it |
+| `audience` | Free text stored with the page, never shown |
 | `id` | Republish in place instead of minting a new page |
 | `cover` | An image URL (absolute or site-relative) used as the unfurl image instead of the share card |
-| `audience` | Free text stored with the page |
 | `voice`, `narration`, `timings`, `narrationHash` | Read-aloud: the audio and word timings a publisher generated. Absent (or the timings will not load), the page is read by the browser's own voice instead, lighting the same words; a browser with no `speechSynthesis` shows no player |
 | `password` | Shuts the body behind a door (below) |
 | `access` | `freedom`, `invite` or `public`: a confidential page (below) |
@@ -486,6 +488,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/front-matter.d.ts

@@ -10,6 +10,10 @@ export type ArtifactMeta = {
     /** A line under the title. Title, subtitle and summary are three separate fields; the summary
      *  is the teaser, and the unfurl carries the title and the summary. */
     subtitle?: string;
+    /** Who the page is for ("For <name>" in the kicker, the unfurl title and the share card). A
+     *  label, not an access control: a republish without it removes it. Never spoken. Distinct from
+     *  `audience`, which is stored and never shown. */
+    to?: string;
     audience?: string;
     cover?: string;
     id?: string;
@@ -47,6 +51,8 @@ export type ArtifactMeta = {
     /** Who sees shared comments: `owner` (the default) or every reader (`readers`). */
     commentsVisible?: CommentsVisible;
 };
+/** The longest `to:` a page may carry: a name or two, never a sentence. */
+export declare const MAX_TO_CHARS = 60;
 export declare function parseArtifactSource(text: string): {
     ok: true;
     meta: ArtifactMeta;

package/lib/artifacts/front-matter.js

@@ -7,7 +7,9 @@ import { mergeWidgetState, scanWidgets } from './widgets.js';
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions', 'change', 'comments', 'comments_visible']);
+/** The longest `to:` a page may carry: a name or two, never a sentence. */
+export const MAX_TO_CHARS = 60;
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions', 'change', 'comments', 'comments_visible']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -33,6 +35,12 @@ export function parseArtifactSource(text) {
         if (typeof v === 'string' && v)
             meta[k] = v;
     }
+    if (d.to !== undefined && d.to !== null) {
+        const to = typeof d.to === 'string' ? d.to.trim() : '';
+        if (!to || to.length > MAX_TO_CHARS || /[\r\n]/.test(to))
+            return { ok: false, error: `to must be one line naming who the page is for, 1 to ${MAX_TO_CHARS} characters` };
+        meta.to = to;
+    }
     if (d.change !== undefined && d.change !== null) {
         if (typeof d.change !== 'string')
             return { ok: false, error: 'change must be one line of text' };

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/artifacts/store.d.ts

@@ -11,6 +11,8 @@ export type ArtifactRecord = {
     summary: string;
     template: 'document';
     subtitle?: string;
+    /** Who the page is for; see ArtifactMeta.to. */
+    to?: string;
     audience?: string;
     cover?: string;
     voice?: string;
@@ -54,6 +56,7 @@ export type VersionRecord = VersionEntry & {
     markdown: string;
     title?: string;
     subtitle?: string;
+    to?: string;
     summary?: string;
 };
 /** A change note is one line: whitespace collapsed, capped, empty means none. */

package/lib/artifacts/store.js

@@ -76,7 +76,7 @@ async function versionOf(col, id, n) {
     const cur = currentOf(a);
     if (n === cur) {
         return { version: n, at: a.updatedAt, markdown: a.markdown, title: a.title, summary: a.summary, current: true,
-            ...(a.subtitle ? { subtitle: a.subtitle } : {}), ...(a.note ? { note: a.note } : {}) };
+            ...(a.subtitle ? { subtitle: a.subtitle } : {}), ...(a.to ? { to: a.to } : {}), ...(a.note ? { note: a.note } : {}) };
     }
     if (n > cur)
         return null;
@@ -123,6 +123,7 @@ async function saveArtifact(col, input) {
         summary: input.meta.summary,
         template: input.meta.template,
         ...(input.meta.subtitle ? { subtitle: input.meta.subtitle } : {}),
+        ...(input.meta.to ? { to: input.meta.to } : {}),
         ...(input.meta.audience ? { audience: input.meta.audience } : {}),
         ...(input.meta.cover ? { cover: input.meta.cover } : {}),
         ...(input.meta.voice ? { voice: input.meta.voice } : {}),
@@ -161,7 +162,7 @@ async function saveArtifact(col, input) {
             await history.doc(vid(current)).set({
                 version: current, markdown: existing.markdown, at: existing.updatedAt,
                 title: existing.title, summary: existing.summary,
-                ...(existing.subtitle ? { subtitle: existing.subtitle } : {}), ...(existing.note ? { note: existing.note } : {}),
+                ...(existing.subtitle ? { subtitle: existing.subtitle } : {}), ...(existing.to ? { to: existing.to } : {}), ...(existing.note ? { note: existing.note } : {}),
             });
         }
         const next = fresh ? current + 1 : current;
@@ -170,6 +171,8 @@ async function saveArtifact(col, input) {
         const password = input.meta.password ? {} : { password: FieldValue.delete() };
         // A subtitle the file no longer carries is gone from the page, like any other content.
         const subtitle = input.meta.subtitle ? {} : { subtitle: FieldValue.delete() };
+        // Who it is for is a label on the content, never an access control: absent clears it.
+        const to = input.meta.to ? {} : { to: FieldValue.delete() };
         // Access is the opposite of password on purpose: absent leaves it alone, and only an explicit
         // `access: public` opens the page. Reopening a confidential page must never be a side effect.
         const access = input.meta.access === 'public' ? { access: FieldValue.delete() } : {};
@@ -186,7 +189,7 @@ async function saveArtifact(col, input) {
             ...(input.meta.commentsVisible ? {} : { commentsVisible: FieldValue.delete() }),
         };
         await ref.update({
-            ...fields, ...password, ...subtitle, ...access, ...state, ...look, markdown: input.markdown, version: next,
+            ...fields, ...password, ...subtitle, ...to, ...access, ...state, ...look, markdown: input.markdown, version: next,
             // `updatedAt` is when this version went live; finishing its own publish does not move it.
             ...(fresh || input.markdown !== existing.markdown ? { updatedAt: now } : {}),
             note: nextNote ?? FieldValue.delete(),

package/lib/brand/share-card.d.ts

@@ -3,11 +3,14 @@ export declare const SHARE_W = 1200;
 export declare const SHARE_H = 630;
 /** Titles get smaller as they get longer, so three lines always fit above the mark. */
 export declare function titleSize(title: string): number;
-export declare function ShareCard({ pack, title, fontName, backdrop }: {
+export declare function ShareCard({ pack, title, to, fontName, backdrop }: {
     pack: BrandPack;
     title: string;
+    to?: string;
     fontName: string;
     backdrop?: string;
 }): import("react").JSX.Element;
 /** A 1200x630 PNG for one page. Caller has already checked `pack.share` exists. */
-export declare function renderShareCard(pack: BrandPack, title: string): Promise<Response>;
+export declare function renderShareCard(pack: BrandPack, title: string, opts?: {
+    to?: string;
+}): Promise<Response>;

package/lib/brand/share-card.js

@@ -24,8 +24,9 @@ export function titleSize(title) {
         return 62;
     return 52;
 }
-export function ShareCard({ pack, title, fontName, backdrop }) {
+export function ShareCard({ pack, title, to, fontName, backdrop }) {
     const size = titleSize(title);
+    const kicker = { display: 'flex', fontSize: 22, letterSpacing: 5, textTransform: 'uppercase', color: pack.accent, fontWeight: 500 };
     return (_jsxs("div", { style: {
             display: 'flex',
             flexDirection: 'column',
@@ -36,12 +37,12 @@ export function ShareCard({ pack, title, fontName, backdrop }) {
             ...(backdrop ? { backgroundImage: `url(${backdrop})`, backgroundSize: `${SHARE_W}px ${SHARE_H}px` } : {}),
             color: pack.ink,
             fontFamily: fontName,
-        }, children: [_jsx("div", { style: { display: 'flex', fontSize: 22, letterSpacing: 5, textTransform: 'uppercase', color: pack.accent, fontWeight: 500 }, children: pack.kicker }), _jsx("div", { style: { display: 'flex', marginTop: 28, fontSize: size, lineHeight: 1.18, maxWidth: 980, lineClamp: 3 }, children: title })] }));
+        }, children: [_jsx("div", { style: kicker, children: pack.kicker }), to ? _jsx("div", { style: { ...kicker, marginTop: 12, lineHeight: 1.4 }, children: `For ${to}` }) : null, _jsx("div", { style: { display: 'flex', marginTop: 28, fontSize: size, lineHeight: 1.18, maxWidth: 980, lineClamp: 3 }, children: title })] }));
 }
 /** A 1200x630 PNG for one page. Caller has already checked `pack.share` exists. */
-export async function renderShareCard(pack, title) {
+export async function renderShareCard(pack, title, opts = {}) {
     const { font, backdrop } = await assetsFor(pack);
-    return new ImageResponse(_jsx(ShareCard, { pack: pack, title: title, fontName: font.name, backdrop: backdrop }), {
+    return new ImageResponse(_jsx(ShareCard, { pack: pack, title: title, to: opts.to, fontName: font.name, backdrop: backdrop }), {
         width: SHARE_W,
         height: SHARE_H,
         fonts: [{ name: font.name, data: font.data, weight: font.weight, style: 'normal' }],

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/artifacts.js

@@ -66,6 +66,11 @@ export function createArtifactRoutes(config) {
         store, state: config.state, personal: config.personal, readers: config.readers, assets: config.assets, transcribe: config.transcribe,
         readerSecret, pageUrl, signInOrigin, siteUrl, clientIp: config.clientIp,
     });
+    /** The kicker over every title: the pack's line, then who the page is for. Never spoken: the
+     *  whole paragraph is data-nospeak, and narrationText has no `to` to read. */
+    function Kicker({ to }) {
+        return (_jsxs("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: [brand.kicker, to ? _jsx("span", { "data-nospeak": true, "data-to": true, children: ` · For ${to}` }) : null] }));
+    }
     async function generateMetadata({ params }) {
         const { id } = await params;
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
@@ -73,13 +78,15 @@ export function createArtifactRoutes(config) {
             return { title: 'Not found', robots: { index: false, follow: false } };
         const url = pageUrl(a.id);
         const image = absolute(a.cover) ?? (brand.share ? shareCardUrl(a.id, a.updatedAt) : absolute(config.defaultShareImage));
+        // Who it is for leads the unfurl, so a thread shows it before the reader opens anything.
+        const title = a.to ? `For ${a.to}: ${a.title}` : a.title;
         return {
-            title: a.title,
+            title,
             description: a.summary,
             alternates: { canonical: pagePath(a.id) },
             robots: { index: false, follow: false },
             openGraph: {
-                title: a.title,
+                title,
                 description: a.summary,
                 url,
                 siteName: brand.name,
@@ -88,7 +95,7 @@ export function createArtifactRoutes(config) {
             },
             twitter: {
                 card: image ? 'summary_large_image' : 'summary',
-                title: a.title,
+                title,
                 description: a.summary,
                 ...(image ? { images: [image] } : {}),
             },
@@ -145,7 +152,7 @@ export function createArtifactRoutes(config) {
         ];
         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 })] }));
+            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(Kicker, { to: a.to }), _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 })] }));
         }
         // 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.
@@ -164,7 +171,7 @@ export function createArtifactRoutes(config) {
         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 })] }));
+        const header = (_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx(Kicker, { to: a.to }), _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 })] }));
         if (!d.open) {
             if (d.why === 'not-allowed' && config.readers)
                 void config.readers.flag({ artifactId: id, reader: d.reader, kind: 'refused' }).catch(() => { });
@@ -205,7 +212,7 @@ export function createArtifactRoutes(config) {
         const title = v.title ?? a.title;
         const summary = v.summary ?? a.summary;
         const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
-        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 })] })] }));
+        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(Kicker, { to: v.to }), _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, reader }) {
@@ -223,7 +230,7 @@ export function createArtifactRoutes(config) {
         const toc = showToc(a.markdown, a.toc) ? tocOf(a.markdown) : [];
         // 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 })) : (
+        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(Kicker, { to: a.to }), _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 }))] }));
     }
@@ -497,7 +504,7 @@ export function createArtifactRoutes(config) {
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
         if (!a)
             return new NextResponse(`no artifact with id ${id}`, { status: 404 });
-        return renderShareCard(pack, a.title);
+        return renderShareCard(pack, a.title, { to: a.to });
     }
     /** GET|POST /api/artifacts/<id>/versions, publish key: the history, and a note written onto one
      *  version after the fact. POST body: { version: number, note: string | null }. */

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.14.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",