@supersuit/artifacts 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 `@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.2.0 (2026-09-24)
+
+**Reader answers.** A page can now take input from the people reading it. It declares named
+slots under `state:` in its front matter, and readers' answers are kept per reader, beside the
+pages, and handed back to the publisher. Nothing renders an answer UI yet: widgets (poll, form,
+checklist, notes) and HTML pages are the next releases, and they are the first callers.
+
+- `state:` in front matter: `writers` (`signed-in`, default, or `anyone`), `visibility`
+  (`private`, default, `tally` or `shared`), and `slots` of shape `one` (one value per reader,
+  replaced) or `many` (an append-only list per reader). A write to an undeclared slot is refused.
+- Routes: `GET`/`POST /api/artifacts/<id>/state` for the reader, `GET`/`DELETE
+  /api/artifacts/<id>/responses` for the publisher (publish key; JSON or `?format=csv`).
+- A reader never receives an email or another reader's key. Shared `one` entries carry an
+  opaque id. Tallies count signed-in and anonymous answers apart, because anyone can answer
+  again by clearing a cookie. The publisher's CSV escapes cells a spreadsheet would run.
+- Anonymous writers (on `writers: anyone` pages) get an HttpOnly `artifact_anon` cookie, limited
+  to 30 writes a minute per page per client; their answers move to them when they sign in, on
+  every page. A gated page (`access:`) always requires a signed-in reader the page is open to
+  who has accepted the agreement. A password page needs its unlock cookie, which is now also
+  set for the page's answer API.
+- Limits: 8 KB per value, 16 KB per request, 200 `many` entries per reader per slot, 2000
+  answers per slot per page, the newest 100 shared entries returned. Cross-origin posts refused.
+- Republishing keeps answers; changing a slot's shape is refused (against the previous file and
+  against stored answers). Adding and removing slots is allowed.
+- **DETECTOR:** a page with `state:` published to a host without a state store gets
+  `warning: this host keeps no answers` in the publish response, and its readers get 501.
+- **REMEDY (hosts):** pass `state: createStateStore(db, '<base>')` to `createArtifactRoutes`,
+  add `app/api/artifacts/[id]/state/route.ts` (GET, POST to `STATE_GET`/`STATE_POST`) and
+  `app/api/artifacts/[id]/responses/route.ts` (GET, DELETE to `RESPONSES`), set a Firestore TTL
+  policy on `expireAt` in `<base>StateRate`, and pass `clientIp` when not on Vercel. README,
+  "Reader answers".
+- **Known, fixed next release:** a reader who unlocked a password page before this version holds
+  only the page's cookie and must reopen the `?key=` link before answering there.
+- **Tests:** `state.test.ts`, `state-store.test.ts` (memory contract), `state-view.test.ts`,
+  `routes/state.test.tsx`, and the packed fixture's anonymous answer round trip (`npm run
+  test:packed`). The Firestore store has no emulator test; it is proven on a live host.
+
 ## 0.1.0 (2026-09-24)
 
 **The site shell behind Freedom's `artifacts.<name>` pages, published as a package.** It was a

package/README.md

@@ -179,6 +179,112 @@ reimplement it. Keep passes short-lived (five minutes is what the tests assume).
 Without `signInOrigin`, a confidential page shows its door with no way through. It fails
 closed, never open.
 
+## Reader answers (`state:`)
+
+A page can take answers from the people reading it: a vote, a reaction, a short response.
+Declare it in front matter:
+
+```yaml
+state:
+  writers: anyone       # or signed-in
+  visibility: tally      # private | tally | shared
+  slots:
+    vote:
+      shape: one          # one value per reader, overwritten by a later `set`
+    reactions:
+      shape: many         # a growing list per reader, built by `append`
+      visibility: shared   # per-slot override of the page default
+```
+
+Four routes, each requiring `state: createStateStore(db, '<base>')` in the config or they answer
+501:
+
+- `GET /api/artifacts/<id>/state`: the reader's own answers plus what the page's visibility lets
+  them see (a tally, or every shared answer).
+- `POST /api/artifacts/<id>/state`: `{ "slot": "vote", "op": "set" | "append" | "remove", "value": ..., "entry": "<id for remove>" }`.
+  `set` is for a `one` slot, `append` for a `many` slot; `remove` takes either.
+- `GET /api/artifacts/<id>/responses` (publish key): every answer with who wrote it, whatever the
+  page's `visibility` says, including each row's `reader` key. `?format=csv` returns the same rows
+  as CSV (a `reader` column after `anonymous`), with formula-injection escaping on any value
+  starting `=`, `+`, `-` or `@`.
+- `DELETE /api/artifacts/<id>/responses?reader=<key>` (publish key): erase one reader's answers,
+  by the `reader` key from the read above.
+
+**Limits**: a value is capped at 8 KB and a request body at 16 KB (Vercel caps bodies at 4.5 MB
+before this runs; on any other host, cap the body size at your proxy too). A `many` slot holds at
+most 200 entries per reader, and a slot holds at most 2,000 entries per page across every reader:
+past that a new answer is refused with 409, though a reader can still replace their own `one`
+answer. A `shared` slot shows readers only its newest 100 entries; tallies count everything. A
+`POST` whose `Origin` header names another site is refused with 403.
+
+**The anonymous rate limit**: 30 writes per minute per client address, counted in the
+`<base>StateRate` collection under an HMAC of the address (keyed by your reader secret when set).
+Each counter carries an `expireAt` a day ahead: set a Firestore TTL policy on `expireAt` for that
+collection, or the counters are kept forever. The address is the first hop of `x-forwarded-for`,
+so without one (plain `next start` with no proxy in front) every client shares one bucket: pass
+`clientIp` there. An IPv6 client can rotate addresses within its /64, so treat the limit as a
+brake, not a wall. A `remove` is never counted.
+
+**Who can write**: a page with `access:` only ever accepts its signed-in readers, whatever
+`writers:` says, and only after they have accepted the page's agreement (403 until then). A page
+with a password takes answers only from a browser that has unlocked it; opening the page with
+`?key=` sets the unlock cookie for the page and for its state API. `writers: anyone` only takes effect on a page with no `access:`: an anonymous
+writer gets an opaque id in an HttpOnly `artifact_anon` cookie, good for a year. A `shared` slot
+shows a reader everyone else's answer, but an anonymous one only ever by that same opaque id,
+never a name or email; a publisher's `/responses` read and the CSV always show everything.
+
+**Signing in after writing anonymously**: the next `GET /api/artifacts/<id>/state` from a reader
+who is now signed in moves that cookie's answers onto their account, once, and clears the cookie.
+
+**Republishing refuses only a shape change**: a slot going from `one` to `many` or back is
+refused, checked both against the previous `state:` in front matter and against the shapes already
+sitting in stored answers, so a republish can never misread history. Adding and removing slots is
+allowed and the answers are kept: a removed slot's answers stop showing to readers and still come
+back in `/responses`, and they reappear if the slot does. Drop `state:` entirely to close the page
+to new answers; existing ones stay. Publishing `state:` to a host with no state store succeeds,
+with a `warning` in the response saying the answers have nowhere to go.
+
+**Host wiring**:
+
+```ts
+export const artifacts = createArtifactRoutes({
+  store,
+  state: createStateStore(getFirestore(), 'artifacts'),
+  // ...the rest of your config
+})
+```
+
+```ts
+// app/api/artifacts/[id]/state/route.ts
+import type { NextRequest } from 'next/server'
+import { artifacts } from '@/lib/artifacts'
+type Ctx = { params: Promise<{ id: string }> }
+export function GET(request: NextRequest, ctx: Ctx) { return artifacts.STATE_GET(request, ctx) }
+export function POST(request: NextRequest, ctx: Ctx) { return artifacts.STATE_POST(request, ctx) }
+```
+
+```ts
+// app/api/artifacts/[id]/responses/route.ts
+import type { NextRequest } from 'next/server'
+import { artifacts } from '@/lib/artifacts'
+type Ctx = { params: Promise<{ id: string }> }
+export function GET(request: NextRequest, ctx: Ctx) { return artifacts.RESPONSES(request, ctx) }
+export function DELETE(request: NextRequest, ctx: Ctx) { return artifacts.RESPONSES(request, ctx) }
+```
+
+**Firestore indexes**: every `append` runs a count over `(artifactId, slot, readerKey)` on
+`<base>State` for `MAX_MANY_PER_READER`, and every new answer runs a count over
+`(artifactId, slot)` for the per-slot total. Firestore may serve both from its single-field
+indexes. If it asks for a composite index instead, the first failure surfaces as a 500 on a
+reader's write, with a create-index link in your host's logs; following it once is the whole step.
+The cross-page move that runs on sign-in queries by `readerKey` alone. Consider a single-field
+index exemption for the `json` field of `<base>State`: it holds whole answers as strings and is
+never queried, so indexing it only costs writes and storage.
+
+On a proxy other than Vercel's, pass `clientIp` to `createArtifactRoutes` (used for the anonymous
+rate limit): the default reads the first hop of `x-forwarded-for`, which Vercel overwrites with
+the real client IP but another proxy may only append to.
+
 ## 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

@@ -1,4 +1,5 @@
 import { type Access } from './reader.js';
+import { type StateConfig } from './state.js';
 export type ArtifactMeta = {
     title: string;
     summary: string;
@@ -23,6 +24,9 @@ export type ArtifactMeta = {
      *  ABSENT CHANGES NOTHING: the level is host-side state, so a republish that omits the line
      *  (or a publisher that strips unknown keys) can never reopen a confidential page. */
     access?: Access | 'public';
+    /** What readers may put into the page. Content, like the body: a republish without it removes
+     *  the slots from the page and KEEPS the answers already given. */
+    state?: StateConfig;
 };
 export declare function parseArtifactSource(text: string): {
     ok: true;

package/lib/artifacts/front-matter.js

@@ -2,7 +2,8 @@
 // Documented in README, "Front matter".
 import matter from 'gray-matter';
 import { ACCESS_LEVELS } from './reader.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access']);
+import { parseStateConfig } from './state.js';
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -33,5 +34,11 @@ export function parseArtifactSource(text) {
             return { ok: false, error: `access must be one of: public, ${ACCESS_LEVELS.join(', ')}` };
         meta.access = d.access;
     }
+    if (d.state !== undefined) {
+        const s = parseStateConfig(d.state);
+        if (!s.ok)
+            return { ok: false, error: s.error };
+        meta.state = s.state;
+    }
     return { ok: true, meta, body: content };
 }

package/lib/artifacts/index.d.ts

@@ -7,3 +7,6 @@ export { createArtifactAssets, contentTypeFor, ASSET_NAME, type ArtifactAssets }
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS, type Access, type Reader, type AllowEntry, type Decision } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc } from './readers-store.js';
+export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeChanges, SLOT_NAME, MAX_VALUE_BYTES, MAX_MANY_PER_READER, ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, SHARED_LIMIT, type StateConfig, type SlotDef, type Shape, type Visibility, type Writers } from './state.js';
+export { createStateStore, createMemoryStateStore, readerKeyFor, type StateStore, type StateEntry, type Writer } from './state-store.js';
+export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';

package/lib/artifacts/index.js

@@ -7,3 +7,6 @@ export { createArtifactAssets, contentTypeFor, ASSET_NAME } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';
+export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeChanges, SLOT_NAME, MAX_VALUE_BYTES, MAX_MANY_PER_READER, ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, SHARED_LIMIT } from './state.js';
+export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
+export { stateView, responsesOf, responsesCsv } from './state-view.js';

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

@@ -0,0 +1,59 @@
+import { type Firestore } from 'firebase-admin/firestore';
+import { type Shape } from './state.js';
+export type Writer = {
+    key: string;
+    uid?: string;
+    email?: string;
+    name: string | null;
+    anonymous: boolean;
+};
+export type StateEntry = {
+    id: string;
+    artifactId: string;
+    slot: string;
+    shape: Shape;
+    readerKey: string;
+    writer: Omit<Writer, 'key'>;
+    value: unknown;
+    at: string;
+};
+export interface StateStore {
+    entries(artifactId: string): Promise<StateEntry[]>;
+    set(input: {
+        artifactId: string;
+        slot: string;
+        writer: Writer;
+        value: unknown;
+    }): Promise<StateEntry>;
+    append(input: {
+        artifactId: string;
+        slot: string;
+        writer: Writer;
+        value: unknown;
+    }): Promise<StateEntry | {
+        full: true;
+    }>;
+    remove(input: {
+        artifactId: string;
+        slot: string;
+        readerKey: string;
+        entryId?: string;
+    }): Promise<number>;
+    removeReader(artifactId: string, readerKey: string): Promise<number>;
+    /** Moves every answer on every page from one reader key to another, not just the page the
+     *  reader signed in from: an anonymous reader who answered several pages before signing in
+     *  must not have the rest stranded under the cookie that is about to be cleared. */
+    moveReader(fromKey: string, to: Writer): Promise<number>;
+    /** Records one anonymous write and returns the count for that minute. The Firestore store
+     *  stamps each counter with `expireAt` a day ahead, for a TTL policy to sweep. */
+    countAnonWrite(artifactId: string, ipHash: string, minute: number): Promise<number>;
+    /** Every reader's entries in one slot on one page, for MAX_ENTRIES_PER_SLOT. */
+    countSlot(artifactId: string, slot: string): Promise<number>;
+}
+export declare const readerKeyFor: {
+    signedIn: (uid: string) => string;
+    anonymous: (id: string) => string;
+};
+export declare function createStateStore(db: Firestore, base: string): StateStore;
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export declare function createMemoryStateStore(): StateStore;

package/lib/artifacts/state-store.js

@@ -0,0 +1,151 @@
+// Where readers' answers live. Beside the pages, per tenant:
+//
+//   <base>State/<page>__<slot>__<readerKey>   shape one, one document per reader per slot
+//   <base>State/<auto>                        shape many, one document per entry
+//   <base>StateRate/<page>__<ipHash>__<min>   anonymous write counter, one per minute, with an
+//                                             `expireAt` a day ahead for a Firestore TTL policy
+//
+// One document per answer keeps every page far from Firestore's 1 MiB document cap, which the
+// lightpaper hit on 2026-09-24 when history lived on the page document. Values are stored as a
+// JSON STRING (`json`), because Firestore refuses nested arrays and a form answer can hold one.
+//
+// The Firestore implementation has no emulator test here; it is proven on the live host after
+// each release that changes it. The memory implementation carries the contract tests.
+import { randomUUID } from 'node:crypto';
+import { FieldValue, Timestamp } from 'firebase-admin/firestore';
+import { MAX_MANY_PER_READER } from './state.js';
+export const readerKeyFor = {
+    signedIn: (uid) => `u:${uid}`,
+    anonymous: (id) => `a:${id}`,
+};
+const writerOf = (w) => ({
+    ...(w.uid ? { uid: w.uid } : {}), ...(w.email ? { email: w.email } : {}), name: w.name, anonymous: w.anonymous,
+});
+const oneId = (artifactId, slot, readerKey) => `${artifactId}__${slot}__${readerKey}`;
+const toEntry = (id, d) => {
+    const { json, ...rest } = d;
+    return { id, ...rest, value: JSON.parse(json) };
+};
+const toStored = (e) => {
+    const { id: _id, value, ...rest } = e;
+    return { ...rest, json: JSON.stringify(value) };
+};
+export function createStateStore(db, base) {
+    const col = () => db.collection(`${base}State`);
+    const rate = () => db.collection(`${base}StateRate`);
+    const load = async (q) => (await q.get()).docs.map((d) => toEntry(d.id, d.data()));
+    const store = {
+        entries: (artifactId) => load(col().where('artifactId', '==', artifactId)),
+        async set({ artifactId, slot, writer, value }) {
+            const e = { id: oneId(artifactId, slot, writer.key), artifactId, slot, shape: 'one', readerKey: writer.key, writer: writerOf(writer), value, at: new Date().toISOString() };
+            await col().doc(e.id).set(toStored(e));
+            return e;
+        },
+        async append({ artifactId, slot, writer, value }) {
+            const n = (await col().where('artifactId', '==', artifactId).where('slot', '==', slot).where('readerKey', '==', writer.key).count().get()).data().count;
+            if (n >= MAX_MANY_PER_READER)
+                return { full: true };
+            const ref = col().doc();
+            const e = { id: ref.id, artifactId, slot, shape: 'many', readerKey: writer.key, writer: writerOf(writer), value, at: new Date().toISOString() };
+            await ref.set(toStored(e));
+            return e;
+        },
+        async remove({ artifactId, slot, readerKey, entryId }) {
+            const mine = (await load(col().where('artifactId', '==', artifactId).where('readerKey', '==', readerKey)))
+                .filter((e) => e.slot === slot && (!entryId || e.id === entryId));
+            await Promise.all(mine.map((e) => col().doc(e.id).delete()));
+            return mine.length;
+        },
+        async removeReader(artifactId, readerKey) {
+            const mine = await load(col().where('artifactId', '==', artifactId).where('readerKey', '==', readerKey));
+            await Promise.all(mine.map((e) => col().doc(e.id).delete()));
+            return mine.length;
+        },
+        async moveReader(fromKey, to) {
+            const from = await load(col().where('readerKey', '==', fromKey));
+            let moved = 0;
+            for (const e of from) {
+                if (e.shape === 'one') {
+                    const target = col().doc(oneId(e.artifactId, e.slot, to.key));
+                    // The signed-in answer wins over one given anonymously on this device.
+                    if (!(await target.get()).exists) {
+                        await target.set(toStored({ ...e, id: target.id, readerKey: to.key, writer: writerOf(to) }));
+                        moved++;
+                    }
+                    await col().doc(e.id).delete();
+                }
+                else {
+                    await col().doc(e.id).update({ readerKey: to.key, writer: writerOf(to) });
+                    moved++;
+                }
+            }
+            return moved;
+        },
+        async countAnonWrite(artifactId, ipHash, minute) {
+            const ref = rate().doc(`${artifactId}__${ipHash}__${minute}`);
+            await ref.set({ count: FieldValue.increment(1), at: new Date().toISOString(), expireAt: Timestamp.fromMillis(Date.now() + 86_400_000) }, { merge: true });
+            return (await ref.get()).data()?.count ?? 1;
+        },
+        async countSlot(artifactId, slot) {
+            return (await col().where('artifactId', '==', artifactId).where('slot', '==', slot).count().get()).data().count;
+        },
+    };
+    return store;
+}
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export function createMemoryStateStore() {
+    const docs = new Map();
+    const counts = new Map();
+    const of = (artifactId, readerKey) => [...docs.values()].filter((e) => e.artifactId === artifactId && (!readerKey || e.readerKey === readerKey));
+    return {
+        entries: async (artifactId) => of(artifactId).map((e) => structuredClone(e)),
+        async set({ artifactId, slot, writer, value }) {
+            const e = { id: oneId(artifactId, slot, writer.key), artifactId, slot, shape: 'one', readerKey: writer.key, writer: writerOf(writer), value: structuredClone(value), at: new Date().toISOString() };
+            docs.set(e.id, e);
+            return structuredClone(e);
+        },
+        async append({ artifactId, slot, writer, value }) {
+            if (of(artifactId, writer.key).filter((e) => e.slot === slot).length >= MAX_MANY_PER_READER)
+                return { full: true };
+            const e = { id: randomUUID(), artifactId, slot, shape: 'many', readerKey: writer.key, writer: writerOf(writer), value: structuredClone(value), at: new Date().toISOString() };
+            docs.set(e.id, e);
+            return structuredClone(e);
+        },
+        async remove({ artifactId, slot, readerKey, entryId }) {
+            const mine = of(artifactId, readerKey).filter((e) => e.slot === slot && (!entryId || e.id === entryId));
+            for (const e of mine)
+                docs.delete(e.id);
+            return mine.length;
+        },
+        async removeReader(artifactId, readerKey) {
+            const mine = of(artifactId, readerKey);
+            for (const e of mine)
+                docs.delete(e.id);
+            return mine.length;
+        },
+        async moveReader(fromKey, to) {
+            let moved = 0;
+            for (const e of [...docs.values()].filter((e) => e.readerKey === fromKey)) {
+                docs.delete(e.id);
+                if (e.shape === 'one') {
+                    const id = oneId(e.artifactId, e.slot, to.key);
+                    if (docs.has(id))
+                        continue;
+                    docs.set(id, { ...e, id, readerKey: to.key, writer: writerOf(to) });
+                }
+                else {
+                    docs.set(e.id, { ...e, readerKey: to.key, writer: writerOf(to) });
+                }
+                moved++;
+            }
+            return moved;
+        },
+        async countAnonWrite(artifactId, ipHash, minute) {
+            const k = `${artifactId}__${ipHash}__${minute}`;
+            const n = (counts.get(k) ?? 0) + 1;
+            counts.set(k, n);
+            return n;
+        },
+        countSlot: async (artifactId, slot) => of(artifactId).filter((e) => e.slot === slot).length,
+    };
+}

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

@@ -0,0 +1,38 @@
+import { type Shape, type StateConfig, type Visibility } from './state.js';
+import type { StateEntry } from './state-store.js';
+export type Tally = {
+    signedIn: Record<string, number>;
+    anonymous: Record<string, number>;
+};
+export type SharedEntry = {
+    id: string;
+    name: string;
+    value: unknown;
+    at: string;
+    mine: boolean;
+};
+export type SlotView = {
+    shape: Shape;
+    visibility: Visibility;
+    mine: unknown | {
+        id: string;
+        value: unknown;
+        at: string;
+    }[] | null;
+    tally?: Tally;
+    shared?: SharedEntry[];
+};
+export declare function stateView(state: StateConfig, entries: StateEntry[], readerKey: string | null): Record<string, SlotView>;
+/** `reader` is the key `DELETE /responses?reader=` takes. Publisher-only: it is a credential. */
+export type Response = {
+    slot: string;
+    id: string;
+    value: unknown;
+    at: string;
+    email: string | null;
+    name: string | null;
+    anonymous: boolean;
+    reader: string;
+};
+export declare function responsesOf(entries: StateEntry[]): Response[];
+export declare function responsesCsv(rows: Response[]): string;

package/lib/artifacts/state-view.js

@@ -0,0 +1,66 @@
+// What each side is shown. A reader gets their own answers, plus tallies or shared entries where
+// the page allows, and NEVER an email. The publisher (publish key) gets everything.
+import { createHash } from 'node:crypto';
+import { SHARED_LIMIT, slotVisibility } from './state.js';
+const byAt = (a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id);
+const firstWord = (name) => (name?.trim() ? name.trim().split(/\s+/)[0] : 'a reader');
+// A `one` entry's raw id is `<page>__<slot>__<readerKey>`, and the reader key inside it (`u:<uid>`
+// or `a:<anonId>`) is a credential: whoever reads it can write as that reader by minting the same
+// anonymous cookie. A `shared` slot handed that id straight to every reader, so it is hashed to
+// an opaque, stable value instead. `many` entries keep their random id; it names nothing.
+const opaqueOneId = (id) => createHash('sha256').update(id).digest('hex').slice(0, 16);
+/** Counts per option. A list value (multiple choice) counts each item; objects are not tallied.
+ *  Anonymous answers are counted apart, because anyone can answer again by clearing a cookie. */
+function tallyOf(entries) {
+    const t = { signedIn: {}, anonymous: {} };
+    for (const e of entries) {
+        const bucket = e.writer.anonymous ? t.anonymous : t.signedIn;
+        const items = Array.isArray(e.value) ? e.value : [e.value];
+        for (const v of items) {
+            if (v === null || typeof v === 'object')
+                continue;
+            const k = String(v);
+            bucket[k] = (bucket[k] ?? 0) + 1;
+        }
+    }
+    return t;
+}
+export function stateView(state, entries, readerKey) {
+    const out = {};
+    for (const [slot, def] of Object.entries(state.slots)) {
+        const here = entries.filter((e) => e.slot === slot).sort(byAt);
+        const mine = readerKey ? here.filter((e) => e.readerKey === readerKey) : [];
+        const visibility = slotVisibility(state, slot);
+        const view = {
+            shape: def.shape,
+            visibility,
+            mine: def.shape === 'one' ? (mine[0]?.value ?? null) : mine.map((e) => ({ id: e.id, value: e.value, at: e.at })),
+        };
+        if (visibility === 'tally')
+            view.tally = tallyOf(here);
+        if (visibility === 'shared')
+            view.shared = here.slice(-SHARED_LIMIT).map((e) => ({
+                id: def.shape === 'one' ? opaqueOneId(e.id) : e.id,
+                name: firstWord(e.writer.name), value: e.value, at: e.at, mine: e.readerKey === readerKey,
+            }));
+        out[slot] = view;
+    }
+    return out;
+}
+export function responsesOf(entries) {
+    return entries.slice().sort(byAt).map((e) => ({
+        slot: e.slot, id: e.id, value: e.value, at: e.at, email: e.writer.email ?? null, name: e.writer.name, anonymous: e.writer.anonymous, reader: e.readerKey,
+    }));
+}
+// A cell a spreadsheet reads as a formula (leading =, +, -, @, tab or CR) gets an escaping
+// leading quote first: a reader's answer becomes text a formula, not a command a publisher's
+// spreadsheet app runs the moment the CSV is opened.
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+const cell = (v) => {
+    const safe = FORMULA_LEAD.test(v) ? `'${v}` : v;
+    return /[",\n]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+};
+export function responsesCsv(rows) {
+    const head = 'slot,id,at,email,name,anonymous,reader,value';
+    return [head, ...rows.map((r) => [r.slot, r.id, r.at, r.email ?? '', r.name ?? '', String(r.anonymous), r.reader, JSON.stringify(r.value)].map(cell).join(','))].join('\n');
+}

package/lib/artifacts/state.d.ts

@@ -0,0 +1,35 @@
+export type Shape = 'one' | 'many';
+export type Visibility = 'private' | 'tally' | 'shared';
+export type Writers = 'signed-in' | 'anyone';
+export type SlotDef = {
+    shape: Shape;
+    visibility?: Visibility;
+};
+export type StateConfig = {
+    writers: Writers;
+    visibility: Visibility;
+    slots: Record<string, SlotDef>;
+};
+export declare const SLOT_NAME: RegExp;
+export declare const MAX_VALUE_BYTES: number;
+export declare const MAX_MANY_PER_READER = 200;
+export declare const ANON_WRITES_PER_MINUTE = 30;
+/** Every reader's answers together, per page per slot. A new answer past it is refused; a reader
+ *  replacing their own `one` answer is not, because that adds nothing. */
+export declare const MAX_ENTRIES_PER_SLOT = 2000;
+/** A `shared` slot shows readers only its newest entries, so one busy page cannot make every read
+ *  ship its whole history. Tallies still count everything. */
+export declare const SHARED_LIMIT = 100;
+export declare function parseStateConfig(raw: unknown): {
+    ok: true;
+    state: StateConfig;
+} | {
+    ok: false;
+    error: string;
+};
+/** A gated page's readers are always signed in, so its state is too, whatever the file says. */
+export declare function effectiveWriters(state: StateConfig, access?: string): Writers;
+export declare function slotVisibility(state: StateConfig, slot: string): Visibility;
+export declare function checkValue(value: unknown): string | null;
+/** Answers are kept across a republish, so a slot may never change what shape its data is. */
+export declare function shapeChanges(prev: StateConfig | undefined, next: StateConfig | undefined): string[];

package/lib/artifacts/state.js

@@ -0,0 +1,83 @@
+export const SLOT_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+export const MAX_VALUE_BYTES = 8 * 1024;
+export const MAX_MANY_PER_READER = 200;
+export const ANON_WRITES_PER_MINUTE = 30;
+/** Every reader's answers together, per page per slot. A new answer past it is refused; a reader
+ *  replacing their own `one` answer is not, because that adds nothing. */
+export const MAX_ENTRIES_PER_SLOT = 2000;
+/** A `shared` slot shows readers only its newest entries, so one busy page cannot make every read
+ *  ship its whole history. Tallies still count everything. */
+export const SHARED_LIMIT = 100;
+const VISIBILITIES = ['private', 'tally', 'shared'];
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export function parseStateConfig(raw) {
+    if (!isMap(raw))
+        return { ok: false, error: 'state must be a map' };
+    for (const k of Object.keys(raw))
+        if (!['writers', 'visibility', 'slots'].includes(k))
+            return { ok: false, error: `state has an unknown key: ${k}` };
+    const writers = raw.writers ?? 'signed-in';
+    if (writers !== 'signed-in' && writers !== 'anyone')
+        return { ok: false, error: 'state.writers must be signed-in or anyone' };
+    const visibility = raw.visibility ?? 'private';
+    if (!VISIBILITIES.includes(visibility))
+        return { ok: false, error: `state.visibility must be one of: ${VISIBILITIES.join(', ')}` };
+    const slots = {};
+    const rawSlots = raw.slots ?? {};
+    if (!isMap(rawSlots))
+        return { ok: false, error: 'state.slots must be a map' };
+    for (const [name, def] of Object.entries(rawSlots)) {
+        if (!SLOT_NAME.test(name))
+            return { ok: false, error: `slot name "${name}" must be lowercase letters, digits and dashes, starting with a letter` };
+        if (!isMap(def))
+            return { ok: false, error: `slot "${name}" needs shape one or many` };
+        for (const k of Object.keys(def))
+            if (k !== 'shape' && k !== 'visibility')
+                return { ok: false, error: `slot "${name}" has an unknown key: ${k}` };
+        if (def.shape !== 'one' && def.shape !== 'many')
+            return { ok: false, error: `slot "${name}" needs shape one or many` };
+        if (def.visibility !== undefined && !VISIBILITIES.includes(def.visibility))
+            return { ok: false, error: `slot "${name}" visibility must be one of: ${VISIBILITIES.join(', ')}` };
+        slots[name] = { shape: def.shape, ...(def.visibility ? { visibility: def.visibility } : {}) };
+    }
+    return { ok: true, state: { writers, visibility: visibility, slots } };
+}
+/** A gated page's readers are always signed in, so its state is too, whatever the file says. */
+export function effectiveWriters(state, access) {
+    return access ? 'signed-in' : state.writers;
+}
+export function slotVisibility(state, slot) {
+    return state.slots[slot]?.visibility ?? state.visibility;
+}
+function isJson(v) {
+    if (v === null || typeof v === 'string' || typeof v === 'boolean')
+        return true;
+    if (typeof v === 'number')
+        return Number.isFinite(v);
+    if (Array.isArray(v))
+        return v.every(isJson);
+    if (isMap(v))
+        return Object.values(v).every(isJson);
+    return false;
+}
+export function checkValue(value) {
+    if (value === undefined)
+        return 'value is required';
+    if (!isJson(value))
+        return 'value must be JSON';
+    if (Buffer.byteLength(JSON.stringify(value), 'utf8') > MAX_VALUE_BYTES)
+        return 'value is over 8 KB';
+    return null;
+}
+/** Answers are kept across a republish, so a slot may never change what shape its data is. */
+export function shapeChanges(prev, next) {
+    if (!prev || !next)
+        return [];
+    const out = [];
+    for (const [name, def] of Object.entries(next.slots)) {
+        const was = prev.slots[name];
+        if (was && was.shape !== def.shape)
+            out.push(`slot "${name}" changed shape from ${was.shape} to ${def.shape}; rename the slot instead`);
+    }
+    return out;
+}

package/lib/artifacts/store.d.ts

@@ -1,6 +1,7 @@
 import { type Firestore } from 'firebase-admin/firestore';
 import type { ArtifactMeta } from './front-matter.js';
 import type { Access } from './reader.js';
+import type { StateConfig } from './state.js';
 export type ArtifactRecord = {
     id: string;
     title: string;
@@ -15,6 +16,7 @@ export type ArtifactRecord = {
     narrationHash?: string;
     password?: string;
     access?: Access;
+    state?: StateConfig;
     markdown: string;
     createdAt: string;
     updatedAt: string;

package/lib/artifacts/store.js

@@ -56,6 +56,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.narrationHash ? { narrationHash: input.meta.narrationHash } : {}),
         ...(input.meta.password ? { password: input.meta.password } : {}),
         ...(input.meta.access && input.meta.access !== 'public' ? { access: input.meta.access } : {}),
+        ...(input.meta.state ? { state: input.meta.state } : {}),
     };
     if (input.id) {
         const existing = await getArtifact(col, input.id);
@@ -79,8 +80,10 @@ async function saveArtifact(col, input) {
         // 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() } : {};
+        // Content, like the body: a republish that no longer declares state removes the slots.
+        const state = input.meta.state ? {} : { state: FieldValue.delete() };
         await ref.update({
-            ...fields, ...password, ...subtitle, ...access, markdown: input.markdown, updatedAt: now, version: next,
+            ...fields, ...password, ...subtitle, ...access, ...state, markdown: input.markdown, updatedAt: now, version: next,
             ...(existing.versions ? { versions: FieldValue.delete() } : {}),
         });
         return { id: input.id, version: next, created: false };

package/lib/index.d.ts

@@ -2,3 +2,4 @@ export * from './artifacts/index.js';
 export * from './brand/index.js';
 export * from './gate.js';
 export { createArtifactRoutes, type ArtifactRoutesConfig } from './routes/artifacts.js';
+export { ANON_COOKIE } from './routes/state-routes.js';

package/lib/index.js

@@ -2,3 +2,4 @@ export * from './artifacts/index.js';
 export * from './brand/index.js';
 export * from './gate.js';
 export { createArtifactRoutes } from './routes/artifacts.js';
+export { ANON_COOKIE } from './routes/state-routes.js';

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,8 +85,11 @@ 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.
+        // 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`;
         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`)}`
+            ? [pagePath(id), `/api/artifacts/${id}`].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 })] }));
@@ -281,11 +291,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 +378,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,213 @@
+// 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 { 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);
+            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' && (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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -10,16 +10,41 @@
   },
   "homepage": "https://github.com/SupersuitUp/artifacts#readme",
   "bugs": "https://github.com/SupersuitUp/artifacts/issues",
-  "keywords": ["nextjs", "markdown", "publishing", "firestore", "read-aloud", "og-image"],
+  "keywords": [
+    "nextjs",
+    "markdown",
+    "publishing",
+    "firestore",
+    "read-aloud",
+    "og-image"
+  ],
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {
-    ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
-    "./artifacts": { "types": "./lib/artifacts/index.d.ts", "default": "./lib/artifacts/index.js" },
-    "./routes": { "types": "./lib/routes/artifacts.d.ts", "default": "./lib/routes/artifacts.js" },
-    "./brand": { "types": "./lib/brand/index.d.ts", "default": "./lib/brand/index.js" },
-    "./reader": { "types": "./lib/reader/artifact-reader.d.ts", "default": "./lib/reader/artifact-reader.js" },
-    "./gate": { "types": "./lib/gate.d.ts", "default": "./lib/gate.js" },
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./artifacts": {
+      "types": "./lib/artifacts/index.d.ts",
+      "default": "./lib/artifacts/index.js"
+    },
+    "./routes": {
+      "types": "./lib/routes/artifacts.d.ts",
+      "default": "./lib/routes/artifacts.js"
+    },
+    "./brand": {
+      "types": "./lib/brand/index.d.ts",
+      "default": "./lib/brand/index.js"
+    },
+    "./reader": {
+      "types": "./lib/reader/artifact-reader.d.ts",
+      "default": "./lib/reader/artifact-reader.js"
+    },
+    "./gate": {
+      "types": "./lib/gate.d.ts",
+      "default": "./lib/gate.js"
+    },
     "./fonts/*": "./fonts/*",
     "./package.json": "./package.json"
   },
@@ -46,7 +71,9 @@
     "react-dom": ">=19"
   },
   "peerDependenciesMeta": {
-    "@google-cloud/storage": { "optional": true }
+    "@google-cloud/storage": {
+      "optional": true
+    }
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
@@ -70,5 +97,7 @@
     "typescript": "~5.9.0",
     "vitest": "^4.0.18"
   },
-  "engines": { "node": ">=20" }
+  "engines": {
+    "node": ">=20"
+  }
 }