@supersuit/artifacts 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 `@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.23.0
+
+**A checklist can keep its ticks in the cloud, shared by everyone on the page.** Two people
+walking one list on a call each saw only their own browser's ticks: 0.22.0 kept ticks in
+`localStorage`, and Send hands one reader's set to the owner rather than to the other reader.
+
+- New fence setting `sync: anyone | signed-in` (who may tick). One block saying it makes every
+  checklist on the page one shared set, kept in the page's `checklist` slot declared `shared`
+  (shape one). Blocks that disagree on `sync`, and `send` on a page that syncs, are refused.
+- The server checks a synced set against every checklist item on the page (the 0.22.0 check took
+  only the first block with `send`). New exports `checklistAnswerIds`, `checklistSyncs`.
+- The widget holds one store per page, shared by all its blocks: reads the newest shared set on
+  load, posts the whole page-wide set 400ms after a tick, polls every 4s while the tab is visible,
+  and shows "Synced" / "Saving…" / the error after the count. Last write wins on the whole set.
+  A host with no state store (501), a page with no slot (404) or a failed first read falls back
+  to `localStorage` exactly as before.
+- No route change: the route's existing `checklist.send` (host keeps answers, page declares the
+  slot) turns sync on for a page whose checklists sync.
+- DETECTOR: publish a page whose checklist says `sync: anyone`. "the checklist block has an unknown
+  setting: sync" means the host is on 0.22.0 or earlier.
+- REMEDY: bump. Pages without `sync` render and behave exactly as before.
+- Tests: the grammar accepts and refuses `sync`; multi-block ids validated server-side (an id from
+  the second block accepted, an id no block draws refused); disagreeing blocks and send-with-sync
+  refused; the slot declared shared; an anonymous reader on an unlocked password page posts and a
+  second browser reads the set, then the reverse; the widget reads the newest shared set into
+  every block with one request, posts the page-wide set after a tick, takes another reader's
+  untick on the next poll, and falls back to storage on 501. Picking the newest set and checking
+  ids page-wide were each broken on purpose and went red.
+
+## 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

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`, `checklistAnswerIds`, `checklistSyncs` | 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 |
@@ -406,9 +407,81 @@ 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 or syncs.
+
+### 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
+                        # or sync: signed-in | anyone; one shared set for every reader, 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` or `sync`, a checklist with no items, a second checklist with `send`,
+  `send` and `sync` on one page, and two checklists that say `sync` differently.
+
+**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.
+
+**Sync** (`sync: anyone` or `sync: signed-in`) makes the ticks the PAGE's: one set every reader
+sees and, as `sync:` names, may change. Two people on a call ticking the same list see each
+other's ticks within a few seconds. One block saying `sync` is enough: every checklist on the page
+then shares the one set, because item ids are page-wide, and two blocks that both say it must say
+the same thing. The page declares its `checklist` slot `shared` (shape `one`), each tick updates
+the screen at once and, after a short pause, posts the whole page-wide `{ done: [ids] }`, and the
+newest set by server time is the page's. The widget reads it on load and every four seconds while
+the tab is visible, and says where it stands after the count: "Synced", "Saving…", or what went
+wrong. The server takes only ids of checklists on the page. `anyone` works for anonymous readers
+(the anonymous cookie and rate limit, as `writers: anyone`), on a password page once it is
+unlocked. **Concurrency is last-write-wins on the whole set**: two readers ticking different items
+inside the same couple of seconds can lose one tick. A page cannot both sync and send. On a host
+with no state store, or where the first read fails, the list falls back to the reader's own
+`localStorage` exactly as an unsynced one.
 
 ### Notes
 

package/lib/artifacts/checklist.d.ts

@@ -0,0 +1,54 @@
+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;
+    sync?: 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 or a synced set: every id is an item of that checklist (of any
+ *  checklist on the page, when it syncs), 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,160 @@
+// 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)
+// sync: anyone                      # optional: signed-in | anyone (who may tick a shared set)
+// - 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.
+//
+// `sync:` makes the ticks the PAGE's instead of the reader's: one page-wide set, kept by the host in
+// the shared `checklist` slot, that every reader sees and (as `sync:` names) may change. One block
+// saying it is enough; every checklist on the page then shares the one set, because item ids are
+// page-wide. A page cannot both sync and send: a synced set already reaches the owner.
+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 sync;
+    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' && s[1] !== 'sync')
+            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 ${s[1]} must be signed-in or anyone` };
+        if (s[1] === 'send')
+            send = s[2];
+        else
+            sync = s[2];
+    }
+    if (send && sync)
+        return { ok: false, error: `line ${line}: a checklist takes send or sync, not both; a synced list already reaches the owner` };
+    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 } : {}), ...(sync ? { sync } : {}), 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 } : {}),
+        ...(b.sync ? { sync: b.sync } : {}),
+        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 or a synced set: every id is an item of that checklist (of any
+ *  checklist on the page, when it syncs), 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, checklistAnswerIds, checklistSyncs, 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, checklistAnswerIds, checklistSyncs, 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,18 @@ 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). On a page whose checklists
+     *  `sync`, the same `send` turns on the shared, page-wide set. 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, checklistSyncs, 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 && !ctx.sync ? c.send : undefined, sync: ctx.sync && !!ctx.artifactId, 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,16 @@ 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
+        // `send` from the host means it keeps answers and the page declared the `checklist` slot; on a
+        // page whose checklists sync, that same slot is the shared set, so it turns sync on instead.
+        ? { byLine: lists, artifactId: checklist?.artifactId, send: !!checklist?.send, sync: !!checklist?.send && checklistSyncs(lists.values()), 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] }));