@supersuit/artifacts 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 `@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.22.0
+
+**A page can carry a checklist a reader ticks off and comes back to.** A per-person Mac setup
+page that remembers its ticks could not be published: the renderer escapes raw HTML (rightly),
+and a ```` ```checklist ```` fence was refused at publish as a widget not yet drawn, so each prep
+page went out as its own one-off site instead of on the operator's host.
+
+- New widget `checklist`: items with stable ids (`{#id}` or the slug of the text, numbered on a
+  repeat), indented descriptions drawn as markdown with raw HTML escaped, ticks kept in the
+  reader's `localStorage` under `artifact-checklist:<page>:<item>` (storage that throws costs only
+  the memory), "n of m done", and 44px rows. Several per page.
+- Optional `send: signed-in | anyone` in the fence: a Send button writes `{ done: [ids] }` to the
+  page's own `checklist` slot (shape one, private), which the owner reads through `/responses`.
+  The server refuses ids that are not that checklist's. Drawn only on a host with a state store.
+- `sms:` and `tel:` links now work on every page (react-markdown's default dropped them), and open
+  without `target="_blank"`. Everything else still goes through the default transform.
+- `ArtifactMarkdown` takes `checklist={{ artifactId, send, owner, accent }}`; the route passes it.
+  New exports: `checklistsOf`, `checklistSendIds`, `mergeChecklistState`, `parseChecklistFence`,
+  `checkChecklistValue`, `checklistStorageKey`, `CHECKLIST_SLOT`, `artifactUrlTransform`.
+- DETECTOR: publish a page with a ```` ```checklist ```` fence. "the checklist widget is not
+  available in this version" means the host is on 0.21.0 or earlier.
+- REMEDY: bump. A page with no checklist renders byte for byte as before (the 0.15.0 golden still
+  passes unchanged).
+- Tests: the fence grammar and every refusal with its file line; ids page-wide; the slot a Send
+  declares; the component's ids and count; raw HTML in an item and a description stays text; a
+  page with no checklist identical with and without the new prop; ticks saved by page and item id
+  and back after a remount; blocked storage; Send's body and its sign-in answer; the route taking
+  only that checklist's ids and `/responses` reading it; sms/tel links and `javascript:` still
+  dead; and the packed fixture drawing and posting one. Each was broken on purpose and went red.
+
+## 0.21.0 (2026-10-08)
+
+**A page's past versions are for its admins.** Every reader who could open a page could also open
+its History and read every earlier version at `/<id>/v/<n>`, so a passage edited out of a page
+(a name taken out, a figure corrected) stayed readable one click away.
+
+- New config `admins` (sign-in emails) and `history: 'admins' | 'everyone'`. The default,
+  `'admins'`, shows the History control and serves `/<id>/v/<n>` only to a signed-in reader whose
+  email is `ownerEmail` or in `admins`, compared without case. To everyone else the control is
+  absent and a past version is not found. "Version N · Updated <minute>" still shows to everyone.
+- DETECTOR: after the bump, a reader who is not an admin no longer sees "History" under a page's
+  summary. A host that configures neither `ownerEmail` nor `admins` hides history from everyone.
+- REMEDY: pass `admins` (and `ownerEmail`) for the people who should keep seeing history, or
+  `history: 'everyone'` to keep the 0.20.0 behaviour.
+- Tests: signed out, a signed-in non-admin, the owner in another case and a listed admin, a past
+  version 404ing for non-admins, nobody configured, and `'everyone'` restoring the old page. The
+  earlier version and golden tests pin `history: 'everyone'`, so they still prove 0.20.0's page.
+
 ## 0.20.0 (2026-10-07)
 
 **A host can hear when a confidential page is read.** The reader record answered `GET /reads`

package/README.md

@@ -27,6 +27,7 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `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 (widget fences included) |
 | `headingsOf`, `scanWidgets`, `placeNotes` | The notes widget's pure parts: heading slugs, fence validation, where each note shows |
+| `checklistsOf`, `parseChecklistFence`, `checklistStorageKey` | The checklist widget's pure parts: the fence grammar, every item's id, where a tick is kept |
 | `mintPass`, `verifyPass` | The reader pass, for the sign-in side (see below) |
 | `mintPublisherPass`, `verifyPublisherPass` | The publisher pass: an hour-long stand-in for the publish key, for one person on one host (see below) |
 | `ARTIFACT_PUBLIC_PREFIXES` (`/gate`) | Paths to leave open if you mount artifacts inside a gated site |
@@ -123,6 +124,17 @@ phone, a side panel on a desk), so opening it moves no text. Each past version i
 the same password or confidential door as the page itself. A version that does not exist is a
 404; on a shut page the door comes first, so it never says which versions exist.
 
+**Past versions are for admins by default (0.21.0).** An earlier draft can hold what the current
+one was edited to remove, so only the page's admins see the History control or open
+`/<id>/v/<n>`: the reader signed in as `ownerEmail` or any address in `admins` (case does not
+matter). Everyone else still sees "Version N · Updated <minute>", and a past version is a 404 to
+them. With neither configured, nobody does. `history: 'everyone'` in the config restores the old
+behaviour, where every reader who can open the page reads its history.
+
+```ts
+createArtifactRoutes({ ..., ownerEmail: 'owner@example.com', admins: ['editor@example.com'] })
+```
+
 **Do not write a "Version history" section in the markdown.** Say what changed when you publish:
 
 - `POST /api/artifacts?id=<id>&note=<one line>`, or a `change:` line in the front matter. The query
@@ -395,9 +407,64 @@ the shell in the page's brand and kept through the state API above. Widgets need
 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.
+This version draws two widgets, **checklist** and **notes**. Poll and form are coming: a fence
+named `poll` or `form` is refused at publish until then, so a page never ships a code block that
+turns into a live widget on a later update. A checklist needs no state store unless it offers
+Send.
+
+### Checklist
+
+A list a reader ticks off and comes back to: a setup page, a pre-call prep list, a launch
+checklist. It is a known component the shell draws, not markup the author writes, so raw HTML
+stays escaped and no author script ever runs.
+
+````markdown
+## Before the call
+
+```checklist
+send: anyone            # optional: signed-in | anyone; adds a Send button, see below
+- Update macOS {#update}
+  Apple menu > System Settings > General > Software Update.
+  Restart and check again until it says you're up to date.
+- [ ] Install Chrome and sign in
+  Download it from [google.com/chrome](https://www.google.com/chrome/).
+- Send us your GitHub username {#gh-send}
+  [Text Sam your username](sms:+15555550100&body=My%20GitHub%20username%20is%20)
+```
+````
+
+- **An item is a line starting with `- `** (or `* `), optionally followed by `[ ]`. `[x]` is
+  accepted and ticks nothing: ticks belong to the reader.
+- **Every item has a stable id.** `{#id}` at the end of the line sets it (lowercase letters,
+  digits, dashes, underscores; unique on the page). Without one the id is the slug of the item's
+  text, the way a heading's is (`Install Chrome and sign in` is `install-chrome-and-sign-in`), and
+  a repeat is numbered `-1`, `-2`. **Give an item an explicit id whenever its wording may change**:
+  a reworded item with a slugged id is a new item, and readers lose that tick.
+- **Indented lines under an item are its description**, drawn as markdown: links, `code`, bold,
+  short lists. Raw HTML in an item or a description is shown as text. Images, headings, tables and
+  fences are not drawn inside a checklist.
+- **Ticks are kept in the reader's browser**, in `localStorage` under
+  `artifact-checklist:<page id>:<item id>`, so they survive a reload, a republish, and a reworded
+  item with a kept id. Where storage is blocked (a private window, blocked site data) ticks last
+  for the visit. Nothing leaves the device unless the reader presses Send.
+- **The list says how far along the reader is**, "3 of 8 done", and every row is a tap target at
+  least 44px tall, so it works one-handed on a phone.
+- **Narration skips it**, like every widget: the fence is not prose and the component is
+  `data-nospeak`.
+- **Several checklists on one page** are fine; ids are unique across all of them.
+- **`sms:` and `tel:` links work on every page**, in a checklist or in prose, so "text us your
+  username" is one tap into the reader's own Messages.
+- Refused at publish, naming the line in the file: an indented line before the first item, an
+  unindented line after one, an empty item, a bad or repeated `{#id}`, a name after `checklist`,
+  any setting but `send`, a checklist with no items, and a second checklist with `send`.
+
+**Send** (`send: signed-in` or `send: anyone`) adds a "Send my progress to <owner>" button under
+the list. It writes `{ done: [item ids] }` to the page's `checklist` slot, shape `one` and
+`private`, so a reader's latest Send replaces their last and only the publisher reads them, through
+`/responses` like any answer. `send:` names who may press it (`anyone` gets the anonymous cookie
+and the rate limit, as `writers: anyone` does). The slot is the widget's own: a page may not
+declare a `checklist` slot in `state:`. The server takes only ids of that checklist, each once. On a
+host with no state store the button is not drawn; the ticks still work.
 
 ### Notes
 

package/lib/artifacts/checklist.d.ts

@@ -0,0 +1,53 @@
+export declare const CHECKLIST_SLOT = "checklist";
+export declare const MAX_CHECKLIST_ITEMS = 200;
+/** An item id: lowercase letters (any script), digits, dashes and underscores. The same alphabet
+ *  a heading slug uses, so a slugged id is always a valid one. */
+export declare const CHECKLIST_ID: RegExp;
+export type SendWriters = 'signed-in' | 'anyone';
+export type ChecklistItem = {
+    id: string;
+    text: string;
+    description: string;
+    line: number;
+};
+export type ChecklistBlock = {
+    line: number;
+    send?: SendWriters;
+    items: ChecklistItem[];
+};
+/** What a Send stores in the page's `checklist` slot: the ids the reader had ticked. */
+export type ChecklistValue = {
+    done: string[];
+};
+/** A block as written, before ids are made unique across the page. */
+export type RawChecklistItem = ChecklistItem & {
+    explicit: boolean;
+};
+export type RawChecklistBlock = Omit<ChecklistBlock, 'items'> & {
+    items: RawChecklistItem[];
+};
+/** The fence body as written, before ids are made unique across the page. `line` is the line the
+ *  fence opens on in the author's file, so every error names a line they can find. */
+export declare function parseChecklistFence(value: string, line: number, meta?: string | null): {
+    ok: true;
+    block: RawChecklistBlock;
+} | {
+    ok: false;
+    error: string;
+};
+/** Gives every item on the page its final id. An explicit `{#id}` is kept as written and must be
+ *  unique on the page; an item without one takes the slug of its text, numbered `-1`, `-2` when
+ *  that slug is already used, the way repeated headings are. Ids are page-wide because ticks are
+ *  saved by page and item id. */
+export declare function assignChecklistIds(blocks: RawChecklistBlock[]): {
+    ok: true;
+    blocks: ChecklistBlock[];
+} | {
+    ok: false;
+    error: string;
+};
+/** The server's check on a Send, on a page whose checklist offers one: every id is an item of
+ *  that checklist, once. The browser sends exactly this; anything else is refused. */
+export declare function checkChecklistValue(v: unknown, ids: readonly string[]): string | null;
+/** Where a reader's tick on one item is kept in their browser. */
+export declare const checklistStorageKey: (artifactId: string, itemId: string) => string;

package/lib/artifacts/checklist.js

@@ -0,0 +1,147 @@
+// The checklist widget's pure parts: the fence's grammar, the ids every item keeps, and the
+// server's check on what a Send hands the owner. Kept free of the markdown parser, like
+// notes-place.ts, because the widget in the reader's browser imports the names from here.
+//
+// ```checklist
+// send: anyone                      # optional: signed-in | anyone (who may press Send)
+// - Update macOS {#update}
+//   Apple menu > System Settings > General > Software Update.
+// - [ ] Sign in with your personal Apple Account
+// ```
+//
+// An item is a line starting with `- ` (or `* `), optionally followed by `[ ]`. Its id is the
+// `{#id}` at the end of the line when there is one, else a slug of its text. Indented lines under
+// an item are its description, drawn as markdown with raw HTML escaped like the rest of the page.
+// Ticks belong to the reader: `[x]` is accepted and ticks nothing.
+export const CHECKLIST_SLOT = 'checklist';
+export const MAX_CHECKLIST_ITEMS = 200;
+const MAX_ITEM_CHARS = 500;
+const MAX_ID_CHARS = 64;
+/** An item id: lowercase letters (any script), digits, dashes and underscores. The same alphabet
+ *  a heading slug uses, so a slugged id is always a valid one. */
+export const CHECKLIST_ID = /^[\p{Ll}\p{Lo}\p{Lm}\p{N}_-]{1,64}$/u;
+const ITEM = /^[-*]\s+(?:\[[ xX]\]\s+)?(.*)$/;
+const EXPLICIT_ID = /\s*\{#([^}\s]*)\}\s*$/;
+/** GitHub's heading rule (widgets.slugify), repeated here so this file stays parser-free. */
+function slug(text) {
+    const s = text.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/\s/g, '-');
+    return (s || 'item').slice(0, MAX_ID_CHARS).replace(/-+$/, '') || 'item';
+}
+/** The fence body as written, before ids are made unique across the page. `line` is the line the
+ *  fence opens on in the author's file, so every error names a line they can find. */
+export function parseChecklistFence(value, line, meta) {
+    if (meta?.trim())
+        return { ok: false, error: `line ${line}: the checklist block takes no name; put settings like "send: anyone" inside it` };
+    const rows = value ? value.split('\n') : [];
+    const items = [];
+    let send;
+    let desc = null;
+    const close = () => {
+        if (desc && items.length)
+            items[items.length - 1].description = desc.join('\n').replace(/^\n+|\n+$/g, '');
+        desc = null;
+    };
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const at = line + 1 + i;
+        if (!row.trim()) {
+            if (desc)
+                desc.push('');
+            continue;
+        }
+        if (/^(\s{2,}|\t)/.test(row)) {
+            if (!items.length)
+                return { ok: false, error: `line ${at}: an indented line belongs under an item; start the list with "- "` };
+            desc.push(row.replace(/^(\t| {2,4})/, ''));
+            continue;
+        }
+        const m = ITEM.exec(row);
+        if (m) {
+            close();
+            let text = m[1];
+            let id;
+            const e = EXPLICIT_ID.exec(text);
+            if (e) {
+                id = e[1];
+                text = text.slice(0, e.index);
+                if (!CHECKLIST_ID.test(id))
+                    return { ok: false, error: `line ${at}: the id {#${id}} must be lowercase letters, digits, dashes or underscores, at most ${MAX_ID_CHARS}` };
+            }
+            text = text.trim();
+            if (!text)
+                return { ok: false, error: `line ${at}: a checklist item needs some text` };
+            if (text.length > MAX_ITEM_CHARS)
+                return { ok: false, error: `line ${at}: a checklist item is at most ${MAX_ITEM_CHARS} characters` };
+            if (items.length >= MAX_CHECKLIST_ITEMS)
+                return { ok: false, error: `line ${at}: a checklist takes at most ${MAX_CHECKLIST_ITEMS} items` };
+            items.push({ id: id ?? '', text, description: '', line: at, explicit: !!id });
+            desc = [];
+            continue;
+        }
+        if (items.length)
+            return { ok: false, error: `line ${at}: a checklist item starts with "- ", and its description under it is indented` };
+        const s = /^([A-Za-z_-]+)\s*:\s*([^#]*?)\s*(#.*)?$/.exec(row.trim());
+        if (!s)
+            return { ok: false, error: `line ${at}: the checklist block takes settings like "send: anyone", then items starting with "- "` };
+        if (s[1] !== 'send')
+            return { ok: false, error: `line ${at}: the checklist block has an unknown setting: ${s[1]}` };
+        if (s[2] !== 'signed-in' && s[2] !== 'anyone')
+            return { ok: false, error: `line ${at}: checklist send must be signed-in or anyone` };
+        send = s[2];
+    }
+    close();
+    if (!items.length)
+        return { ok: false, error: `line ${line}: a checklist needs at least one item starting with "- "` };
+    return { ok: true, block: { line, ...(send ? { send } : {}), items } };
+}
+/** Gives every item on the page its final id. An explicit `{#id}` is kept as written and must be
+ *  unique on the page; an item without one takes the slug of its text, numbered `-1`, `-2` when
+ *  that slug is already used, the way repeated headings are. Ids are page-wide because ticks are
+ *  saved by page and item id. */
+export function assignChecklistIds(blocks) {
+    const taken = new Map();
+    for (const b of blocks)
+        for (const it of b.items) {
+            if (!it.explicit)
+                continue;
+            if (taken.has(it.id))
+                return { ok: false, error: `line ${it.line}: the id {#${it.id}} is already used on line ${taken.get(it.id)}` };
+            taken.set(it.id, it.line);
+        }
+    const out = blocks.map((b) => ({
+        line: b.line,
+        ...(b.send ? { send: b.send } : {}),
+        items: b.items.map(({ explicit, ...it }) => {
+            if (explicit)
+                return it;
+            const base = slug(it.text);
+            let id = base;
+            for (let k = 1; taken.has(id); k++)
+                id = `${base}-${k}`;
+            taken.set(id, it.line);
+            return { ...it, id };
+        }),
+    }));
+    return { ok: true, blocks: out };
+}
+/** The server's check on a Send, on a page whose checklist offers one: every id is an item of
+ *  that checklist, once. The browser sends exactly this; anything else is refused. */
+export function checkChecklistValue(v, ids) {
+    if (!v || typeof v !== 'object' || Array.isArray(v) || Object.keys(v).some((k) => k !== 'done'))
+        return 'a checklist answer is { done: [item ids] }';
+    const done = v.done;
+    if (!Array.isArray(done))
+        return 'a checklist answer is { done: [item ids] }';
+    const known = new Set(ids);
+    const seen = new Set();
+    for (const id of done) {
+        if (typeof id !== 'string' || !known.has(id))
+            return 'a checklist answer names only items on this page';
+        if (seen.has(id))
+            return 'a checklist answer names each item once';
+        seen.add(id);
+    }
+    return null;
+}
+/** Where a reader's tick on one item is kept in their browser. */
+export const checklistStorageKey = (artifactId, itemId) => `artifact-checklist:${artifactId}:${itemId}`;

package/lib/artifacts/front-matter.js

@@ -3,7 +3,7 @@
 import matter from 'gray-matter';
 import { ACCESS_LEVELS } from './reader.js';
 import { parseStateConfig } from './state.js';
-import { mergeWidgetState, scanWidgets } from './widgets.js';
+import { mergeChecklistState, mergeWidgetState, scanWidgets } from './widgets.js';
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
@@ -94,14 +94,17 @@ export function parseArtifactSource(text) {
             return { ok: false, error: 'comments_visible must be owner or readers' };
         meta.commentsVisible = d.comments_visible;
     }
-    // Widgets declare their own slots, so a notes block is merged into state: here, before the
+    // Widgets declare their own slots, so a notes block (and a checklist with send) 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);
+    const noted = mergeWidgetState(meta.state, w.notes);
+    if (!noted.ok)
+        return { ok: false, error: noted.error };
+    const merged = mergeChecklistState(noted.state, w.checklists);
     if (!merged.ok)
         return { ok: false, error: merged.error };
     const withComments = mergeCommentsState(merged.state, meta.comments, meta.commentsVisible);

package/lib/artifacts/index.d.ts

@@ -1,5 +1,5 @@
 export { parseArtifactSource, type ArtifactMeta } from './front-matter.js';
-export { ArtifactMarkdown } from './render.js';
+export { ArtifactMarkdown, artifactUrlTransform } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';
 export { isPublishAuthed, isPublisherAuthed, type PublishAuth } from './auth.js';
@@ -12,7 +12,8 @@ export { readAlertsDue, readSecondsFor, wordCount, localDay, READ_ALERT_KINDS, W
 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, blocksOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
+export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
+export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence, type ChecklistBlock, type ChecklistItem, type ChecklistValue } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment, type CommentsMode, type CommentsVisible, type CommentValue } from './comments.js';
 export { createPersonalStore, createMemoryPersonalStore, validatePersonal, personalAudioDir, MAX_PERSONAL_PER_READER, type PersonalStore, type PersonalNote, type PersonalNoteValue } from './personal-store.js';

package/lib/artifacts/index.js

@@ -1,5 +1,5 @@
 export { parseArtifactSource } from './front-matter.js';
-export { ArtifactMarkdown } from './render.js';
+export { ArtifactMarkdown, artifactUrlTransform } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS } from './store.js';
 export { isPublishAuthed, isPublisherAuthed } from './auth.js';
@@ -12,7 +12,8 @@ export { readAlertsDue, readSecondsFor, wordCount, localDay, READ_ALERT_KINDS, W
 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, blocksOf, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
+export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
+export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment } from './comments.js';
 export { createPersonalStore, createMemoryPersonalStore, validatePersonal, personalAudioDir, MAX_PERSONAL_PER_READER } from './personal-store.js';

package/lib/artifacts/render.d.ts

@@ -3,6 +3,7 @@ import type { FigureProps, SectionOutline, SectionProps } from '../brand/pack.js
 import { type Heading } from './widgets.js';
 import { type Definition } from './definitions.js';
 export declare function isReachableHref(href: unknown): href is string;
+export declare function artifactUrlTransform(url: string): string;
 /** A pack's figure resolver (BrandPack.figure). */
 export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps> | undefined;
 /** The page's top-level sections: every heading among the body's top-level blocks at the
@@ -10,8 +11,17 @@ export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps>
 export declare function sectionOutline(markdown: string, headings?: Heading[]): SectionOutline[];
 /** `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, definitions, Section, figure, }: {
+export declare function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, }: {
     markdown: string;
+    /** The page a ```checklist keeps its ticks under, and whether its Send can reach the owner
+     *  (a host that keeps answers, on a page that declares the slot). Without it a checklist still
+     *  draws and ticks, for the visit only. */
+    checklist?: {
+        artifactId: string;
+        send?: boolean;
+        owner?: string;
+        accent?: string;
+    };
     /** The pack's section component (BrandPack.Section): each top-level section is drawn through it. */
     Section?: ComponentType<SectionProps>;
     /** The pack's figure resolver (BrandPack.figure). */

package/lib/artifacts/render.js

@@ -2,16 +2,20 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // Markdown to the house look, for /a/<id>. Server-safe: no hooks, no client
 // directive. Raw HTML is escaped by react-markdown's default; never add
 // rehype-raw here, this renders strangers' links on a public route.
-// Two extensions past GFM, both small on purpose:
+// Three extensions past GFM, all small on purpose:
 //   ```links   one "url | note" per line, rendered as link cards
+//   ```checklist   items a reader ticks, kept in their browser (widgets/checklist.tsx)
 //   > [!note] / > [!warning]   a callout instead of a blockquote
+// A checklist's item text and descriptions are markdown drawn by the same safe renderer: raw
+// HTML escaped, links only where a reader can follow them, no images.
 import { Children, isValidElement } from 'react';
-import ReactMarkdown from 'react-markdown';
+import ReactMarkdown, { defaultUrlTransform } from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
-import { blocksOf, hasNotesWidget, headingsOf } from './widgets.js';
+import { blocksOf, checklistsOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
+import { Checklist } from '../widgets/checklist.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
@@ -58,6 +62,13 @@ const REACHABLE = /^(?:[a-z][a-z0-9+.-]*:|\/|#)/i;
 export function isReachableHref(href) {
     return typeof href === 'string' && REACHABLE.test(href);
 }
+/** `sms:` and `tel:` links open the reader's own Messages or Phone: a prep page's "text us your
+ *  username" is one tap. react-markdown's default drops both schemes (it keeps http(s), mailto,
+ *  xmpp and irc); everything else still goes through that default, so `javascript:` stays dead. */
+const PHONE_LINK = /^(?:sms|tel):/i;
+export function artifactUrlTransform(url) {
+    return PHONE_LINK.test(url) ? url : defaultUrlTransform(url);
+}
 /** `![alt](x.mp4)` plays as video: an animation that must stay smooth on a phone. Animated WebP
  *  is decoded frame by frame on the CPU and stuttered on an iPhone at 24fps (2026-09-27); video
  *  is decoded in hardware. */
@@ -91,7 +102,27 @@ function soleImage(node) {
     const src = kids[0].properties?.src;
     return typeof src === 'string' ? { src, alt: String(kids[0].properties?.alt ?? '') } : null;
 }
-function baseComponents(block, figure) {
+// Item text and descriptions: the page's own safe link, inline code and emphasis, nothing that
+// would break out of a list row (no images, headings, tables, fences or rules).
+const CHECKLIST_DISALLOWED = ['img', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'table', 'pre', 'hr', 'blockquote', 'input'];
+function checklistMarkdown(source, inline) {
+    const a = baseComponents(() => ({})).a;
+    return (_jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], urlTransform: artifactUrlTransform, disallowedElements: CHECKLIST_DISALLOWED, unwrapDisallowed: true, components: {
+            a,
+            p: ({ children }) => (inline ? _jsx(_Fragment, { children: children }) : _jsx("p", { className: "my-1 leading-relaxed", children: children })),
+            ul: ({ children }) => _jsx("ul", { className: "my-1 list-disc pl-5", children: children }),
+            ol: ({ children }) => _jsx("ol", { className: "my-1 list-decimal pl-5", children: children }),
+            code: ({ children }) => _jsx("code", { className: "rounded bg-[color:var(--a-surface-strong)] px-1.5 py-0.5 text-[0.9em] text-[color:var(--a-strong)]", children: children }),
+        }, children: source }));
+}
+function ChecklistFence({ line, ctx }) {
+    const c = ctx.byLine.get(line);
+    // Not a checklist this page validated: draw nothing rather than its source as code.
+    if (!c)
+        return null;
+    return (_jsx(Checklist, { items: c.items.map((it) => ({ id: it.id, title: checklistMarkdown(it.text, true), description: it.description ? checklistMarkdown(it.description, false) : null })), artifactId: ctx.artifactId, send: ctx.send && ctx.artifactId ? c.send : undefined, owner: ctx.owner, accent: ctx.accent }));
+}
+function baseComponents(block, figure, checklists) {
     return {
         p: ({ node, children }) => {
             // An image alone in its paragraph that the pack draws itself replaces the paragraph, so the
@@ -118,11 +149,15 @@ function baseComponents(block, figure) {
             // eslint-disable-next-line @next/next/no-img-element
             _jsx("img", { src: typeof src === 'string' ? src : undefined, alt: alt ?? '', className: "my-6 w-full rounded-lg border border-[color:var(--a-line)]" }));
         },
-        a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, target: "_blank", rel: "noopener noreferrer", className: "text-[color:var(--a-strong)] underline decoration-[color:var(--a-line-strong)] underline-offset-4 hover:decoration-[color:var(--a-strong)]", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-[color:var(--a-muted)]", children: ["(", hostOf(href), ")"] })) : null] })),
-        code: ({ className, children }) => {
+        a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, 
+            // A phone link opens an app, not a tab.
+            target: PHONE_LINK.test(href) ? undefined : '_blank', rel: "noopener noreferrer", className: "text-[color:var(--a-strong)] underline decoration-[color:var(--a-line-strong)] underline-offset-4 hover:decoration-[color:var(--a-strong)]", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-[color:var(--a-muted)]", children: ["(", hostOf(href), ")"] })) : null] })),
+        code: ({ node, className, children }) => {
             const lang = /language-(\w+)/.exec(className ?? '')?.[1];
             if (lang === 'links')
                 return _jsx(LinkCards, { source: textOf(children) });
+            if (lang === 'checklist')
+                return checklists ? _jsx(ChecklistFence, { line: node?.position?.start.line ?? -1, ctx: checklists }) : null;
             // 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')
@@ -136,7 +171,7 @@ function baseComponents(block, figure) {
             // 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|notes)/.test(cls))
+            if (/language-(links|notes|checklist)/.test(cls))
                 return _jsx(_Fragment, { children: children });
             return (_jsx("pre", { ...block(node), "data-artifact-code": true, 
                 // whitespace-pre-wrap, because a fence here usually holds PROSE meant to be pasted
@@ -169,20 +204,20 @@ const HEADING_CLASS = {
 };
 /** Components for any page: every heading gets its slug as an id, the one headingsOf derived,
  *  so a contents link and a note both land on it. */
-function pageComponents(headings, block, figure) {
+function pageComponents(headings, block, figure, checklists) {
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function Heading({ node, children }) {
         const Tag = `h${depth}`;
         const h = byLine.get(node?.position?.start.line ?? -1);
         return _jsx(Tag, { id: h?.slug, ...block(node), className: HEADING_CLASS[depth], children: children });
     };
-    return { ...baseComponents(block, figure), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
+    return { ...baseComponents(block, figure, checklists), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
 }
 /** 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, block, figure) {
-    const components = baseComponents(block, figure);
+function notesComponents(headings, block, figure, checklists) {
+    const components = baseComponents(block, figure, checklists);
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function NotedHeading({ node, children }) {
         const Tag = `h${depth}`;
@@ -261,7 +296,7 @@ const DEFINED_TERM_CSS = '.artifact-defined-term{text-decoration-line:underline;
     'clip:rect(0,0,0,0);white-space:nowrap;border:0}';
 /** `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, definitions, Section, figure, }) {
+export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, }) {
     const on = !!notes && hasNotesWidget(markdown);
     const headings = headingsOf(markdown);
     const blocks = blocksOf(markdown);
@@ -272,10 +307,14 @@ export function ArtifactMarkdown({ markdown, notes, definitions, Section, figure
     const defined = definitions?.length ? definitions : null;
     const outline = Section ? sectionOutline(markdown, headings) : [];
     const plugins = [remarkGfm, ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
-    const components = on ? notesComponents(headings, block, figure) : pageComponents(headings, block, figure);
+    const lists = /^ {0,3}(`{3,}|~{3,})\s*checklist\b/m.test(markdown) ? checklistsOf(markdown) : null;
+    const checklists = lists
+        ? { byLine: lists, artifactId: checklist?.artifactId, send: !!checklist?.send, owner: checklist?.owner, accent: checklist?.accent }
+        : undefined;
+    const components = on ? notesComponents(headings, block, figure, checklists) : pageComponents(headings, block, figure, checklists);
     if (outline.length)
         components.section = sectionComponent(Section, outline, block);
-    const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, children: markdown }));
+    const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, urlTransform: artifactUrlTransform, children: markdown }));
     return (
     // break-words: a bare URL in prose is one unbreakable word and pushed phones 7px sideways (2026-09-26).
     _jsxs("div", { className: "break-words text-[17px] text-[color:var(--a-body)]", children: [on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body, VIDEO_IN_MD.test(markdown) ? _jsx(VideoAutoplay, {}) : null, CODE_IN_MD.test(markdown) ? _jsx(CodeCopy, {}) : null, defined ? (_jsxs(_Fragment, { children: [_jsx("style", { children: DEFINED_TERM_CSS }), _jsx(DefinitionLayer, {})] })) : null] }));

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,24 @@ 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. The state
+ *  route asks, to check what a Send may name. */
+export declare function checklistSendIds(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. 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 +57,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,58 @@ 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` };
+        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. The state
+ *  route asks, to check what a Send may name. */
+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;
+}
+/** A checklist with `send` declares its own slot, `checklist`, shape one, private, written by
+ *  whoever `send:` names; the owner reads it through /responses. 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.send);
+    if (!c)
+        return { ok: true, state };
+    if (state && Object.hasOwn(state.slots, CHECKLIST_SLOT))
+        return { ok: false, error: `line ${c.line}: the checklist's send 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: {} };
+    return { ok: true, state: { ...base, slots: { ...base.slots, [CHECKLIST_SLOT]: { shape: 'one', visibility: 'private', writers: c.send } } } };
 }
 /** 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 +211,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 +249,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.d.ts

@@ -64,6 +64,15 @@ export type ArtifactRoutesConfig = {
      *  its writer's name, whatever `comments_visible:` says. Without it nobody is the owner, and
      *  the publisher reads comments through /responses. */
     ownerEmail?: string;
+    /** Sign-in emails, besides `ownerEmail`, of the people who administer this host's pages. They
+     *  see a page's version history; with `history: 'admins'` (the default) nobody else does. */
+    admins?: readonly string[];
+    /** Who sees a page's past versions: the History control under the summary and every
+     *  `/<id>/v/<n>`. `'admins'` (default): only `ownerEmail` and `admins`, signed in; to everyone
+     *  else the History control is absent and a past version is not found, because an earlier draft
+     *  can hold what the current one was edited to remove. `'everyone'`: every reader who can open
+     *  the page, which was the only behaviour before 0.21.0. */
+    history?: 'admins' | 'everyone';
     /** Turns a reader's voice memo into text on the server, so the service's key never reaches a
      *  browser: `deepgramTranscriber(key)` or `openaiTranscriber(key)` from `./artifacts`, or your
      *  own. Without it the transcribe route answers 404 and readers get the browser's live

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';
@@ -60,6 +61,9 @@ export function createArtifactRoutes(config) {
     const signInOrigin = config.signInOrigin;
     const owner = config.owner ?? brand.name;
     const ownerEmail = config.ownerEmail?.trim().toLowerCase();
+    const admins = new Set([ownerEmail, ...(config.admins ?? []).map((e) => e.trim().toLowerCase())].filter((e) => !!e));
+    /** Whether this reader may see a page's past versions (config `history`). */
+    const seesHistory = (reader) => config.history === 'everyone' || (!!reader && admins.has(reader.email.trim().toLowerCase()));
     const readerSecret = () => config.readerSecret?.();
     const signOutUrl = (id) => `/api/reader/leave?to=${encodeURIComponent(pagePath(id))}`;
     // Signing out alone cannot change the account: the authority still holds the Google session
@@ -195,7 +199,7 @@ export function createArtifactRoutes(config) {
         if (!a)
             notFound();
         const { pack, brand } = lookOf(a);
-        const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top }));
+        const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top, reader }));
         if (a.access)
             return GatedPage(a, id, render, n);
         // A password shuts the body, never the title: the header stays so the reader knows which
@@ -273,8 +277,8 @@ export function createArtifactRoutes(config) {
         return store.history(id).catch(() => null);
     }
     /** "Version N · Updated <minute> · History": the line under the summary. */
-    function VersionLine({ a, n, at, history }) {
-        return (_jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-60", children: [`Version ${n} · Updated `, _jsx(UpdatedTime, { iso: at }), history && history.length > 1 ? (_jsxs(_Fragment, { children: [' · ', _jsx(VersionHistory, { items: history, base: pagePath(a.id), viewing: n })] })) : null] }));
+    function VersionLine({ a, n, at, history, reader }) {
+        return (_jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-60", children: [`Version ${n} · Updated `, _jsx(UpdatedTime, { iso: at }), history && history.length > 1 && seesHistory(reader) ? (_jsxs(_Fragment, { children: [' · ', _jsx(VersionHistory, { items: history, base: pagePath(a.id), viewing: n })] })) : null] }));
     }
     /** The title block and the body, in the pack's Article when it has one. Without one this is
      *  exactly the markup every page had before packs could frame it. */
@@ -284,8 +288,11 @@ export function createArtifactRoutes(config) {
         return (_jsxs(_Fragment, { children: [cover, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc, children] })] }));
     }
     /** A past version: its own body and title, read-only (no narration, no answers), under a banner. */
-    async function VersionBody(a, n, { top }) {
+    async function VersionBody(a, n, { top, reader }) {
         const { pack, brand } = lookOf(a);
+        // Past versions are for admins unless the host says otherwise: to anyone else none exists.
+        if (!seesHistory(reader))
+            notFound();
         const v = store.version ? await store.version(a.id, n) : null;
         if (!v)
             notFound();
@@ -296,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 }), 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 })] })), 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 }) {
@@ -317,9 +324,11 @@ export function createArtifactRoutes(config) {
         const mode = config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
         return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { id: "artifact-narration-root", children: await (async () => {
                         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) }), 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 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, checklistSendIds, 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 ? checklistSendIds(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.d.ts

@@ -0,0 +1,16 @@
+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, 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;
+    owner?: string;
+    accent?: string;
+}): import("react").JSX.Element;

package/lib/widgets/checklist.js

@@ -0,0 +1,95 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The checklist widget in the reader's browser. Each tick is kept in localStorage under the page
+// and the item id (checklist.ts, checklistStorageKey), so it survives a reload, a republish and a
+// reworded item, and never leaves the device unless the reader presses Send. Storage that throws
+// (a private window, blocked site data) costs the reader only the memory: ticks still work for
+// the visit.
+//
+// The item text and description arrive already drawn on the server, as markdown with raw HTML
+// escaped, so this file draws no author content itself. Everything here is data-nospeak: the
+// narrator reads the prose, never the checklist.
+import { useCallback, useEffect, useState } from 'react';
+import { CHECKLIST_SLOT, checklistStorageKey } from '../artifacts/checklist.js';
+function readTick(key) {
+    if (!key)
+        return false;
+    try {
+        return globalThis.localStorage?.getItem(key) === '1';
+    }
+    catch {
+        return false;
+    }
+}
+function writeTick(key, on) {
+    if (!key)
+        return;
+    try {
+        if (on)
+            globalThis.localStorage?.setItem(key, '1');
+        else
+            globalThis.localStorage?.removeItem(key);
+    }
+    catch {
+        // Storage blocked: the tick lives for this visit only.
+    }
+}
+export function Checklist({ items, artifactId, send, owner, accent, }) {
+    const key = useCallback((id) => (artifactId ? checklistStorageKey(artifactId, id) : null), [artifactId]);
+    const [done, setDone] = useState({});
+    const [sent, setSent] = useState({ status: 'idle' });
+    // Read after mount, never during render: the server has no storage, and reading it while
+    // hydrating would draw a page that disagrees with the server's.
+    const ids = items.map((it) => it.id).join('\n');
+    useEffect(() => {
+        const next = {};
+        for (const id of ids.split('\n'))
+            if (readTick(key(id)))
+                next[id] = true;
+        setDone(next);
+    }, [ids, key]);
+    const toggle = (id) => {
+        setDone((d) => {
+            const on = !d[id];
+            writeTick(key(id), on);
+            const next = { ...d };
+            if (on)
+                next[id] = true;
+            else
+                delete next[id];
+            return next;
+        });
+        setSent((s) => (s.status === 'sent' ? { status: 'idle' } : s));
+    };
+    const count = items.filter((it) => done[it.id]).length;
+    const color = accent ?? 'var(--a-accent)';
+    const doSend = async () => {
+        if (!artifactId)
+            return;
+        setSent({ status: 'busy' });
+        try {
+            const r = await fetch(`/api/artifacts/${artifactId}/state`, {
+                method: 'POST',
+                credentials: 'same-origin',
+                cache: 'no-store',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ slot: CHECKLIST_SLOT, op: 'set', value: { done: items.filter((it) => done[it.id]).map((it) => it.id) } }),
+            });
+            const body = (await r.json().catch(() => ({})));
+            if (r.ok)
+                setSent({ status: 'sent' });
+            else if (r.status === 401)
+                setSent({ status: 'sign-in', signIn: typeof body.signIn === 'string' ? body.signIn : null });
+            else
+                setSent({ status: 'error', message: typeof body.error === 'string' ? body.error : 'that did not send; try again' });
+        }
+        catch {
+            setSent({ status: 'error', message: 'that did not reach the page; try again' });
+        }
+    };
+    return (_jsxs("div", { "data-nospeak": true, "data-artifact-checklist": true, className: "my-6 rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)]", children: [_jsx("p", { "data-checklist-count": true, "aria-live": "polite", className: "m-0 border-b border-[color:var(--a-line)] px-4 py-2 text-[11px] uppercase tracking-[0.2em]", style: { color }, children: `${count} of ${items.length} done` }), _jsx("ul", { className: "m-0 list-none p-0", children: items.map((it) => {
+                    const on = !!done[it.id];
+                    const inputId = `checklist-${artifactId ?? 'page'}-${it.id}`;
+                    return (_jsxs("li", { "data-checklist-item": it.id, "data-done": on ? 'yes' : 'no', className: "m-0 border-b border-[color:var(--a-line)] px-4 py-1 last:border-b-0", children: [_jsxs("label", { htmlFor: inputId, className: "flex cursor-pointer items-start gap-3 py-2", style: { minHeight: 44 }, children: [_jsx("input", { id: inputId, type: "checkbox", checked: on, onChange: () => toggle(it.id), className: "mt-0.5 shrink-0 cursor-pointer", style: { accentColor: color, width: 24, height: 24 } }), _jsx("span", { className: on ? 'text-[color:var(--a-muted)] line-through' : 'text-[color:var(--a-strong)]', children: it.title })] }), it.description ? _jsx("div", { className: "pb-2 pl-9 text-[15px] text-[color:var(--a-body)]", children: it.description }) : null] }, it.id));
+                }) }), send && artifactId ? (_jsxs("div", { className: "border-t border-[color:var(--a-line)] px-4 py-3", children: [_jsx("button", { type: "button", "data-checklist-send": true, disabled: sent.status === 'busy', onClick: () => void doSend(), className: "rounded-full px-5 text-sm font-medium disabled:opacity-40", style: { background: color, color: 'var(--a-on-accent, #111)', minHeight: 44 }, children: owner ? `Send my progress to ${owner}` : 'Send my progress' }), sent.status === 'sent' ? _jsx("p", { "data-checklist-sent": true, className: "mt-2 text-sm opacity-80", children: `Sent: ${count} of ${items.length} done.` }) : null, sent.status === 'error' ? _jsx("p", { className: "mt-2 text-sm text-amber-500", children: sent.message }) : null, sent.status === 'sign-in' ? (sent.signIn ? (_jsx("p", { className: "mt-2 text-sm", children: _jsx("a", { href: sent.signIn, className: "underline", style: { color }, children: "Sign in to send" }) })) : (_jsx("p", { className: "mt-2 text-sm opacity-70", children: "Sending is open to signed-in readers." }))) : null] })) : null] }));
+}

package/package.json

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