@supersuit/artifacts 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 `@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.16.0 (2026-09-29)
+
+**A brand pack can draw a page's structure, and one page can wear a pack of its own.** Four new
+optional `BrandPack` fields: `Cover` (the title block), `Article` (what holds the cover and body),
+`Section` (each top-level section, with its index, count and the outline, for a break before it
+or a wrapper around it) and `figure(src, alt)` (a component in place of an image or embed). New
+routes config `packs` (by name) and `packFor(artifact)`, and front matter `pack: <name>`.
+
+- DETECTOR: none needed. A pack that uses none of the new fields renders exactly as on 0.15.0,
+  pinned by a golden rendered from 0.15.0 itself (`src/routes/__golden__`).
+- REMEDY: nothing, unless you want a page drawn differently: set the fields on a pack of your
+  own and register it with `packs` or choose it with `packFor`.
+- Tests: the golden (default and wrapped packs, current page and a past version); each extension
+  point; a claimed image replacing its paragraph and an unclaimed one untouched; `pack:` by name,
+  an unknown name, `packFor` ahead of front matter, other pages untouched, the share card following
+  the page's pack; `pack:` parse and refusals and the store round trip; and the read-along: a page
+  rendered through all four has exactly the narrated words. Each was broken on purpose once and
+  failed (figure left speakable, sections not split, cover and article ignored, `packFor` and
+  `pack:` ignored, `pack` not cleared on republish).
+
 ## 0.15.0 (2026-09-29)
 
 **A reader signed in with the wrong Google account can change it.** Before, "Sign out" only

package/README.md

@@ -157,6 +157,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `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 |
+| `pack` | A brand pack the host registered by name (`packs` in the routes config). An unknown name renders in the host's default pack; a republish without the line goes back to it |
 | `toc` | The table of contents. Absent, it appears once the page has four `##` sections; `false` never; `true` from one |
 | `definitions` | Terms defined inline (below). A republish without it removes them |
 | `change` | One line saying what this version changed (see Version history) |
@@ -546,6 +547,29 @@ motion. `colors` are `r,g,b` triplets (default `GLOW_PASTELS`); `veil` is 0 to 1
 const pack: BrandPack = { ...freedomDefault, mode: 'light', backdrop: { kind: 'bubbles' } }
 ```
 
+**Drawing more than colours.** Four optional fields let a pack draw a page's structure. A pack
+that sets none of them renders every page byte for byte as before (a test holds that).
+
+- `Cover` draws the title block instead of the centred header. It is handed `title`, `subtitle`
+  and `summary` to render (they are spoken, in that order), the shell's `kicker` and `meta`
+  (version line, signed-in line) to place, and the page's `markdown` to quote from.
+- `Article` holds the cover, the inline contents and the body, instead of the centred column.
+- `Section` receives each top-level section (split at the shallowest heading level the page
+  uses): its `index`, `count`, the whole `outline`, the heading's `text` and `slug`, the default
+  `heading`, or its `headingContent` and `headingAttrs` (id and comment anchor) for a pack that
+  draws the heading itself, and the section's body as `children`.
+- `figure(src, alt)` returns a component to draw an image or embed in its place, or undefined to
+  keep the default. An image alone in its paragraph replaces the paragraph.
+
+Everything a pack adds beyond the text it is handed must sit inside `data-nospeak`, which the
+read-along skips; the shell puts figures there itself. A test renders a page through all four
+and checks the words on the page are exactly the words narrated.
+
+**One page in a different pack.** Register packs by name with `packs: { name: pack }` and a page
+picks one with `pack: name` in its front matter. `packFor(artifact)` lets the host choose instead,
+ahead of the front matter, for a page whose file cannot carry the line. The share card follows
+the page's pack.
+
 ## Environment
 
 | Variable | Used for |

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

@@ -36,6 +36,10 @@ export type ArtifactMeta = {
     state?: StateConfig;
     /** Light, dark, or the reader's device, overriding the brand pack's mode for this page. */
     theme?: ThemeMode;
+    /** The brand pack this page renders in, by the name the host registered it under (`packs` in
+     *  the routes config). A name the host does not know renders in its default pack. Content, like
+     *  `theme:`: a republish without the line goes back to the default. */
+    pack?: string;
     /** The table of contents: absent draws it once the page has four sections, false never. */
     toc?: boolean;
     /** Terms this page defines inline: the first occurrence of each is underlined and opens its
@@ -51,6 +55,8 @@ export type ArtifactMeta = {
     /** Who sees shared comments: `owner` (the default) or every reader (`readers`). */
     commentsVisible?: CommentsVisible;
 };
+/** A pack name, as a host registers one. */
+export declare const PACK_NAME: RegExp;
 /** The longest `to:` a page may carry: a name or two, never a sentence. */
 export declare const MAX_TO_CHARS = 60;
 export declare function parseArtifactSource(text: string): {

package/lib/artifacts/front-matter.js

@@ -7,9 +7,11 @@ import { mergeWidgetState, scanWidgets } from './widgets.js';
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
+/** A pack name, as a host registers one. */
+export const PACK_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** The longest `to:` a page may carry: a name or two, never a sentence. */
 export const MAX_TO_CHARS = 60;
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'toc', 'definitions', 'change', 'comments', 'comments_visible']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible']);
 export function parseArtifactSource(text) {
     const { data, content } = matter(text);
     const d = data;
@@ -57,6 +59,11 @@ export function parseArtifactSource(text) {
             return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
         meta.theme = d.theme;
     }
+    if (d.pack !== undefined && d.pack !== null) {
+        if (typeof d.pack !== 'string' || !PACK_NAME.test(d.pack))
+            return { ok: false, error: 'pack must be a pack name: lowercase letters, digits and dashes, up to 40 characters' };
+        meta.pack = d.pack;
+    }
     if (d.toc !== undefined) {
         if (typeof d.toc !== 'boolean')
             return { ok: false, error: 'toc must be true or false' };

package/lib/artifacts/render.d.ts

@@ -1,9 +1,21 @@
+import { type ComponentType } from 'react';
+import type { FigureProps, SectionOutline, SectionProps } from '../brand/pack.js';
+import { type Heading } from './widgets.js';
 import { type Definition } from './definitions.js';
 export declare function isReachableHref(href: unknown): href is string;
+/** A pack's figure resolver (BrandPack.figure). */
+export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps> | undefined;
+/** The page's top-level sections: every heading among the body's top-level blocks at the
+ *  shallowest depth any of them uses. Headings inside lists or quotes never start a section. */
+export declare function sectionOutline(markdown: string, headings?: Heading[]): SectionOutline[];
 /** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
  *  page carries a ```notes block. */
-export declare function ArtifactMarkdown({ markdown, notes, definitions, }: {
+export declare function ArtifactMarkdown({ markdown, notes, definitions, Section, figure, }: {
     markdown: string;
+    /** The pack's section component (BrandPack.Section): each top-level section is drawn through it. */
+    Section?: ComponentType<SectionProps>;
+    /** The pack's figure resolver (BrandPack.figure). */
+    figure?: FigureFor;
     notes?: {
         artifactId: string;
         accent?: string;

package/lib/artifacts/render.js

@@ -1,6 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Markdown to the house look, for /a/<id>. Server-safe: no hooks, no client
+// directive. Raw HTML is escaped by react-markdown's default; never add
+// rehype-raw here, this renders strangers' links on a public route.
+// Two extensions past GFM, both small on purpose:
+//   ```links   one "url | note" per line, rendered as link cards
+//   > [!note] / > [!warning]   a callout instead of a blockquote
+import { Children, isValidElement } from 'react';
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
 import { blocksOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
@@ -70,18 +79,41 @@ function InlineAudio({ src, label }) {
     const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio controls preload="none" class="block w-full"></audio>`;
     return (_jsxs("span", { className: "my-6 block rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-4 py-3", children: [label ? _jsx("span", { className: "mb-2 block text-sm text-[color:var(--a-strong)]", children: label }) : null, _jsx("span", { className: "block", dangerouslySetInnerHTML: { __html: html } })] }));
 }
-function baseComponents(block) {
+/** The one image a paragraph holds and nothing else (whitespace aside), or null. */
+function soleImage(node) {
+    const kids = (node?.children ?? []).filter((c) => !(c.type === 'text' && !c.value?.trim()));
+    if (kids.length !== 1 || kids[0].type !== 'element' || kids[0].tagName !== 'img')
+        return null;
+    const src = kids[0].properties?.src;
+    return typeof src === 'string' ? { src, alt: String(kids[0].properties?.alt ?? '') } : null;
+}
+function baseComponents(block, figure) {
     return {
-        p: ({ node, children }) => _jsx("p", { ...block(node), className: "my-4 leading-relaxed", children: children }),
+        p: ({ node, children }) => {
+            // An image alone in its paragraph that the pack draws itself replaces the paragraph, so the
+            // pack's figure may hold block content (a <p> cannot) and still carry the comment anchor.
+            const img = figure ? soleImage(node) : null;
+            const F = img ? figure(img.src, img.alt) : undefined;
+            if (img && F) {
+                return (_jsx("div", { ...block(node), "data-nospeak": true, "data-artifact-figure": true, children: _jsx(F, { src: img.src, alt: img.alt }) }));
+            }
+            return _jsx("p", { ...block(node), className: "my-4 leading-relaxed", children: children });
+        },
         ul: ({ node, children }) => _jsx("ul", { ...block(node), className: "my-4 list-disc space-y-1 pl-6", children: children }),
         ol: ({ node, children }) => _jsx("ol", { ...block(node), className: "my-4 list-decimal space-y-1 pl-6", children: children }),
         hr: () => _jsx("hr", { className: "my-10 border-[color:var(--a-line)]" }),
         table: ({ node, children }) => (_jsx("div", { ...block(node), 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-[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 }) => typeof src === 'string' && VIDEO.test(src) ? (_jsx(InlineVideo, { src: src, label: alt ?? '' })) : typeof src === 'string' && AUDIO.test(src) ? (_jsx(InlineAudio, { src: src, label: 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-[color:var(--a-line)]" })),
+        img: ({ src, alt }) => {
+            const F = typeof src === 'string' ? figure?.(src, alt ?? '') : undefined;
+            if (F) {
+                return (_jsx("span", { "data-nospeak": true, "data-artifact-figure": true, className: "block", children: _jsx(F, { src: src, alt: alt ?? '' }) }));
+            }
+            return typeof src === 'string' && VIDEO.test(src) ? (_jsx(InlineVideo, { src: src, label: alt ?? '' })) : typeof src === 'string' && AUDIO.test(src) ? (_jsx(InlineAudio, { src: src, label: 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-[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];
@@ -127,20 +159,20 @@ const HEADING_CLASS = {
 };
 /** Components for any page: every heading gets its slug as an id, the one headingsOf derived,
  *  so a contents link and a note both land on it. */
-function pageComponents(headings, block) {
+function pageComponents(headings, block, figure) {
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function Heading({ node, children }) {
         const Tag = `h${depth}`;
         const h = byLine.get(node?.position?.start.line ?? -1);
         return _jsx(Tag, { id: h?.slug, ...block(node), className: HEADING_CLASS[depth], children: children });
     };
-    return { ...baseComponents(block), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
+    return { ...baseComponents(block, figure), h1: heading(1), h2: heading(2), h3: heading(3), h4: heading(4), h5: heading(5), h6: heading(6) };
 }
 /** Components for a page with a notes block: every heading gets its slug as an id, a note
  *  control, and its notes after it. The heading is found by its source line, so the slug is the
  *  one headingsOf derived, the same one a note stores. */
-function notesComponents(headings, block) {
-    const components = baseComponents(block);
+function notesComponents(headings, block, figure) {
+    const components = baseComponents(block, figure);
     const byLine = new Map(headings.map((h) => [h.line, h]));
     const heading = (depth) => function NotedHeading({ node, children }) {
         const Tag = `h${depth}`;
@@ -156,6 +188,55 @@ function notesComponents(headings, block) {
         code: (props) => (/language-notes/.test(props.className ?? '') ? _jsx(NotesEarlier, {}) : _jsx(Code, { ...props })),
     };
 }
+/** The page's top-level sections: every heading among the body's top-level blocks at the
+ *  shallowest depth any of them uses. Headings inside lists or quotes never start a section. */
+export function sectionOutline(markdown, headings = headingsOf(markdown)) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(markdown);
+    const tops = tree.children.filter((n) => n.type === 'heading');
+    if (!tops.length)
+        return [];
+    const depth = Math.min(...tops.map((h) => h.depth));
+    const byLine = new Map(headings.map((h) => [h.line, h]));
+    return tops
+        .filter((h) => h.depth === depth)
+        .map((h, index) => {
+        const known = byLine.get(h.position?.start.line ?? -1);
+        return { index, depth, text: known?.text ?? '', slug: known?.slug ?? '' };
+    });
+}
+/** Groups the root's blocks into one node per top-level section (a heading at `depth` and what
+ *  follows it up to the next), so the renderer can hand each to the pack's Section. The blocks
+ *  keep their positions, so comment anchors and heading slugs are exactly what they were. */
+function remarkSections(depth) {
+    return () => (tree) => {
+        const out = [];
+        let body = null;
+        let i = 0;
+        for (const n of tree.children) {
+            if (n.type === 'heading' && n.depth === depth) {
+                body = { children: [] };
+                const b = { type: 'artifactSectionBody', data: { hName: 'div', hProperties: { dataArtifactSectionBody: '' } }, children: body.children };
+                out.push({ type: 'artifactSection', data: { hName: 'section', hProperties: { dataArtifactSection: String(i++) } }, children: [n, b] });
+            }
+            else if (body)
+                body.children.push(n);
+            else
+                out.push(n);
+        }
+        tree.children = out;
+    };
+}
+function sectionComponent(Section, outline, block) {
+    return function ArtifactSection({ node, children }) {
+        const i = Number(node?.properties?.dataArtifactSection);
+        const o = outline[i];
+        // Not one of ours (a raw <section> never reaches here: raw HTML is escaped).
+        if (!o)
+            return _jsx("section", { children: children });
+        const [heading, body] = Children.toArray(children).filter(isValidElement);
+        return (_jsx(Section, { index: i, count: outline.length, outline: outline, text: o.text, slug: o.slug, heading: heading, headingContent: heading?.props.children, headingAttrs: { id: o.slug, ...block(heading?.props.node) }, children: body?.props.children }));
+    };
+}
 // The term is text with a dotted underline; the description copy is visually hidden and out of
 // flow (absolute), so it takes no room in the line. Neither ever changes size: the definition
 // that opens is drawn by DefinitionLayer on document.body.
@@ -170,7 +251,7 @@ const DEFINED_TERM_CSS = '.artifact-defined-term{text-decoration-line:underline;
     'clip:rect(0,0,0,0);white-space:nowrap;border:0}';
 /** `notes` turns on the notes widget, for a host that keeps answers; it draws only when the
  *  page carries a ```notes block. */
-export function ArtifactMarkdown({ markdown, notes, definitions, }) {
+export function ArtifactMarkdown({ markdown, notes, definitions, Section, figure, }) {
     const on = !!notes && hasNotesWidget(markdown);
     const headings = headingsOf(markdown);
     const blocks = blocksOf(markdown);
@@ -179,7 +260,12 @@ export function ArtifactMarkdown({ markdown, notes, definitions, }) {
         return id ? { 'data-block': id } : {};
     };
     const defined = definitions?.length ? definitions : null;
-    const body = (_jsx(ReactMarkdown, { remarkPlugins: defined ? [remarkGfm, remarkDefinitions(defined)] : [remarkGfm], components: on ? notesComponents(headings, block) : pageComponents(headings, block), children: markdown }));
+    const outline = Section ? sectionOutline(markdown, headings) : [];
+    const plugins = [remarkGfm, ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
+    const components = on ? notesComponents(headings, block, figure) : pageComponents(headings, block, figure);
+    if (outline.length)
+        components.section = sectionComponent(Section, outline, block);
+    const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, children: markdown }));
     return (
     // break-words: a bare URL in prose is one unbreakable word and pushed phones 7px sideways (2026-09-26).
     _jsxs("div", { className: "break-words text-[17px] text-[color:var(--a-body)]", children: [on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body, VIDEO_IN_MD.test(markdown) ? _jsx(VideoAutoplay, {}) : null, defined ? (_jsxs(_Fragment, { children: [_jsx("style", { children: DEFINED_TERM_CSS }), _jsx(DefinitionLayer, {})] })) : null] }));

package/lib/artifacts/store.d.ts

@@ -23,6 +23,8 @@ export type ArtifactRecord = {
     access?: Access;
     state?: StateConfig;
     theme?: ThemeMode;
+    /** The brand pack the page asked for by name; see ArtifactMeta.pack. */
+    pack?: string;
     toc?: boolean;
     definitions?: Definition[];
     /** Who may leave shared comments; absent is off. Personal notes need nothing. */

package/lib/artifacts/store.js

@@ -134,6 +134,7 @@ async function saveArtifact(col, input) {
         ...(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.pack ? { pack: input.meta.pack } : {}),
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
         ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
         ...(input.meta.comments ? { comments: input.meta.comments } : {}),
@@ -181,6 +182,7 @@ async function saveArtifact(col, input) {
         // 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.pack ? {} : { pack: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
             ...(input.meta.definitions?.length ? {} : { definitions: FieldValue.delete() }),
             // Comments are not an access control, so a line the file no longer carries goes back to

package/lib/brand/index.d.ts

@@ -1,4 +1,4 @@
-export { freedomDefault, type BrandPack, type ShareCardAssets, type Palette, type Backdrop } from './pack.js';
+export { freedomDefault, type BrandPack, type ShareCardAssets, type Palette, type Backdrop, type CoverProps, type ArticleProps, type SectionProps, type SectionOutline, type FigureProps } 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';

package/lib/brand/pack.d.ts

@@ -52,6 +52,76 @@ export type BrandPack = {
      *  previews as the page rather than as the brand. Absent, the instance's static default
      *  share image is used. Both loaders run once per instance. */
     share?: ShareCardAssets;
+    /** Optional: draws the page's title block instead of the default centred header. Receives the
+     *  title, subtitle and summary to render (they are SPOKEN, in that order, so render all three),
+     *  plus the shell's unspoken kicker and version line to place. Anything else it draws must be
+     *  inside `data-nospeak`, or the read-along highlight loses its place. */
+    Cover?: ComponentType<CoverProps>;
+    /** Optional: the element that holds the title block and the body, instead of the default
+     *  centred column. Receives the cover (the pack's Cover or the default header), the inline
+     *  table of contents when the page shows one, and the body. */
+    Article?: ComponentType<ArticleProps>;
+    /** Optional: each top-level section of the body (split at the shallowest heading level the page
+     *  uses) is rendered through this, so a pack can draw a break before it or wrap it. Content
+     *  before the first such heading is left as it is. Decoration must be `data-nospeak`. */
+    Section?: ComponentType<SectionProps>;
+    /** Optional: replaces an image (or `.mp4`/`.mp3` embed) with a component, by its src. Return
+     *  undefined to keep the default. The shell wraps the result in `data-nospeak`, and an image
+     *  alone in its paragraph replaces the paragraph, so the component may draw block content. */
+    figure?: (src: string, alt: string) => ComponentType<FigureProps> | undefined;
+};
+export type CoverProps = {
+    title: string;
+    subtitle?: string;
+    summary: string;
+    /** Who the page is for, when it says. Already inside `kicker`. */
+    to?: string;
+    /** The body, for a cover that quotes from it (anything quoted must be `data-nospeak`). */
+    markdown: string;
+    /** The shell's kicker line (the pack's kicker, then who it is for), unspoken. */
+    kicker: ReactNode;
+    /** The version line and, for a signed-in reader, who they are signed in as. Unspoken. */
+    meta: ReactNode;
+    version: number;
+    updatedAt: string;
+    createdAt: string;
+};
+export type ArticleProps = {
+    cover: ReactNode;
+    toc: ReactNode;
+    children: ReactNode;
+};
+/** One top-level heading of the page, in order. */
+export type SectionOutline = {
+    index: number;
+    depth: number;
+    text: string;
+    slug: string;
+};
+export type SectionProps = {
+    /** This section's place among the page's top-level sections, from 0, and how many there are. */
+    index: number;
+    count: number;
+    /** Every top-level section, so a pack can tell what came before and what comes next. */
+    outline: SectionOutline[];
+    /** The heading's plain text and slug (its id, which the table of contents links to). */
+    text: string;
+    slug: string;
+    /** The heading as the shell draws it by default. */
+    heading: ReactNode;
+    /** The heading's inner content and the attributes it carries (its id and its comment anchor),
+     *  for a pack that draws the heading element itself. Put the attributes on whatever holds it. */
+    headingContent: ReactNode;
+    headingAttrs: {
+        id?: string;
+        'data-block'?: string;
+    };
+    /** Everything under the heading, up to the next top-level heading. */
+    children: ReactNode;
+};
+export type FigureProps = {
+    src: string;
+    alt: string;
 };
 export type ShareCardAssets = {
     /** The display font, as bytes the renderer can embed. Satori needs a real file: a CSS

package/lib/routes/artifacts.d.ts

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next';
 import { NextRequest, NextResponse } from 'next/server';
-import { type ArtifactStore, type VersionEntry } from '../artifacts/store.js';
+import { type ArtifactRecord, type ArtifactStore, type VersionEntry } from '../artifacts/store.js';
 import type { StateStore } from '../artifacts/state-store.js';
 import { type ArtifactAssets } from '../artifacts/assets.js';
 import type { BrandPack } from '../brand/pack.js';
@@ -18,6 +18,12 @@ export type ArtifactRoutesConfig = {
     /** Where uploaded files go. Optional; without it PUT_ASSET answers 501. */
     assets?: ArtifactAssets;
     brand: BrandPack;
+    /** Other packs a page may choose by name with `pack: <name>` in its front matter. A name this
+     *  host does not know falls back to `brand`, so a page never fails to render over its look. */
+    packs?: Record<string, BrandPack>;
+    /** Choose a page's pack on the host, ahead of its front matter: for a page whose file cannot
+     *  carry the line, or a look the host decides. Undefined means no opinion. */
+    packFor?: (artifact: ArtifactRecord) => BrandPack | undefined;
     /** The host that serves a 200, e.g. https://artifacts.example.com. No trailing slash. */
     siteUrl: string;
     /** Read at request time, so a rotated key needs no rebuild. */

package/lib/routes/artifacts.js

@@ -43,6 +43,15 @@ export function createArtifactRoutes(config) {
     // page follows its light, dark or system mode (brand/theme.ts).
     const pack = config.brand;
     const brand = themedPack(pack);
+    /** The pack one page renders in: the host's choice, then the page's `pack:`, then the default. */
+    const looks = new Map();
+    function lookOf(a) {
+        const p = config.packFor?.(a) ?? (a.pack ? config.packs?.[a.pack] : undefined) ?? pack;
+        let l = looks.get(p);
+        if (!l)
+            looks.set(p, (l = { pack: p, brand: themedPack(p) }));
+        return l;
+    }
     const prefix = config.pagePrefix ?? '/';
     const pageUrl = (id) => `${siteUrl}${prefix}${id}`;
     const pagePath = (id) => `${prefix}${id}`;
@@ -71,7 +80,7 @@ export function createArtifactRoutes(config) {
     });
     /** The kicker over every title: the pack's line, then who the page is for. Never spoken: the
      *  whole paragraph is data-nospeak, and narrationText has no `to` to read. */
-    function Kicker({ to }) {
+    function Kicker({ to, brand }) {
         return (_jsxs("p", { "data-nospeak": true, className: "mb-4 text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: [brand.kicker, to ? _jsx("span", { "data-nospeak": true, "data-to": true, children: ` · For ${to}` }) : null] }));
     }
     async function generateMetadata({ params }) {
@@ -80,6 +89,7 @@ export function createArtifactRoutes(config) {
         if (!a)
             return { title: 'Not found', robots: { index: false, follow: false } };
         const url = pageUrl(a.id);
+        const { brand } = lookOf(a);
         const image = absolute(a.cover) ?? (brand.share ? shareCardUrl(a.id, a.updatedAt) : absolute(config.defaultShareImage));
         // Who it is for leads the unfurl, so a thread shows it before the reader opens anything.
         const title = a.to ? `For ${a.to}: ${a.title}` : a.title;
@@ -129,6 +139,7 @@ export function createArtifactRoutes(config) {
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
         if (!a)
             notFound();
+        const { pack, brand } = lookOf(a);
         const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top }));
         if (a.access)
             return GatedPage(a, id, render, n);
@@ -155,7 +166,7 @@ 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: 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(Kicker, { to: a.to }), _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(Kicker, { to: a.to, brand: brand }), _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 })] }));
         }
         // Who is reading an open page, when they happen to be signed in: their comments follow them.
         // Only a host that signs readers in can know one; the read never fails the page.
@@ -168,13 +179,14 @@ export function createArtifactRoutes(config) {
     /** 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. */
     async function GatedPage(a, id, render, n) {
+        const { pack, brand } = lookOf(a);
         const here = n === null ? pageUrl(id) : `${pageUrl(id)}/v/${n}`;
         const readCookie = config.readCookie ?? defaultReadCookie;
         // Only a host that signs readers in can know one; the read never fails the page.
         const reader = readerSecret() ? verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE).catch(() => undefined)) : null;
         const allow = config.readers && reader ? await config.readers.allowList(id) : [];
         const d = config.readers ? decide(a.access, reader, allow) : { open: false, why: 'signed-out' };
-        const header = (_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx(Kicker, { to: a.to }), _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 })] }));
+        const header = (_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx(Kicker, { to: a.to, brand: brand }), _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 })] }));
         if (!d.open) {
             if (d.why === 'not-allowed' && config.readers)
                 void config.readers.flag({ artifactId: id, reader: d.reader, kind: 'refused' }).catch(() => { });
@@ -203,8 +215,16 @@ export function createArtifactRoutes(config) {
     function VersionLine({ a, n, at, history }) {
         return (_jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-60", children: [`Version ${n} · Updated `, _jsx(UpdatedTime, { iso: at }), history && history.length > 1 ? (_jsxs(_Fragment, { children: [' · ', _jsx(VersionHistory, { items: history, base: pagePath(a.id), viewing: n })] })) : null] }));
     }
+    /** The title block and the body, in the pack's Article when it has one. Without one this is
+     *  exactly the markup every page had before packs could frame it. */
+    function Framed({ pack, cover, toc, children }) {
+        if (pack.Article)
+            return _jsx(pack.Article, { cover: cover, toc: toc, children: children });
+        return (_jsxs(_Fragment, { children: [cover, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc, children] })] }));
+    }
     /** A past version: its own body and title, read-only (no narration, no answers), under a banner. */
     async function VersionBody(a, n, { top }) {
+        const { pack, brand } = lookOf(a);
         const v = store.version ? await store.version(a.id, n) : null;
         if (!v)
             notFound();
@@ -215,10 +235,11 @@ export function createArtifactRoutes(config) {
         const title = v.title ?? a.title;
         const summary = v.summary ?? a.summary;
         const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.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: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history })] }), _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc.length ? _jsx(TocInline, { items: toc }) : null, _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions })] })] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.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: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader }) {
+        const { pack, brand } = lookOf(a);
         let words = [];
         if (a.narration && a.timings) {
             try {
@@ -233,7 +254,12 @@ export function createArtifactRoutes(config) {
         const toc = showToc(a.markdown, a.toc) ? tocOf(a.markdown) : [];
         // Shared comments need the page to take them AND a host that keeps answers; personal notes need neither.
         const mode = config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
-        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(Kicker, { to: a.to }), _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(VersionLine, { a: a, n: a.version ?? (a.versions?.length ?? 0) + 1, at: a.updatedAt, history: await historyOf(a.id) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }), 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, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined })] })] }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), 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 })) : (
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { id: "artifact-narration-root", children: await (async () => {
+                        const n = a.version ?? (a.versions?.length ?? 0) + 1;
+                        const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { a: a, n: n, at: a.updatedAt, history: await historyOf(a.id) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
+                        const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _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 }), meta] }));
+                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, 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] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, Section: pack.Section, figure: pack.figure }) }));
+                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), 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 })) : (
                 // No recorded narration, or its timings would not load: the browser reads the page.
                 _jsx(BrowserReader, { rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground }))] }));
     }
@@ -505,12 +531,13 @@ export function createArtifactRoutes(config) {
      *  tenant on the static default never serves a half-styled card. */
     async function SHARE_IMAGE(_request, { params }) {
         const { id } = await params;
-        if (!brand.share)
-            return new NextResponse('no share card for this host', { status: 404 });
         const a = ARTIFACT_ID.test(id) ? await store.get(id) : null;
+        const look = a ? lookOf(a) : { pack, brand };
+        if (!look.brand.share)
+            return new NextResponse('no share card for this host', { status: 404 });
         if (!a)
             return new NextResponse(`no artifact with id ${id}`, { status: 404 });
-        return renderShareCard(pack, a.title, { to: a.to });
+        return renderShareCard(look.pack, a.title, { to: a.to });
     }
     /** GET|POST /api/artifacts/<id>/versions, publish key: the history, and a note written onto one
      *  version after the fact. POST body: { version: number, note: string | null }. */

package/package.json

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