@supersuit/artifacts 0.1.0 → 0.3.0

package/lib/routes/artifacts.d.ts

@@ -1,12 +1,15 @@
 import type { Metadata } from 'next';
 import { NextRequest, NextResponse } from 'next/server';
 import type { ArtifactStore } from '../artifacts/store.js';
+import type { StateStore } from '../artifacts/state-store.js';
 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';
 export type ArtifactRoutesConfig = {
     store: ArtifactStore;
+    /** Where readers' answers live. Without it every state route answers 501. */
+    state?: StateStore;
     /** Where uploaded files go. Optional; without it PUT_ASSET answers 501. */
     assets?: ArtifactAssets;
     brand: BrandPack;
@@ -31,6 +34,10 @@ export type ArtifactRoutesConfig = {
     signInOrigin?: string;
     /** Who the banner says grants access, e.g. "Example Co". Default the brand name. */
     owner?: string;
+    /** The address the state routes' rate limit counts by. Default reads the first hop of
+     *  `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;
 };
 /** 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;
@@ -45,11 +52,29 @@ type PageProps = Params & {
     }>;
 };
 export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
+    dynamic: "force-dynamic";
+    maxDuration: number;
+    STATE_GET: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown> | undefined>;
+    STATE_POST: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown> | undefined>;
+    RESPONSES: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
     Page: ({ params, searchParams }: PageProps) => Promise<import("react").JSX.Element>;
     generateMetadata: ({ params }: Params) => Promise<Metadata>;
     POST: (request: NextRequest) => Promise<NextResponse<{
         error: string;
     }> | NextResponse<{
+        warning?: string | undefined;
         id: string;
         url: string;
         version: number;
@@ -109,7 +134,5 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         access: Access | null;
         views: number;
     }>>;
-    dynamic: "force-dynamic";
-    maxDuration: number;
 };
 export {};

package/lib/routes/artifacts.js

@@ -8,6 +8,7 @@ import { narrationText } from '../artifacts/narration.js';
 import { ArtifactMarkdown } from '../artifacts/render.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
+import { shapeChanges } from '../artifacts/state.js';
 import { ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
 import { BrandGround } from '../brand/wrapper.js';
 import { renderShareCard } from '../brand/share-card.js';
@@ -16,8 +17,10 @@ import { ReaderWatch } from '../reader/reader-watch.js';
 import { ACCESS_LEVELS, GRANT_COOKIE, GRANT_TTL_SECONDS, decide, firstName, mintGrant, safeReturnPath, signInUrl, verifyGrant, verifyPass, } from '../artifacts/reader.js';
 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';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
-export const ARTIFACT_ID = /^[abcdefghjkmnpqrstuvwxyz23456789]{8}$/;
+export const ARTIFACT_ID = ARTIFACT_ID_RE;
 async function defaultReadCookie(name) {
     const { cookies } = await import('next/headers');
     return (await cookies()).get(name)?.value;
@@ -34,6 +37,10 @@ export function createArtifactRoutes(config) {
     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,
+    });
     async function generateMetadata({ params }) {
         const { id } = await params;
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
@@ -78,9 +85,18 @@ export function createArtifactRoutes(config) {
         const open = isUnlocked({ id, password: a.password, key, cookie });
         // Opened by the key in the URL: remember it in a cookie holding the hash, never the
         // password, scoped to this page, so a refresh or a shared device does not ask again.
-        const remember = open && a.password && key !== undefined && cookie !== keyHash(id, a.password)
-            ? `document.cookie=${JSON.stringify(`${unlockCookieName(id)}=${keyHash(id, a.password)}; Path=${pagePath(id)}; Max-Age=31536000; SameSite=Lax; Secure`)}`
-            : null;
+        // 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
+        // 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}`] : []),
+        ];
+        const remember = paths.length ? paths.map((p) => `document.cookie=${JSON.stringify(unlockLine(p))}`).join(';') : null;
         if (!open) {
             return (_jsxs(BrandGround, { pack: brand, 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 })] }));
         }
@@ -97,7 +113,7 @@ export function createArtifactRoutes(config) {
             }
         }
         const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-        return (_jsxs(BrandGround, { pack: brand, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, _jsxs("div", { id: "artifact-narration-root", 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 }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), 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-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        return (_jsxs(BrandGround, { pack: brand, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, _jsxs("div", { id: "artifact-narration-root", 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 }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), 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-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
     }
     /** A page with `access:`. The body is rendered only after the reader is known and allowed;
      *  everyone else gets the title, the summary, and a door. */
@@ -136,7 +152,7 @@ export function createArtifactRoutes(config) {
             }
         }
         const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-        return (_jsxs(_Fragment, { children: [_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 }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), 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-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        return (_jsxs(_Fragment, { children: [_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 }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), 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-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in
@@ -281,11 +297,38 @@ export function createArtifactRoutes(config) {
         if (!parsed.ok)
             return NextResponse.json({ error: parsed.error }, { status: 400 });
         const id = request.nextUrl.searchParams.get('id') ?? parsed.meta.id ?? undefined;
+        if (id && parsed.meta.state) {
+            const existing = await store.get(id);
+            const changed = shapeChanges(existing?.state, parsed.meta.state);
+            if (changed.length)
+                return NextResponse.json({ error: changed.join('; ') }, { status: 400 });
+            // The declared shape can be dodged by republishing once with `state` omitted (which clears
+            // it) and then again with the slot's shape flipped: `existing.state` reads as undefined at
+            // that final publish, so the check above sees nothing to compare against. The ANSWERS
+            // never went anywhere, so the truth is in what is actually stored, not in the file.
+            if (config.state) {
+                const shapeOf = new Map();
+                for (const e of await config.state.entries(id))
+                    if (!shapeOf.has(e.slot))
+                        shapeOf.set(e.slot, e.shape);
+                const dodged = [];
+                for (const [name, def] of Object.entries(parsed.meta.state.slots)) {
+                    const was = shapeOf.get(name);
+                    if (was && was !== def.shape)
+                        dodged.push(`slot "${name}" changed shape from ${was} to ${def.shape}; rename the slot instead`);
+                }
+                if (dodged.length)
+                    return NextResponse.json({ error: dodged.join('; ') }, { status: 400 });
+            }
+        }
         const result = await store.save({ id, meta: parsed.meta, markdown: parsed.body });
         if ('notFound' in result)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         revalidatePath(pagePath(result.id));
-        return NextResponse.json({ id: result.id, url: pageUrl(result.id), version: result.version }, { status: result.created ? 201 : 200 });
+        return NextResponse.json({
+            id: result.id, url: pageUrl(result.id), version: result.version,
+            ...(parsed.meta.state && !config.state ? { warning: 'this host keeps no answers; state: is stored but inert' } : {}),
+        }, { status: result.created ? 201 : 200 });
     }
     async function GET(request, { params }) {
         if (!isPublishAuthed(request, config.publishKey()))
@@ -341,5 +384,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/lib/routes/ids.d.ts

@@ -0,0 +1 @@
+export declare const ARTIFACT_ID_RE: RegExp;

package/lib/routes/ids.js

@@ -0,0 +1,3 @@
+// Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store.
+// No 0/o, 1/l/i: an id read aloud or retyped from a screenshot must survive it.
+export const ARTIFACT_ID_RE = /^[abcdefghjkmnpqrstuvwxyz23456789]{8}$/;

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

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+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 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
+ *  hosts sharing a secret still count one visitor under unrelated ids. */
+export declare function rateKey(ip: string, siteUrl: string, secret?: string): string;
+export type StateRoutesContext = {
+    store: ArtifactStore;
+    state?: StateStore;
+    readers?: ReadersStore;
+    readerSecret: () => string | undefined;
+    publishKey: () => string | undefined;
+    pageUrl: (id: string) => string;
+    signInOrigin?: string;
+    siteUrl: string;
+    /** The address the rate limit counts by. Default reads the first hop of `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; a host behind one of those passes its own. */
+    clientIp?: (req: NextRequest) => string;
+};
+type Params = {
+    params: Promise<{
+        id: string;
+    }>;
+};
+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>>;
+};
+export {};

package/lib/routes/state-routes.js

@@ -0,0 +1,216 @@
+// 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? }
+//   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
+//
+// 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
+// signed-in reader, once, and the cookie is cleared.
+import { createHmac, randomBytes } from 'node:crypto';
+import { NextResponse } from 'next/server';
+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 { readerKeyFor } from '../artifacts/state-store.js';
+import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
+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 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
+ *  hosts sharing a secret still count one visitor under unrelated ids. */
+export function rateKey(ip, siteUrl, secret) {
+    return createHmac('sha256', secret || siteUrl).update(`${siteUrl}|${ip}`).digest('hex').slice(0, 16);
+}
+export function createStateRoutes(ctx) {
+    const anonCookie = (v, maxAge) => `${ANON_COOKIE}=${v}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
+    const json = (body, status = 200) => NextResponse.json(body, { status, headers: { 'cache-control': 'no-store' } });
+    const newAnonId = () => { let s = ''; while (s.length < 24)
+        s += randomBytes(24).toString('base64').replace(/[^A-Za-z0-9]/g, ''); return s.slice(0, 24); };
+    const defaultClientIp = (req) => (req.headers.get('x-forwarded-for') ?? '').split(',')[0].trim();
+    const ipHash = (req) => rateKey((ctx.clientIp ?? defaultClientIp)(req), ctx.siteUrl, ctx.readerSecret());
+    const siteOrigin = new URL(ctx.siteUrl).origin;
+    /** Resolve the page and who is asking, or the refusal. Shared by GET and POST. */
+    async function open(req, id) {
+        if (!ctx.state)
+            return { error: json({ error: 'this host keeps no answers' }, 501) };
+        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.state)
+            return { error: json({ error: 'this page takes no answers' }, 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 answer', 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) };
+            // The page shows its body only after the agreement, so its answers wait for it too.
+            if (!(await ctx.readers.acknowledged(id, reader.email)))
+                return { error: json({ error: 'accept the agreement first' }, 403) };
+        }
+        const rawAnon = req.cookies.get(ANON_COOKIE)?.value;
+        const anonId = rawAnon && ANON_ID.test(rawAnon) ? rawAnon : null;
+        return { a, reader, anonId, signIn };
+    }
+    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) : [];
+        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),
+        };
+    }
+    // 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
+    // cookie is SameSite=Lax, so a cross-site page can trigger it only by top-level navigation,
+    // which moves the reader's own answers onto the reader's own account and nothing else.
+    async function STATE_GET(req, { params }) {
+        const { id } = await params;
+        const o = await open(req, id);
+        if ('error' in o)
+            return o.error;
+        const { a, reader, anonId, signIn } = o;
+        let clearAnon = false;
+        if (reader && anonId) {
+            await ctx.state.moveReader(readerKeyFor.anonymous(anonId), writerFor(reader));
+            clearAnon = true;
+        }
+        const key = reader ? readerKeyFor.signedIn(reader.uid) : anonId ? readerKeyFor.anonymous(anonId) : null;
+        const res = json({ ...(await viewBody(a, reader, key)), ...(reader ? {} : { signIn }) });
+        if (clearAnon)
+            res.headers.append('set-cookie', anonCookie('', 0));
+        return res;
+    }
+    async function STATE_POST(req, { params }) {
+        const { id } = await params;
+        // A cross-site form or fetch carries the reader's cookies (anonymous or Lax grant on a
+        // top-level POST); a browser always names its Origin on a POST, so a foreign one is refused.
+        const origin = req.headers.get('origin');
+        if (origin !== null && origin !== siteOrigin)
+            return json({ error: 'wrong origin' }, 403);
+        // Refuse on the declared length before reading a byte: a client naming an oversize body
+        // does not get the server to buffer it first.
+        const declaredLength = Number(req.headers.get('content-length') ?? '');
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY)
+            return json({ error: 'request over 16 KB' }, 413);
+        const raw = await req.text();
+        // Measured in bytes, not JS string length: a string of multi-byte characters can sit under
+        // the code-unit count and over the byte cap the limit is actually about.
+        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, id);
+        if ('error' in o)
+            return o.error;
+        const { a, reader, signIn } = o;
+        let { anonId } = o;
+        const slot = typeof b.slot === 'string' ? b.slot : '';
+        // Object.hasOwn, never a bracket read: `slots['__proto__']` or `slots['constructor']`
+        // resolves through the prototype chain to a real (truthy) object that names no slot.
+        const def = Object.hasOwn(a.state.slots, slot) ? a.state.slots[slot] : undefined;
+        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' && def.shape !== 'one')
+            return json({ error: `slot ${slot} takes append` }, 400);
+        if (op === 'append' && def.shape !== 'many')
+            return json({ error: `slot ${slot} takes set` }, 400);
+        let setCookie = null;
+        let writer;
+        if (reader)
+            writer = writerFor(reader);
+        else {
+            if (effectiveWriters(a.state, a.access) !== '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.
+            if (op === 'remove') {
+                if (!anonId)
+                    return 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 });
+                return json(await viewBody(a, null, key));
+            }
+            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);
+            if (!anonId) {
+                anonId = newAnonId();
+                setCookie = anonCookie(anonId, 31536000);
+            }
+            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 });
+        }
+        else {
+            const bad = checkValue(b.value) ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null);
+            if (bad)
+                return json({ error: bad }, 400);
+            // 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) {
+                const replacing = op === 'set' && (ctx.state.hasOne
+                    ? await ctx.state.hasOne(id, slot, writer.key)
+                    : (await ctx.state.entries(id)).some((e) => e.slot === slot && e.readerKey === writer.key));
+                if (!replacing)
+                    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 });
+            if ('full' in r)
+                return json({ error: 'you have left the most answers this page takes here' }, 409);
+        }
+        const res = json(await viewBody(a, reader, writer.key));
+        if (setCookie)
+            res.headers.append('set-cookie', setCookie);
+        return res;
+    }
+    async function RESPONSES(req, { params }) {
+        if (!isPublishAuthed(req, ctx.publishKey()))
+            return json({ error: 'Unauthorized' }, 401);
+        if (!ctx.state)
+            return json({ error: 'this host keeps no answers' }, 501);
+        const { id } = await params;
+        const a = ARTIFACT_ID_RE.test(id) ? await ctx.store.get(id) : null;
+        if (!a)
+            return json({ error: `no artifact with id ${id}` }, 404);
+        if (req.method === 'DELETE') {
+            const key = req.nextUrl.searchParams.get('reader') ?? '';
+            if (!/^[ua]:[A-Za-z0-9_-]{1,128}$/.test(key))
+                return json({ error: 'reader must be a reader key like u:<uid> or a:<id>' }, 400);
+            return json({ removed: await ctx.state.removeReader(id, key) });
+        }
+        const rows = responsesOf(await ctx.state.entries(id));
+        if (req.nextUrl.searchParams.get('format') === 'csv')
+            return new NextResponse(responsesCsv(rows), { headers: { 'content-type': 'text/csv; charset=utf-8', 'cache-control': 'no-store' } });
+        return json({ id, title: a.title, responses: rows });
+    }
+    return { STATE_GET, STATE_POST, RESPONSES };
+}

package/lib/widgets/notes.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+export declare function NotesProvider({ artifactId, headings, accent, children }: {
+    artifactId: string;
+    headings: {
+        slug: string;
+        text: string;
+    }[];
+    accent?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The small control inside a heading. */
+export declare function NoteToggle({ slug }: {
+    slug: string;
+}): import("react").JSX.Element | null;
+/** After each heading: its notes, and the box when its control is open. */
+export declare function HeadingNotes({ slug, text }: {
+    slug: string;
+    text: string;
+}): import("react").JSX.Element | null;
+/** Where the ```notes fence sits: a line saying notes are on, and the notes whose heading is gone. */
+export declare function NotesEarlier(): import("react").JSX.Element | null;

package/lib/widgets/notes.js

@@ -0,0 +1,134 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// The notes widget in the reader's browser. One provider per page reads the page's state once
+// (GET /api/artifacts/<id>/state), places every note under the heading it was left under, and
+// sets aside the ones whose heading is gone. A small "note" control sits in each heading; the
+// panel after the heading lists its notes and, when open, takes a new one.
+//
+// Everything drawn here carries data-nospeak: narration reads the prose, never the notes, and
+// the read-along highlighter skips the same nodes. Notes are shown as text, never as markup.
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes } from '../artifacts/notes-place.js';
+const NotesContext = createContext(null);
+const isNote = (v) => !!v && typeof v === 'object' && typeof v.slug === 'string' &&
+    typeof v.heading === 'string' && typeof v.note === 'string';
+function notesFrom(body) {
+    const slot = body?.slots?.[NOTES_SLOT];
+    if (!slot)
+        return [];
+    const rows = Array.isArray(slot.shared) ? slot.shared : Array.isArray(slot.mine) ? slot.mine.map((e) => ({ ...e, mine: true })) : [];
+    const out = [];
+    for (const r of rows) {
+        if (!isNote(r.value))
+            continue;
+        out.push({
+            id: String(r.id ?? ''), slug: r.value.slug, heading: r.value.heading, note: r.value.note,
+            name: r.mine ? 'You' : typeof r.name === 'string' ? r.name : 'a reader', at: String(r.at ?? ''), mine: r.mine === true,
+        });
+    }
+    return out;
+}
+export function NotesProvider({ artifactId, headings, accent, children }) {
+    const endpoint = `/api/artifacts/${artifactId}/state`;
+    const [notes, setNotes] = useState([]);
+    const [off, setOff] = useState(false);
+    const [canWrite, setCanWrite] = useState(false);
+    const [signIn, setSignIn] = useState(null);
+    const [open, setOpen] = useState(null);
+    const [error, setError] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const apply = useCallback((status, body) => {
+        if (status === 200) {
+            setNotes(notesFrom(body));
+            setCanWrite(body.canWrite === true);
+            setSignIn(typeof body.signIn === 'string' ? body.signIn : null);
+            setError(null);
+            return true;
+        }
+        if (status === 401) {
+            setCanWrite(false);
+            setSignIn(typeof body.signIn === 'string' ? body.signIn : null);
+            return false;
+        }
+        // No state store, no such page, or no slot: the page takes no notes here, so draw nothing.
+        if (status === 404 || status === 501) {
+            setOff(true);
+            return false;
+        }
+        setError(typeof body.error === 'string' ? body.error : 'that did not save; try again');
+        return false;
+    }, []);
+    const call = useCallback(async (init) => {
+        try {
+            const r = await fetch(endpoint, { credentials: 'same-origin', cache: 'no-store', ...init });
+            const body = (await r.json().catch(() => ({})));
+            return apply(r.status, body);
+        }
+        catch {
+            setError('that did not reach the page; try again');
+            return false;
+        }
+    }, [endpoint, apply]);
+    useEffect(() => { void call(); }, [call]);
+    const post = useCallback(async (slug, heading, note) => {
+        setBusy(true);
+        const done = await call({
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ slot: NOTES_SLOT, op: 'append', value: { slug, heading, note } }),
+        });
+        setBusy(false);
+        if (done)
+            setOpen(null);
+        return done;
+    }, [call]);
+    const remove = useCallback(async (id) => {
+        await call({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ slot: NOTES_SLOT, op: 'remove', entry: id }) });
+    }, [call]);
+    const placed = useMemo(() => placeNotes(headings, notes), [headings, notes]);
+    const value = { off, accent: accent ?? 'currentColor', ...placed, canWrite, signIn, open, setOpen, error, busy, post, remove };
+    return _jsx(NotesContext.Provider, { value: value, children: children });
+}
+/** The small control inside a heading. */
+export function NoteToggle({ slug }) {
+    const c = useContext(NotesContext);
+    if (!c || c.off)
+        return null;
+    const n = c.bySlug[slug]?.length ?? 0;
+    return (_jsx("button", { type: "button", "data-nospeak": true, "data-note-toggle": slug, "aria-expanded": c.open === slug, onClick: () => c.setOpen(c.open === slug ? null : slug), className: "ml-3 inline-block rounded-full border px-2 py-0.5 align-middle font-sans text-[11px] font-medium uppercase tracking-[0.15em] opacity-70 transition-opacity hover:opacity-100", style: { borderColor: c.accent, color: c.accent }, children: n ? `note · ${n}` : 'note' }));
+}
+function NoteItem({ n, c, under }) {
+    return (_jsxs("li", { className: "m-0 border-l-2 py-1 pl-3", style: { borderColor: c.accent }, children: [_jsx("span", { className: "block whitespace-pre-wrap text-[15px] text-zinc-100", children: n.note }), _jsxs("span", { className: "block text-xs opacity-60", children: [n.name, under ? _jsxs(_Fragment, { children: [" \u00B7 under \u201C", n.heading, "\u201D"] }) : null, n.mine && n.id ? (_jsx("button", { type: "button", "data-note-remove": n.id, onClick: () => void c.remove(n.id), className: "ml-2 underline opacity-80 hover:opacity-100", children: "remove" })) : null] })] }));
+}
+function NoteForm({ slug, heading, c }) {
+    const [text, setText] = useState('');
+    const submit = async (e) => {
+        e.preventDefault();
+        const note = text.trim();
+        if (!note)
+            return;
+        if (await c.post(slug, heading, note))
+            setText('');
+    };
+    if (!c.canWrite) {
+        return c.signIn ? (_jsx("p", { className: "my-2 text-sm", children: _jsx("a", { href: c.signIn, className: "underline", style: { color: c.accent }, children: "Sign in to leave a note" }) })) : (_jsx("p", { className: "my-2 text-sm opacity-70", children: "Notes here are open to signed-in readers." }));
+    }
+    return (_jsxs("form", { onSubmit: submit, className: "my-2", children: [_jsx("textarea", { value: text, onChange: (e) => setText(e.target.value), maxLength: MAX_NOTE_CHARS, rows: 3, "aria-label": `A note on ${heading}`, placeholder: `A note on “${heading}”`, className: "w-full rounded-lg border border-white/15 bg-white/[0.04] p-3 text-[15px] text-zinc-100" }), c.error ? _jsx("p", { className: "mt-1 text-xs text-amber-500", children: c.error }) : null, _jsxs("div", { className: "mt-2 flex gap-3", children: [_jsx("button", { type: "submit", disabled: c.busy || !text.trim(), className: "rounded-full px-4 py-1 text-sm font-medium disabled:opacity-40", style: { background: c.accent, color: '#111' }, children: "Save note" }), _jsx("button", { type: "button", onClick: () => c.setOpen(null), className: "text-sm opacity-70 hover:opacity-100", children: "Cancel" })] })] }));
+}
+/** After each heading: its notes, and the box when its control is open. */
+export function HeadingNotes({ slug, text }) {
+    const c = useContext(NotesContext);
+    if (!c || c.off)
+        return null;
+    const list = c.bySlug[slug] ?? [];
+    const isOpen = c.open === slug;
+    if (!list.length && !isOpen)
+        return null;
+    return (_jsxs("div", { "data-nospeak": true, "data-heading-notes": slug, className: "my-3", children: [list.length ? _jsx("ul", { className: "m-0 grid list-none gap-2 p-0", children: list.map((n) => _jsx(NoteItem, { n: n, c: c }, n.id)) }) : null, isOpen ? _jsx(NoteForm, { slug: slug, heading: text, c: c }) : null] }));
+}
+/** Where the ```notes fence sits: a line saying notes are on, and the notes whose heading is gone. */
+export function NotesEarlier() {
+    const c = useContext(NotesContext);
+    if (!c || c.off)
+        return null;
+    return (_jsxs("section", { "data-nospeak": true, "data-artifact-notes": true, className: "my-8 text-sm", children: [_jsx("p", { className: "opacity-60", children: "Leave a note beside any heading." }), c.earlier.length ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mt-4 text-[11px] uppercase tracking-[0.2em]", style: { color: c.accent }, children: "Notes on earlier versions" }), _jsx("ul", { className: "m-0 mt-2 grid list-none gap-2 p-0", children: c.earlier.map((n) => _jsx(NoteItem, { n: n, c: c, under: true }, n.id)) })] })) : null] }));
+}