@supersuit/artifacts 0.3.0 → 0.4.0

package/CHANGELOG.md

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

package/README.md

@@ -130,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.
@@ -342,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

@@ -4,7 +4,8 @@ import matter from 'gray-matter';
 import { ACCESS_LEVELS } from './reader.js';
 import { parseStateConfig } from './state.js';
 import { mergeWidgetState, scanWidgets } from './widgets.js';
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state']);
+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;
@@ -35,6 +36,16 @@ 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)

package/lib/artifacts/render.js

@@ -3,7 +3,8 @@ import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
-const GOLD = '#C2A15C';
+// 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\./, '');
@@ -33,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
@@ -45,20 +46,17 @@ 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')
@@ -68,7 +66,7 @@ const components = {
         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 });
     },
@@ -78,27 +76,39 @@ const components = {
         const cls = inner?.props?.className ?? '';
         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 })] }));
     },
 };
+// 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 font-serif text-3xl text-zinc-50',
-    2: 'mt-10 mb-3 font-serif text-2xl text-zinc-50',
-    3: 'mt-8 mb-2 text-lg font-semibold text-zinc-100',
-    4: 'mt-6 mb-2 font-semibold text-zinc-100',
-    5: 'mt-6 mb-2 font-semibold text-zinc-100',
-    6: 'mt-6 mb-2 font-semibold text-zinc-100',
+    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. */
@@ -122,7 +132,9 @@ function notesComponents(headings) {
  *  page carries a ```notes block. */
 export function ArtifactMarkdown({ markdown, notes }) {
     const on = !!notes && hasNotesWidget(markdown);
-    const headings = on ? headingsOf(markdown) : [];
-    const body = (_jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: on ? notesComponents(headings) : components, children: markdown }));
-    return (_jsx("div", { className: "text-[17px] text-zinc-200", children: on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body }));
+    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/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 }) })] }));
+}

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}`;
@@ -98,22 +104,10 @@ export function createArtifactRoutes(config) {
         ];
         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, 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] }));
+        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. */
@@ -126,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 }) {
@@ -152,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, 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 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
@@ -372,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/widgets/notes.js

@@ -97,7 +97,7 @@ export function NoteToggle({ slug }) {
     return (_jsx("button", { type: "button", "data-nospeak": true, "data-note-toggle": slug, "aria-expanded": c.open === slug, onClick: () => c.setOpen(c.open === slug ? null : slug), className: "ml-3 inline-block rounded-full border px-2 py-0.5 align-middle font-sans text-[11px] font-medium uppercase tracking-[0.15em] opacity-70 transition-opacity hover:opacity-100", style: { borderColor: c.accent, color: c.accent }, children: n ? `note · ${n}` : 'note' }));
 }
 function NoteItem({ n, c, under }) {
-    return (_jsxs("li", { className: "m-0 border-l-2 py-1 pl-3", style: { borderColor: c.accent }, children: [_jsx("span", { className: "block whitespace-pre-wrap text-[15px] text-zinc-100", children: n.note }), _jsxs("span", { className: "block text-xs opacity-60", children: [n.name, under ? _jsxs(_Fragment, { children: [" \u00B7 under \u201C", n.heading, "\u201D"] }) : null, n.mine && n.id ? (_jsx("button", { type: "button", "data-note-remove": n.id, onClick: () => void c.remove(n.id), className: "ml-2 underline opacity-80 hover:opacity-100", children: "remove" })) : null] })] }));
+    return (_jsxs("li", { className: "m-0 border-l-2 py-1 pl-3", style: { borderColor: c.accent }, children: [_jsx("span", { className: "block whitespace-pre-wrap text-[15px] text-[color:var(--a-strong)]", children: n.note }), _jsxs("span", { className: "block text-xs opacity-60", children: [n.name, under ? _jsxs(_Fragment, { children: [" \u00B7 under \u201C", n.heading, "\u201D"] }) : null, n.mine && n.id ? (_jsx("button", { type: "button", "data-note-remove": n.id, onClick: () => void c.remove(n.id), className: "ml-2 underline opacity-80 hover:opacity-100", children: "remove" })) : null] })] }));
 }
 function NoteForm({ slug, heading, c }) {
     const [text, setText] = useState('');
@@ -112,7 +112,7 @@ function NoteForm({ slug, heading, c }) {
     if (!c.canWrite) {
         return c.signIn ? (_jsx("p", { className: "my-2 text-sm", children: _jsx("a", { href: c.signIn, className: "underline", style: { color: c.accent }, children: "Sign in to leave a note" }) })) : (_jsx("p", { className: "my-2 text-sm opacity-70", children: "Notes here are open to signed-in readers." }));
     }
-    return (_jsxs("form", { onSubmit: submit, className: "my-2", children: [_jsx("textarea", { value: text, onChange: (e) => setText(e.target.value), maxLength: MAX_NOTE_CHARS, rows: 3, "aria-label": `A note on ${heading}`, placeholder: `A note on “${heading}”`, className: "w-full rounded-lg border border-white/15 bg-white/[0.04] p-3 text-[15px] text-zinc-100" }), c.error ? _jsx("p", { className: "mt-1 text-xs text-amber-500", children: c.error }) : null, _jsxs("div", { className: "mt-2 flex gap-3", children: [_jsx("button", { type: "submit", disabled: c.busy || !text.trim(), className: "rounded-full px-4 py-1 text-sm font-medium disabled:opacity-40", style: { background: c.accent, color: '#111' }, children: "Save note" }), _jsx("button", { type: "button", onClick: () => c.setOpen(null), className: "text-sm opacity-70 hover:opacity-100", children: "Cancel" })] })] }));
+    return (_jsxs("form", { onSubmit: submit, className: "my-2", children: [_jsx("textarea", { value: text, onChange: (e) => setText(e.target.value), maxLength: MAX_NOTE_CHARS, rows: 3, "aria-label": `A note on ${heading}`, placeholder: `A note on “${heading}”`, className: "w-full rounded-lg border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] p-3 text-[15px] text-[color:var(--a-strong)]" }), c.error ? _jsx("p", { className: "mt-1 text-xs text-amber-500", children: c.error }) : null, _jsxs("div", { className: "mt-2 flex gap-3", children: [_jsx("button", { type: "submit", disabled: c.busy || !text.trim(), className: "rounded-full px-4 py-1 text-sm font-medium disabled:opacity-40", style: { background: c.accent, color: 'var(--a-on-accent, #111)' }, children: "Save note" }), _jsx("button", { type: "button", onClick: () => c.setOpen(null), className: "text-sm opacity-70 hover:opacity-100", children: "Cancel" })] })] }));
 }
 /** After each heading: its notes, and the box when its control is open. */
 export function HeadingNotes({ slug, text }) {

package/package.json

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