@supersuit/artifacts 0.21.0 → 0.23.0

package/lib/artifacts/widgets.d.ts

@@ -1,5 +1,6 @@
 import type { StateConfig, Visibility } from './state.js';
 import { type Heading } from './notes-place.js';
+import { type ChecklistBlock } from './checklist.js';
 export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes, type Heading, type NoteValue, type PlacedNote } from './notes-place.js';
 export type NotesWidget = {
     line: number;
@@ -17,6 +18,32 @@ export declare function headingsOf(markdown: string): Heading[];
 export declare function scanWidgets(body: string, offset: number): {
     ok: true;
     notes: NotesWidget | null;
+    checklists: ChecklistBlock[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Every checklist on a page, by the line its fence opens on in the body, with the ids the page
+ *  draws. A page whose checklists do not parse (published before checklists existed, so never
+ *  validated) draws none rather than half of them. */
+export declare function checklistsOf(markdown: string): Map<number, ChecklistBlock>;
+/** The item ids of the page's checklist that offers Send, or null when none does. */
+export declare function checklistSendIds(markdown: string): string[] | null;
+/** Does any checklist on this page sync? Then every checklist on it shares one set of ticks. */
+export declare function checklistSyncs(checklists: Iterable<ChecklistBlock>): boolean;
+/** The ids an answer in the `checklist` slot may name, or null when the page takes none: on a page
+ *  that syncs, every item of every checklist on it (ids are page-wide); else the items of the
+ *  checklist that offers Send. The state route asks, so a synced set can never carry an id the
+ *  page does not draw. */
+export declare function checklistAnswerIds(markdown: string): string[] | null;
+/** A checklist with `send` declares its own slot, `checklist`, shape one, private, written by
+ *  whoever `send:` names; the owner reads it through /responses. A page whose checklists `sync`
+ *  declares the same slot SHARED instead, so every reader is shown every reader's set and the
+ *  widget takes the newest as the page's. Like `comments:`, the slot is the widget's own, so
+ *  state: may not declare one by that name. */
+export declare function mergeChecklistState(state: StateConfig | undefined, checklists: ChecklistBlock[]): {
+    ok: true;
+    state: StateConfig | undefined;
 } | {
     ok: false;
     error: string;
@@ -38,5 +65,5 @@ export declare function hasNotesWidget(markdown: string): boolean;
 export declare function checkNoteValue(v: unknown): string | null;
 /** The stable id of every top-level block, by the offset it starts at in the markdown. The
  *  renderer puts it on the block as `data-block`, and a region comment is pinned to it. Blocks
- *  that draw no prose (a notes or links fence, a rule, raw html) get none. */
+ *  that draw no prose (a notes, links or checklist fence, a rule, raw html) get none. */
 export declare function blocksOf(markdown: string): Map<number, string>;

package/lib/artifacts/widgets.js

@@ -1,8 +1,10 @@
 // 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,
+// This version draws two widgets. `checklist` (./checklist.ts) is a list of items a reader ticks,
+// kept in their own browser, with an optional Send that hands their ticks to the page's owner
+// through the `one` slot `checklist`. `notes` is 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.
 //
@@ -14,10 +16,11 @@ import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import { blockId } from './anchor.js';
 import { MAX_NOTE_CHARS, NOTES_SLOT } from './notes-place.js';
+import { CHECKLIST_SLOT, assignChecklistIds, parseChecklistFence } from './checklist.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 NOT_YET = ['poll', 'form'];
 const MAX_HEADING_CHARS = 300;
 const parse = (markdown) => unified().use(remarkParse).use(remarkGfm).parse(markdown);
 function inline(nodes) {
@@ -97,7 +100,88 @@ export function scanWidgets(body, offset) {
         }
         notes = w;
     }
-    return { ok: true, notes };
+    const lists = scanChecklists(fences, offset);
+    if (!lists.ok)
+        return lists;
+    return { ok: true, notes, checklists: lists.checklists };
+}
+function scanChecklists(fences, offset) {
+    const lists = [];
+    for (const f of fences) {
+        if (f.lang !== 'checklist')
+            continue;
+        const line = (f.position?.start.line ?? 1) + offset;
+        const c = parseChecklistFence(f.value, line, f.meta);
+        if (!c.ok)
+            return c;
+        if (c.block.send && lists.some((l) => l.send))
+            return { ok: false, error: `line ${line}: a page takes at most one checklist with send` };
+        const synced = lists.find((l) => l.sync);
+        if (c.block.sync && synced && synced.sync !== c.block.sync)
+            return { ok: false, error: `line ${line}: this checklist says sync: ${c.block.sync} and the one on line ${synced.line} says sync: ${synced.sync}; a page's ticks are one set, so say it one way` };
+        if ((c.block.sync && lists.some((l) => l.send)) || (c.block.send && synced))
+            return { ok: false, error: `line ${line}: a page whose checklists sync takes no send; the synced ticks already reach the owner` };
+        lists.push(c.block);
+    }
+    const ids = assignChecklistIds(lists);
+    return ids.ok ? { ok: true, checklists: ids.blocks } : ids;
+}
+const fencesOf = (markdown) => {
+    const fences = [];
+    walk(parse(markdown).children, (n) => { if (n.type === 'code' && n.lang === 'checklist')
+        fences.push(n); });
+    return fences;
+};
+/** Every checklist on a page, by the line its fence opens on in the body, with the ids the page
+ *  draws. A page whose checklists do not parse (published before checklists existed, so never
+ *  validated) draws none rather than half of them. */
+export function checklistsOf(markdown) {
+    const r = scanChecklists(fencesOf(markdown), 0);
+    return new Map(r.ok ? r.checklists.map((c) => [c.line, c]) : []);
+}
+/** The item ids of the page's checklist that offers Send, or null when none does. */
+export function checklistSendIds(markdown) {
+    const r = scanChecklists(fencesOf(markdown), 0);
+    const c = r.ok ? r.checklists.find((l) => l.send) : undefined;
+    return c ? c.items.map((i) => i.id) : null;
+}
+/** Does any checklist on this page sync? Then every checklist on it shares one set of ticks. */
+export function checklistSyncs(checklists) {
+    for (const c of checklists)
+        if (c.sync)
+            return true;
+    return false;
+}
+/** The ids an answer in the `checklist` slot may name, or null when the page takes none: on a page
+ *  that syncs, every item of every checklist on it (ids are page-wide); else the items of the
+ *  checklist that offers Send. The state route asks, so a synced set can never carry an id the
+ *  page does not draw. */
+export function checklistAnswerIds(markdown) {
+    const r = scanChecklists(fencesOf(markdown), 0);
+    if (!r.ok)
+        return null;
+    if (checklistSyncs(r.checklists))
+        return r.checklists.flatMap((c) => c.items.map((i) => i.id));
+    const c = r.checklists.find((l) => l.send);
+    return c ? c.items.map((i) => i.id) : null;
+}
+/** A checklist with `send` declares its own slot, `checklist`, shape one, private, written by
+ *  whoever `send:` names; the owner reads it through /responses. A page whose checklists `sync`
+ *  declares the same slot SHARED instead, so every reader is shown every reader's set and the
+ *  widget takes the newest as the page's. Like `comments:`, the slot is the widget's own, so
+ *  state: may not declare one by that name. */
+export function mergeChecklistState(state, checklists) {
+    const c = checklists.find((l) => l.sync) ?? checklists.find((l) => l.send);
+    if (!c)
+        return { ok: true, state };
+    const what = c.sync ? 'sync' : 'send';
+    if (state && Object.hasOwn(state.slots, CHECKLIST_SLOT))
+        return { ok: false, error: `line ${c.line}: the checklist's ${what} writes to slot "${CHECKLIST_SLOT}", and state: declares a slot by that name; rename that slot` };
+    const base = state ?? { writers: 'signed-in', visibility: 'private', slots: {} };
+    const slot = c.sync
+        ? { shape: 'one', visibility: 'shared', writers: c.sync }
+        : { shape: 'one', visibility: 'private', writers: c.send };
+    return { ok: true, state: { ...base, slots: { ...base.slots, [CHECKLIST_SLOT]: slot } } };
 }
 /** 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
@@ -157,7 +241,7 @@ function assetName(url) {
 }
 /** The stable id of every top-level block, by the offset it starts at in the markdown. The
  *  renderer puts it on the block as `data-block`, and a region comment is pinned to it. Blocks
- *  that draw no prose (a notes or links fence, a rule, raw html) get none. */
+ *  that draw no prose (a notes, links or checklist fence, a rule, raw html) get none. */
 export function blocksOf(markdown) {
     const out = new Map();
     const seen = new Map();
@@ -195,7 +279,7 @@ export function blocksOf(markdown) {
             content = plain(n);
         }
         else if (n.type === 'code') {
-            if (n.lang === 'links' || n.lang === NOTES_SLOT)
+            if (n.lang === 'links' || n.lang === NOTES_SLOT || n.lang === 'checklist')
                 continue;
             kind = 'code';
             content = n.value;

package/lib/routes/artifacts.js

@@ -6,6 +6,7 @@ import { isPublisherAuthed } from '../artifacts/auth.js';
 import { parseArtifactSource } from '../artifacts/front-matter.js';
 import { narrationText } from '../artifacts/narration.js';
 import { ArtifactMarkdown } from '../artifacts/render.js';
+import { CHECKLIST_SLOT } from '../artifacts/checklist.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
 import { cleanNote } from '../artifacts/store.js';
@@ -302,7 +303,7 @@ export function createArtifactRoutes(config) {
         const title = v.title ?? a.title;
         const summary = v.summary ?? a.summary;
         const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.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: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions, Section: pack.Section, figure: pack.figure }) })] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.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: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader }) {
@@ -325,7 +326,9 @@ export function createArtifactRoutes(config) {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
                         const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { a: a, n: n, at: a.updatedAt, history: await historyOf(a.id), reader: reader }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _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 }), meta] }));
-                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, 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-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, Section: pack.Section, figure: pack.figure }) }));
+                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, 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-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
+                                // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
+                                checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) }));
                     })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), 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 /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));

package/lib/routes/state-routes.js

@@ -19,7 +19,8 @@ import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWrit
 import { COMMENTS_SLOT, validateComment } from '../artifacts/comments.js';
 import { isCommentAudioPath } from '../artifacts/audio.js';
 import { readerKeyFor } from '../artifacts/state-store.js';
-import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
+import { NOTES_SLOT, checkNoteValue, checklistAnswerIds, hasNotesWidget } from '../artifacts/widgets.js';
+import { CHECKLIST_SLOT, checkChecklistValue } from '../artifacts/checklist.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
 export const ANON_COOKIE = 'artifact_anon';
 const ANON_ID = /^[A-Za-z0-9]{24}$/;
@@ -242,7 +243,10 @@ export function createStateRoutes(ctx) {
                 return json({ error: 'no comment of yours with that id' }, 404);
         }
         else {
-            const bad = checkValue(b.value) ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null);
+            const sendIds = slot === CHECKLIST_SLOT ? checklistAnswerIds(a.markdown) : null;
+            const bad = checkValue(b.value)
+                ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null)
+                ?? (sendIds ? checkChecklistValue(b.value, sendIds) : null);
             if (bad)
                 return json({ error: bad }, 400);
             let value = b.value;

package/lib/widgets/checklist-sync.d.ts

@@ -0,0 +1,54 @@
+export type SyncStatus = 'loading' | 'synced' | 'saving' | 'error' | 'sign-in' | 'local';
+export type SyncSnapshot = {
+    done: ReadonlySet<string>;
+    status: SyncStatus;
+    message?: string;
+    signIn?: string | null;
+};
+export declare const SYNC_POLL_MS = 4000;
+export declare const SYNC_SAVE_DELAY_MS = 400;
+/** The page's set from a state answer: the newest shared entry's `done`, or null when the answer
+ *  carries no checklist slot. An empty slot is an empty set. */
+export declare function latestSharedDone(body: unknown): string[] | null;
+declare class SyncStore {
+    private artifactId;
+    private blocks;
+    private done;
+    private status;
+    private message?;
+    private signIn?;
+    private snap;
+    private listeners;
+    private dirty;
+    private inflight;
+    private saveTimer;
+    private pollTimer;
+    private onVisible;
+    constructor(artifactId: string);
+    private make;
+    private emit;
+    private set;
+    private visible;
+    private url;
+    /** Every id a checklist on the page draws. A set from an earlier version can name an item the
+     *  page no longer has, and the server refuses a set naming one, so only these are posted. */
+    private known;
+    snapshot: () => SyncSnapshot;
+    subscribe: (l: () => void) => () => void;
+    register(block: object, ids: readonly string[]): void;
+    unregister(block: object): void;
+    private start;
+    private stop;
+    private toLocal;
+    /** Read the page's set. Skipped while this reader has a change not yet saved, so a poll can
+     *  never take back a tick the reader just made. */
+    pull(): Promise<void>;
+    toggle(id: string): void;
+    private schedule;
+    /** Post the whole page-wide set. Last write wins on the whole set (see the top of this file). */
+    push(): Promise<void>;
+}
+/** The one store for a page, shared by every checklist block on it. */
+export declare function syncStoreFor(artifactId: string): SyncStore;
+export declare const SERVER_SYNC_SNAPSHOT: SyncSnapshot;
+export {};

package/lib/widgets/checklist-sync.js

@@ -0,0 +1,255 @@
+'use client';
+// The shared set behind a page whose checklists `sync`: one store per page, held by every
+// checklist block on it, because item ids are page-wide and the host keeps ONE set for the page
+// (the shared `one` slot `checklist`, where each writer's latest set is an entry).
+//
+// The newest entry by its server time is the page's set. A tick updates the screen at once and,
+// after a short pause, posts the WHOLE page-wide set; a poll every few seconds while the tab is
+// visible brings in the other readers' ticks. Concurrency is last-write-wins on the whole set: two
+// people ticking different items inside the same couple of seconds can lose one of the two ticks.
+// That is accepted for a list two people walk through together; a per-item merge would need the
+// host to keep per-item state, which this version does not.
+//
+// A host that keeps no answers (501), a page that takes none (404), or a first read that fails
+// drops the store to `local`: ticks live in localStorage exactly as an unsynced checklist's do.
+import { CHECKLIST_SLOT, checklistStorageKey } from '../artifacts/checklist.js';
+export const SYNC_POLL_MS = 4000;
+export const SYNC_SAVE_DELAY_MS = 400;
+const RETRY_MS = 5000;
+/** The page's set from a state answer: the newest shared entry's `done`, or null when the answer
+ *  carries no checklist slot. An empty slot is an empty set. */
+export function latestSharedDone(body) {
+    const slot = body?.slots?.[CHECKLIST_SLOT];
+    if (!slot)
+        return null;
+    let best = null;
+    for (const e of slot.shared ?? [])
+        if (typeof e?.at === 'string' && (!best || e.at > best.at))
+            best = e;
+    const done = best?.value?.done;
+    return Array.isArray(done) ? done.filter((d) => typeof d === 'string') : [];
+}
+function readLocal(artifactId, id) {
+    try {
+        return globalThis.localStorage?.getItem(checklistStorageKey(artifactId, id)) === '1';
+    }
+    catch {
+        return false;
+    }
+}
+function writeLocal(artifactId, id, on) {
+    try {
+        if (on)
+            globalThis.localStorage?.setItem(checklistStorageKey(artifactId, id), '1');
+        else
+            globalThis.localStorage?.removeItem(checklistStorageKey(artifactId, id));
+    }
+    catch {
+        // Storage blocked: the tick lives for this visit only.
+    }
+}
+class SyncStore {
+    artifactId;
+    blocks = new Map();
+    done = new Set();
+    status = 'loading';
+    message;
+    signIn;
+    snap;
+    listeners = new Set();
+    dirty = false;
+    inflight = false;
+    saveTimer = null;
+    pollTimer = null;
+    onVisible = () => { if (this.visible())
+        void this.pull(); };
+    constructor(artifactId) {
+        this.artifactId = artifactId;
+        this.snap = this.make();
+    }
+    make() {
+        return { done: new Set(this.done), status: this.status, ...(this.message ? { message: this.message } : {}), ...(this.signIn !== undefined ? { signIn: this.signIn } : {}) };
+    }
+    emit() {
+        this.snap = this.make();
+        for (const l of this.listeners)
+            l();
+    }
+    set(status, message, signIn) {
+        this.status = status;
+        this.message = message;
+        this.signIn = signIn;
+    }
+    visible() {
+        return typeof document === 'undefined' || document.visibilityState !== 'hidden';
+    }
+    url() {
+        return `/api/artifacts/${this.artifactId}/state`;
+    }
+    /** Every id a checklist on the page draws. A set from an earlier version can name an item the
+     *  page no longer has, and the server refuses a set naming one, so only these are posted. */
+    known() {
+        const out = new Set();
+        for (const ids of this.blocks.values())
+            for (const id of ids)
+                out.add(id);
+        return out;
+    }
+    snapshot = () => this.snap;
+    subscribe = (l) => {
+        this.listeners.add(l);
+        return () => { this.listeners.delete(l); };
+    };
+    register(block, ids) {
+        // Back in the map after a stop (React's strict mode unmounts and remounts once).
+        if (!stores.has(this.artifactId))
+            stores.set(this.artifactId, this);
+        this.blocks.set(block, ids);
+        if (this.status === 'local') {
+            for (const id of ids)
+                if (readLocal(this.artifactId, id))
+                    this.done.add(id);
+            this.emit();
+        }
+        if (this.blocks.size === 1)
+            this.start();
+    }
+    unregister(block) {
+        this.blocks.delete(block);
+        if (this.blocks.size === 0)
+            this.stop();
+    }
+    start() {
+        void this.pull();
+        if (typeof document !== 'undefined')
+            document.addEventListener('visibilitychange', this.onVisible);
+        this.pollTimer = setInterval(() => { if (this.visible())
+            void this.pull(); }, SYNC_POLL_MS);
+    }
+    stop() {
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        if (this.saveTimer)
+            clearTimeout(this.saveTimer);
+        this.pollTimer = this.saveTimer = null;
+        if (typeof document !== 'undefined')
+            document.removeEventListener('visibilitychange', this.onVisible);
+        stores.delete(this.artifactId);
+    }
+    toLocal() {
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        this.pollTimer = null;
+        this.done = new Set([...this.known()].filter((id) => readLocal(this.artifactId, id)));
+        this.set('local');
+        this.emit();
+    }
+    /** Read the page's set. Skipped while this reader has a change not yet saved, so a poll can
+     *  never take back a tick the reader just made. */
+    async pull() {
+        if (this.status === 'local' || this.dirty || this.inflight)
+            return;
+        let r;
+        try {
+            r = await fetch(this.url(), { credentials: 'same-origin', cache: 'no-store' });
+        }
+        catch {
+            if (this.status === 'loading')
+                return this.toLocal();
+            this.set('error', 'offline; will retry');
+            return this.emit();
+        }
+        if (r.status === 501 || r.status === 404)
+            return this.toLocal();
+        const body = await r.json().catch(() => null);
+        if (!r.ok) {
+            if (this.status === 'loading')
+                return this.toLocal();
+            this.set('error', 'could not read the shared list; will retry');
+            return this.emit();
+        }
+        const done = latestSharedDone(body);
+        if (done === null)
+            return this.toLocal();
+        if (this.dirty || this.inflight)
+            return;
+        this.done = new Set(done);
+        if (this.status !== 'sign-in')
+            this.set('synced');
+        this.emit();
+    }
+    toggle(id) {
+        const on = !this.done.has(id);
+        if (on)
+            this.done.add(id);
+        else
+            this.done.delete(id);
+        writeLocal(this.artifactId, id, on);
+        if (this.status === 'local')
+            return this.emit();
+        this.dirty = true;
+        this.set('saving');
+        this.emit();
+        this.schedule(SYNC_SAVE_DELAY_MS);
+    }
+    schedule(ms) {
+        if (this.saveTimer)
+            clearTimeout(this.saveTimer);
+        this.saveTimer = setTimeout(() => { this.saveTimer = null; void this.push(); }, ms);
+    }
+    /** Post the whole page-wide set. Last write wins on the whole set (see the top of this file). */
+    async push() {
+        if (this.inflight || !this.dirty)
+            return;
+        this.inflight = true;
+        this.dirty = false;
+        const known = this.known();
+        const done = [...this.done].filter((id) => known.has(id));
+        let r = null;
+        let body = null;
+        try {
+            r = await fetch(this.url(), {
+                method: 'POST',
+                credentials: 'same-origin',
+                cache: 'no-store',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ slot: CHECKLIST_SLOT, op: 'set', value: { done } }),
+            });
+            body = (await r.json().catch(() => null));
+        }
+        catch {
+            r = null;
+        }
+        this.inflight = false;
+        if (r?.ok) {
+            if (this.dirty)
+                return this.schedule(SYNC_SAVE_DELAY_MS);
+            const latest = latestSharedDone(body);
+            if (latest)
+                this.done = new Set(latest);
+            this.set('synced');
+        }
+        else if (r?.status === 401) {
+            this.set('sign-in', undefined, typeof body?.signIn === 'string' ? body.signIn : null);
+        }
+        else if (r && r.status >= 400 && r.status < 500 && r.status !== 429) {
+            this.set('error', typeof body?.error === 'string' ? body.error : 'that tick did not save');
+        }
+        else {
+            // Offline, rate-limited or a server error: keep the tick and try again shortly.
+            this.dirty = true;
+            this.set('error', 'not saved yet; retrying');
+            this.schedule(RETRY_MS);
+        }
+        this.emit();
+    }
+}
+const stores = new Map();
+/** The one store for a page, shared by every checklist block on it. */
+export function syncStoreFor(artifactId) {
+    let s = stores.get(artifactId);
+    if (!s)
+        stores.set(artifactId, (s = new SyncStore(artifactId)));
+    return s;
+}
+export const SERVER_SYNC_SNAPSHOT = { done: new Set(), status: 'loading' };

package/lib/widgets/checklist.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import { type SendWriters } from '../artifacts/checklist.js';
+export type ChecklistViewItem = {
+    id: string;
+    title: ReactNode;
+    description: ReactNode | null;
+};
+export declare function Checklist({ items, artifactId, send, sync, owner, accent, }: {
+    items: ChecklistViewItem[];
+    /** The page, for the storage key. Without one (a past version) ticks last for the visit. */
+    artifactId?: string;
+    /** Who may press Send, when the page offers it and the host keeps answers. */
+    send?: SendWriters;
+    /** The page's ticks are one shared set the host keeps (a page whose checklists `sync`). */
+    sync?: boolean;
+    owner?: string;
+    accent?: string;
+}): import("react").JSX.Element;