@supersuit/artifacts 0.1.0 → 0.3.0

package/lib/artifacts/state-store.js

@@ -0,0 +1,153 @@
+// 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;
+        },
+        hasOne: async (artifactId, slot, readerKey) => (await col().doc(oneId(artifactId, slot, readerKey)).get()).exists,
+    };
+    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,
+        hasOne: async (artifactId, slot, readerKey) => docs.has(oneId(artifactId, slot, readerKey)),
+    };
+}

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/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/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';