@supersuit/artifacts 0.2.0 → 0.4.0

package/lib/artifacts/widgets.d.ts

@@ -0,0 +1,38 @@
+import type { StateConfig, Visibility } from './state.js';
+import { type Heading } from './notes-place.js';
+export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes, type Heading, type NoteValue, type PlacedNote } from './notes-place.js';
+export type NotesWidget = {
+    line: number;
+    visibility?: Exclude<Visibility, 'tally'>;
+};
+/** GitHub's rule: lowercase, drop everything but letters, digits, spaces, dashes and
+ *  underscores, spaces to dashes. A heading of only punctuation is `section`. */
+export declare function slugify(text: string): string;
+/** Every heading in source order, with the line it starts on and a slug unique on the page
+ *  (a repeated heading gets `-1`, `-2`). The renderer finds a heading here by its line, so the
+ *  slug a note stores is exactly the slug the page draws. */
+export declare function headingsOf(markdown: string): Heading[];
+/** Finds the widget fences in a body. `offset` is how many lines of the file sit above the body
+ *  (the front matter), so every error names the line the author sees in their editor. */
+export declare function scanWidgets(body: string, offset: number): {
+    ok: true;
+    notes: NotesWidget | null;
+} | {
+    ok: false;
+    error: string;
+};
+/** 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
+ *  takes notes with no change and a republish's shape checks cover the slot. */
+export declare function mergeWidgetState(state: StateConfig | undefined, notes: NotesWidget | null): {
+    ok: true;
+    state: StateConfig | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/** Does this page's body carry a notes block? The state route asks, to check a note's shape. */
+export declare function hasNotesWidget(markdown: string): boolean;
+/** The server's check on a note, on a page with a notes block. The browser checks too; this is
+ *  the one that counts. */
+export declare function checkNoteValue(v: unknown): string | null;

package/lib/artifacts/widgets.js

@@ -0,0 +1,141 @@
+// Widgets: fenced blocks in a document's markdown that give readers a place to answer, drawn by
+// the shell in the page's brand and written through the state API (state.ts, state-routes.ts).
+//
+// This version draws ONE widget, `notes`: a small note control beside every heading, kept in the
+// `many` slot `notes`. A note stores the heading it was left under, both its slug and its text,
+// so a republish that renames or removes the heading keeps the note and shows it under "notes
+// on earlier versions" instead of losing it or attaching it to the wrong section.
+//
+// Everything here is pure and server-safe: parsing, publish-time validation, the heading slugs
+// the renderer and the stored notes agree on, and where each note is placed. The drawing lives
+// in ../widgets/notes.tsx.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { MAX_NOTE_CHARS, NOTES_SLOT } from './notes-place.js';
+export { MAX_NOTE_CHARS, NOTES_SLOT, placeNotes } from './notes-place.js';
+/** Widgets the design names and this version does not draw yet. A fence using one is refused at
+ *  publish, so a page never ships a code block that turns into a live widget on a later update. */
+const NOT_YET = ['poll', 'form', 'checklist'];
+const MAX_HEADING_CHARS = 300;
+const parse = (markdown) => unified().use(remarkParse).use(remarkGfm).parse(markdown);
+function inline(nodes) {
+    let out = '';
+    for (const n of nodes) {
+        if (n.type === 'text' || n.type === 'inlineCode')
+            out += n.value;
+        else if (n.type === 'break')
+            out += ' ';
+        else if ('children' in n)
+            out += inline(n.children);
+    }
+    return out;
+}
+function walk(nodes, visit) {
+    for (const n of nodes) {
+        visit(n);
+        if ('children' in n && n.type !== 'heading' && n.type !== 'paragraph')
+            walk(n.children, visit);
+    }
+}
+/** GitHub's rule: lowercase, drop everything but letters, digits, spaces, dashes and
+ *  underscores, spaces to dashes. A heading of only punctuation is `section`. */
+export function slugify(text) {
+    const s = text.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/\s/g, '-');
+    return s || 'section';
+}
+/** Every heading in source order, with the line it starts on and a slug unique on the page
+ *  (a repeated heading gets `-1`, `-2`). The renderer finds a heading here by its line, so the
+ *  slug a note stores is exactly the slug the page draws. */
+export function headingsOf(markdown) {
+    const out = [];
+    const seen = new Map();
+    walk(parse(markdown).children, (n) => {
+        if (n.type !== 'heading')
+            return;
+        const text = inline(n.children).replace(/\s+/g, ' ').trim();
+        const base = slugify(text);
+        const k = seen.get(base) ?? 0;
+        seen.set(base, k + 1);
+        out.push({ depth: n.depth, line: n.position?.start.line ?? 0, text, slug: k ? `${base}-${k}` : base });
+    });
+    return out;
+}
+/** Finds the widget fences in a body. `offset` is how many lines of the file sit above the body
+ *  (the front matter), so every error names the line the author sees in their editor. */
+export function scanWidgets(body, offset) {
+    const fences = [];
+    walk(parse(body).children, (n) => { if (n.type === 'code')
+        fences.push(n); });
+    let notes = null;
+    for (const f of fences) {
+        const line = (f.position?.start.line ?? 1) + offset;
+        if (f.lang && NOT_YET.includes(f.lang))
+            return { ok: false, error: `line ${line}: the ${f.lang} widget is not available in this version of the artifacts package` };
+        if (f.lang !== NOTES_SLOT)
+            continue;
+        if (notes)
+            return { ok: false, error: `line ${line}: a page takes at most one notes block` };
+        if (f.meta?.trim())
+            return { ok: false, error: `line ${line}: the notes block takes no name; it always writes to slot "notes"` };
+        const w = { line };
+        const rows = f.value ? f.value.split('\n') : [];
+        for (let i = 0; i < rows.length; i++) {
+            const raw = rows[i].replace(/#.*$/, '').trim();
+            if (!raw)
+                continue;
+            const at = line + 1 + i;
+            const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(raw);
+            if (!m)
+                return { ok: false, error: `line ${at}: the notes block takes lines like "visibility: shared"` };
+            if (m[1] !== 'visibility')
+                return { ok: false, error: `line ${at}: the notes block has an unknown key: ${m[1]}` };
+            if (m[2] !== 'private' && m[2] !== 'shared')
+                return { ok: false, error: `line ${at}: notes visibility must be private or shared` };
+            w.visibility = m[2];
+        }
+        notes = w;
+    }
+    return { ok: true, notes };
+}
+/** 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
+ *  takes notes with no change and a republish's shape checks cover the slot. */
+export function mergeWidgetState(state, notes) {
+    if (!notes)
+        return { ok: true, state };
+    const had = state?.slots[NOTES_SLOT];
+    if (had && had.shape !== 'many')
+        return { ok: false, error: `line ${notes.line}: the notes block writes to slot "notes" as shape many, and state: declares it shape ${had.shape}; rename that slot` };
+    if (had?.visibility && notes.visibility && had.visibility !== notes.visibility)
+        return { ok: false, error: `line ${notes.line}: the notes block says visibility ${notes.visibility} and state: says ${had.visibility} for slot "notes"; say it once` };
+    const slot = had
+        ? (notes.visibility && !had.visibility ? { ...had, visibility: notes.visibility } : had)
+        : { shape: 'many', ...(notes.visibility ? { visibility: notes.visibility } : {}) };
+    const base = state ?? { writers: 'signed-in', visibility: 'private', slots: {} };
+    if (slot === had)
+        return { ok: true, state: base };
+    return { ok: true, state: { ...base, slots: { ...base.slots, [NOTES_SLOT]: slot } } };
+}
+/** Does this page's body carry a notes block? The state route asks, to check a note's shape. */
+export function hasNotesWidget(markdown) {
+    const r = scanWidgets(markdown, 0);
+    return r.ok && r.notes !== null;
+}
+const SLUG = /^[\p{Ll}\p{Lo}\p{Lm}\p{N}_-]{1,120}$/u;
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** The server's check on a note, on a page with a notes block. The browser checks too; this is
+ *  the one that counts. */
+export function checkNoteValue(v) {
+    if (!isMap(v) || Object.keys(v).some((k) => !['slug', 'heading', 'note'].includes(k)))
+        return 'a note is { slug, heading, note }';
+    if (typeof v.slug !== 'string' || !SLUG.test(v.slug))
+        return 'a note needs the slug of the heading it is under';
+    if (typeof v.heading !== 'string' || v.heading.length > MAX_HEADING_CHARS)
+        return 'a note needs the heading it is under';
+    if (typeof v.note !== 'string' || !v.note.trim())
+        return 'a note needs some text';
+    if (v.note.length > MAX_NOTE_CHARS)
+        return `a note is at most ${MAX_NOTE_CHARS} characters`;
+    return null;
+}

package/lib/brand/backdrop.d.ts

@@ -0,0 +1,7 @@
+import type { Backdrop } from './pack.js';
+/** The Freedom Glow's colours (a blue core and the spectrum it separates into), mixed most of
+ *  the way to cream so a light page still reads as light. */
+export declare const GLOW_PASTELS: string[];
+export declare function Bubbles({ backdrop }: {
+    backdrop: Backdrop;
+}): import("react").JSX.Element;

package/lib/brand/backdrop.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The Freedom Glow's colours (a blue core and the spectrum it separates into), mixed most of
+ *  the way to cream so a light page still reads as light. */
+export const GLOW_PASTELS = ['150,190,255', '215,185,240', '160,225,220', '250,195,180', '250,215,160', '190,210,255'];
+// [animation, duration s, transform-origin] per bubble, after the original's six.
+const MOTION = [
+    ['a-bubble-v', 30, 'center center'],
+    ['a-bubble-c', 20, 'calc(50% - 400px) center'],
+    ['a-bubble-c', 40, 'calc(50% + 400px) center'],
+    ['a-bubble-h', 40, 'calc(50% - 200px) center'],
+    ['a-bubble-c', 20, 'calc(50% - 800px) calc(50% + 200px)'],
+    ['a-bubble-v', 35, 'calc(50% + 300px) calc(50% - 200px)'],
+];
+const CSS = `
+@keyframes a-bubble-v{0%,100%{transform:translateY(-50%)}50%{transform:translateY(50%)}}
+@keyframes a-bubble-c{0%{transform:rotate(0deg)}50%{transform:rotate(180deg)}100%{transform:rotate(360deg)}}
+@keyframes a-bubble-h{0%,100%{transform:translateX(-50%) translateY(-10%)}50%{transform:translateX(50%) translateY(10%)}}
+[data-artifact-backdrop] .a-bubble{position:absolute;width:80%;height:80%;top:10%;left:10%;border-radius:9999px;mix-blend-mode:hard-light;animation-timing-function:ease;animation-iteration-count:infinite}
+@media (prefers-reduced-motion: reduce){[data-artifact-backdrop] .a-bubble{animation:none!important}}
+`;
+export function Bubbles({ backdrop }) {
+    const colors = backdrop.colors?.length ? backdrop.colors : GLOW_PASTELS;
+    const veil = Math.round((backdrop.veil ?? 0.4) * 100);
+    return (_jsxs("div", { "data-artifact-backdrop": "bubbles", "aria-hidden": true, style: { position: 'fixed', inset: 0, zIndex: -1, overflow: 'hidden', background: 'var(--a-ground)', pointerEvents: 'none' }, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: CSS } }), _jsx("div", { style: { position: 'absolute', inset: 0, filter: 'blur(40px)' }, children: colors.map((c, i) => {
+                    const [name, secs, origin] = MOTION[i % MOTION.length];
+                    return (_jsx("div", { className: "a-bubble", style: {
+                            background: `radial-gradient(circle at center, rgba(${c},0.8) 0, rgba(${c},0) 50%)`,
+                            animationName: name,
+                            animationDuration: `${secs}s`,
+                            animationDirection: i % 2 ? 'reverse' : 'normal',
+                            transformOrigin: origin,
+                        } }, i));
+                }) }), _jsx("div", { style: { position: 'absolute', inset: 0, background: `color-mix(in srgb, var(--a-ground) ${veil}%, transparent)` } })] }));
+}

package/lib/brand/index.d.ts

@@ -1,3 +1,5 @@
-export { freedomDefault, type BrandPack, type ShareCardAssets } from './pack.js';
+export { freedomDefault, type BrandPack, type ShareCardAssets, type Palette, type Backdrop } from './pack.js';
 export { BrandGround, BrandMark } from './wrapper.js';
 export { renderShareCard } from './share-card.js';
+export { THEME_MODES, type ThemeMode, themeCss, themedPack, resolveMode } from './theme.js';
+export { GLOW_PASTELS } from './backdrop.js';

package/lib/brand/index.js

@@ -1,3 +1,5 @@
 export { freedomDefault } from './pack.js';
 export { BrandGround, BrandMark } from './wrapper.js';
 export { renderShareCard } from './share-card.js';
+export { THEME_MODES, themeCss, themedPack, resolveMode } from './theme.js';
+export { GLOW_PASTELS } from './backdrop.js';

package/lib/brand/pack.d.ts

@@ -1,4 +1,18 @@
 import type { ComponentType, ReactNode } from 'react';
+import type { ThemeMode } from './theme.js';
+/** One set of page colours. */
+export type Palette = {
+    ground: string;
+    ink: string;
+    accent: string;
+};
+/** The animated ground behind a page. `bubbles` is soft colour drifting under a veil of the
+ *  ground colour. Colours are `r,g,b` triplets. */
+export type Backdrop = {
+    kind: 'bubbles';
+    colors?: string[];
+    veil?: number;
+};
 /**
  * A brand pack is what makes an operator's pages theirs: data plus at most two
  * components. The package ships `freedomDefault`; an instance passes its own. A pack
@@ -7,10 +21,16 @@ import type { ComponentType, ReactNode } from 'react';
 export type BrandPack = {
     id: string;
     name: string;
-    /** CSS colours. */
+    /** CSS colours: the DARK palette, which is every pack's original one. */
     ground: string;
     ink: string;
     accent: string;
+    /** The light palette. Absent, a warm paper palette with this pack's accent is used. */
+    light?: Palette;
+    /** The mode a page opens in unless its front matter says otherwise. Default `dark`. */
+    mode?: ThemeMode;
+    /** An animated ground drawn behind the page. Ignored when the pack has its own Wrapper. */
+    backdrop?: Backdrop;
     /** CSS font-family values for headings and body. */
     type: {
         display: string;

package/lib/brand/pack.js

@@ -5,6 +5,7 @@ export const freedomDefault = {
     ground: '#0e0f13',
     ink: '#ece7dc',
     accent: '#c9a96e',
+    light: { ground: '#f6f1e7', ink: '#1c1a17', accent: '#8a6a2c' },
     type: {
         display: 'Georgia, "Iowan Old Style", "Times New Roman", serif',
         body: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',

package/lib/brand/theme.d.ts

@@ -0,0 +1,9 @@
+import type { BrandPack } from './pack.js';
+export declare const THEME_MODES: readonly ["light", "dark", "system"];
+export type ThemeMode = (typeof THEME_MODES)[number];
+export declare function resolveMode(pack: BrandPack, page?: ThemeMode): ThemeMode;
+/** The stylesheet for one pack: its two palettes, the tones derived from them, and the
+ *  device switch for `system`. */
+export declare function themeCss(pack: BrandPack): string;
+/** The pack as the page renders it: every colour is the variable the mode sets. */
+export declare function themedPack(pack: BrandPack): BrandPack;

package/lib/brand/theme.js

@@ -0,0 +1,30 @@
+export const THEME_MODES = ['light', 'dark', 'system'];
+/** The light palette a pack gets when it declares none: warm paper, near-black ink, and its
+ *  own accent, which every shipped accent is dark enough to read on. */
+const FALLBACK_LIGHT = { ground: '#f7f3ea', ink: '#1d1b17' };
+export function resolveMode(pack, page) {
+    return page ?? pack.mode ?? 'dark';
+}
+function vars(p, scheme) {
+    return `--a-ground:${p.ground};--a-ink:${p.ink};--a-accent:${p.accent};color-scheme:${scheme}`;
+}
+/** The stylesheet for one pack: its two palettes, the tones derived from them, and the
+ *  device switch for `system`. */
+export function themeCss(pack) {
+    const dark = { ground: pack.ground, ink: pack.ink, accent: pack.accent };
+    const light = pack.light ?? { ...FALLBACK_LIGHT, accent: pack.accent };
+    const mix = (n) => `color-mix(in srgb,var(--a-ink) ${n}%,var(--a-ground))`;
+    return [
+        `[data-artifact-theme]{--a-strong:var(--a-ink);--a-body:${mix(86)};--a-muted:${mix(55)};` +
+            `--a-line:${mix(12)};--a-line-strong:${mix(28)};--a-surface:${mix(4)};--a-surface-strong:${mix(9)};` +
+            `--a-code:${mix(6)};--a-on-accent:var(--a-ground)}`,
+        `[data-artifact-theme="dark"]{${vars(dark, 'dark')}}`,
+        `[data-artifact-theme="light"]{${vars(light, 'light')}}`,
+        `[data-artifact-theme="system"]{${vars(dark, 'dark')}}`,
+        `@media (prefers-color-scheme: light){[data-artifact-theme="system"]{${vars(light, 'light')}}}`,
+    ].join('\n');
+}
+/** The pack as the page renders it: every colour is the variable the mode sets. */
+export function themedPack(pack) {
+    return { ...pack, ground: 'var(--a-ground)', ink: 'var(--a-ink)', accent: 'var(--a-accent)' };
+}

package/lib/brand/wrapper.d.ts

@@ -1,8 +1,12 @@
 import type { ReactNode } from 'react';
 import type { BrandPack } from './pack.js';
-/** The page backdrop: the pack's own Wrapper when it has one, else a flat ground. */
-export declare function BrandGround({ pack, children }: {
+import { type ThemeMode } from './theme.js';
+/** The page backdrop: the pack's own Wrapper when it has one, else its ground (and its animated
+ *  backdrop, when it declares one). Either way the colour variables for the mode are set here,
+ *  so everything inside paints with them. `mode` is the page's override of the pack's. */
+export declare function BrandGround({ pack, mode, children }: {
     pack: BrandPack;
+    mode?: ThemeMode;
     children: ReactNode;
 }): import("react").JSX.Element;
 /** The mark above the kicker: the pack's own, else a small dove. */

package/lib/brand/wrapper.js

@@ -1,9 +1,19 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/** The page backdrop: the pack's own Wrapper when it has one, else a flat ground. */
-export function BrandGround({ pack, children }) {
-    if (pack.Wrapper)
-        return _jsx(pack.Wrapper, { children: children });
-    return (_jsx("div", { "data-brand-ground": pack.id, className: "min-h-screen", style: { background: pack.ground, color: pack.ink, fontFamily: pack.type.body }, children: children }));
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bubbles } from './backdrop.js';
+import { resolveMode, themeCss } from './theme.js';
+/** The page backdrop: the pack's own Wrapper when it has one, else its ground (and its animated
+ *  backdrop, when it declares one). Either way the colour variables for the mode are set here,
+ *  so everything inside paints with them. `mode` is the page's override of the pack's. */
+export function BrandGround({ pack, mode, children }) {
+    const m = resolveMode(pack, mode);
+    const css = _jsx("style", { dangerouslySetInnerHTML: { __html: themeCss(pack) } });
+    if (pack.Wrapper) {
+        // display:contents keeps the wrapper's own layout; custom properties still inherit through it.
+        return (_jsxs("div", { "data-artifact-theme": m, style: { display: 'contents' }, children: [css, _jsx(pack.Wrapper, { children: children })] }));
+    }
+    return (_jsxs("div", { "data-brand-ground": pack.id, "data-artifact-theme": m, className: "min-h-screen", 
+        // isolation puts the fixed backdrop (z-index -1) above this ground and below the page.
+        style: { background: 'var(--a-ground)', color: 'var(--a-ink)', fontFamily: pack.type.body, position: 'relative', isolation: 'isolate' }, children: [css, pack.backdrop?.kind === 'bubbles' ? _jsx(Bubbles, { backdrop: pack.backdrop }) : null, children] }));
 }
 /** The mark above the kicker: the pack's own, else a small dove. */
 export function BrandMark({ pack, className }) {

package/lib/reader/artifact-reader.js

@@ -152,14 +152,14 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
     };
     return (_jsxs(_Fragment, { children: [_jsx("style", { children: `
         .artifact-word { border-radius: 3px; transition: background-color 120ms; }
-        .artifact-word:hover { background: rgba(255,255,255,0.08); cursor: pointer; }
-        .artifact-word-lit { background: ${accent}59; color: #fff; }
-      ` }), _jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => setPlaying(true), onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx("div", { className: "fixed inset-x-0 bottom-0 z-40 border-t border-white/10 backdrop-blur", style: { background: `${ground}e6` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: narrator }), _jsx("input", { type: "range", min: 0, max: dur || 0, step: 0.1, value: Math.min(t, dur || 0), onChange: (e) => {
+        .artifact-word:hover { background: var(--a-surface-strong, rgba(255,255,255,0.08)); cursor: pointer; }
+        .artifact-word-lit { background: color-mix(in srgb, ${accent} 35%, transparent); color: var(--a-strong, #fff); }
+      ` }), _jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => setPlaying(true), onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx("div", { className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: narrator }), _jsx("input", { type: "range", min: 0, max: dur || 0, step: 0.1, value: Math.min(t, dur || 0), onChange: (e) => {
                                         if (audioRef.current)
                                             audioRef.current.currentTime = Number(e.target.value);
-                                    }, "aria-label": "Seek", className: "mt-1 w-full", style: { accentColor: accent } })] }), _jsxs("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-zinc-400", children: [fmt(t), " / ", fmt(dur)] }), _jsxs("button", { type: "button", onClick: () => {
+                                    }, "aria-label": "Seek", className: "mt-1 w-full", style: { accentColor: accent } })] }), _jsxs("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: [fmt(t), " / ", fmt(dur)] }), _jsxs("button", { type: "button", onClick: () => {
                                 const next = rate >= 1.5 ? 1 : rate + 0.25;
                                 if (audioRef.current)
                                     audioRef.current.playbackRate = next;
-                            }, className: "shrink-0 rounded border border-white/15 px-2 py-1 text-xs text-zinc-300", "aria-label": "Playback speed", children: [rate, "x"] })] }) }), _jsx("div", { className: "h-20", "aria-hidden": true })] }));
+                            }, className: "shrink-0 rounded border border-[color:var(--a-line-strong)] px-2 py-1 text-xs text-[color:var(--a-body)]", "aria-label": "Playback speed", children: [rate, "x"] })] }) }), _jsx("div", { className: "h-20", "aria-hidden": true })] }));
 }

package/lib/reader/reader-watch.js

@@ -121,5 +121,5 @@ export function ReaderWatch({ artifactId, endpoint, accent }) {
                 window.removeEventListener(ev, active);
         };
     }, [artifactId, endpoint]);
-    return notice ? (_jsx("div", { role: "status", "data-nospeak": true, className: "fixed inset-x-0 bottom-6 z-50 mx-auto w-fit max-w-[90vw] rounded-lg px-4 py-3 text-sm shadow-lg", style: { background: '#111', color: '#fff', border: `1px solid ${accent}` }, children: notice })) : null;
+    return notice ? (_jsx("div", { role: "status", "data-nospeak": true, className: "fixed inset-x-0 bottom-6 z-50 mx-auto w-fit max-w-[90vw] rounded-lg px-4 py-3 text-sm shadow-lg", style: { background: 'var(--a-ground, #111)', color: 'var(--a-ink, #fff)', border: `1px solid ${accent}` }, children: notice })) : null;
 }

package/lib/routes/artifacts.js

@@ -11,6 +11,8 @@ import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
 import { shapeChanges } from '../artifacts/state.js';
 import { ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
 import { BrandGround } from '../brand/wrapper.js';
+import { themedPack } from '../brand/theme.js';
+import { showToc, tocOf, TocInline, TocRail } from '../artifacts/toc.js';
 import { renderShareCard } from '../brand/share-card.js';
 import { ArtifactReader } from '../reader/artifact-reader.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
@@ -26,7 +28,11 @@ async function defaultReadCookie(name) {
     return (await cookies()).get(name)?.value;
 }
 export function createArtifactRoutes(config) {
-    const { store, brand, siteUrl } = config;
+    const { store, siteUrl } = config;
+    // The pack as configured draws the share card; the page paints with its theme variables, so a
+    // page follows its light, dark or system mode (brand/theme.ts).
+    const pack = config.brand;
+    const brand = themedPack(pack);
     const prefix = config.pagePrefix ?? '/';
     const pageUrl = (id) => `${siteUrl}${prefix}${id}`;
     const pagePath = (id) => `${prefix}${id}`;
@@ -88,26 +94,20 @@ export function createArtifactRoutes(config) {
         // The same cookie again on the page's state API: a cookie scoped to the page path is never
         // sent to /api/artifacts/<id>/state, so without it a password page could not take answers.
         const unlockLine = (path) => `${unlockCookieName(id)}=${keyHash(id, a.password)}; Path=${path}; Max-Age=31536000; SameSite=Lax; Secure`;
-        const remember = open && a.password && key !== undefined && cookie !== keyHash(id, a.password)
-            ? [pagePath(id), `/api/artifacts/${id}`].map((p) => `document.cookie=${JSON.stringify(unlockLine(p))}`).join(';')
-            : null;
+        // The API copy is set on EVERY open of a page with state:, because the page cannot see it (a
+        // cookie scoped to /api/... never reaches the page path): a reader who unlocked the page
+        // before its API cookie existed would otherwise be refused every answer until they reopened
+        // the ?key= link.
+        const paths = !open || !a.password ? [] : [
+            ...(key !== undefined && cookie !== keyHash(id, a.password) ? [pagePath(id)] : []),
+            ...(a.state ? [`/api/artifacts/${id}`] : key !== undefined && cookie !== keyHash(id, a.password) ? [`/api/artifacts/${id}`] : []),
+        ];
+        const remember = paths.length ? paths.map((p) => `document.cookie=${JSON.stringify(unlockLine(p))}`).join(';') : null;
         if (!open) {
-            return (_jsxs(BrandGround, { pack: brand, children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }), _jsx(ArtifactDoor, { brand: brand, wrongKey: key !== undefined })] }));
+            return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }), _jsx(ArtifactDoor, { brand: brand, wrongKey: key !== undefined })] }));
         }
         void store.bumpViews(id);
-        let words = [];
-        if (a.narration && a.timings) {
-            try {
-                const r = await fetch(a.timings, { next: { revalidate: 3600 } });
-                if (r.ok)
-                    words = (await r.json()).words ?? [];
-            }
-            catch {
-                words = [];
-            }
-        }
-        const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-        return (_jsxs(BrandGround, { pack: brand, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, await Body(a, { top: true })] }));
     }
     /** A page with `access:`. The body is rendered only after the reader is known and allowed;
      *  everyone else gets the title, the summary, and a door. */
@@ -120,17 +120,17 @@ export function createArtifactRoutes(config) {
         if (!d.open) {
             if (d.why === 'not-allowed' && config.readers)
                 void config.readers.flag({ artifactId: id, reader: d.reader, kind: 'refused' }).catch(() => { });
-            return (_jsxs(BrandGround, { pack: brand, children: [header, d.why === 'not-allowed'
+            return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [header, d.why === 'not-allowed'
                         ? _jsx(NotAllowedDoor, { brand: brand, reader: d.reader, signOutUrl: signOutUrl(id) })
                         : _jsx(SignInDoor, { brand: brand, href: signInOrigin ? signInUrl(signInOrigin, pageUrl(id)) : undefined })] }));
         }
         const r = reader;
         // The agreement comes before the body, every reader, once per page. No agreement, no body.
         if (config.readers && !(await config.readers.acknowledged(id, r.email))) {
-            return (_jsxs(BrandGround, { pack: brand, children: [header, _jsx(AckDoor, { brand: brand, name: firstName(r, allow), email: r.email, owner: owner, pageId: id, signOutUrl: signOutUrl(id) })] }));
+            return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [header, _jsx(AckDoor, { brand: brand, name: firstName(r, allow), email: r.email, owner: owner, pageId: id, signOutUrl: signOutUrl(id) })] }));
         }
         void store.bumpViews(id);
-        return (_jsxs(BrandGround, { pack: brand, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: NO_PRINT_CSS } }), _jsx(Watermark, { email: r.email }), _jsx("div", { className: "px-6 pt-20 sm:pt-24", children: _jsx(ConfidentialBanner, { name: firstName(r, allow), email: r.email, reason: d.reason, owner: owner, brand: brand, signOutUrl: signOutUrl(id) }) }), await Body(a, { top: false }), _jsx(ReaderWatch, { artifactId: id, endpoint: "/api/reader/track", accent: brand.accent })] }));
+        return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [_jsx("style", { dangerouslySetInnerHTML: { __html: NO_PRINT_CSS } }), _jsx(Watermark, { email: r.email }), _jsx("div", { className: "px-6 pt-20 sm:pt-24", children: _jsx(ConfidentialBanner, { name: firstName(r, allow), email: r.email, reason: d.reason, owner: owner, brand: brand, signOutUrl: signOutUrl(id) }) }), await Body(a, { top: false }), _jsx(ReaderWatch, { artifactId: id, endpoint: "/api/reader/track", accent: brand.accent })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top }) {
@@ -146,7 +146,8 @@ export function createArtifactRoutes(config) {
             }
         }
         const when = new Date(a.updatedAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
-        return (_jsxs(_Fragment, { children: [_jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-white/10" }) })) : null, _jsx("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: _jsx(ArtifactMarkdown, { markdown: a.markdown }) })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
+        const toc = showToc(a.markdown, a.toc) ? tocOf(a.markdown) : [];
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsxs("div", { id: "artifact-narration-root", children: [_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: brand.kicker }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), _jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-50", children: ["Updated ", when] })] }), a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: a.markdown, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null] }));
     }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in
@@ -366,7 +367,7 @@ export function createArtifactRoutes(config) {
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
         if (!a)
             return new NextResponse(`no artifact with id ${id}`, { status: 404 });
-        return renderShareCard(brand, a.title);
+        return renderShareCard(pack, a.title);
     }
     async function DELETE(request, { params }) {
         if (!isPublishAuthed(request, config.publishKey()))

package/lib/routes/state-routes.js

@@ -16,6 +16,7 @@ import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../arti
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
 import { ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, checkValue, effectiveWriters } from '../artifacts/state.js';
 import { readerKeyFor } from '../artifacts/state-store.js';
+import { NOTES_SLOT, checkNoteValue, hasNotesWidget } from '../artifacts/widgets.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
 export const ANON_COOKIE = 'artifact_anon';
 const ANON_ID = /^[A-Za-z0-9]{24}$/;
@@ -168,13 +169,15 @@ export function createStateRoutes(ctx) {
             await ctx.state.remove({ artifactId: id, slot, readerKey: writer.key, entryId: typeof b.entry === 'string' ? b.entry : undefined });
         }
         else {
-            const bad = checkValue(b.value);
+            const bad = checkValue(b.value) ?? (slot === NOTES_SLOT && hasNotesWidget(a.markdown) ? checkNoteValue(b.value) : null);
             if (bad)
                 return json({ error: bad }, 400);
             // The page-wide cap per slot. Counted before the write and not atomically with it, so a
             // burst can overshoot by the writes in flight; it bounds the slot, it is not a quota.
             if ((await ctx.state.countSlot(id, slot)) >= MAX_ENTRIES_PER_SLOT) {
-                const replacing = op === 'set' && (await ctx.state.entries(id)).some((e) => e.slot === slot && e.readerKey === writer.key);
+                const replacing = op === 'set' && (ctx.state.hasOne
+                    ? await ctx.state.hasOne(id, slot, writer.key)
+                    : (await ctx.state.entries(id)).some((e) => e.slot === slot && e.readerKey === writer.key));
                 if (!replacing)
                     return json({ error: 'this page is not taking more answers here' }, 409);
             }

package/lib/widgets/notes.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+export declare function NotesProvider({ artifactId, headings, accent, children }: {
+    artifactId: string;
+    headings: {
+        slug: string;
+        text: string;
+    }[];
+    accent?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The small control inside a heading. */
+export declare function NoteToggle({ slug }: {
+    slug: string;
+}): import("react").JSX.Element | null;
+/** After each heading: its notes, and the box when its control is open. */
+export declare function HeadingNotes({ slug, text }: {
+    slug: string;
+    text: string;
+}): import("react").JSX.Element | null;
+/** Where the ```notes fence sits: a line saying notes are on, and the notes whose heading is gone. */
+export declare function NotesEarlier(): import("react").JSX.Element | null;