@supersuit/artifacts 0.22.0 → 0.23.0

package/CHANGELOG.md

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

package/README.md

@@ -27,7 +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 |
+| `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 |
@@ -410,7 +410,7 @@ response carries the no-answers warning.
 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.
+Send or syncs.
 
 ### Checklist
 
@@ -423,6 +423,7 @@ stays escaped and no author script ever runs.
 
 ```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.
@@ -456,7 +457,8 @@ send: anyone            # optional: signed-in | anyone; adds a Send button, see
   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`.
+  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
@@ -466,6 +468,21 @@ and the rate limit, as `writers: anyone` does). The slot is the widget's own: a
 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
 
 ````markdown

package/lib/artifacts/checklist.d.ts

@@ -13,6 +13,7 @@ export type ChecklistItem = {
 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. */
@@ -46,8 +47,8 @@ export declare function assignChecklistIds(blocks: RawChecklistBlock[]): {
     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. */
+/** 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

@@ -4,6 +4,7 @@
 //
 // ```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
@@ -13,6 +14,11 @@
 // `{#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;
@@ -35,6 +41,7 @@ export function parseChecklistFence(value, line, meta) {
     const rows = value ? value.split('\n') : [];
     const items = [];
     let send;
+    let sync;
     let desc = null;
     const close = () => {
         if (desc && items.length)
@@ -83,16 +90,21 @@ export function parseChecklistFence(value, line, meta) {
         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')
+        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 send must be signed-in or anyone` };
-        send = s[2];
+            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 } : {}), items } };
+    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
@@ -111,6 +123,7 @@ export function assignChecklistIds(blocks) {
     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;
@@ -124,8 +137,8 @@ export function assignChecklistIds(blocks) {
     }));
     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. */
+/** 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] }';

package/lib/artifacts/index.d.ts

@@ -12,7 +12,7 @@ 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, mergeChecklistState, checklistsOf, checklistSendIds, 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';

package/lib/artifacts/index.js

@@ -12,7 +12,7 @@ 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, mergeChecklistState, checklistsOf, checklistSendIds, 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';

package/lib/artifacts/render.d.ts

@@ -14,7 +14,8 @@ export declare function sectionOutline(markdown: string, headings?: Heading[]):
 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
+     *  (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;

package/lib/artifacts/render.js

@@ -13,7 +13,7 @@ import ReactMarkdown, { defaultUrlTransform } from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
-import { blocksOf, checklistsOf, 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';
@@ -120,7 +120,7 @@ function ChecklistFence({ line, ctx }) {
     // 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 }));
+    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 {
@@ -309,7 +309,9 @@ export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Sect
     const plugins = [remarkGfm, ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
     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 }
+        // `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)

package/lib/artifacts/widgets.d.ts

@@ -27,12 +27,20 @@ export declare function scanWidgets(body: string, offset: number): {
  *  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. */
+/** The item ids of the page's checklist that offers Send, or null when none does. */
 export declare function checklistSendIds(markdown: string): string[] | null;
+/** Does any checklist on this page sync? Then every checklist on it shares one set of ticks. */
+export declare function checklistSyncs(checklists: Iterable<ChecklistBlock>): boolean;
+/** The ids an answer in the `checklist` slot may name, or null when the page takes none: on a page
+ *  that syncs, every item of every checklist on it (ids are page-wide); else the items of the
+ *  checklist that offers Send. The state route asks, so a synced set can never carry an id the
+ *  page does not draw. */
+export declare function checklistAnswerIds(markdown: string): string[] | null;
 /** A checklist with `send` declares its own slot, `checklist`, shape one, private, written by
- *  whoever `send:` names; the owner reads it through /responses. Like `comments:`, the slot is
- *  the widget's own, so state: may not declare one by that name. */
+ *  whoever `send:` names; the owner reads it through /responses. A page whose checklists `sync`
+ *  declares the same slot SHARED instead, so every reader is shown every reader's set and the
+ *  widget takes the newest as the page's. Like `comments:`, the slot is the widget's own, so
+ *  state: may not declare one by that name. */
 export declare function mergeChecklistState(state: StateConfig | undefined, checklists: ChecklistBlock[]): {
     ok: true;
     state: StateConfig | undefined;

package/lib/artifacts/widgets.js

@@ -116,6 +116,11 @@ function scanChecklists(fences, offset) {
             return c;
         if (c.block.send && lists.some((l) => l.send))
             return { ok: false, error: `line ${line}: a page takes at most one checklist with send` };
+        const synced = lists.find((l) => l.sync);
+        if (c.block.sync && synced && synced.sync !== c.block.sync)
+            return { ok: false, error: `line ${line}: this checklist says sync: ${c.block.sync} and the one on line ${synced.line} says sync: ${synced.sync}; a page's ticks are one set, so say it one way` };
+        if ((c.block.sync && lists.some((l) => l.send)) || (c.block.send && synced))
+            return { ok: false, error: `line ${line}: a page whose checklists sync takes no send; the synced ticks already reach the owner` };
         lists.push(c.block);
     }
     const ids = assignChecklistIds(lists);
@@ -134,24 +139,49 @@ 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. */
+/** The item ids of the page's checklist that offers Send, or null when none does. */
 export function checklistSendIds(markdown) {
     const r = scanChecklists(fencesOf(markdown), 0);
     const c = r.ok ? r.checklists.find((l) => l.send) : undefined;
     return c ? c.items.map((i) => i.id) : null;
 }
+/** Does any checklist on this page sync? Then every checklist on it shares one set of ticks. */
+export function checklistSyncs(checklists) {
+    for (const c of checklists)
+        if (c.sync)
+            return true;
+    return false;
+}
+/** The ids an answer in the `checklist` slot may name, or null when the page takes none: on a page
+ *  that syncs, every item of every checklist on it (ids are page-wide); else the items of the
+ *  checklist that offers Send. The state route asks, so a synced set can never carry an id the
+ *  page does not draw. */
+export function checklistAnswerIds(markdown) {
+    const r = scanChecklists(fencesOf(markdown), 0);
+    if (!r.ok)
+        return null;
+    if (checklistSyncs(r.checklists))
+        return r.checklists.flatMap((c) => c.items.map((i) => i.id));
+    const c = r.checklists.find((l) => l.send);
+    return c ? c.items.map((i) => i.id) : null;
+}
 /** A checklist with `send` declares its own slot, `checklist`, shape one, private, written by
- *  whoever `send:` names; the owner reads it through /responses. Like `comments:`, the slot is
- *  the widget's own, so state: may not declare one by that name. */
+ *  whoever `send:` names; the owner reads it through /responses. A page whose checklists `sync`
+ *  declares the same slot SHARED instead, so every reader is shown every reader's set and the
+ *  widget takes the newest as the page's. Like `comments:`, the slot is the widget's own, so
+ *  state: may not declare one by that name. */
 export function mergeChecklistState(state, checklists) {
-    const c = checklists.find((l) => l.send);
+    const c = checklists.find((l) => l.sync) ?? checklists.find((l) => l.send);
     if (!c)
         return { ok: true, state };
+    const what = c.sync ? 'sync' : 'send';
     if (state && Object.hasOwn(state.slots, CHECKLIST_SLOT))
-        return { ok: false, error: `line ${c.line}: the checklist's send writes to slot "${CHECKLIST_SLOT}", and state: declares a slot by that name; rename that slot` };
+        return { ok: false, error: `line ${c.line}: the checklist's ${what} writes to slot "${CHECKLIST_SLOT}", and state: declares a slot by that name; rename that slot` };
     const base = state ?? { writers: 'signed-in', visibility: 'private', slots: {} };
-    return { ok: true, state: { ...base, slots: { ...base.slots, [CHECKLIST_SLOT]: { shape: 'one', visibility: 'private', writers: c.send } } } };
+    const slot = c.sync
+        ? { shape: 'one', visibility: 'shared', writers: c.sync }
+        : { shape: 'one', visibility: 'private', writers: c.send };
+    return { ok: true, state: { ...base, slots: { ...base.slots, [CHECKLIST_SLOT]: slot } } };
 }
 /** A widget declares its own slot. The notes block adds `notes: { shape: many }` to the page's
  *  `state:` (creating `state:` with its defaults when the page had none), so the state API

package/lib/routes/state-routes.js

@@ -19,7 +19,7 @@ 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, checklistSendIds, hasNotesWidget } from '../artifacts/widgets.js';
+import { NOTES_SLOT, checkNoteValue, checklistAnswerIds, hasNotesWidget } from '../artifacts/widgets.js';
 import { CHECKLIST_SLOT, checkChecklistValue } from '../artifacts/checklist.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
 export const ANON_COOKIE = 'artifact_anon';
@@ -243,7 +243,7 @@ export function createStateRoutes(ctx) {
                 return json({ error: 'no comment of yours with that id' }, 404);
         }
         else {
-            const sendIds = slot === CHECKLIST_SLOT ? checklistSendIds(a.markdown) : null;
+            const sendIds = slot === CHECKLIST_SLOT ? checklistAnswerIds(a.markdown) : null;
             const bad = checkValue(b.value)
                 ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null)
                 ?? (sendIds ? checkChecklistValue(b.value, sendIds) : null);

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

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

package/lib/widgets/checklist-sync.js

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

package/lib/widgets/checklist.d.ts

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

package/lib/widgets/checklist.js

@@ -9,8 +9,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // 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';
+//
+// With `sync`, the ticks are the page's, not the reader's: every checklist block on the page reads
+// and writes one shared set through ./checklist-sync.ts, and falls back to the localStorage path
+// below when the host keeps no answers.
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
 import { CHECKLIST_SLOT, checklistStorageKey } from '../artifacts/checklist.js';
+import { SERVER_SYNC_SNAPSHOT, syncStoreFor } from './checklist-sync.js';
 function readTick(key) {
     if (!key)
         return false;
@@ -34,21 +39,48 @@ function writeTick(key, on) {
         // Storage blocked: the tick lives for this visit only.
     }
 }
-export function Checklist({ items, artifactId, send, owner, accent, }) {
+const noopSubscribe = () => () => { };
+const nullSnapshot = () => null;
+const serverSnapshot = () => SERVER_SYNC_SNAPSHOT;
+const SYNC_WORDS = { loading: 'Connecting…', synced: 'Synced', saving: 'Saving…' };
+/** The quiet word after the count: where the shared set stands. */
+function SyncLabel({ s, color }) {
+    const words = s.status === 'error' ? (s.message ?? 'not saved') : s.status === 'sign-in' ? null : SYNC_WORDS[s.status];
+    return (_jsxs("span", { "data-checklist-sync": s.status, className: "normal-case tracking-normal opacity-70", children: [' · ', s.status === 'sign-in'
+                ? (s.signIn ? _jsx("a", { href: s.signIn, className: "underline", style: { color }, children: "Sign in to tick" }) : 'Ticking is open to signed-in readers')
+                : words] }));
+}
+export function Checklist({ items, artifactId, send, sync, owner, accent, }) {
     const key = useCallback((id) => (artifactId ? checklistStorageKey(artifactId, id) : null), [artifactId]);
-    const [done, setDone] = useState({});
+    const [local, setDone] = useState({});
     const [sent, setSent] = useState({ status: 'idle' });
+    const store = useMemo(() => (sync && artifactId ? syncStoreFor(artifactId) : null), [sync, artifactId]);
+    const shared = useSyncExternalStore(store ? store.subscribe : noopSubscribe, store ? store.snapshot : nullSnapshot, store ? serverSnapshot : nullSnapshot);
     // 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(() => {
+        if (store)
+            return;
         const next = {};
         for (const id of ids.split('\n'))
             if (readTick(key(id)))
                 next[id] = true;
         setDone(next);
-    }, [ids, key]);
+    }, [ids, key, store]);
+    // A synced block hands the page's store the ids it draws; the store reads and polls while any
+    // block on the page is mounted.
+    useEffect(() => {
+        if (!store)
+            return;
+        const block = {};
+        store.register(block, ids.split('\n'));
+        return () => store.unregister(block);
+    }, [store, ids]);
+    const done = shared ? Object.fromEntries([...shared.done].map((id) => [id, true])) : local;
     const toggle = (id) => {
+        if (store)
+            return store.toggle(id);
         setDone((d) => {
             const on = !d[id];
             writeTick(key(id), on);
@@ -87,7 +119,7 @@ export function Checklist({ items, artifactId, send, owner, accent, }) {
             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) => {
+    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: [_jsxs("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`, shared && shared.status !== 'local' ? _jsx(SyncLabel, { s: shared, color: color }) : null] }), _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));

package/package.json

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