@supersuit/artifacts 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,82 @@
 `@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.3.0 (2026-09-25)
+
+**Notes, the first widget.** A ```` ```notes ```` block in a page puts a small "note" control
+beside every heading, so readers can leave notes on a section and, on a `shared` page, read each
+other's. Poll, form and checklist follow in a later release.
+
+- **Fence:** ```` ```notes ```` with an optional `visibility: private | shared` line. At most one
+  per page. It declares slot `notes` of shape `many` itself, merged into `state:` at parse time
+  (a page with no `state:` gets `writers: signed-in`, `visibility: private`), so the 0.2.0 state
+  API takes notes unchanged. Refused at publish with the file's line number: a second block, a
+  name, an unknown key, `tally`, a `notes` slot declared `one`, a visibility that disagrees with
+  `state:`. `poll`, `form` and `checklist` fences are refused until they ship.
+- **A note is `{ slug, heading, note }`**, checked by the server on a page with a notes block.
+  Headings carry their GitHub-style slug as an `id`; the renderer finds each heading by its source
+  line, so the slug on the page and the slug a note stores come from one derivation.
+- **A renamed or removed heading keeps its notes**, shown under "Notes on earlier versions" with
+  the heading they were left under, never attached to another section.
+- **Narration skips the widget**: the fence is not spoken and everything drawn is `data-nospeak`.
+- **Password pages with `state:`** now set the answer API's unlock cookie on every open, not only
+  on `?key=`. Readers who unlocked such a page before 0.2.0 are no longer refused (the item parked
+  in 0.2.0).
+- **The replace-at-cap check** reads one document (`StateStore.hasOne`, optional, implemented by
+  both shipped stores) instead of every answer on the page.
+- **DETECTOR:** a page with a notes block published to a host with no state store gets `warning:
+  this host keeps no answers` and draws no controls. A notes page whose readers see no "note"
+  button beside its headings is on 0.2.0 or earlier.
+- **REMEDY (hosts):** take 0.3.0. No new routes: the notes widget uses the 0.2.0 state routes
+  (`app/api/artifacts/[id]/state/route.ts`), which a host must already mount. A host with its own
+  `StateStore` may add `hasOne`; without it the old full read is used.
+- **Tests:** `widgets.test.ts` (slugs, fence parsing, one per page, reserved widgets, merge,
+  note shape, placement), `front-matter.test.ts` (line numbers in the file, the first real page's
+  front matter), `render.test.tsx` (controls beside headings, fence never drawn as code),
+  `widgets/notes.test.tsx` (jsdom: shared notes under their heading, earlier versions, posting
+  appends `{ slug, heading, note }`, sign-in offer, removal, no-store host), `narration.test.ts`,
+  `state.test.tsx` (note shape refused, shared read, `hasOne` path), `artifacts.test.tsx` (API
+  cookie on every open, page wiring, publish refusal), `state-store.test.ts` (`hasOne`), and the
+  packed fixture (a notes page draws its controls, a note posts and reads back, a malformed one is
+  refused, the compiled widget keeps `'use client'`).
+
+## 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

@@ -25,7 +25,8 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `createArtifactAssets(bucket, prefix)` | Uploaded images for a page, in a Cloud Storage bucket |
 | `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
 | `BrandGround`, `BrandMark` | The pack's page backdrop and mark, for your own pages (a home, a 404) |
-| `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing |
+| `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing (widget fences included) |
+| `headingsOf`, `scanWidgets`, `placeNotes` | The notes widget's pure parts: heading slugs, fence validation, where each note shows |
 | `mintPass`, `verifyPass` | The reader pass, for the sign-in side (see below) |
 | `ARTIFACT_PUBLIC_PREFIXES` (`/gate`) | Paths to leave open if you mount artifacts inside a gated site |
 
@@ -179,6 +180,161 @@ 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.
+
+## Widgets in a page
+
+A widget is a fenced block in a page's markdown that gives readers a place to answer, drawn by
+the shell in the page's brand and kept through the state API above. Widgets need a host with a
+state store (`state:` in the config); on a host without one they draw nothing, and the publish
+response carries the no-answers warning.
+
+This version draws one widget, **notes**. Poll, form and checklist are coming: a fence named
+`poll`, `form` or `checklist` is refused at publish until then, so a page never ships a code
+block that turns into a live widget on a later update.
+
+### Notes
+
+````markdown
+## Sales
+
+The weekly pipeline review.
+
+```notes
+visibility: shared   # optional: private | shared
+```
+````
+
+- **A small "note" control sits beside every heading.** A reader opens it, writes, and saves. The
+  note appears under that heading; with `visibility: shared` every reader sees every note with
+  the writer's first name ("a reader" for a signed-out one), with `private` each reader sees only
+  their own and the publisher sees all through `/responses`.
+- **At most one notes block per page.** Where it sits is where the page shows "Notes on earlier
+  versions" (below).
+- **The block declares its own slot**: `notes`, shape `many`. A page needs no `state:` for it;
+  without one the page takes `writers: signed-in` and `visibility: private`. A page may declare
+  the slot itself (`slots: { notes: { shape: many } }`) and set `writers:` and `visibility:` as
+  usual. Refused at publish, naming the line in the file: a second notes block, a name after
+  `notes`, any key but `visibility`, `visibility: tally`, a `notes` slot declared `shape: one`,
+  and a block visibility that disagrees with one `state:` sets on the `notes` slot.
+- **A note is `{ slug, heading, note }`**: the slug and the text of the heading it was left under,
+  and up to 4,000 characters of text. On a page with a notes block the server refuses any other
+  shape in the `notes` slot. Slugs follow GitHub's rule (lowercase, punctuation dropped, spaces
+  to dashes, a repeated heading `-1`, `-2`), and each heading carries its slug as its `id`, so
+  `#sales` links to it.
+- **Notes survive a changed heading.** A note shows under the heading with its slug; failing
+  that, under a heading with exactly its text; otherwise under "Notes on earlier versions", with
+  the heading it was left under. It never attaches to a different section.
+- **Narration skips it.** The fence is not prose, and everything the widget draws is marked
+  `data-nospeak`, so the narrator and the read-along highlighter read the page as before.
+- On a gated page (`access:`) only signed-in readers the page is open to, after the agreement,
+  can leave or read notes; the banner, watermark and print refusal are unchanged. On a public
+  page with `writers: signed-in`, the control offers sign-in through `signInOrigin`.
+
 ## 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,9 @@
 // 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';
+import { mergeWidgetState, scanWidgets } from './widgets.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 +35,23 @@ 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;
+    }
+    // Widgets declare their own slots, so a notes block is merged into state: here, before the
+    // page is stored, and the state API and the republish shape checks see it like any slot.
+    // Errors name the line in the FILE: the body's lines are counted after the front matter's.
+    const offset = text.endsWith(content) ? (text.slice(0, text.length - content.length).match(/\n/g) ?? []).length : 0;
+    const w = scanWidgets(content, offset);
+    if (!w.ok)
+        return { ok: false, error: w.error };
+    const merged = mergeWidgetState(meta.state, w.notes);
+    if (!merged.ok)
+        return { ok: false, error: merged.error };
+    if (merged.state)
+        meta.state = merged.state;
     return { ok: true, meta, body: content };
 }

package/lib/artifacts/index.d.ts

@@ -7,3 +7,7 @@ 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';
+export { slugify, headingsOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';

package/lib/artifacts/index.js

@@ -7,3 +7,7 @@ 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';
+export { slugify, headingsOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';

package/lib/artifacts/notes-place.d.ts

@@ -0,0 +1,27 @@
+export declare const NOTES_SLOT = "notes";
+export declare const MAX_NOTE_CHARS = 4000;
+export type Heading = {
+    depth: number;
+    line: number;
+    text: string;
+    slug: string;
+};
+export type NoteValue = {
+    slug: string;
+    heading: string;
+    note: string;
+};
+/** A note as a reader's page holds it: the stored value plus who and when. */
+export type PlacedNote = NoteValue & {
+    id: string;
+    name: string;
+    at: string;
+    mine: boolean;
+};
+/** Where each note shows: under the heading with its slug, else under a heading with its exact
+ *  text (a repeated heading renumbered), else under "notes on earlier versions". Never under a
+ *  heading that merely looks close: a note on the wrong section is worse than one set aside. */
+export declare function placeNotes(headings: Pick<Heading, 'slug' | 'text'>[], notes: PlacedNote[]): {
+    bySlug: Record<string, PlacedNote[]>;
+    earlier: PlacedNote[];
+};

package/lib/artifacts/notes-place.js

@@ -0,0 +1,25 @@
+// Where each note on a page shows, and the few names both sides share. Kept free of the
+// markdown parser on purpose: the notes widget runs in the reader's browser and imports this,
+// and the parser has no business in that bundle.
+export const NOTES_SLOT = 'notes';
+export const MAX_NOTE_CHARS = 4000;
+/** Where each note shows: under the heading with its slug, else under a heading with its exact
+ *  text (a repeated heading renumbered), else under "notes on earlier versions". Never under a
+ *  heading that merely looks close: a note on the wrong section is worse than one set aside. */
+export function placeNotes(headings, notes) {
+    const bySlug = {};
+    const earlier = [];
+    const slugs = new Set(headings.map((h) => h.slug));
+    const byText = new Map();
+    for (const h of headings)
+        if (!byText.has(h.text))
+            byText.set(h.text, h.slug);
+    for (const n of notes) {
+        const at = slugs.has(n.slug) ? n.slug : byText.get(n.heading);
+        if (at)
+            (bySlug[at] ??= []).push(n);
+        else
+            earlier.push(n);
+    }
+    return { bySlug, earlier };
+}

package/lib/artifacts/render.d.ts

@@ -1,4 +1,10 @@
 export declare function isReachableHref(href: unknown): href is string;
-export declare function ArtifactMarkdown({ markdown }: {
+/** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
+ *  page carries a ```notes block. */
+export declare function ArtifactMarkdown({ markdown, notes }: {
     markdown: string;
+    notes?: {
+        artifactId: string;
+        accent?: string;
+    };
 }): import("react").JSX.Element;

package/lib/artifacts/render.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
+import { hasNotesWidget, headingsOf } from './widgets.js';
+import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 const GOLD = '#C2A15C';
 function hostOf(url) {
     try {
@@ -61,6 +63,10 @@ const components = {
         const lang = /language-(\w+)/.exec(className ?? '')?.[1];
         if (lang === 'links')
             return _jsx(LinkCards, { source: textOf(children) });
+        // A notes fence is the widget's place on the page. Without notes enabled (the host keeps no
+        // answers) it draws nothing: its settings are not prose and never shown as code.
+        if (lang === 'notes')
+            return null;
         if (!className) {
             return _jsx("code", { className: "rounded bg-white/10 px-1.5 py-0.5 text-[0.9em] text-zinc-100", children: children });
         }
@@ -70,7 +76,7 @@ const components = {
         // A links fence renders its own block; do not wrap it in <pre>.
         const inner = Array.isArray(children) ? children[0] : children;
         const cls = inner?.props?.className ?? '';
-        if (/language-links/.test(cls))
+        if (/language-(links|notes)/.test(cls))
             return _jsx(_Fragment, { children: children });
         return (_jsx("pre", { "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-white/10 bg-black/40 p-4 text-sm text-zinc-100", children: children }));
     },
@@ -85,6 +91,38 @@ const components = {
         return (_jsxs("aside", { "data-callout": kind, className: "my-6 rounded-lg border px-4 py-3", style: { borderColor: kind === 'warning' ? '#d97706' : GOLD, background: 'rgba(255,255,255,0.03)' }, children: [_jsx("span", { "data-nospeak": true, className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: kind }), _jsx("p", { className: "mt-1 text-zinc-100", children: body })] }));
     },
 };
-export function ArtifactMarkdown({ markdown }) {
-    return (_jsx("div", { className: "text-[17px] text-zinc-200", children: _jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: components, children: markdown }) }));
+const HEADING_CLASS = {
+    1: 'mt-10 mb-4 font-serif text-3xl text-zinc-50',
+    2: 'mt-10 mb-3 font-serif text-2xl text-zinc-50',
+    3: 'mt-8 mb-2 text-lg font-semibold text-zinc-100',
+    4: 'mt-6 mb-2 font-semibold text-zinc-100',
+    5: 'mt-6 mb-2 font-semibold text-zinc-100',
+    6: 'mt-6 mb-2 font-semibold text-zinc-100',
+};
+/** Components for a page with a notes block: every heading gets its slug as an id, a note
+ *  control, and its notes after it. The heading is found by its source line, so the slug is the
+ *  one headingsOf derived, the same one a note stores. */
+function notesComponents(headings) {
+    const byLine = new Map(headings.map((h) => [h.line, h]));
+    const heading = (depth) => function NotedHeading({ node, children }) {
+        const Tag = `h${depth}`;
+        const h = byLine.get(node?.position?.start.line ?? -1);
+        if (!h)
+            return _jsx(Tag, { className: HEADING_CLASS[depth], children: children });
+        return (_jsxs(_Fragment, { children: [_jsxs(Tag, { id: h.slug, className: HEADING_CLASS[depth], children: [children, _jsx(NoteToggle, { slug: h.slug })] }), _jsx(HeadingNotes, { slug: h.slug, text: h.text })] }));
+    };
+    const Code = components.code;
+    return {
+        ...components,
+        h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6),
+        code: (props) => (/language-notes/.test(props.className ?? '') ? _jsx(NotesEarlier, {}) : _jsx(Code, { ...props })),
+    };
+}
+/** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
+ *  page carries a ```notes block. */
+export function ArtifactMarkdown({ markdown, notes }) {
+    const on = !!notes && hasNotesWidget(markdown);
+    const headings = on ? headingsOf(markdown) : [];
+    const body = (_jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: on ? notesComponents(headings) : components, children: markdown }));
+    return (_jsx("div", { className: "text-[17px] text-zinc-200", children: on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body }));
 }

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

@@ -0,0 +1,62 @@
+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>;
+    /** Does this reader already hold a `one` answer in this slot? One document read. Optional so a
+     *  host's own store keeps working; without it the route falls back to loading the page. */
+    hasOne?(artifactId: string, slot: string, readerKey: string): Promise<boolean>;
+}
+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;