@supersuit/artifacts 0.46.1 → 0.48.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 `@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.48.0
+
+**Unpublishing keeps the history.** `POST /api/artifacts?id=<id>&unpublish=1` takes a page off the
+web and keeps everything that happened on it: the record, every version, every comment, every
+file. Every reader-facing path (the page, its versions, its share card, comments, answers, per-reader
+links) reads through a view of the store that does not see an unpublished page, so each answers
+404; the publisher's own routes (publish, the narration GET, uploads, DELETE) still reach it. A
+republish to the id puts the page back at the same link. Until now the only way to take a page
+down was DELETE, which destroys every version and every comment for good. DELETE is unchanged,
+and is now the explicit "destroy" rather than the only "take down". The new store method is
+`setUnpublished(id, at | null)`; the Firestore store has it, and a store without it answers 501.
+On the publish route rather than a new one, so no host has a route file to add, and a host older
+than this answers the empty body with a 400 and changes nothing.
+
+- DETECTOR: a publisher that sends `?unpublish=1` and gets a 400 is talking to a host before 0.48.0.
+- REMEDY: update the dependency. Nothing to configure.
+- Tests: unpublish.test.tsx.
+
+## 0.47.0
+
+**Figures and Helm scenes play inline, as two new embed fences.** A ```` ```figure ```` block
+(`figure: <id>`, `caption:`, optional `height:`, default 560px) plays an interactive figure, and a
+```` ```helm ```` block (`scene: <id>`, `caption:`, optional `height:`, default 760px, optional
+`autoplay: true`) plays a scene on a Helm phone, both in the same fitted, lazy frame and under the
+same caption as `simulator` and `messages`. They are rows in the one table of embed kinds, which
+now also carries per-kind options (helm's `autoplay`, passed to the embed page only when true), so
+a fifth kind is one line. Publish refuses a block with no id or no caption, naming the line. Embed
+blocks, the old two included, no longer take a comment anchor: the player and its caption were
+never selectable text. The host names the pages with two new config fields, `figureEmbed` and
+`helmEmbed`; there is no default. `ArtifactMarkdown` takes every kind's page as `embeds`
+(`simulator` and `messages` still work).
+
+- DETECTOR: a page carrying a ```` ```figure ```` or ```` ```helm ```` block. Before, it drew as a code block.
+- REMEDY: update the dependency, and set `figureEmbed` / `helmEmbed` in `createArtifactRoutes` to
+  the host's figure and Helm embed pages. Without them the blocks show their caption only.
+- Tests: simulator.test.ts ("the figure block", "the helm block", "every embed kind"),
+  render.test.tsx ("the figure and helm blocks", "an embed block is not read aloud"),
+  widgets.test.ts ("scanWidgets and the figure and helm blocks", "blocksOf and embed blocks").
+
 ## 0.46.1
 
 0.46.0 republished: its tag's publish run refused on two settings-menu tests that still listed the

package/README.md

@@ -116,6 +116,13 @@ hostname and pick by the `host` header.
 body. The response carries the page's id and URL. Posting a file whose front matter carries
 that `id:` republishes it in place, keeping every earlier version.
 
+**Taking a page down keeps its history (0.48.0).** `POST /api/artifacts?id=<id>&unpublish=1`
+(publish key, empty body) takes the page off the web: every reader path answers 404, and the
+record, every version, every comment and every file are kept. Republishing to that id puts it back
+at the same link. `DELETE /api/artifacts/<id>` is the separate act that destroys all of it. A host
+older than 0.48.0 answers the unpublish with a 400 and changes nothing, so a publisher can never
+mistake it for a delete; a store without `setUnpublished` answers 501, likewise changing nothing.
+
 ## The page menu
 
 Every page, past version and door carries one small round **⋯** button in the top right corner
@@ -676,6 +683,43 @@ Paste it under the audio line, then correct any word (a name, a phrase in anothe
 and keep its two times. `transcriptFenceFromWords` and `wordsFromWhisperJson` (from
 `@supersuit/artifacts/artifacts`) do the same from code.
 
+## Embedded players (`simulator`, `messages`, `figure`, `helm`)
+
+Four fences play a page the HOST serves, inline, in a frame under a caption:
+
+| Fence | Names | Default height | Plays |
+| --- | --- | --- | --- |
+| `simulator` | `scenario: <id>` (required) | 720px | a Supersuit Session demo |
+| `messages` | `chat: <id>` (optional) | 760px | a Messages-app phone, open on one thread or the list |
+| `figure` | `figure: <id>` (required) | 560px | an interactive figure |
+| `helm` | `scene: <id>` (required), `autoplay: true` (optional) | 760px | a scene on a Helm phone |
+
+````markdown
+```figure
+figure: doug-week
+caption: A week of Doug, before and after.
+height: 560px        # optional
+```
+
+```helm
+scene: doug-walk
+caption: A year later, on the reservoir loop.
+autoplay: true       # optional, true or false
+```
+````
+
+- **Every block needs a `caption`**, the line a reader sees under the player. Publish refuses a
+  block with no caption, no required id, an id that is not lowercase letters, digits and dashes, a
+  height that is not pixels, or an unknown key, naming the line in the file.
+- **The host names each player's embed page** (`simulatorEmbed`, `messagesEmbed`, `figureEmbed`,
+  `helmEmbed` in `createArtifactRoutes`, each an https URL; or `embeds` on `ArtifactMarkdown`). The
+  frame loads it with the id (`?figure=doug-week`, `?scene=doug-walk`) and `fit=content`. There is
+  no default: a host that names no page for a kind shows that block's caption alone, never its
+  source as code, which is also what print and a page with the player blocked show.
+- **The frame fits its player.** It opens at `height:` and takes the height the embed page posts
+  as `{ type: 'embed:fit', height }` from its own origin.
+- **Narration skips it**, caption included, and it carries no comment anchor.
+
 ## Comments and personal notes
 
 Every page takes comments pinned to any part of it. A reader selects text (a **Comment** chip

package/lib/artifacts/index.d.ts

@@ -1,5 +1,5 @@
 export { parseArtifactSource, ARTIFACT_KINDS, PAGE_HISTORY, type ArtifactMeta, type ArtifactKind, type PageHistory } from './front-matter.js';
-export { ArtifactMarkdown, artifactUrlTransform } from './render.js';
+export { ArtifactMarkdown, artifactUrlTransform, type EmbedCtx } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, cleanNote, kindOf, listOfKind, MAX_CHANGE_NOTE_CHARS, type ArtifactListItem, type ArtifactStore, type ArtifactRecord, type SaveResult, type SaveInput, type VersionEntry, type VersionRecord } from './store.js';
 export { isPublishAuthed, isPublisherAuthed, type PublishAuth } from './auth.js';

package/lib/artifacts/render.d.ts

@@ -1,12 +1,15 @@
 import { type ComponentType } from 'react';
 import type { FigureProps, SectionOutline, SectionProps } from '../brand/pack.js';
 import { type Heading } from './widgets.js';
+import { type EmbedKind } from './simulator.js';
 import { type Definition } from './definitions.js';
 export declare function isReachableHref(href: unknown): href is string;
 export declare function artifactUrlTransform(url: string): string;
 type SimulatorCtx = {
     embed: string;
 };
+/** The host's embed page for each embed kind it serves (ArtifactMarkdown `embeds`). */
+export type EmbedCtx = Partial<Record<EmbedKind, SimulatorCtx>>;
 /** 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
@@ -14,7 +17,7 @@ export type FigureFor = (src: string, alt: string) => ComponentType<FigureProps>
 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, checklist, definitions, Section, figure, simulator, messages, }: {
+export declare function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, messages, embeds: hosted, }: {
     markdown: string;
     /** The page a ```checklist keeps its ticks under, and whether its Send can reach the owner
      *  (a host that keeps answers, on a page that declares the slot). On a page whose checklists
@@ -40,5 +43,9 @@ export declare function ArtifactMarkdown({ markdown, notes, checklist, definitio
     simulator?: SimulatorCtx;
     /** The host's Messages phone, for ```messages blocks. Without it a block shows its caption only. */
     messages?: SimulatorCtx;
+    /** The host's embed page for every embed kind it serves (```simulator, ```messages, ```figure,
+     *  ```helm). A kind with none shows its caption only. `simulator` and `messages` above still work
+     *  and win over this. */
+    embeds?: EmbedCtx;
 }): import("react").JSX.Element;
 export {};

package/lib/artifacts/render.js

@@ -17,7 +17,7 @@ import { unified } from 'unified';
 import { blocksOf, checklistSyncs, checklistsOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { Checklist } from '../widgets/checklist.js';
-import { embedSrc, parseEmbedFence } from './simulator.js';
+import { embedSrc, isEmbedKind, parseEmbedFence, EMBED_KINDS } from './simulator.js';
 import { EmbedFrame } from './embed-frame.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
@@ -114,6 +114,8 @@ function InlineAudio({ src, label }) {
     const html = `<audio src="${escapeAttr(src)}" aria-label="${escapeAttr(label)}" data-artifact-audio data-artifact-media="${escapeAttr(mediaName(src))}" 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 } })] }));
 }
+/** Fences that draw something other than code, so `pre` must not wrap them. */
+const OWN_BLOCK = new RegExp(`language-(links|notes|checklist|transcript|${EMBED_KINDS.join('|')})\\b`);
 // A session demo on a wide screen is wider than the reading column, so the device it draws (a
 // laptop, or a phone beside what was made) has room: up to 64rem, centred on the column, and clear
 // of the contents rail fixed in the left margin from 1280px (w-56 at left-6, w-64 at left-12).
@@ -125,14 +127,14 @@ const WIDE_EMBED_CSS = `@media (min-width:1024px){${WIDE}{width:max(100%,min(64r
     `[data-broadcast] ${WIDE}{width:auto;margin-left:0;transform:none}[data-broadcast] ${WIDE} figcaption{text-align:inherit}}` +
     `@media (min-width:1280px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 36rem)))}}` +
     `@media (min-width:1536px){${WIDE}{width:max(100%,min(64rem,calc(100vw - 40rem)))}}`;
-/** An embed block (```simulator, ```messages): the player in a frame when the host names one, its
+/** An embed block (```simulator, ```messages, ```figure, ```helm): the player in a frame when the host names one, its
  *  caption alone when it does not, and nothing when the block does not parse (a page published
  *  before validation existed). */
 function EmbedFence({ kind, source, ctx }) {
     const r = parseEmbedFence(kind, source.replace(/\n$/, ''), 0);
     if (!r.ok)
         return null;
-    const src = ctx ? embedSrc(kind, ctx.embed, r.block.value) : null;
+    const src = ctx ? embedSrc(kind, ctx.embed, r.block.value, r.block.options) : null;
     const wide = kind === 'simulator' && src != null;
     return (
     // data-nospeak: the narration skips every fenced block (narration.ts), so the caption must not
@@ -219,7 +221,7 @@ function baseComponents(block, figure, checklists, embeds, voiceNotes) {
             // A transcript not under an audio line draws nothing (publish refuses one; an old page may hold it).
             if (lang === TRANSCRIPT_LANG)
                 return null;
-            if (lang === 'simulator' || lang === 'messages')
+            if (isEmbedKind(lang))
                 return _jsx(EmbedFence, { kind: lang, source: textOf(children), ctx: embeds?.[lang] });
             if (!className) {
                 return _jsx("code", { className: "rounded bg-[color:var(--a-surface-strong)] px-1.5 py-0.5 text-[0.9em] text-[color:var(--a-strong)]", children: children });
@@ -230,7 +232,7 @@ function baseComponents(block, figure, checklists, embeds, voiceNotes) {
             // A links fence renders its own block; do not wrap it in <pre>.
             const inner = Array.isArray(children) ? children[0] : children;
             const cls = inner?.props?.className ?? '';
-            if (/language-(links|notes|checklist|simulator|messages|transcript)/.test(cls))
+            if (OWN_BLOCK.test(cls))
                 return _jsx(_Fragment, { children: children });
             return (_jsx("pre", { ...block(node), "data-artifact-code": true, 
                 // whitespace-pre-wrap, because a fence here usually holds PROSE meant to be pasted
@@ -355,9 +357,9 @@ 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, checklist, definitions, Section, figure, simulator, messages, }) {
+export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Section, figure, simulator, messages, embeds: hosted, }) {
     const on = !!notes && hasNotesWidget(markdown);
-    const embeds = { simulator, messages };
+    const embeds = { ...hosted, ...(simulator ? { simulator } : {}), ...(messages ? { messages } : {}) };
     const headings = headingsOf(markdown);
     const blocks = blocksOf(markdown);
     const block = (node) => {

package/lib/artifacts/simulator.d.ts

@@ -1,10 +1,12 @@
-export type EmbedKind = 'simulator' | 'messages';
+export type EmbedKind = 'simulator' | 'messages' | 'figure' | 'helm';
 export declare const EMBED_KINDS: EmbedKind[];
 export declare const isEmbedKind: (k: unknown) => k is EmbedKind;
+/** `options` holds a kind's further keys (helm's `autoplay`) as written, and is absent when none were. */
 export type EmbedBlock = {
     value: string | null;
     caption: string;
     height: string;
+    options?: Record<string, string>;
 };
 export type SimulatorBlock = {
     scenario: string;
@@ -22,7 +24,7 @@ export declare function parseEmbedFence(kind: EmbedKind, value: string, line: nu
 };
 /** The address a player loads: the host's embed page, what to open, any fixed switches. Null for an
  *  embed address that is not https, so a misconfigured host frames nothing. */
-export declare function embedSrc(kind: EmbedKind, embed: string, value: string | null): string | null;
+export declare function embedSrc(kind: EmbedKind, embed: string, value: string | null, options?: Record<string, string>): string | null;
 /** The ```simulator block (kept for callers of 0.25.0). */
 export declare function parseSimulatorFence(value: string, line: number): {
     ok: true;

package/lib/artifacts/simulator.js

@@ -8,7 +8,7 @@
 //
 // `simulator` is a Supersuit Session demo; `messages` is a Messages-app phone of real threads. The
 // block names what to open and a caption; the HOST names each player's embed page
-// (ArtifactRoutesConfig.simulatorEmbed / messagesEmbed), so this public package points at nobody's
+// (ArtifactRoutesConfig.simulatorEmbed / messagesEmbed / figureEmbed / helmEmbed), so this public package points at nobody's
 // service by default, and a host without the player draws the caption alone rather than the block's
 // source as code. `simulator` keeps the syntax the Superskills book's reader takes.
 //
@@ -19,9 +19,12 @@
 // frame then takes (EmbedFrame). A page that posts nothing keeps the block's height. The embed
 // page must hold its player's size once asked, never size it from its own viewport, or the two
 // chase each other; that is why the frame listens only for this message and for no player's own.
+const BOOL = { values: ['true', 'false'], off: 'false' };
 const KINDS = {
     simulator: { key: 'scenario', required: true, fixed: { timeline: 'off', fit: 'content' }, height: '720px' },
     messages: { key: 'chat', required: false, fixed: {}, height: '760px' },
+    figure: { key: 'figure', required: true, fixed: { fit: 'content' }, height: '560px' },
+    helm: { key: 'scene', required: true, fixed: { fit: 'content' }, height: '760px', options: { autoplay: BOOL } },
 };
 export const EMBED_KINDS = Object.keys(KINDS);
 export const isEmbedKind = (k) => typeof k === 'string' && Object.hasOwn(KINDS, k);
@@ -31,7 +34,8 @@ const HEIGHT = /^\d{3,4}px$/;
  *  line the author sees. */
 export function parseEmbedFence(kind, value, line) {
     const spec = KINDS[kind];
-    const keys = [spec.key, 'caption', 'height'];
+    const opts = spec.options ?? {};
+    const keys = [spec.key, 'caption', 'height', ...Object.keys(opts)];
     const got = {};
     const rows = value ? value.split('\n') : [];
     for (let i = 0; i < rows.length; i++) {
@@ -55,11 +59,23 @@ export function parseEmbedFence(kind, value, line) {
         return { ok: false, error: `line ${line}: the ${kind} block needs a caption, the line a reader sees under it` };
     if (got.height && !HEIGHT.test(got.height.v))
         return { ok: false, error: `line ${got.height.at}: a ${kind} height is a number of pixels, like 760px` };
-    return { ok: true, block: { value: id?.v ?? null, caption: got.caption.v, height: got.height?.v ?? spec.height } };
+    const options = {};
+    for (const [name, o] of Object.entries(opts)) {
+        const g = got[name];
+        if (!g)
+            continue;
+        if (!o.values.includes(g.v))
+            return { ok: false, error: `line ${g.at}: a ${kind} ${name} is ${o.values.join(' or ')}` };
+        options[name] = g.v;
+    }
+    const block = { value: id?.v ?? null, caption: got.caption.v, height: got.height?.v ?? spec.height };
+    if (Object.keys(options).length)
+        block.options = options;
+    return { ok: true, block };
 }
 /** The address a player loads: the host's embed page, what to open, any fixed switches. Null for an
  *  embed address that is not https, so a misconfigured host frames nothing. */
-export function embedSrc(kind, embed, value) {
+export function embedSrc(kind, embed, value, options) {
     let u;
     try {
         u = new URL(embed);
@@ -72,6 +88,11 @@ export function embedSrc(kind, embed, value) {
     const spec = KINDS[kind];
     if (value)
         u.searchParams.set(spec.key, value);
+    for (const [name, o] of Object.entries(spec.options ?? {})) {
+        const v = options?.[name];
+        if (v && v !== o.off && o.values.includes(v))
+            u.searchParams.set(name, v);
+    }
     for (const [k, v] of Object.entries(spec.fixed))
         u.searchParams.set(k, v);
     return u.toString();

package/lib/artifacts/store.d.ts

@@ -57,6 +57,10 @@ export type ArtifactRecord = {
      *  given: a version is never described by anything its author did not write. */
     note?: string;
     views: number;
+    /** When the page was taken off the web (0.48.0). The record, every version, every comment and
+     *  every file are KEPT: an unpublished page is served to no reader, and a republish to its id
+     *  puts it back. DELETE is the separate act that destroys. */
+    unpublishedAt?: string;
 };
 /** One line of a page's history. `at` is when that version went live. */
 export type VersionEntry = {
@@ -130,6 +134,9 @@ export interface ArtifactStore {
     version?(id: string, n: number): Promise<VersionRecord | null>;
     /** Write (or, with null, clear) the change note on one version after the fact. */
     setNote?(id: string, n: number, note: string | null): Promise<boolean>;
+    /** Take a page off the web keeping everything (an ISO time), or put it back (null). False when
+     *  no such page. A store without it can only destroy, and the host refuses to unpublish. */
+    setUnpublished?(id: string, at: string | null): Promise<boolean>;
     /** Every page of one kind, newest first, without bodies (0.37.0): the owner's documents and the
      *  owner's broadcasts are two lists. */
     list?(kind: ArtifactKind): Promise<ArtifactListItem[]>;

package/lib/artifacts/store.js

@@ -69,6 +69,13 @@ export function createArtifactStore(db, collection = 'artifacts') {
         history: (id) => historyOf(col, id),
         version: (id, n) => versionOf(col, id, n),
         setNote: (id, n, note) => setNote(col, id, n, note),
+        setUnpublished: async (id, at) => {
+            const ref = col().doc(id);
+            if (!(await ref.get()).exists)
+                return false;
+            await ref.update({ unpublishedAt: at ?? FieldValue.delete() });
+            return true;
+        },
         list: async (kind) => {
             // `select` keeps every body out of the listing; a tenant's pages number in the hundreds.
             const snap = await col().select('title', 'summary', 'template', 'createdAt', 'updatedAt', 'views').get();
@@ -231,6 +238,8 @@ async function saveArtifact(col, input) {
             // `updatedAt` is when this version went live; finishing its own publish does not move it.
             ...(fresh || input.markdown !== existing.markdown ? { updatedAt: now } : {}),
             note: nextNote ?? FieldValue.delete(),
+            // A republish is the page going back up: an unpublished page is live again at the same link.
+            unpublishedAt: FieldValue.delete(),
             ...(existing.versions ? { versions: FieldValue.delete() } : {}),
         });
         return { id: input.id, version: next, created: false };

package/lib/artifacts/widgets.js

@@ -292,7 +292,9 @@ export function blocksOf(markdown) {
             content = plain(n);
         }
         else if (n.type === 'code') {
-            if (n.lang === 'links' || n.lang === NOTES_SLOT || n.lang === 'checklist' || n.lang === TRANSCRIPT_LANG)
+            // An embed block draws a player and a caption the reader cannot comment on (data-nospeak, no
+            // data-block), so it takes no anchor either.
+            if (n.lang === 'links' || n.lang === NOTES_SLOT || n.lang === 'checklist' || n.lang === TRANSCRIPT_LANG || isEmbedKind(n.lang))
                 continue;
             kind = 'code';
             content = n.value;

package/lib/routes/artifacts.d.ts

@@ -37,6 +37,13 @@ export type ArtifactRoutesConfig = {
     /** The embed page of this host's Messages phone (an https URL), for ```messages blocks: a
      *  `chat=<id>` opens one thread. Without it a block shows its caption only. No default. */
     messagesEmbed?: string;
+    /** The embed page of this host's interactive figures (an https URL, e.g.
+     *  https://example.com/figures/embed), for ```figure blocks: `figure=<id>` opens one. Without it
+     *  a block shows its caption only. No default. */
+    figureEmbed?: string;
+    /** The embed page of this host's Helm player (an https URL), for ```helm blocks: `scene=<id>`
+     *  plays one, `autoplay=true` when the block asks. Without it a block shows its caption only. No default. */
+    helmEmbed?: 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
@@ -222,6 +229,10 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     }>>;
     POST: (request: NextRequest) => Promise<NextResponse<{
         error: string;
+    }> | NextResponse<{
+        id: string;
+        unpublished: boolean;
+        at: string;
     }> | NextResponse<{
         warning?: string | undefined;
         expireAt?: string | null | undefined;

package/lib/routes/artifacts.js

@@ -71,7 +71,11 @@ function ViewingAsReader({ back }) {
     return (_jsx("div", { "data-viewing-as-reader": true, "data-nospeak": true, className: "fixed inset-x-0 top-3 z-50 flex justify-center px-3", children: _jsxs("p", { className: "m-0 rounded-full border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] px-4 py-1.5 font-sans text-xs text-[color:var(--a-strong)] shadow-lg", children: ["Viewing as a reader \u00B7 ", _jsx("a", { href: back, className: "underline", children: "Back to your view" })] }) }));
 }
 export function createArtifactRoutes(config) {
-    const { store, siteUrl } = config;
+    const { store: kept, siteUrl } = config;
+    // An unpublished page (0.48.0) is KEPT, versions, comments and files all, and served to nobody:
+    // every reader-facing path reads through this view, which does not see it. The publisher's own
+    // routes (POST, GET, DELETE, the uploads) read `kept`, so the page can be put back or destroyed.
+    const store = { ...kept, get: async (id) => { const a = await kept.get(id); return a?.unpublishedAt ? null : a; } };
     // The pack as configured draws the share card; the page paints with its theme variables, so a
     // page follows its light, dark or system mode (brand/theme.ts).
     const pack = config.brand;
@@ -92,6 +96,11 @@ export function createArtifactRoutes(config) {
     // The version in the URL is what makes a re-publish show up: every unfurler caches by URL.
     const signInOrigin = config.signInOrigin;
     const owner = config.owner ?? brand.name;
+    // The embed page of each player this host serves, for every ArtifactMarkdown below.
+    const embeds = {};
+    for (const [kind, url] of [['simulator', config.simulatorEmbed], ['messages', config.messagesEmbed], ['figure', config.figureEmbed], ['helm', config.helmEmbed]])
+        if (url)
+            embeds[kind] = { embed: url };
     const ownerEmail = config.ownerEmail?.trim().toLowerCase();
     const admins = new Set([ownerEmail, ...(config.admins ?? []).map((e) => e.trim().toLowerCase())].filter((e) => !!e));
     /** Whether this reader may see this page's version number and past versions: the page's own
@@ -465,7 +474,7 @@ 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: [_jsx(Menu, { a: a, reader: reader, history: history, viewing: n, settings: await settingsFor(a, reader), source: isAdmin(reader) ? sourceOf(a.id, { title, subtitle: v.subtitle, summary, to: v.to }, v.markdown) : null }), 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, { n: n, at: v.at, numbered: true }), version: n, showVersion: true, 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, { n: n, at: v.at, numbered: true })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
+        return (_jsxs(_Fragment, { children: [_jsx(Menu, { a: a, reader: reader, history: history, viewing: n, settings: await settingsFor(a, reader), source: isAdmin(reader) ? sourceOf(a.id, { title, subtitle: v.subtitle, summary, to: v.to }, v.markdown) : null }), 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, { n: n, at: v.at, numbered: true }), version: n, showVersion: true, 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, { n: n, at: v.at, numbered: true })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, embeds: embeds, definitions: a.definitions, checklist: { artifactId: a.id, accent: brand.accent }, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** A broadcast: one message card. The sender's words at the top, then the media (a video with
      *  sound and controls, photos, a voice note's player, link cards) in the order the words put
@@ -480,7 +489,7 @@ export function createArtifactRoutes(config) {
         const cover = !bot && a.cover && !/!\[[^\]]*\]\(/.test(a.markdown) ? a.cover : null;
         return (_jsxs(_Fragment, { children: [admin ? (_jsx(PageMenu, { role: roleOf(reader), name: reader ? reader.name ?? reader.email : null, share: null, comments: mode !== 'off', signIn: null, signOut: signOutUrl(a.id), history: null, markdown: null, settings: null })) : null, _jsx("main", { "data-broadcast": true, className: "mx-auto max-w-lg px-4 pt-16 pb-20 sm:pt-24", children: _jsxs("article", { id: "broadcast-root", "data-broadcast-card": true, className: "rounded-2xl border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-5 py-6 sm:px-7 sm:py-8", children: [_jsx("p", { "data-nospeak": true, "data-broadcast-from": true, className: "text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: `From ${owner}` }), _jsx("h1", { className: "mt-3 text-2xl sm:text-3xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), cover ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone', signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null] }));
+                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone', signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader, perReader }) {
@@ -507,7 +516,7 @@ export function createArtifactRoutes(config) {
                         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, showVersion: seesHistory(a, reader), 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: [perReader?.closesAt && !perReader.owner ? (_jsx(FeedbackWindow, { owner: owner, label: perReader.label, note: perReader.note, group: perReader.group, closesAt: perReader.closesAt })) : perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, 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, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
-                                checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }));
+                                checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, embeds: embeds }) }));
                     })() }), _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: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));
@@ -766,6 +775,21 @@ export function createArtifactRoutes(config) {
     async function POST(request) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        // `?unpublish=1`: take the page off the web and keep everything. On the publish route rather
+        // than a route of its own so no host has a file to add, and so a host older than 0.48.0 refuses
+        // the empty body with a 400 instead of doing anything at all: it can never be mistaken for a delete.
+        if (request.nextUrl.searchParams.get('unpublish') === '1') {
+            const id = request.nextUrl.searchParams.get('id');
+            if (!id || !ARTIFACT_ID.test(id))
+                return NextResponse.json({ error: 'unpublish needs ?id=<page id>' }, { status: 400 });
+            if (!kept.setUnpublished)
+                return NextResponse.json({ error: 'this store cannot keep a page unpublished; nothing was changed' }, { status: 501 });
+            const at = new Date().toISOString();
+            if (!(await kept.get(id)) || !(await kept.setUnpublished(id, at)))
+                return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+            revalidatePath(pagePath(id));
+            return NextResponse.json({ id, unpublished: true, at });
+        }
         const text = await request.text();
         let parsed = parseArtifactSource(text);
         if (!parsed.ok)
@@ -774,7 +798,7 @@ export function createArtifactRoutes(config) {
         // The kind is sticky, like `links:`: a republish of a broadcast that leaves `template:` out is
         // still a broadcast, and one that says `document` is refused rather than quietly changed.
         if (id && parsed.meta.template === 'document') {
-            const stored = await store.get(id);
+            const stored = await kept.get(id);
             if (stored && kindOf(stored) === 'broadcast') {
                 const again = parseArtifactSource(text, { defaultKind: 'broadcast' });
                 if (!again.ok)
@@ -787,10 +811,10 @@ export function createArtifactRoutes(config) {
         // Fail closed: private media needs a private store. Without one the media would have to sit in
         // the public bucket, which may carry a bucket-wide public read grant, so nothing is saved.
         // `media:` is sticky, so a stored page that already keeps private media counts too.
-        if (!keepsPrivateMedia() && (parsed.meta.privateMedia || (id && (await store.get(id))?.privateMedia)))
+        if (!keepsPrivateMedia() && (parsed.meta.privateMedia || (id && (await kept.get(id))?.privateMedia)))
             return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         if (id && parsed.meta.state) {
-            const existing = await store.get(id);
+            const existing = await kept.get(id);
             const changed = shapeChanges(existing?.state, parsed.meta.state);
             if (changed.length)
                 return NextResponse.json({ error: changed.join('; ') }, { status: 400 });
@@ -817,7 +841,7 @@ export function createArtifactRoutes(config) {
         // `?amend=1` is the publisher finishing the publish it started (image URLs, then narration).
         const note = cleanNote(request.nextUrl.searchParams.get('note')) ?? parsed.meta.change;
         const amend = request.nextUrl.searchParams.get('amend') === '1';
-        const result = await store.save({ id, meta: parsed.meta, markdown: parsed.body, note, amend });
+        const result = await kept.save({ id, meta: parsed.meta, markdown: parsed.body, note, amend });
         if ('notFound' in result)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         // A broadcast with no date gets one: 90 days from now. A date already set (by the sender, or
@@ -845,7 +869,7 @@ export function createArtifactRoutes(config) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
-        const a = await store.get(id);
+        const a = await kept.get(id);
         if (!a)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         return NextResponse.json({ id, text: narrationText({ title: a.title, subtitle: a.subtitle, summary: a.summary, markdown: a.markdown }) });
@@ -862,7 +886,7 @@ export function createArtifactRoutes(config) {
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
-        if (!(await store.get(id)))
+        if (!(await kept.get(id)))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         if (!ASSET_NAME.test(name))
             return NextResponse.json({ error: 'asset name must be one path segment: letters, digits, dot, dash, underscore' }, { status: 400 });
@@ -912,7 +936,7 @@ export function createArtifactRoutes(config) {
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
-        if (!(await store.get(id)))
+        if (!(await kept.get(id)))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         if (!ASSET_NAME.test(name))
             return NextResponse.json({ error: 'asset name must be one path segment: letters, digits, dot, dash, underscore' }, { status: 400 });
@@ -972,7 +996,7 @@ export function createArtifactRoutes(config) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
-        if (!ARTIFACT_ID.test(id) || !(await store.get(id)))
+        if (!ARTIFACT_ID.test(id) || !(await kept.get(id)))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         let files = 0;
         if (config.assets?.deletePage) {
@@ -990,7 +1014,7 @@ export function createArtifactRoutes(config) {
         catch (e) {
             return NextResponse.json({ error: `the page's readers could not be forgotten, so the page was kept; delete it again: ${e instanceof Error ? e.message : String(e)}` }, { status: 502 });
         }
-        const ok = await store.delete(id);
+        const ok = await kept.delete(id);
         if (!ok)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         revalidatePath(pagePath(id));

package/package.json

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