@supersuit/artifacts 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 `@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.4.0 (2026-09-26)
+
+**Light and dark modes, a table of contents, and an animated ground.**
+
+- **Modes.** `BrandPack` gains `light` (a second palette), `mode` (`light`, `dark` or `system`,
+  default `dark`) and `backdrop`. A page may override the mode with `theme:` in its front matter.
+  Every colour the page draws is now a CSS variable set by `BrandGround` for the mode, so `system`
+  follows the reader's device. `freedomDefault` carries a light palette.
+- **Table of contents.** Built from the page's `##` headings: a sticky rail in the left margin at
+  `xl` widths, highlighting the section being read, and a closed "Contents" list above the body
+  below that. Both are `data-nospeak`. It appears once a page has four sections; `toc: false`
+  removes it and `toc: true` draws it from one. Every heading now carries its slug as an `id`,
+  with or without the notes widget.
+- **Bubbles.** `backdrop: { kind: 'bubbles' }` draws drifting colour behind the page in plain CSS,
+  held still under `prefers-reduced-motion`. A pack with its own `Wrapper` draws its own ground
+  and ignores `backdrop`.
+- **Long words wrap.** The body is `break-words`, so a bare URL in prose no longer pushes a phone
+  sideways (a 390px screen scrolled 7px on the first page checked).
+- **DETECTOR:** a page's root carries `data-artifact-theme`; an open page with four sections
+  carries `data-artifact-toc`. A host whose pages still show zinc-on-black text in a light mode is
+  building from a Tailwind `content` list that does not scan this package's `lib/`.
+- **REMEDY:** none required. A pack with no `mode` keeps its dark look, and `theme`/`toc` are new
+  optional keys. A host whose publisher strips unknown front matter keys must forward `theme` and
+  `toc` for pages to set them.
+- **Tests:** theme CSS per mode and the fallback light palette; the ground, the wrapper-pack path
+  and the backdrop; `theme` and `toc` parsed, refused, stored and cleared on republish; heading ids
+  without notes; the route's mode and both contents placements.
+
+## 0.3.0 (2026-09-25)
+
+**Notes, the first widget.** A ```` ```notes ```` block in a page puts a small "note" control
+beside every heading, so readers can leave notes on a section and, on a `shared` page, read each
+other's. Poll, form and checklist follow in a later release.
+
+- **Fence:** ```` ```notes ```` with an optional `visibility: private | shared` line. At most one
+  per page. It declares slot `notes` of shape `many` itself, merged into `state:` at parse time
+  (a page with no `state:` gets `writers: signed-in`, `visibility: private`), so the 0.2.0 state
+  API takes notes unchanged. Refused at publish with the file's line number: a second block, a
+  name, an unknown key, `tally`, a `notes` slot declared `one`, a visibility that disagrees with
+  `state:`. `poll`, `form` and `checklist` fences are refused until they ship.
+- **A note is `{ slug, heading, note }`**, checked by the server on a page with a notes block.
+  Headings carry their GitHub-style slug as an `id`; the renderer finds each heading by its source
+  line, so the slug on the page and the slug a note stores come from one derivation.
+- **A renamed or removed heading keeps its notes**, shown under "Notes on earlier versions" with
+  the heading they were left under, never attached to another section.
+- **Narration skips the widget**: the fence is not spoken and everything drawn is `data-nospeak`.
+- **Password pages with `state:`** now set the answer API's unlock cookie on every open, not only
+  on `?key=`. Readers who unlocked such a page before 0.2.0 are no longer refused (the item parked
+  in 0.2.0).
+- **The replace-at-cap check** reads one document (`StateStore.hasOne`, optional, implemented by
+  both shipped stores) instead of every answer on the page.
+- **DETECTOR:** a page with a notes block published to a host with no state store gets `warning:
+  this host keeps no answers` and draws no controls. A notes page whose readers see no "note"
+  button beside its headings is on 0.2.0 or earlier.
+- **REMEDY (hosts):** take 0.3.0. No new routes: the notes widget uses the 0.2.0 state routes
+  (`app/api/artifacts/[id]/state/route.ts`), which a host must already mount. A host with its own
+  `StateStore` may add `hasOne`; without it the old full read is used.
+- **Tests:** `widgets.test.ts` (slugs, fence parsing, one per page, reserved widgets, merge,
+  note shape, placement), `front-matter.test.ts` (line numbers in the file, the first real page's
+  front matter), `render.test.tsx` (controls beside headings, fence never drawn as code),
+  `widgets/notes.test.tsx` (jsdom: shared notes under their heading, earlier versions, posting
+  appends `{ slug, heading, note }`, sign-in offer, removal, no-store host), `narration.test.ts`,
+  `state.test.tsx` (note shape refused, shared read, `hasOne` path), `artifacts.test.tsx` (API
+  cookie on every open, page wiring, publish refusal), `state-store.test.ts` (`hasOne`), and the
+  packed fixture (a notes page draws its controls, a note posts and reads back, a malformed one is
+  refused, the compiled widget keeps `'use client'`).
+
 ## 0.2.0 (2026-09-24)
 
 **Reader answers.** A page can now take input from the people reading it. It declares named

package/README.md

@@ -25,7 +25,8 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `createArtifactAssets(bucket, prefix)` | Uploaded images for a page, in a Cloud Storage bucket |
 | `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
 | `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 |
+| `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 |
 | `mintPass`, `verifyPass` | The reader pass, for the sign-in side (see below) |
 | `ARTIFACT_PUBLIC_PREFIXES` (`/gate`) | Paths to leave open if you mount artifacts inside a gated site |
 
@@ -129,6 +130,8 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `voice`, `narration`, `timings`, `narrationHash` | Read-aloud: the audio and word timings a publisher generated. Absent, no player |
 | `password` | Shuts the body behind a door (below) |
 | `access` | `freedom`, `invite` or `public`: a confidential page (below) |
+| `theme` | `light`, `dark` or `system` (follow the reader's device). Overrides the brand pack's mode for this page |
+| `toc` | The table of contents. Absent, it appears once the page has four `##` sections; `false` never; `true` from one |
 | `template` | `document`, the only one so far |
 
 An unknown key is refused, so a typo fails loudly instead of being ignored.
@@ -285,6 +288,55 @@ On a proxy other than Vercel's, pass `clientIp` to `createArtifactRoutes` (used
 rate limit): the default reads the first hop of `x-forwarded-for`, which Vercel overwrites with
 the real client IP but another proxy may only append to.
 
+## Widgets in a page
+
+A widget is a fenced block in a page's markdown that gives readers a place to answer, drawn by
+the shell in the page's brand and kept through the state API above. Widgets need a host with a
+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.
+
+### Notes
+
+````markdown
+## Sales
+
+The weekly pipeline review.
+
+```notes
+visibility: shared   # optional: private | shared
+```
+````
+
+- **A small "note" control sits beside every heading.** A reader opens it, writes, and saves. The
+  note appears under that heading; with `visibility: shared` every reader sees every note with
+  the writer's first name ("a reader" for a signed-out one), with `private` each reader sees only
+  their own and the publisher sees all through `/responses`.
+- **At most one notes block per page.** Where it sits is where the page shows "Notes on earlier
+  versions" (below).
+- **The block declares its own slot**: `notes`, shape `many`. A page needs no `state:` for it;
+  without one the page takes `writers: signed-in` and `visibility: private`. A page may declare
+  the slot itself (`slots: { notes: { shape: many } }`) and set `writers:` and `visibility:` as
+  usual. Refused at publish, naming the line in the file: a second notes block, a name after
+  `notes`, any key but `visibility`, `visibility: tally`, a `notes` slot declared `shape: one`,
+  and a block visibility that disagrees with one `state:` sets on the `notes` slot.
+- **A note is `{ slug, heading, note }`**: the slug and the text of the heading it was left under,
+  and up to 4,000 characters of text. On a page with a notes block the server refuses any other
+  shape in the `notes` slot. Slugs follow GitHub's rule (lowercase, punctuation dropped, spaces
+  to dashes, a repeated heading `-1`, `-2`), and each heading carries its slug as its `id`, so
+  `#sales` links to it.
+- **Notes survive a changed heading.** A note shows under the heading with its slug; failing
+  that, under a heading with exactly its text; otherwise under "Notes on earlier versions", with
+  the heading it was left under. It never attaches to a different section.
+- **Narration skips it.** The fence is not prose, and everything the widget draws is marked
+  `data-nospeak`, so the narrator and the read-along highlighter read the page as before.
+- On a gated page (`access:`) only signed-in readers the page is open to, after the agreement,
+  can leave or read notes; the banner, watermark and print refusal are unchanged. On a public
+  page with `writers: signed-in`, the control offers sign-in through `signInOrigin`.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,
@@ -292,6 +344,20 @@ the narrator label, an optional full-page `Wrapper` and `Mark`, and an optional
 (a font loader and a backdrop) that draws the unfurl card. `freedomDefault` is the default look.
 Keep a pack carrying your own trademark in your own app, not in a pull request here.
 
+**Light, dark or system.** A pack's `ground`, `ink` and `accent` are its dark palette; `light` is
+the other one (absent, warm paper with the pack's accent), and `mode` is the one a page opens in
+(`dark` by default; a page's `theme:` overrides it). Pages paint with CSS variables
+(`--a-ground`, `--a-ink`, `--a-accent` and tones derived from them), which is what lets `system`
+follow the device.
+
+**An animated ground.** `backdrop: { kind: 'bubbles', colors?, veil? }` draws soft colour drifting
+behind the page under a veil of the ground, in plain CSS, still for readers who ask for reduced
+motion. `colors` are `r,g,b` triplets (default `GLOW_PASTELS`); `veil` is 0 to 1 (default 0.4).
+
+```ts
+const pack: BrandPack = { ...freedomDefault, mode: 'light', backdrop: { kind: 'bubbles' } }
+```
+
 ## Environment
 
 | Variable | Used for |

package/lib/artifacts/front-matter.d.ts

@@ -1,5 +1,6 @@
 import { type Access } from './reader.js';
 import { type StateConfig } from './state.js';
+import { type ThemeMode } from '../brand/theme.js';
 export type ArtifactMeta = {
     title: string;
     summary: string;
@@ -27,6 +28,10 @@ export type ArtifactMeta = {
     /** What readers may put into the page. Content, like the body: a republish without it removes
      *  the slots from the page and KEEPS the answers already given. */
     state?: StateConfig;
+    /** Light, dark, or the reader's device, overriding the brand pack's mode for this page. */
+    theme?: ThemeMode;
+    /** The table of contents: absent draws it once the page has four sections, false never. */
+    toc?: boolean;
 };
 export declare function parseArtifactSource(text: string): {
     ok: true;

package/lib/artifacts/front-matter.js

@@ -3,7 +3,9 @@
 import matter from 'gray-matter';
 import { ACCESS_LEVELS } from './reader.js';
 import { parseStateConfig } from './state.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state']);
+import { mergeWidgetState, scanWidgets } from './widgets.js';
+import { THEME_MODES } from '../brand/theme.js';
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -34,11 +36,33 @@ export function parseArtifactSource(text) {
             return { ok: false, error: `access must be one of: public, ${ACCESS_LEVELS.join(', ')}` };
         meta.access = d.access;
     }
+    if (d.theme !== undefined) {
+        if (!THEME_MODES.includes(d.theme))
+            return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
+        meta.theme = d.theme;
+    }
+    if (d.toc !== undefined) {
+        if (typeof d.toc !== 'boolean')
+            return { ok: false, error: 'toc must be true or false' };
+        meta.toc = d.toc;
+    }
     if (d.state !== undefined) {
         const s = parseStateConfig(d.state);
         if (!s.ok)
             return { ok: false, error: s.error };
         meta.state = s.state;
     }
+    // Widgets declare their own slots, so a notes block 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);
+    if (!merged.ok)
+        return { ok: false, error: merged.error };
+    if (merged.state)
+        meta.state = merged.state;
     return { ok: true, meta, body: content };
 }

package/lib/artifacts/index.d.ts

@@ -10,3 +10,4 @@ export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type Flag
 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, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';

package/lib/artifacts/index.js

@@ -10,3 +10,4 @@ export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';
 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, scanWidgets, mergeWidgetState, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';

package/lib/artifacts/notes-place.d.ts

@@ -0,0 +1,27 @@
+export declare const NOTES_SLOT = "notes";
+export declare const MAX_NOTE_CHARS = 4000;
+export type Heading = {
+    depth: number;
+    line: number;
+    text: string;
+    slug: string;
+};
+export type NoteValue = {
+    slug: string;
+    heading: string;
+    note: string;
+};
+/** A note as a reader's page holds it: the stored value plus who and when. */
+export type PlacedNote = NoteValue & {
+    id: string;
+    name: string;
+    at: string;
+    mine: boolean;
+};
+/** Where each note shows: under the heading with its slug, else under a heading with its exact
+ *  text (a repeated heading renumbered), else under "notes on earlier versions". Never under a
+ *  heading that merely looks close: a note on the wrong section is worse than one set aside. */
+export declare function placeNotes(headings: Pick<Heading, 'slug' | 'text'>[], notes: PlacedNote[]): {
+    bySlug: Record<string, PlacedNote[]>;
+    earlier: PlacedNote[];
+};

package/lib/artifacts/notes-place.js

@@ -0,0 +1,25 @@
+// Where each note on a page shows, and the few names both sides share. Kept free of the
+// markdown parser on purpose: the notes widget runs in the reader's browser and imports this,
+// and the parser has no business in that bundle.
+export const NOTES_SLOT = 'notes';
+export const MAX_NOTE_CHARS = 4000;
+/** Where each note shows: under the heading with its slug, else under a heading with its exact
+ *  text (a repeated heading renumbered), else under "notes on earlier versions". Never under a
+ *  heading that merely looks close: a note on the wrong section is worse than one set aside. */
+export function placeNotes(headings, notes) {
+    const bySlug = {};
+    const earlier = [];
+    const slugs = new Set(headings.map((h) => h.slug));
+    const byText = new Map();
+    for (const h of headings)
+        if (!byText.has(h.text))
+            byText.set(h.text, h.slug);
+    for (const n of notes) {
+        const at = slugs.has(n.slug) ? n.slug : byText.get(n.heading);
+        if (at)
+            (bySlug[at] ??= []).push(n);
+        else
+            earlier.push(n);
+    }
+    return { bySlug, earlier };
+}

package/lib/artifacts/render.d.ts

@@ -1,4 +1,10 @@
 export declare function isReachableHref(href: unknown): href is string;
-export declare function ArtifactMarkdown({ markdown }: {
+/** `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 }: {
     markdown: string;
+    notes?: {
+        artifactId: string;
+        accent?: string;
+    };
 }): import("react").JSX.Element;

package/lib/artifacts/render.js

@@ -1,7 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
-const GOLD = '#C2A15C';
+import { hasNotesWidget, headingsOf } from './widgets.js';
+import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
+// Every colour is a theme variable (brand/theme.ts), so a page follows its light, dark or system mode.
+const GOLD = 'var(--a-accent)';
 function hostOf(url) {
     try {
         return new URL(url).host.replace(/^www\./, '');
@@ -31,7 +34,7 @@ function LinkCards({ source }) {
         const [url, ...rest] = l.split('|');
         return { url: url.trim(), note: rest.join('|').trim() };
     });
-    return (_jsx("ul", { "data-artifact-links": true, className: "my-6 grid list-none gap-3 p-0", children: rows.map((r) => (_jsx("li", { className: "m-0 p-0", children: _jsxs("a", { href: r.url, target: "_blank", rel: "noopener noreferrer", className: "block rounded-lg border border-white/10 bg-white/[0.03] px-4 py-3 no-underline transition-colors hover:border-white/25", children: [_jsx("span", { className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: hostOf(r.url) }), _jsx("span", { className: "block text-zinc-100", children: r.note || r.url })] }) }, r.url))) }));
+    return (_jsx("ul", { "data-artifact-links": true, className: "my-6 grid list-none gap-3 p-0", children: rows.map((r) => (_jsx("li", { className: "m-0 p-0", children: _jsxs("a", { href: r.url, target: "_blank", rel: "noopener noreferrer", className: "block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3 no-underline transition-colors hover:border-[color:var(--a-line-strong)]", children: [_jsx("span", { className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: hostOf(r.url) }), _jsx("span", { className: "block text-[color:var(--a-strong)]", children: r.note || r.url })] }) }, r.url))) }));
 }
 const CALLOUT = /^\[!(note|warning)\]\s*/i;
 // A link the reader can actually follow: absolute, a scheme like mailto:, a
@@ -43,26 +46,27 @@ export function isReachableHref(href) {
     return typeof href === 'string' && REACHABLE.test(href);
 }
 const components = {
-    h1: ({ children }) => _jsx("h1", { className: "mt-10 mb-4 font-serif text-3xl text-zinc-50", children: children }),
-    h2: ({ children }) => _jsx("h2", { className: "mt-10 mb-3 font-serif text-2xl text-zinc-50", children: children }),
-    h3: ({ children }) => _jsx("h3", { className: "mt-8 mb-2 text-lg font-semibold text-zinc-100", children: children }),
     p: ({ children }) => _jsx("p", { className: "my-4 leading-relaxed", children: children }),
     ul: ({ children }) => _jsx("ul", { className: "my-4 list-disc space-y-1 pl-6", children: children }),
     ol: ({ children }) => _jsx("ol", { className: "my-4 list-decimal space-y-1 pl-6", children: children }),
-    hr: () => _jsx("hr", { className: "my-10 border-white/10" }),
+    hr: () => _jsx("hr", { className: "my-10 border-[color:var(--a-line)]" }),
     table: ({ children }) => (_jsx("div", { className: "my-6 overflow-x-auto", children: _jsx("table", { className: "w-full border-collapse text-sm", children: children }) })),
-    th: ({ children }) => (_jsx("th", { className: "border-b border-white/20 px-3 py-2 text-left font-semibold text-zinc-100", children: children })),
-    td: ({ children }) => _jsx("td", { className: "border-b border-white/10 px-3 py-2 align-top", children: children }),
+    th: ({ children }) => (_jsx("th", { className: "border-b border-[color:var(--a-line-strong)] px-3 py-2 text-left font-semibold text-[color:var(--a-strong)]", children: children })),
+    td: ({ children }) => _jsx("td", { className: "border-b border-[color:var(--a-line)] px-3 py-2 align-top", children: children }),
     img: ({ src, alt }) => (
     // 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-white/10" })),
-    a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, target: "_blank", rel: "noopener noreferrer", className: "text-zinc-50 underline decoration-white/30 underline-offset-4 hover:decoration-white", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-zinc-500", children: ["(", hostOf(href), ")"] })) : null] })),
+    _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 }) => {
         const lang = /language-(\w+)/.exec(className ?? '')?.[1];
         if (lang === 'links')
             return _jsx(LinkCards, { source: textOf(children) });
+        // 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')
+            return null;
         if (!className) {
-            return _jsx("code", { className: "rounded bg-white/10 px-1.5 py-0.5 text-[0.9em] text-zinc-100", children: children });
+            return _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 });
         }
         return _jsx("code", { className: className, children: children });
     },
@@ -70,21 +74,67 @@ const components = {
         // 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/.test(cls))
+        if (/language-(links|notes)/.test(cls))
             return _jsx(_Fragment, { children: children });
-        return (_jsx("pre", { "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-white/10 bg-black/40 p-4 text-sm text-zinc-100", children: children }));
+        return (_jsx("pre", { "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-code)] p-4 text-sm text-[color:var(--a-strong)]", children: children }));
     },
     blockquote: ({ children }) => {
         const t = textOf(children).trim();
         const m = CALLOUT.exec(t);
         if (!m) {
-            return (_jsx("blockquote", { className: "my-6 border-l-2 pl-4 italic text-zinc-300", style: { borderColor: GOLD }, children: children }));
+            return (_jsx("blockquote", { className: "my-6 border-l-2 pl-4 italic text-[color:var(--a-body)]", style: { borderColor: GOLD }, children: children }));
         }
         const kind = m[1].toLowerCase();
         const body = t.replace(CALLOUT, '');
-        return (_jsxs("aside", { "data-callout": kind, className: "my-6 rounded-lg border px-4 py-3", style: { borderColor: kind === 'warning' ? '#d97706' : GOLD, background: 'rgba(255,255,255,0.03)' }, children: [_jsx("span", { "data-nospeak": true, className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: kind }), _jsx("p", { className: "mt-1 text-zinc-100", children: body })] }));
+        return (_jsxs("aside", { "data-callout": kind, className: "my-6 rounded-lg border px-4 py-3", style: { borderColor: kind === 'warning' ? '#d97706' : GOLD, background: 'var(--a-surface)' }, children: [_jsx("span", { "data-nospeak": true, className: "block text-[11px] uppercase tracking-[0.2em]", style: { color: GOLD }, children: kind }), _jsx("p", { className: "mt-1 text-[color:var(--a-strong)]", children: body })] }));
     },
 };
-export function ArtifactMarkdown({ markdown }) {
-    return (_jsx("div", { className: "text-[17px] text-zinc-200", children: _jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: components, children: markdown }) }));
+// scroll-mt keeps a heading clear of the top of the screen when a contents link jumps to it.
+const HEADING_CLASS = {
+    1: 'mt-10 mb-4 scroll-mt-24 font-serif text-3xl text-[color:var(--a-strong)]',
+    2: 'mt-10 mb-3 scroll-mt-24 font-serif text-2xl text-[color:var(--a-strong)]',
+    3: 'mt-8 mb-2 scroll-mt-24 text-lg font-semibold text-[color:var(--a-strong)]',
+    4: 'mt-6 mb-2 scroll-mt-24 font-semibold text-[color:var(--a-strong)]',
+    5: 'mt-6 mb-2 scroll-mt-24 font-semibold text-[color:var(--a-strong)]',
+    6: 'mt-6 mb-2 scroll-mt-24 font-semibold text-[color:var(--a-strong)]',
+};
+/** 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) {
+    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, className: HEADING_CLASS[depth], children: children });
+    };
+    return { ...components, 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) {
+    const byLine = new Map(headings.map((h) => [h.line, h]));
+    const heading = (depth) => function NotedHeading({ node, children }) {
+        const Tag = `h${depth}`;
+        const h = byLine.get(node?.position?.start.line ?? -1);
+        if (!h)
+            return _jsx(Tag, { className: HEADING_CLASS[depth], children: children });
+        return (_jsxs(_Fragment, { children: [_jsxs(Tag, { id: h.slug, className: HEADING_CLASS[depth], children: [children, _jsx(NoteToggle, { slug: h.slug })] }), _jsx(HeadingNotes, { slug: h.slug, text: h.text })] }));
+    };
+    const Code = components.code;
+    return {
+        ...components,
+        h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6),
+        code: (props) => (/language-notes/.test(props.className ?? '') ? _jsx(NotesEarlier, {}) : _jsx(Code, { ...props })),
+    };
+}
+/** `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 }) {
+    const on = !!notes && hasNotesWidget(markdown);
+    const headings = headingsOf(markdown);
+    const body = (_jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: on ? notesComponents(headings) : pageComponents(headings), children: markdown }));
+    return (
+    // break-words: a bare URL in prose is one unbreakable word and pushed phones 7px sideways (2026-09-26).
+    _jsx("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 }));
 }

package/lib/artifacts/state-store.d.ts

@@ -49,6 +49,9 @@ export interface StateStore {
     countAnonWrite(artifactId: string, ipHash: string, minute: number): Promise<number>;
     /** Every reader's entries in one slot on one page, for MAX_ENTRIES_PER_SLOT. */
     countSlot(artifactId: string, slot: string): Promise<number>;
+    /** Does this reader already hold a `one` answer in this slot? One document read. Optional so a
+     *  host's own store keeps working; without it the route falls back to loading the page. */
+    hasOne?(artifactId: string, slot: string, readerKey: string): Promise<boolean>;
 }
 export declare const readerKeyFor: {
     signedIn: (uid: string) => string;

package/lib/artifacts/state-store.js

@@ -89,6 +89,7 @@ export function createStateStore(db, base) {
         async countSlot(artifactId, slot) {
             return (await col().where('artifactId', '==', artifactId).where('slot', '==', slot).count().get()).data().count;
         },
+        hasOne: async (artifactId, slot, readerKey) => (await col().doc(oneId(artifactId, slot, readerKey)).get()).exists,
     };
     return store;
 }
@@ -147,5 +148,6 @@ export function createMemoryStateStore() {
             return n;
         },
         countSlot: async (artifactId, slot) => of(artifactId).filter((e) => e.slot === slot).length,
+        hasOne: async (artifactId, slot, readerKey) => docs.has(oneId(artifactId, slot, readerKey)),
     };
 }

package/lib/artifacts/store.d.ts

@@ -2,6 +2,7 @@ import { type Firestore } from 'firebase-admin/firestore';
 import type { ArtifactMeta } from './front-matter.js';
 import type { Access } from './reader.js';
 import type { StateConfig } from './state.js';
+import type { ThemeMode } from '../brand/theme.js';
 export type ArtifactRecord = {
     id: string;
     title: string;
@@ -17,6 +18,8 @@ export type ArtifactRecord = {
     password?: string;
     access?: Access;
     state?: StateConfig;
+    theme?: ThemeMode;
+    toc?: boolean;
     markdown: string;
     createdAt: string;
     updatedAt: string;

package/lib/artifacts/store.js

@@ -57,6 +57,8 @@ async function saveArtifact(col, input) {
         ...(input.meta.password ? { password: input.meta.password } : {}),
         ...(input.meta.access && input.meta.access !== 'public' ? { access: input.meta.access } : {}),
         ...(input.meta.state ? { state: input.meta.state } : {}),
+        ...(input.meta.theme ? { theme: input.meta.theme } : {}),
+        ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
     };
     if (input.id) {
         const existing = await getArtifact(col, input.id);
@@ -82,8 +84,13 @@ async function saveArtifact(col, input) {
         const access = input.meta.access === 'public' ? { access: FieldValue.delete() } : {};
         // Content, like the body: a republish that no longer declares state removes the slots.
         const state = input.meta.state ? {} : { state: FieldValue.delete() };
+        // How the page looks is content too: a line the file no longer carries goes back to the default.
+        const look = {
+            ...(input.meta.theme ? {} : { theme: FieldValue.delete() }),
+            ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
+        };
         await ref.update({
-            ...fields, ...password, ...subtitle, ...access, ...state, markdown: input.markdown, updatedAt: now, version: next,
+            ...fields, ...password, ...subtitle, ...access, ...state, ...look, markdown: input.markdown, updatedAt: now, version: next,
             ...(existing.versions ? { versions: FieldValue.delete() } : {}),
         });
         return { id: input.id, version: next, created: false };

package/lib/artifacts/toc-spy.d.ts

@@ -0,0 +1,3 @@
+export declare function TocSpy({ slugs }: {
+    slugs: string[];
+}): null;

package/lib/artifacts/toc-spy.js

@@ -0,0 +1,40 @@
+'use client';
+// Marks the contents entry for the section being read. Renders nothing: it only sets
+// aria-current on the links the server drew, which is also what styles them.
+import { useEffect } from 'react';
+export function TocSpy({ slugs }) {
+    const key = slugs.join('|');
+    useEffect(() => {
+        const ids = key.split('|');
+        let frame = 0;
+        const mark = () => {
+            frame = 0;
+            let current = ids[0];
+            for (const id of ids) {
+                const el = document.getElementById(id);
+                if (el && el.getBoundingClientRect().top <= 140)
+                    current = id;
+            }
+            document.querySelectorAll('a[data-toc-slug]').forEach((a) => {
+                if (a.dataset.tocSlug === current)
+                    a.setAttribute('aria-current', 'location');
+                else
+                    a.removeAttribute('aria-current');
+            });
+        };
+        const onScroll = () => {
+            if (!frame)
+                frame = requestAnimationFrame(mark);
+        };
+        mark();
+        window.addEventListener('scroll', onScroll, { passive: true });
+        window.addEventListener('resize', onScroll);
+        return () => {
+            window.removeEventListener('scroll', onScroll);
+            window.removeEventListener('resize', onScroll);
+            if (frame)
+                cancelAnimationFrame(frame);
+        };
+    }, [key]);
+    return null;
+}

package/lib/artifacts/toc.d.ts

@@ -0,0 +1,15 @@
+export type TocItem = {
+    slug: string;
+    text: string;
+};
+export declare function tocOf(markdown: string): TocItem[];
+/** `flag` is the page's `toc:`. Absent, the list appears once there are enough sections. */
+export declare function showToc(markdown: string, flag?: boolean): boolean;
+/** Wide screens: fixed in the left margin, so the reading column stays centred. */
+export declare function TocRail({ items }: {
+    items: TocItem[];
+}): import("react").JSX.Element;
+/** Narrow screens: a closed list above the body. */
+export declare function TocInline({ items }: {
+    items: TocItem[];
+}): import("react").JSX.Element;

package/lib/artifacts/toc.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The table of contents: the page's sections, as a sticky rail on a wide screen and a
+// collapsible list above the body on a narrow one. Both are marked data-nospeak so the
+// read-along never narrates them, and both link to the ids the renderer puts on headings,
+// which come from the same headingsOf the notes widget uses.
+import { headingsOf } from './widgets.js';
+import { TocSpy } from './toc-spy.js';
+/** Sections below this count read fine without a contents list. */
+const AUTO_MIN = 4;
+export function tocOf(markdown) {
+    return headingsOf(markdown).filter((h) => h.depth === 2).map(({ slug, text }) => ({ slug, text }));
+}
+/** `flag` is the page's `toc:`. Absent, the list appears once there are enough sections. */
+export function showToc(markdown, flag) {
+    if (flag === false)
+        return false;
+    const n = tocOf(markdown).length;
+    return flag === true ? n > 0 : n >= AUTO_MIN;
+}
+const LINK = 'block border-l-2 border-transparent py-1 pl-3 no-underline transition-colors text-[color:var(--a-muted)] hover:text-[color:var(--a-strong)] aria-[current=location]:border-[color:var(--a-accent)] aria-[current=location]:text-[color:var(--a-strong)]';
+function List({ items }) {
+    return (_jsx("ol", { className: "m-0 list-none space-y-0.5 p-0 text-sm leading-snug", children: items.map((i) => (_jsx("li", { className: "m-0 p-0", children: _jsx("a", { href: `#${i.slug}`, "data-toc-slug": i.slug, className: LINK, children: i.text }) }, i.slug))) }));
+}
+/** Wide screens: fixed in the left margin, so the reading column stays centred. */
+export function TocRail({ items }) {
+    return (_jsxs("nav", { "data-nospeak": true, "data-artifact-toc": "rail", "aria-label": "Contents", className: "fixed top-28 left-6 z-10 hidden max-h-[calc(100vh-10rem)] w-56 overflow-y-auto xl:block 2xl:left-12 2xl:w-64", children: [_jsx("p", { className: "mb-3 pl-3 text-[11px] font-medium uppercase tracking-[0.25em] text-[color:var(--a-accent)]", children: "Contents" }), _jsx(List, { items: items }), _jsx(TocSpy, { slugs: items.map((i) => i.slug) })] }));
+}
+/** Narrow screens: a closed list above the body. */
+export function TocInline({ items }) {
+    return (_jsxs("details", { "data-nospeak": true, "data-artifact-toc": "inline", className: "mb-8 rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3 xl:hidden", children: [_jsx("summary", { className: "cursor-pointer text-[11px] font-medium uppercase tracking-[0.25em] text-[color:var(--a-accent)]", children: "Contents" }), _jsx("div", { className: "mt-3", children: _jsx(List, { items: items }) })] }));
+}