@supersuit/artifacts 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 `@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

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 |
 
@@ -285,6 +286,55 @@ On a proxy other than Vercel's, pass `clientIp` to `createArtifactRoutes` (used
 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.js

@@ -3,6 +3,7 @@
 import matter from 'gray-matter';
 import { ACCESS_LEVELS } from './reader.js';
 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);
@@ -40,5 +41,17 @@ export function parseArtifactSource(text) {
             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

@@ -10,3 +10,4 @@ export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type Flag
 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

@@ -10,3 +10,4 @@ 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

@@ -49,6 +49,9 @@ export interface StateStore {
     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;

package/lib/artifacts/state-store.js

@@ -89,6 +89,7 @@ export function createStateStore(db, base) {
         async countSlot(artifactId, slot) {
             return (await col().where('artifactId', '==', artifactId).where('slot', '==', slot).count().get()).data().count;
         },
+        hasOne: async (artifactId, slot, readerKey) => (await col().doc(oneId(artifactId, slot, readerKey)).get()).exists,
     };
     return store;
 }
@@ -147,5 +148,6 @@ export function createMemoryStateStore() {
             return n;
         },
         countSlot: async (artifactId, slot) => of(artifactId).filter((e) => e.slot === slot).length,
+        hasOne: async (artifactId, slot, readerKey) => docs.has(oneId(artifactId, slot, readerKey)),
     };
 }

package/lib/artifacts/widgets.d.ts

@@ -0,0 +1,38 @@
+import type { StateConfig, Visibility } from './state.js';
+import { type Heading } from './notes-place.js';
+export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes, type Heading, type NoteValue, type PlacedNote } from './notes-place.js';
+export type NotesWidget = {
+    line: number;
+    visibility?: Exclude<Visibility, 'tally'>;
+};
+/** GitHub's rule: lowercase, drop everything but letters, digits, spaces, dashes and
+ *  underscores, spaces to dashes. A heading of only punctuation is `section`. */
+export declare function slugify(text: string): string;
+/** Every heading in source order, with the line it starts on and a slug unique on the page
+ *  (a repeated heading gets `-1`, `-2`). The renderer finds a heading here by its line, so the
+ *  slug a note stores is exactly the slug the page draws. */
+export declare function headingsOf(markdown: string): Heading[];
+/** Finds the widget fences in a body. `offset` is how many lines of the file sit above the body
+ *  (the front matter), so every error names the line the author sees in their editor. */
+export declare function scanWidgets(body: string, offset: number): {
+    ok: true;
+    notes: NotesWidget | null;
+} | {
+    ok: false;
+    error: string;
+};
+/** A widget declares its own slot. The notes block adds `notes: { shape: many }` to the page's
+ *  `state:` (creating `state:` with its defaults when the page had none), so the state API
+ *  takes notes with no change and a republish's shape checks cover the slot. */
+export declare function mergeWidgetState(state: StateConfig | undefined, notes: NotesWidget | null): {
+    ok: true;
+    state: StateConfig | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/** Does this page's body carry a notes block? The state route asks, to check a note's shape. */
+export declare function hasNotesWidget(markdown: string): boolean;
+/** The server's check on a note, on a page with a notes block. The browser checks too; this is
+ *  the one that counts. */
+export declare function checkNoteValue(v: unknown): string | null;

package/lib/artifacts/widgets.js

@@ -0,0 +1,141 @@
+// Widgets: fenced blocks in a document's markdown that give readers a place to answer, drawn by
+// the shell in the page's brand and written through the state API (state.ts, state-routes.ts).
+//
+// This version draws ONE widget, `notes`: a small note control beside every heading, kept in the
+// `many` slot `notes`. A note stores the heading it was left under, both its slug and its text,
+// so a republish that renames or removes the heading keeps the note and shows it under "notes
+// on earlier versions" instead of losing it or attaching it to the wrong section.
+//
+// Everything here is pure and server-safe: parsing, publish-time validation, the heading slugs
+// the renderer and the stored notes agree on, and where each note is placed. The drawing lives
+// in ../widgets/notes.tsx.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { MAX_NOTE_CHARS, NOTES_SLOT } from './notes-place.js';
+export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes } from './notes-place.js';
+/** Widgets the design names and this version does not draw yet. A fence using one is refused at
+ *  publish, so a page never ships a code block that turns into a live widget on a later update. */
+const NOT_YET = ['poll', 'form', 'checklist'];
+const MAX_HEADING_CHARS = 300;
+const parse = (markdown) => unified().use(remarkParse).use(remarkGfm).parse(markdown);
+function inline(nodes) {
+    let out = '';
+    for (const n of nodes) {
+        if (n.type === 'text' || n.type === 'inlineCode')
+            out += n.value;
+        else if (n.type === 'break')
+            out += ' ';
+        else if ('children' in n)
+            out += inline(n.children);
+    }
+    return out;
+}
+function walk(nodes, visit) {
+    for (const n of nodes) {
+        visit(n);
+        if ('children' in n && n.type !== 'heading' && n.type !== 'paragraph')
+            walk(n.children, visit);
+    }
+}
+/** GitHub's rule: lowercase, drop everything but letters, digits, spaces, dashes and
+ *  underscores, spaces to dashes. A heading of only punctuation is `section`. */
+export function slugify(text) {
+    const s = text.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/\s/g, '-');
+    return s || 'section';
+}
+/** Every heading in source order, with the line it starts on and a slug unique on the page
+ *  (a repeated heading gets `-1`, `-2`). The renderer finds a heading here by its line, so the
+ *  slug a note stores is exactly the slug the page draws. */
+export function headingsOf(markdown) {
+    const out = [];
+    const seen = new Map();
+    walk(parse(markdown).children, (n) => {
+        if (n.type !== 'heading')
+            return;
+        const text = inline(n.children).replace(/\s+/g, ' ').trim();
+        const base = slugify(text);
+        const k = seen.get(base) ?? 0;
+        seen.set(base, k + 1);
+        out.push({ depth: n.depth, line: n.position?.start.line ?? 0, text, slug: k ? `${base}-${k}` : base });
+    });
+    return out;
+}
+/** Finds the widget fences in a body. `offset` is how many lines of the file sit above the body
+ *  (the front matter), so every error names the line the author sees in their editor. */
+export function scanWidgets(body, offset) {
+    const fences = [];
+    walk(parse(body).children, (n) => { if (n.type === 'code')
+        fences.push(n); });
+    let notes = null;
+    for (const f of fences) {
+        const line = (f.position?.start.line ?? 1) + offset;
+        if (f.lang && NOT_YET.includes(f.lang))
+            return { ok: false, error: `line ${line}: the ${f.lang} widget is not available in this version of the artifacts package` };
+        if (f.lang !== NOTES_SLOT)
+            continue;
+        if (notes)
+            return { ok: false, error: `line ${line}: a page takes at most one notes block` };
+        if (f.meta?.trim())
+            return { ok: false, error: `line ${line}: the notes block takes no name; it always writes to slot "notes"` };
+        const w = { line };
+        const rows = f.value ? f.value.split('\n') : [];
+        for (let i = 0; i < rows.length; i++) {
+            const raw = rows[i].replace(/#.*$/, '').trim();
+            if (!raw)
+                continue;
+            const at = line + 1 + i;
+            const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(raw);
+            if (!m)
+                return { ok: false, error: `line ${at}: the notes block takes lines like "visibility: shared"` };
+            if (m[1] !== 'visibility')
+                return { ok: false, error: `line ${at}: the notes block has an unknown key: ${m[1]}` };
+            if (m[2] !== 'private' && m[2] !== 'shared')
+                return { ok: false, error: `line ${at}: notes visibility must be private or shared` };
+            w.visibility = m[2];
+        }
+        notes = w;
+    }
+    return { ok: true, notes };
+}
+/** A widget declares its own slot. The notes block adds `notes: { shape: many }` to the page's
+ *  `state:` (creating `state:` with its defaults when the page had none), so the state API
+ *  takes notes with no change and a republish's shape checks cover the slot. */
+export function mergeWidgetState(state, notes) {
+    if (!notes)
+        return { ok: true, state };
+    const had = state?.slots[NOTES_SLOT];
+    if (had && had.shape !== 'many')
+        return { ok: false, error: `line ${notes.line}: the notes block writes to slot "notes" as shape many, and state: declares it shape ${had.shape}; rename that slot` };
+    if (had?.visibility && notes.visibility && had.visibility !== notes.visibility)
+        return { ok: false, error: `line ${notes.line}: the notes block says visibility ${notes.visibility} and state: says ${had.visibility} for slot "notes"; say it once` };
+    const slot = had
+        ? (notes.visibility && !had.visibility ? { ...had, visibility: notes.visibility } : had)
+        : { shape: 'many', ...(notes.visibility ? { visibility: notes.visibility } : {}) };
+    const base = state ?? { writers: 'signed-in', visibility: 'private', slots: {} };
+    if (slot === had)
+        return { ok: true, state: base };
+    return { ok: true, state: { ...base, slots: { ...base.slots, [NOTES_SLOT]: slot } } };
+}
+/** Does this page's body carry a notes block? The state route asks, to check a note's shape. */
+export function hasNotesWidget(markdown) {
+    const r = scanWidgets(markdown, 0);
+    return r.ok && r.notes !== null;
+}
+const SLUG = /^[\p{Ll}\p{Lo}\p{Lm}\p{N}_-]{1,120}$/u;
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** The server's check on a note, on a page with a notes block. The browser checks too; this is
+ *  the one that counts. */
+export function checkNoteValue(v) {
+    if (!isMap(v) || Object.keys(v).some((k) => !['slug', 'heading', 'note'].includes(k)))
+        return 'a note is { slug, heading, note }';
+    if (typeof v.slug !== 'string' || !SLUG.test(v.slug))
+        return 'a note needs the slug of the heading it is under';
+    if (typeof v.heading !== 'string' || v.heading.length > MAX_HEADING_CHARS)
+        return 'a note needs the heading it is under';
+    if (typeof v.note !== 'string' || !v.note.trim())
+        return 'a note needs some text';
+    if (v.note.length > MAX_NOTE_CHARS)
+        return `a note is at most ${MAX_NOTE_CHARS} characters`;
+    return null;
+}

package/lib/routes/artifacts.js

@@ -88,9 +88,15 @@ export function createArtifactRoutes(config) {
         // The same cookie again on the page's state API: a cookie scoped to the page path is never
         // sent to /api/artifacts/<id>/state, so without it a password page could not take answers.
         const unlockLine = (path) => `${unlockCookieName(id)}=${keyHash(id, a.password)}; Path=${path}; Max-Age=31536000; SameSite=Lax; Secure`;
-        const remember = open && a.password && key !== undefined && cookie !== keyHash(id, a.password)
-            ? [pagePath(id), `/api/artifacts/${id}`].map((p) => `document.cookie=${JSON.stringify(unlockLine(p))}`).join(';')
-            : null;
+        // The API copy is set on EVERY open of a page with state:, because the page cannot see it (a
+        // cookie scoped to /api/... never reaches the page path): a reader who unlocked the page
+        // before its API cookie existed would otherwise be refused every answer until they reopened
+        // the ?key= link.
+        const paths = !open || !a.password ? [] : [
+            ...(key !== undefined && cookie !== keyHash(id, a.password) ? [pagePath(id)] : []),
+            ...(a.state ? [`/api/artifacts/${id}`] : key !== undefined && cookie !== keyHash(id, a.password) ? [`/api/artifacts/${id}`] : []),
+        ];
+        const remember = paths.length ? paths.map((p) => `document.cookie=${JSON.stringify(unlockLine(p))}`).join(';') : null;
         if (!open) {
             return (_jsxs(BrandGround, { pack: brand, children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }), _jsx(ArtifactDoor, { brand: brand, wrongKey: key !== undefined })] }));
         }
@@ -107,7 +113,7 @@ export function createArtifactRoutes(config) {
             }
         }
         const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-        return (_jsxs(BrandGround, { pack: brand, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        return (_jsxs(BrandGround, { pack: brand, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
     }
     /** A page with `access:`. The body is rendered only after the reader is known and allowed;
      *  everyone else gets the title, the summary, and a door. */
@@ -146,7 +152,7 @@ export function createArtifactRoutes(config) {
             }
         }
         const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-        return (_jsxs(_Fragment, { children: [_jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        return (_jsxs(_Fragment, { children: [_jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in

package/lib/routes/state-routes.js

@@ -16,6 +16,7 @@ import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../arti
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
 import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters } from '../artifacts/state.js';
 import { readerKeyFor } from '../artifacts/state-store.js';
+import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
 export const ANON_COOKIE = 'artifact_anon';
 const ANON_ID = /^[A-Za-z0-9]{24}$/;
@@ -168,13 +169,15 @@ export function createStateRoutes(ctx) {
             await ctx.state.remove({ artifactId: id, slot, readerKey: writer.key, entryId: typeof b.entry === 'string' ? b.entry : undefined });
         }
         else {
-            const bad = checkValue(b.value);
+            const bad = checkValue(b.value) ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null);
             if (bad)
                 return json({ error: bad }, 400);
             // The page-wide cap per slot. Counted before the write and not atomically with it, so a
             // burst can overshoot by the writes in flight; it bounds the slot, it is not a quota.
             if ((await ctx.state.countSlot(id, slot)) >= MAX_ENTRIES_PER_SLOT) {
-                const replacing = op === 'set' && (await ctx.state.entries(id)).some((e) => e.slot === slot && e.readerKey === writer.key);
+                const replacing = op === 'set' && (ctx.state.hasOne
+                    ? await ctx.state.hasOne(id, slot, writer.key)
+                    : (await ctx.state.entries(id)).some((e) => e.slot === slot && e.readerKey === writer.key));
                 if (!replacing)
                     return json({ error: 'this page is not taking more answers here' }, 409);
             }

package/lib/widgets/notes.d.ts

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

package/lib/widgets/notes.js

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

package/package.json

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