@supersuit/artifacts 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 `@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.17.0 (2026-09-29)
+
+**A host can accept a signed, hour-long publisher pass wherever it accepts the publish key.** A
+shared key cannot be self-served and cannot be revoked for one person without rotating it for
+everyone. New routes config `publisherSecret` and `publisherHost`: when both are set, every
+publish-key route (publish, read, delete, versions, access, reads, assets, upload, responses, the
+comments feed) also accepts `Authorization: Bearer p1.<payload>.<sig>`, a pass naming one person
+and this host, signed with the reader pass's HMAC scheme under its own domain
+(`artifact-publisher`). New exports `mintPublisherPass`, `verifyPublisherPass`,
+`PUBLISHER_PASS_TTL_SECONDS` (3600), `isPublisherAuthed`. `isPublishAuthed` is unchanged.
+
+- DETECTOR: none needed. A host that sets neither field refuses every pass and takes its key
+  exactly as on 0.16.0.
+- REMEDY: nothing, unless you want admins to publish without the key: set both fields, and have
+  your sign-in side mint passes for the people it vouches for.
+- Tests: the pass vector pinned byte for byte; a valid pass for the right host gets exactly what
+  the key gets on every publish-key handler; wrong host, expired, bad signature, a reader pass
+  (`a1`) and a grant (`g1`) are refused on every handler; a `p1` pass never verifies as a reader
+  pass or grant; a host missing either field refuses a pass and still takes its key. Broken on
+  purpose twice and failed: the host check removed (11 failures), and the comments feed left on
+  the bare key check (its pass case failed).
+
+## 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

@@ -28,6 +28,7 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing (widget fences included) |
 | `headingsOf`, `scanWidgets`, `placeNotes` | The notes widget's pure parts: heading slugs, fence validation, where each note shows |
 | `mintPass`, `verifyPass` | The reader pass, for the sign-in side (see below) |
+| `mintPublisherPass`, `verifyPublisherPass` | The publisher pass: an hour-long stand-in for the publish key, for one person on one host (see below) |
 | `ARTIFACT_PUBLIC_PREFIXES` (`/gate`) | Paths to leave open if you mount artifacts inside a gated site |
 
 Subpath imports: `@supersuit/artifacts/artifacts`, `/routes`, `/brand`, `/reader`, `/gate`.
@@ -157,6 +158,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) |
@@ -231,6 +233,29 @@ reimplement it. Keep passes short-lived (five minutes is what the tests assume).
 Without `signInOrigin`, a confidential page shows its door with no way through. It fails
 closed, never open.
 
+### The publisher pass (publishing without the shared key)
+
+A shared publish key cannot be handed to one person and taken back from one person. A host can
+also accept a **publisher pass** wherever it accepts the key: a signed, hour-long statement that
+a named person may publish on that host, minted by an authority that knows who may.
+
+```ts
+createArtifactRoutes({
+  // ...
+  publisherSecret: () => process.env.ARTIFACT_PASS_SECRET, // shared with the minting side
+  publisherHost: 'artifacts.example.com',                  // the host a pass must name
+})
+```
+
+Both fields are optional; without either, passes are refused and only the key works. The pass is
+`p1.<payload>.<sig>`: `payload` is the base64url of
+`{"u": uid, "e": email, "n": name|null, "h": host, "x": expiry-unix-seconds}`, and `sig` is the
+first 32 hex characters of `HMAC-SHA256(secret, "artifact-publisher:p1.<payload>")`. It is sent as
+`Authorization: Bearer <pass>`. A pass for another host is refused even under the same secret, and
+a reader pass or grant never verifies as a publisher pass (nor the reverse), because the domain
+and version differ. `mintPublisherPass(secret, { uid, email, name, host }, exp)` builds one;
+`PUBLISHER_PASS_TTL_SECONDS` is 3600.
+
 ## Reader answers (`state:`)
 
 A page can take answers from the people reading it: a vote, a reaction, a short response.
@@ -546,12 +571,36 @@ 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 |
 |---|---|
 | your publish key (named by you, read in `publishKey`) | Authorises publish, delete and access changes |
 | `ARTIFACT_PASS_SECRET` (named by you, read in `readerSecret`) | Verifies reader passes and signs grants; shared with your sign-in side |
+| a publisher-pass secret (named by you, read in `publisherSecret`; may be the same one) | Verifies publisher passes; shared with whatever mints them |
 | Firebase Admin credentials | The store and readers store |
 
 ## Contributing

package/lib/artifacts/auth.d.ts

@@ -1 +1,13 @@
+/** The Bearer is exactly this instance's publish key. */
 export declare function isPublishAuthed(request: Request, key: string | undefined): boolean;
+export type PublishAuth = {
+    /** The tenant's shared publish key. Read at request time. */
+    publishKey: () => string | undefined;
+    /** Verifies publisher passes. Absent, or returning nothing, means passes are refused. */
+    publisherSecret?: () => string | undefined;
+    /** The hostname a pass must name (`h`), e.g. artifacts.example.com. Absent means passes are refused. */
+    publisherHost?: string;
+};
+/** Every publish-key route's check: the tenant key, OR a valid publisher pass for this host
+ *  when the host opted in. A host that configures neither pass field behaves exactly as before. */
+export declare function isPublisherAuthed(request: Request, auth: PublishAuth, now?: number): boolean;

package/lib/artifacts/auth.js

@@ -1,8 +1,22 @@
-// One publish key per instance. The site gate lets the artifacts API through precisely
-// because this header is the whole authorization.
+// Who may publish. The site gate lets the artifacts API through precisely because the
+// Authorization header is the whole authorization.
+import { verifyPublisherPass } from './publisher.js';
+/** The Bearer is exactly this instance's publish key. */
 export function isPublishAuthed(request, key) {
     if (!key)
         return false;
     const h = request.headers.get('authorization') ?? '';
     return h === `Bearer ${key}`;
 }
+/** Every publish-key route's check: the tenant key, OR a valid publisher pass for this host
+ *  when the host opted in. A host that configures neither pass field behaves exactly as before. */
+export function isPublisherAuthed(request, auth, now = Date.now()) {
+    if (isPublishAuthed(request, auth.publishKey()))
+        return true;
+    if (!auth.publisherHost || !auth.publisherSecret)
+        return false;
+    const h = request.headers.get('authorization') ?? '';
+    if (!h.startsWith('Bearer '))
+        return false;
+    return verifyPublisherPass(auth.publisherSecret(), h.slice(7).trim(), auth.publisherHost, now) !== null;
+}

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/index.d.ts

@@ -2,7 +2,8 @@ export { parseArtifactSource, type ArtifactMeta } from './front-matter.js';
 export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';
-export { isPublishAuthed } from './auth.js';
+export { isPublishAuthed, isPublisherAuthed, type PublishAuth } from './auth.js';
+export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS, type Publisher } from './publisher.js';
 export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS, type Access, type Reader, type AllowEntry, type Decision } from './reader.js';

package/lib/artifacts/index.js

@@ -2,7 +2,8 @@ export { parseArtifactSource } from './front-matter.js';
 export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS } from './store.js';
-export { isPublishAuthed } from './auth.js';
+export { isPublishAuthed, isPublisherAuthed } from './auth.js';
+export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS } from './publisher.js';
 export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS } from './reader.js';

package/lib/artifacts/publisher.d.ts

@@ -0,0 +1,15 @@
+export declare const PUBLISHER_DOMAIN = "artifact-publisher";
+export declare const PUBLISHER_VERSION = "p1";
+export declare const PUBLISHER_PASS_TTL_SECONDS = 3600;
+/** Who a publisher pass names, and the one host it is good for. */
+export type Publisher = {
+    uid: string;
+    email: string;
+    name: string | null;
+    host: string;
+};
+export declare function mintPublisherPass(secret: string, p: Publisher, exp: number): string;
+/** The publisher a pass names, if it is correctly signed, unexpired, and for `host` (a hostname
+ *  like `artifacts.example.com`, no scheme). Anything else is null: a pass for another host is
+ *  refused even under the same secret, because two hosts can share one. */
+export declare function verifyPublisherPass(secret: string | undefined, pass: string | null | undefined, host: string | undefined, now?: number): Publisher | null;

package/lib/artifacts/publisher.js

@@ -0,0 +1,48 @@
+// The publisher pass: a short-lived, signed statement that a named person may do what the
+// publish key does, on ONE host.
+//
+// A shared publish key cannot be self-served and cannot be revoked for one person without
+// rotating it for everyone. A host that opts in (routes config `publisherSecret` +
+// `publisherHost`) also accepts this pass as the Bearer: a sign-in authority that knows who the
+// host's admins are mints it for one of them, and it expires within an hour, so revoking the
+// admin stops new passes and an outstanding one dies on its own.
+//
+// THE SHAPE IS A CONTRACT WITH THE AUTHORITY THAT MINTS IT, byte for byte: `p1.<payload>.<sig>`,
+// payload the base64url of `{ u, e, n, h, x }`, sig the first 32 hex of
+// HMAC-SHA256(secret, `artifact-publisher:p1.<payload>`). Same scheme as the reader pass, with its
+// own domain and version, so a reader pass (a1) or grant (g1) never verifies here and a
+// publisher pass never verifies as either (publisher.test.ts pins both directions and the vector).
+import { openToken, signToken } from './reader.js';
+export const PUBLISHER_DOMAIN = 'artifact-publisher';
+export const PUBLISHER_VERSION = 'p1';
+export const PUBLISHER_PASS_TTL_SECONDS = 3600;
+const normHost = (h) => h.trim().toLowerCase();
+export function mintPublisherPass(secret, p, exp) {
+    return signToken(secret, PUBLISHER_DOMAIN, PUBLISHER_VERSION, {
+        u: p.uid,
+        e: p.email.trim().toLowerCase(),
+        n: p.name,
+        h: normHost(p.host),
+        x: exp,
+    });
+}
+/** The publisher a pass names, if it is correctly signed, unexpired, and for `host` (a hostname
+ *  like `artifacts.example.com`, no scheme). Anything else is null: a pass for another host is
+ *  refused even under the same secret, because two hosts can share one. */
+export function verifyPublisherPass(secret, pass, host, now = Date.now()) {
+    if (!host)
+        return null;
+    const d = openToken(secret, PUBLISHER_DOMAIN, PUBLISHER_VERSION, pass, now);
+    if (!d)
+        return null;
+    if (typeof d.u !== 'string' || !d.u || typeof d.e !== 'string' || !d.e.includes('@') || typeof d.h !== 'string')
+        return null;
+    if (normHost(d.h) !== normHost(host))
+        return null;
+    return {
+        uid: d.u,
+        email: d.e.trim().toLowerCase(),
+        name: typeof d.n === 'string' && d.n.trim() ? d.n.trim() : null,
+        host: normHost(d.h),
+    };
+}

package/lib/artifacts/reader.d.ts

@@ -12,6 +12,13 @@ export declare const PASS_TTL_SECONDS = 300;
  *  changes need no wait: the list is read on every request. */
 export declare const GRANT_TTL_SECONDS: number;
 export declare const GRANT_COOKIE = "artifact_reader";
+/** Sign a small JSON payload as `<version>.<b64url(json)>.<sig>` under one domain. The domain is
+ *  in the MAC and the version is the token's first segment, so a token minted for one purpose
+ *  (reader pass, grant, publisher pass) never verifies as another. */
+export declare function signToken(secret: string, domain: string, version: string, data: Record<string, unknown>): string;
+/** The payload of a correctly signed, unexpired token of this domain and version, else null.
+ *  `x` (unix seconds) is required and checked; every other field is the caller's to validate. */
+export declare function openToken(secret: string | undefined, domain: string, version: string, token: string | null | undefined, now: number): Record<string, unknown> | null;
 export declare function mintPass(secret: string, reader: Reader, exp: number): string;
 export declare function verifyPass(secret: string | undefined, pass: string | null | undefined, now?: number): Reader | null;
 export declare function mintGrant(secret: string, reader: Reader, now?: number): string;

package/lib/artifacts/reader.js

@@ -29,13 +29,16 @@ function safeEqual(a, b) {
         return false;
     return timingSafeEqual(Buffer.from(a), Buffer.from(b));
 }
-function encode(secret, domain, version, reader, exp) {
-    // Short keys: this rides in a URL and a cookie.
-    const payload = b64url(JSON.stringify({ u: reader.uid, e: reader.email, n: reader.name, m: reader.member, x: exp }));
-    const body = `${version}.${payload}`;
+/** Sign a small JSON payload as `<version>.<b64url(json)>.<sig>` under one domain. The domain is
+ *  in the MAC and the version is the token's first segment, so a token minted for one purpose
+ *  (reader pass, grant, publisher pass) never verifies as another. */
+export function signToken(secret, domain, version, data) {
+    const body = `${version}.${b64url(JSON.stringify(data))}`;
     return `${body}.${sig(secret, domain, body)}`;
 }
-function decode(secret, domain, version, token, now) {
+/** The payload of a correctly signed, unexpired token of this domain and version, else null.
+ *  `x` (unix seconds) is required and checked; every other field is the caller's to validate. */
+export function openToken(secret, domain, version, token, now) {
     if (!secret || typeof token !== 'string')
         return null;
     const parts = token.split('.');
@@ -51,7 +54,20 @@ function decode(secret, domain, version, token, now) {
     catch {
         return null;
     }
-    if (typeof d.x !== 'number' || d.x * 1000 < now)
+    if (!d || typeof d !== 'object' || Array.isArray(d))
+        return null;
+    const o = d;
+    if (typeof o.x !== 'number' || o.x * 1000 < now)
+        return null;
+    return o;
+}
+function encode(secret, domain, version, reader, exp) {
+    // Short keys: this rides in a URL and a cookie.
+    return signToken(secret, domain, version, { u: reader.uid, e: reader.email, n: reader.name, m: reader.member, x: exp });
+}
+function decode(secret, domain, version, token, now) {
+    const d = openToken(secret, domain, version, token, now);
+    if (!d)
         return null;
     if (typeof d.u !== 'string' || !d.u || typeof d.e !== 'string' || !d.e.includes('@'))
         return null;

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,10 +18,23 @@ 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. */
     publishKey: () => string | undefined;
+    /** Verifies publisher passes (`p1`, see artifacts/publisher.ts): a signed, hour-long stand-in
+     *  for the publish key, minted for one person by an authority that knows who may publish here.
+     *  Read at request time. Without it, or without `publisherHost`, passes are refused. */
+    publisherSecret?: () => string | undefined;
+    /** The hostname a publisher pass must name, e.g. artifacts.example.com. Set it only on a host
+     *  that opts in to passes. */
+    publisherHost?: string;
     /** Share image when an artifact has no cover. Absolute or site-relative. */
     defaultShareImage?: string;
     /** Where a page lives under the origin. '/' on a dedicated host (artifacts.<name>/<id>);

package/lib/routes/artifacts.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { revalidatePath } from 'next/cache';
 import { notFound, redirect } from 'next/navigation';
 import { NextResponse } from 'next/server';
-import { isPublishAuthed } from '../artifacts/auth.js';
+import { isPublisherAuthed } from '../artifacts/auth.js';
 import { parseArtifactSource } from '../artifacts/front-matter.js';
 import { narrationText } from '../artifacts/narration.js';
 import { ArtifactMarkdown } from '../artifacts/render.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}`;
@@ -60,8 +69,11 @@ export function createArtifactRoutes(config) {
     // Readers' recordings are played through short-lived signed URLs, issued only beside the comment
     // or note they belong to; a host whose assets cannot sign them shows no play control.
     const audioUrl = config.assets?.audioUrl ? (id, path) => config.assets.audioUrl(id, path) : undefined;
+    const publishAuth = { publishKey: config.publishKey, publisherSecret: config.publisherSecret, publisherHost: config.publisherHost };
+    const authed = (request) => isPublisherAuthed(request, publishAuth);
     const stateRoutes = createStateRoutes({
-        store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey, pageUrl, signInOrigin, siteUrl,
+        store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey,
+        publisherSecret: config.publisherSecret, publisherHost: config.publisherHost, pageUrl, signInOrigin, siteUrl,
         clientIp: config.clientIp, ownerEmail: config.ownerEmail, audioUrl,
     });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
@@ -71,7 +83,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 +92,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 +142,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 +169,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 +182,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 +218,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 +238,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 +257,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 }))] }));
     }
@@ -329,7 +358,7 @@ export function createArtifactRoutes(config) {
     /** GET|POST /api/artifacts/<id>/access, publish key: the page's level and its list.
      *  POST body: { access?: 'freedom'|'invite'|'public', add?: [{ email, name?, reason? }], remove?: [email] }. */
     async function ACCESS(request, { params }) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         if (!config.readers)
             return NextResponse.json({ error: 'this host keeps no reader record' }, { status: 501 });
@@ -364,7 +393,7 @@ export function createArtifactRoutes(config) {
     /** GET /api/artifacts/<id>/reads, publish key: who read it, for how long, how far, and every
      *  attempt to take it away or to open it without being let in. */
     async function READS(request, { params }) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         if (!config.readers)
             return NextResponse.json({ error: 'this host keeps no reader record' }, { status: 501 });
@@ -376,7 +405,7 @@ export function createArtifactRoutes(config) {
         return NextResponse.json({ id, title: a.title, access: a.access ?? null, views: a.views, ...summarize(sessions, flags), acks: acks.map((k) => ({ email: k.email, name: k.name, at: k.at })) }, { headers: { 'cache-control': 'no-store' } });
     }
     async function POST(request) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const text = await request.text();
         const parsed = parseArtifactSource(text);
@@ -421,7 +450,7 @@ export function createArtifactRoutes(config) {
         }, { status: result.created ? 201 : 200 });
     }
     async function GET(request, { params }) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
         const a = await store.get(id);
@@ -431,7 +460,7 @@ export function createArtifactRoutes(config) {
     }
     /** PUT /api/artifacts/<id>/assets/<name>: raw bytes in, public URL out. 16 MiB cap. */
     async function PUT_ASSET(request, { params }) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         if (!config.assets)
             return NextResponse.json({ error: 'this host does not store assets' }, { status: 501 });
@@ -475,7 +504,7 @@ export function createArtifactRoutes(config) {
             const { id, name } = await params;
             return voiceRoutes.readerUpload(request, id, name, body);
         }
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const assets = config.assets;
         if (!assets?.signUpload || !assets.finishUpload)
@@ -505,17 +534,18 @@ 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 }. */
     async function VERSIONS(request, { params }) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
         if (!store.history || !store.setNote)
@@ -534,7 +564,7 @@ export function createArtifactRoutes(config) {
         return NextResponse.json({ id, versions: await store.history(id) });
     }
     async function DELETE(request, { params }) {
-        if (!isPublishAuthed(request, config.publishKey()))
+        if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
         const ok = await store.delete(id);

package/lib/routes/state-routes.d.ts

@@ -20,6 +20,9 @@ export type StateRoutesContext = {
     readers?: ReadersStore;
     readerSecret: () => string | undefined;
     publishKey: () => string | undefined;
+    /** Publisher passes, as in ArtifactRoutesConfig. Both absent means passes are refused. */
+    publisherSecret?: () => string | undefined;
+    publisherHost?: string;
     pageUrl: (id: string) => string;
     signInOrigin?: string;
     siteUrl: string;

package/lib/routes/state-routes.js

@@ -11,7 +11,7 @@
 // signed-in reader, once, and the cookie is cleared.
 import { createHmac, randomBytes } from 'node:crypto';
 import { NextResponse } from 'next/server';
-import { isPublishAuthed } from '../artifacts/auth.js';
+import { isPublisherAuthed } from '../artifacts/auth.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { GRANT_COOKIE, decide, firstName, signInUrl, verifyGrant } from '../artifacts/reader.js';
 import { isUnlocked, unlockCookieName } from '../artifacts/unlock.js';
@@ -290,7 +290,7 @@ export function createStateRoutes(ctx) {
         return res;
     }
     async function RESPONSES(req, { params }) {
-        if (!isPublishAuthed(req, ctx.publishKey()))
+        if (!isPublisherAuthed(req, ctx))
             return json({ error: 'Unauthorized' }, 401);
         if (!ctx.state)
             return json({ error: 'this host keeps no answers' }, 501);
@@ -316,7 +316,7 @@ export function createStateRoutes(ctx) {
      *  page. It reads the `comments` slot of the state core only; personal notes live in a store no
      *  publisher route reads, so they cannot appear here. The publisher's own notifier polls it. */
     async function COMMENTS_FEED(req) {
-        if (!isPublishAuthed(req, ctx.publishKey()))
+        if (!isPublisherAuthed(req, ctx))
             return json({ error: 'Unauthorized' }, 401);
         const since = feedSince(req.nextUrl.searchParams.get('since'));
         if (!since)

package/package.json

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