@supersuit/artifacts 0.10.0 → 0.11.0

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,7 +9,8 @@ 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';
@@ -17,6 +18,7 @@ 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';
@@ -25,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. */
@@ -46,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;
@@ -106,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
@@ -121,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] }));
@@ -143,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 })] }));
@@ -159,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 })] }));
@@ -190,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 {
@@ -203,7 +213,9 @@ 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 })) : (
+        // 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 }))] }));
     }
@@ -496,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 {};

package/lib/routes/personal-routes.js

@@ -0,0 +1,100 @@
+// The reader's own notes on a page, and nobody else's.
+//
+//   GET    /api/artifacts/<id>/personal              the signed-in reader's notes on this page
+//   POST   /api/artifacts/<id>/personal              { value } adds one; { entry, value } edits one
+//   DELETE /api/artifacts/<id>/personal?entry=<id>   deletes one
+//
+// Signed-in readers only, by the grant cookie. A reader who is not signed in gets 401 with
+// `{ device: true }` and keeps the note in their browser instead, where no server (this host's
+// owner included) can read it. There is deliberately NO publisher variant of any of these: the
+// publish key opens nothing here, and personal-privacy.test.ts holds every handler to that.
+import { NextResponse } from 'next/server';
+import { ARTIFACT_ID_RE } from './ids.js';
+import { GRANT_COOKIE, decide, signInUrl, verifyGrant } from '../artifacts/reader.js';
+import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
+import { validatePersonal } from '../artifacts/personal-store.js';
+const MAX_BODY = 16 * 1024;
+export function createPersonalRoutes(ctx) {
+    const json = (body, status = 200) => NextResponse.json(body, { status, headers: { 'cache-control': 'no-store' } });
+    const siteOrigin = new URL(ctx.siteUrl).origin;
+    /** The page, the signed-in reader, and every door the page itself has; or the refusal. */
+    async function open(req, id) {
+        const a = ARTIFACT_ID_RE.test(id) ? await ctx.store.get(id) : null;
+        if (!a)
+            return { error: json({ error: `no artifact with id ${id}` }, 404) };
+        if (a.password && !isUnlocked({ id, password: a.password, cookie: req.cookies.get(unlockCookieName(id))?.value }))
+            return { error: json({ error: 'this page is locked' }, 403) };
+        const reader = verifyGrant(ctx.readerSecret(), req.cookies.get(GRANT_COOKIE)?.value);
+        const signIn = ctx.signInOrigin ? signInUrl(ctx.signInOrigin, ctx.pageUrl(id)) : null;
+        if (a.access) {
+            if (!ctx.readers)
+                return { error: json({ error: 'this page is closed' }, 403) };
+            if (!reader)
+                return { error: json({ error: 'sign in to read this page', signIn }, 401) };
+            if (!decide(a.access, reader, await ctx.readers.allowList(id)).open)
+                return { error: json({ error: 'this page is not open to you' }, 403) };
+            if (!(await ctx.readers.acknowledged(id, reader.email)))
+                return { error: json({ error: 'accept the agreement first' }, 403) };
+        }
+        // The client reads `device: true` as "keep this note in the browser".
+        if (!ctx.personal)
+            return { error: json({ error: 'this host keeps no personal notes', device: true }, 501) };
+        if (!reader)
+            return { error: json({ error: 'sign in to keep notes everywhere', device: true, signIn }, 401) };
+        return { id, uid: reader.uid, personal: ctx.personal };
+    }
+    const list = async (o) => json({ notes: await o.personal.list(o.id, o.uid) });
+    // A write carries the reader's cookies; a browser always names its Origin on one, so a foreign one is refused.
+    const foreign = (req) => { const origin = req.headers.get('origin'); return origin !== null && origin !== siteOrigin; };
+    async function PERSONAL_GET(req, { params }) {
+        const o = await open(req, (await params).id);
+        return 'error' in o ? o.error : list(o);
+    }
+    async function PERSONAL_POST(req, { params }) {
+        if (foreign(req))
+            return json({ error: 'wrong origin' }, 403);
+        const declared = Number(req.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared > MAX_BODY)
+            return json({ error: 'request over 16 KB' }, 413);
+        const raw = await req.text();
+        if (Buffer.byteLength(raw, 'utf8') > MAX_BODY)
+            return json({ error: 'request over 16 KB' }, 413);
+        let b;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return json({ error: 'body must be JSON' }, 400);
+            b = parsed;
+        }
+        catch {
+            return json({ error: 'body must be JSON' }, 400);
+        }
+        const o = await open(req, (await params).id);
+        if ('error' in o)
+            return o.error;
+        const v = validatePersonal(b.value);
+        if (!v.ok)
+            return json({ error: v.error }, 400);
+        if (b.entry !== undefined) {
+            if (typeof b.entry !== 'string' || !(await o.personal.replace(o.id, o.uid, b.entry, v.value)))
+                return json({ error: 'no note of yours with that id' }, 404);
+            return list(o);
+        }
+        const r = await o.personal.add(o.id, o.uid, v.value);
+        if ('full' in r)
+            return json({ error: 'you have left the most notes this page keeps' }, 409);
+        return list(o);
+    }
+    async function PERSONAL_DELETE(req, { params }) {
+        if (foreign(req))
+            return json({ error: 'wrong origin' }, 403);
+        const o = await open(req, (await params).id);
+        if ('error' in o)
+            return o.error;
+        const entry = req.nextUrl.searchParams.get('entry') ?? '';
+        if (!(await o.personal.remove(o.id, o.uid, entry)))
+            return json({ error: 'no note of yours with that id' }, 404);
+        return list(o);
+    }
+    return { PERSONAL_GET, PERSONAL_POST, PERSONAL_DELETE };
+}

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

@@ -21,6 +21,9 @@ export type StateRoutesContext = {
      *  which is correct on Vercel (it overwrites XFF with the real client IP) and wrong behind any
      *  other proxy that appends rather than replaces; a host behind one of those passes its own. */
     clientIp?: (req: NextRequest) => string;
+    /** The page owner's sign-in email. Signed in as them, a page's comments show every entry with
+     *  full names, whatever `comments_visible:` says. */
+    ownerEmail?: string;
 };
 type Params = {
     params: Promise<{

package/lib/routes/state-routes.js

@@ -1,7 +1,7 @@
 // The state routes: what readers put into a page, and what the publisher gets back.
 //
 //   GET  /api/artifacts/<id>/state      the reader's own answers + what the page lets them see
-//   POST /api/artifacts/<id>/state      { slot, op: set|append|remove, value?, entry? }
+//   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
 //
@@ -14,7 +14,8 @@ import { isPublishAuthed } from '../artifacts/auth.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../artifacts/reader.js';
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
-import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters } from '../artifacts/state.js';
+import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters, slotVisibility } from '../artifacts/state.js';
+import { COMMENTS_SLOT, validateComment } from '../artifacts/comments.js';
 import { readerKeyFor } from '../artifacts/state-store.js';
 import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
@@ -64,15 +65,39 @@ export function createStateRoutes(ctx) {
         const anonId = rawAnon && ANON_ID.test(rawAnon) ? rawAnon : null;
         return { a, reader, anonId, signIn };
     }
+    const ownerEmail = ctx.ownerEmail?.trim().toLowerCase();
+    const isOwner = (r) => !!r && !!ownerEmail && r.email === ownerEmail;
+    /** Comments are on for this page: the slot exists because `comments:` put it there. */
+    const commentsOn = (a) => !!a.comments && a.comments !== 'off' && Object.hasOwn(a.state.slots, COMMENTS_SLOT);
     const writerFor = (r) => ({ key: readerKeyFor.signedIn(r.uid), uid: r.uid, email: r.email, name: r.name, anonymous: false });
     async function viewBody(a, reader, readerKey) {
         const allow = reader && ctx.readers && a.access ? await ctx.readers.allowList(a.id) : [];
+        const entries = await ctx.state.entries(a.id);
+        const slots = stateView(a.state, entries, readerKey);
+        const owner = isOwner(reader);
+        // The owner reads every comment with its writer's full name, whatever the page shows readers.
+        if (owner && commentsOn(a)) {
+            slots[COMMENTS_SLOT].shared = entries.filter((e) => e.slot === COMMENTS_SLOT)
+                .sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id))
+                .map((e) => ({ id: e.id, name: e.writer.name?.trim() || 'a reader', value: e.value, at: e.at, mine: e.readerKey === readerKey }));
+        }
         return {
             reader: reader ? { firstName: firstName(reader, allow) } : null,
             canWrite: !!reader || effectiveWriters(a.state, a.access) === 'anyone',
-            slots: stateView(a.state, await ctx.state.entries(a.id), readerKey),
+            ...(owner ? { owner: true } : {}),
+            slots,
         };
     }
+    /** The comments a writer can see, by id: every one on a readers-visible page, else their own,
+     *  and every one for the owner. A reply may name only a comment its writer was shown. */
+    async function visibleComments(a, writerKey, reader) {
+        const all = slotVisibility(a.state, COMMENTS_SLOT) === 'shared' || isOwner(reader);
+        const byId = new Map();
+        for (const e of await ctx.state.entries(a.id))
+            if (e.slot === COMMENTS_SLOT && (all || e.readerKey === writerKey))
+                byId.set(e.id, e.value);
+        return byId;
+    }
     // A GET that writes, on purpose: when a signed-in reader still carries an anonymous cookie, the
     // answers move here, because this is the first request that sees both. It is safe as a GET:
     // moveReader is idempotent (a second run finds nothing under the cleared key), and the grant
@@ -134,28 +159,40 @@ export function createStateRoutes(ctx) {
         if (!def)
             return json({ error: `no slot named ${slot} on this page` }, 400);
         const op = b.op;
-        if (op !== 'set' && op !== 'append' && op !== 'remove')
-            return json({ error: 'op must be set, append or remove' }, 400);
+        if (op !== 'set' && op !== 'append' && op !== 'remove' && op !== 'replace')
+            return json({ error: 'op must be set, append, remove or replace' }, 400);
         if (op === 'set' && def.shape !== 'one')
             return json({ error: `slot ${slot} takes append` }, 400);
-        if (op === 'append' && def.shape !== 'many')
+        if ((op === 'append' || op === 'replace') && def.shape !== 'many')
             return json({ error: `slot ${slot} takes set` }, 400);
+        const entryId = typeof b.entry === 'string' ? b.entry : undefined;
+        if (op === 'replace' && !entryId)
+            return json({ error: 'replace names the entry it edits' }, 400);
+        if (op === 'replace' && !ctx.state.replace)
+            return json({ error: 'this host cannot edit an answer' }, 501);
+        const isComments = slot === COMMENTS_SLOT && commentsOn(a);
         let setCookie = null;
         let writer;
         if (reader)
             writer = writerFor(reader);
         else {
-            if (effectiveWriters(a.state, a.access) !== 'anyone')
+            if (effectiveWriters(a.state, a.access, slot) !== 'anyone')
                 return json({ error: 'sign in to answer', signIn }, 401);
             // A remove adds nothing, so it is never counted and never mints a cookie: with no cookie
             // there is nothing of theirs to remove, and the answer is simply the page as it stands.
+            // Comments say so instead: deleting a comment that is not yours is a refusal, not a no-op.
             if (op === 'remove') {
                 if (!anonId)
-                    return json(await viewBody(a, null, null));
+                    return isComments && entryId ? json({ error: 'no comment of yours with that id' }, 404) : json(await viewBody(a, null, null));
                 const key = readerKeyFor.anonymous(anonId);
-                await ctx.state.remove({ artifactId: id, slot, readerKey: key, entryId: typeof b.entry === 'string' ? b.entry : undefined });
+                const n = await ctx.state.remove({ artifactId: id, slot, readerKey: key, entryId });
+                if (isComments && entryId && !n)
+                    return json({ error: 'no comment of yours with that id' }, 404);
                 return json(await viewBody(a, null, key));
             }
+            // An edit with no cookie has nothing of theirs to edit.
+            if (op === 'replace' && !anonId)
+                return json({ error: 'no answer of yours with that id' }, 404);
             const n = await ctx.state.countAnonWrite(id, ipHash(req), Math.floor(Date.now() / 60000));
             if (n > ANON_WRITES_PER_MINUTE)
                 return json({ error: 'too many answers from here; try again in a minute' }, 429);
@@ -166,12 +203,34 @@ export function createStateRoutes(ctx) {
             writer = { key: readerKeyFor.anonymous(anonId), name: null, anonymous: true };
         }
         if (op === 'remove') {
-            await ctx.state.remove({ artifactId: id, slot, readerKey: writer.key, entryId: typeof b.entry === 'string' ? b.entry : undefined });
+            const n = await ctx.state.remove({ artifactId: id, slot, readerKey: writer.key, entryId });
+            if (isComments && entryId && !n)
+                return json({ error: 'no comment of yours with that id' }, 404);
         }
         else {
             const bad = checkValue(b.value) ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null);
             if (bad)
                 return json({ error: bad }, 400);
+            let value = b.value;
+            if (isComments) {
+                const seen = await visibleComments(a, writer.key, reader);
+                const c = validateComment(b.value, (cid) => seen.get(cid) ?? null);
+                if (!c.ok)
+                    return json({ error: c.error }, 400);
+                // An edit keeps the comment where it is in its thread: a reply stays a reply to the same one.
+                if (op === 'replace' && seen.has(entryId) && (seen.get(entryId).parent ?? null) !== (c.value.parent ?? null))
+                    return json({ error: 'an edit cannot move a comment into or out of a thread' }, 400);
+                value = c.value;
+            }
+            if (op === 'replace') {
+                const r = await ctx.state.replace({ artifactId: id, slot, readerKey: writer.key, entryId: entryId, value });
+                if (!r)
+                    return json({ error: 'no answer of yours with that id' }, 404);
+                const res = json(await viewBody(a, reader, writer.key));
+                if (setCookie)
+                    res.headers.append('set-cookie', setCookie);
+                return res;
+            }
             // The page-wide cap per slot. Counted before the write and not atomically with it, so a
             // burst can overshoot by the writes in flight; it bounds the slot, it is not a quota.
             if ((await ctx.state.countSlot(id, slot)) >= MAX_ENTRIES_PER_SLOT) {
@@ -182,8 +241,8 @@ export function createStateRoutes(ctx) {
                     return json({ error: 'this page is not taking more answers here' }, 409);
             }
             const r = op === 'set'
-                ? await ctx.state.set({ artifactId: id, slot, writer, value: b.value })
-                : await ctx.state.append({ artifactId: id, slot, writer, value: b.value });
+                ? await ctx.state.set({ artifactId: id, slot, writer, value })
+                : await ctx.state.append({ artifactId: id, slot, writer, value });
             if ('full' in r)
                 return json({ error: 'you have left the most answers this page takes here' }, 409);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.10.0",
+  "version": "0.11.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",