@supersuit/artifacts 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -3,6 +3,76 @@
 `@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.37.0
+
+**A broadcast is its own page kind.** `template: broadcast` in front matter makes a page one
+message sent to several people, each through their own link, instead of a document with extra
+lines. Documents are unchanged: an ordinary page renders byte for byte as before (the golden render
+test is untouched) and lists as it always would have.
+
+- The message card: the sender's words, then the media in the order written (a video with sound
+  and controls, photos, a voice note's player, link cards), then the reader's own note. No table of
+  contents, no version line, no read-along player, no page menu for a reader.
+- The kind's defaults: per-reader links implied; private media implied wherever the body has a
+  stored private file or a local one (a remote URL alone stores nothing); the kind is sticky like
+  `links:` (a republish leaving `template:` out stays a broadcast, `template: document` is refused
+  with 409); `access`, `password` and `comments_visible: readers` refused in words; comments off unless
+  the file turns them on; no narration player (a voice note is its own audio). A body pointing at a
+  local file without `media: private` is refused, because that line is what makes the publisher
+  upload it privately.
+- Expiry: `POST /api/artifacts` gives a broadcast with no date one 90 days out (`BROADCAST_TTL_MS`)
+  and answers it as `expireAt`. A date already set stands; Keep holds.
+- `GET /api/artifacts?kind=broadcast|document` (`LIST`, publish key or the owner or an admin signed
+  in): the owner's two lists. A broadcast's line carries `readers` (live links) and `revoked`; a
+  recipients store that fails fails the list. `ArtifactStore.list(kind)` (optional; the Firestore store has it),
+  `kindOf`, `listOfKind`, `ARTIFACT_KINDS`.
+- An unfurl fetcher never gets a signed media URL. DETECTOR: a per-reader page fetched with a
+  preview agent's user agent rendered its private media's signed URLs into the HTML, which a
+  preview service may cache. REMEDY: none in the host; the page now renders its text only to a
+  known fetcher or a request with no agent (`readHeader`, default through `next/headers`).
+- `DELETE /api/artifacts/<id>` removes the page's files from both buckets (`deletePage`), then its
+  readers, their notes and views and every comment on it, before the record. DETECTOR: a deleted
+  page's media stayed in the bucket, and a kept broadcast's per-person notes and comments outlived
+  it. REMEDY: none; a failure to remove either answers 502 and keeps the record so the delete can be run again. An id that is not a
+  page id is refused before the bucket is touched.
+- `shutPageResponse(request)`: a revoked or expired per-reader link answers 410 Gone with the same
+  quiet words. DETECTOR: a revoked link answered 200. REMEDY: call it from your `proxy.ts` (README,
+  Broadcasts: skip requests with no link or rid cookie before loading anything, and catch every
+  failure); without it the page still says the same words with a 200.
+- Documents: the one output change is the bot rule above, on per-reader documents only.
+- TESTS: `src/routes/broadcast.test.tsx`, `src/artifacts/store.test.ts` (listing one kind),
+  `src/artifacts/index.test.ts`, `src/artifacts/front-matter.test.ts`.
+
+## 0.36.0
+
+**Private media moves to its own private bucket, and a host without one refuses it.** 0.35.0 kept
+`media: private` files under `<prefix>/<id>/private/` in the same bucket as public assets and
+never called `makePublic` on them. That is no protection on a bucket that carries a bucket-wide
+public read grant: every "private" object was readable by anyone holding its URL.
+
+- `createArtifactAssets(bucket, prefix, { privateBucket })`. With `privateBucket`, `putPrivate`,
+  `signPrivateUpload`, `finishPrivateUpload` and `privateUrl` use it (same `<prefix>/<id>/private/`
+  keys); `put`, `signUpload`, `finishUpload`, covers and narration stay on `bucket`. `deletePage`
+  clears the page from both. Passing the public bucket again as the private one throws.
+- Without `privateBucket` the four private methods are not defined, so the host fails closed:
+  `POST /api/artifacts` refuses a page with `media: private` (or a republish of a page that already
+  keeps private media) with 501 and saves nothing, and `?private=1` uploads answer 501, all with
+  the same words naming `privateBucket`.
+- `PRIVATE_READ_TTL_MS` (exported, `60 * 60 * 1000`): the life of a signed V4 read URL. One is
+  minted per private file on every render that passed the per-reader gate, and none for a revoked
+  or expired link.
+- DETECTOR: your host passes `media: private` pages and calls `createArtifactAssets(bucket, prefix)`
+  with two arguments; or `gcloud storage buckets get-iam-policy` on your bucket lists `allUsers`
+  and you have objects under `*/private/`.
+- REMEDY: create a separate bucket (uniform access, public access prevention enforced, object
+  access for the host's service account only), pass it as `privateBucket`, give it CORS for `PUT`
+  from your origin if browsers upload to it directly, and republish any page whose private media
+  sits in the public bucket (then delete those old objects). A host that publishes no private
+  media needs nothing; until it adds a private bucket, `media: private` is refused.
+- TESTS: `src/artifacts/assets.test.ts` (private media), `src/routes/private-media.test.tsx`
+  (publishing media: private), `src/routes/per-reader.test.tsx` (mints a fresh signed URL on every
+  passing render), `src/artifacts/index.test.ts`.
+
 ## 0.35.0
 
 **Per-reader links, private media, video with sound, quiet views, and expiry.** A page can now go

package/README.md

@@ -22,7 +22,7 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `createArtifactRoutes(config)` | Every route handler: the page, its metadata, the publish API, the share card, the reader sign-in exchange, access control |
 | `createArtifactStore(db, path)` | Firestore store for pages and their version history, under any collection path |
 | `createReadersStore(db, path)` | The record for confidential pages: allowlist, agreements, reading sessions, flags |
-| `createArtifactAssets(bucket, prefix)` | Uploaded images for a page, in a Cloud Storage bucket |
+| `createArtifactAssets(bucket, prefix, { privateBucket? })` | Uploaded images for a page, in a Cloud Storage bucket; private media in a separate private bucket |
 | `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
 | `BrandGround`, `BrandMark` | The pack's page backdrop and mark, for your own pages (a home, a 404) |
 | `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing (widget fences included) |
@@ -254,7 +254,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `links` | `per-reader`: the page opens only through a link made for one reader (see Per-reader links). Sticky: a republish whose file leaves the line out changes nothing |
 | `media` | `private`: the page's body media is kept private and served through short-lived signed URLs. Needs `links: per-reader`. Sticky like `links` |
 | `change` | One line saying what this version changed (see Version history) |
-| `template` | `document`, the only one so far |
+| `template` | `document` (the default, the read-along reader) or `broadcast` (one message card sent to several people; see Broadcasts) |
 
 An unknown key is refused, so a typo fails loudly instead of being ignored.
 
@@ -849,6 +849,14 @@ media: private
 
 `links: per-reader` shuts the page to everyone who does not arrive through a valid, unrevoked, unexpired link. It cannot be combined with `password`, `access` or `comments_visible: readers` (readers never see each other's comments). `media: private` keeps body media under the page's private prefix; `.mp4` and `.m4a` (and `.mp3`) are supported, and `sound:` at the start of a video's alt makes it a clip with controls and sound. Both lines are sticky: republishing a file that leaves them out changes nothing.
 
+### Private media lives in its own bucket
+
+`media: private` needs a private store: `createArtifactAssets(bucket, prefix, { privateBucket })`. Private files go to `privateBucket` under `<prefix>/<id>/private/`; covers, images and narration stay on the public `bucket`. Without `privateBucket` the private methods are not defined, and the host refuses private media with 501 at every door: publishing a page with `media: private` (or republishing a page that already keeps it), and `?private=1` uploads. Nothing is saved. This is on purpose: a public bucket often carries a bucket-wide public read grant, so an object written there is readable by anyone who has its URL, whatever the object's own settings say.
+
+The private bucket must be a different bucket from the public one (passing the same bucket twice throws), with uniform bucket-level access, public access prevention enforced, and object access granted only to the host's own service account. The page signs a V4 read URL per private file on every render that passed the per-reader gate, valid `PRIVATE_READ_TTL_MS` (one hour); a revoked or expired link renders nothing and mints nothing. A reader revoked after a render can keep loading a URL already handed to them for at most that hour. Expiry's `deletePage` clears the page from both buckets.
+
+If the publisher uploads straight to the private bucket from a browser (`?private=1` on `UPLOAD`), give that bucket a CORS rule allowing `PUT` from your origin with the `content-type` and `cache-control` headers; a reader's browser playing a signed URL needs `GET` (and `HEAD`) from your origin only if your player fetches it with CORS.
+
 Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `VIEWS`, `SEEN`, and `sweepExpired`.
 
 | Route | Who | What |
@@ -868,7 +876,61 @@ A view is the page rendered in a real browser, visible, for at least 2 seconds.
 
 ### Expiry
 
-`expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
+`expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. With a private bucket configured it deletes from both buckets. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
+
+## Broadcasts (`template: broadcast`)
+
+A broadcast is its own page kind, not a document with extra flags. It is one message sent to several people, each through their own link, and it renders as one card: the sender's words at the top, then the media in the order the words put it (a video with sound and controls, photos, a voice note's player, link cards), then that person's own note. None of the document's furniture: no table of contents, no version line, no read-along, and no page menu for a reader.
+
+```markdown
+---
+title: At the lake
+summary: We finally made it up there.
+template: broadcast
+links: per-reader
+media: private
+voice: none
+---
+We finally made it up there.
+
+![sound: The lake at dusk](lake.mp4)
+```
+
+What the kind decides, so the file does not have to:
+
+- **Per-reader links, always.** `links: per-reader` is implied. The kind is sticky like `links:`: a republish that leaves `template:` out stays a broadcast, and one that says `document` is refused (409). `access`, `password` and `comments_visible: readers` are refused in words.
+- **Private media wherever there is media.** `media: private` is implied as soon as the body carries a stored private file or a local one (a remote URL alone stores nothing, so it does not count). A body that points at a local file (one the publisher will upload) must still say `media: private`, because that line is what makes the publisher upload it privately; without it the page is refused before anything is uploaded.
+- **Expires 90 days after it is published** (`BROADCAST_TTL_MS`), set by `POST /api/artifacts` when the page has no date yet, and answered as `expireAt` in its response. A date set on the recipients route stands, a republish never moves it, and Keep (`expires: null`) holds.
+- **Comments off** unless the file turns them on. **No narration player**, ever: a voice note is its own audio (`![Voice note](note.m4a)` draws a player). Write `voice: none` so the publisher does not record one.
+- **Silent view tracking**: the quiet view beacon, as on every per-reader page.
+
+Routes:
+
+| Route | Who | What |
+|---|---|---|
+| `GET /api/artifacts?kind=broadcast` | publish key, or the owner or an admin signed in | Every broadcast, newest first: id, title, summary, url, dates, `expireAt`, `keep`, `readers` (people whose link still works) and `revoked`. `?kind=document` (the default) lists documents, never a broadcast |
+| `shutPageResponse(request)` | your proxy | A per-reader page whose link was revoked or whose date passed answers **410 Gone** with the quiet words the page shows. Null for everything else, which the proxy passes on. Reads nothing unless the request carries a reader's link or its cookie |
+
+```ts
+// proxy.ts
+import { NextResponse, type NextRequest } from 'next/server'
+export async function proxy(request: NextRequest) {
+  // Only a request carrying a reader's link or its cookie can be shut; skip the rest cheaply.
+  const hasLink = request.nextUrl.searchParams.has('r') || request.cookies.getAll().some((c) => c.name.startsWith('artifact_r_'))
+  if (!hasLink) return NextResponse.next()
+  try {
+    const { routes } = await import('./routes') // your createArtifactRoutes(...)
+    const shut = await routes.shutPageResponse(request)
+    if (shut) return shut
+  } catch {
+    // A store outage never costs a reader the page: the page applies the same gate itself.
+  }
+  return NextResponse.next()
+}
+export const config = { matcher: ['/:id([a-z0-9]{8})'] }
+```
+
+Any per-reader page served to a known unfurl fetcher (or a request with no user agent) carries its text only: no media, no signed URL, no reader's note, no cookie. `readHeader` on `createArtifactRoutes` reads the agent (default through `next/headers`). `DELETE /api/artifacts/<id>` removes the page's files from both buckets (`deletePage`), then its readers, their notes and views and every comment, before the record, and keeps the record (502) if the files could not go, so it can be run again.
 
 ## Brand packs
 

package/lib/artifacts/assets.d.ts

@@ -35,15 +35,27 @@ export interface ArtifactAssets {
     }>;
     /** After a signed private upload: `private:<stored name>`, or null if nothing arrived. */
     finishPrivateUpload?(id: string, name: string, digest: string): Promise<string | null>;
-    /** A signed read URL for a stored private name, valid one hour. */
+    /** A V4 signed read URL for a stored private name, valid PRIVATE_READ_TTL_MS (one hour). */
     privateUrl?(id: string, stored: string): Promise<string>;
-    /** Delete every object under `<prefix>/<id>/`; returns how many. */
+    /** Delete every object under `<prefix>/<id>/`, in the public bucket and the private one; returns how many. */
     deletePage?(id: string): Promise<number>;
 }
 /** A reference to a private file as it appears in a page: `private:<stored name>`. */
 export declare const PRIVATE_REF: RegExp;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export declare const ASSET_DIGEST: RegExp;
+/** How long a signed read URL for private media stays valid: one hour. A reader revoked after a
+ *  render can keep loading a URL already handed to them for at most this long. */
+export declare const PRIVATE_READ_TTL_MS: number;
+export interface ArtifactAssetsOptions {
+    /**
+     * The bucket private media lives in. It must be a different bucket from the public one, with
+     * uniform access, public access prevention enforced, and object access granted only to the
+     * host's own service account. Without it the private methods are not defined at all, so a
+     * `media: private` page is refused instead of being stored where anyone could read it by URL.
+     */
+    privateBucket?: Bucket;
+}
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export declare const ASSET_NAME: RegExp;
 export declare const ASSET_TYPES: Record<string, string>;
@@ -67,4 +79,4 @@ export declare function contentTypeFor(name: string): string | undefined;
 export declare function hashedName(name: string, bytes: Buffer): string;
 /** `name` with `digest` spliced in before the extension, the way hashedName stores it. */
 export declare function storedName(name: string, digest: string): string;
-export declare function createArtifactAssets(bucket: Bucket, prefix: string): ArtifactAssets;
+export declare function createArtifactAssets(bucket: Bucket, prefix: string, options?: ArtifactAssetsOptions): ArtifactAssets;

package/lib/artifacts/assets.js

@@ -10,6 +10,9 @@ export const PRIVATE_REF = /^private:([A-Za-z0-9][A-Za-z0-9._-]{0,140})$/;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export const ASSET_DIGEST = /^[0-9a-f]{8}$/;
 const CACHE_CONTROL = 'public, max-age=31536000, immutable';
+/** How long a signed read URL for private media stays valid: one hour. A reader revoked after a
+ *  render can keep loading a URL already handed to them for at most this long. */
+export const PRIVATE_READ_TTL_MS = 60 * 60 * 1000;
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export const ASSET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
 export const ASSET_TYPES = {
@@ -52,9 +55,13 @@ export function storedName(name, digest) {
     // A name with no extension is legal here, so append rather than assume there is a dot.
     return dot <= 0 ? `${name}.${digest}` : `${name.slice(0, dot)}.${digest}${name.slice(dot)}`;
 }
-export function createArtifactAssets(bucket, prefix) {
+export function createArtifactAssets(bucket, prefix, options = {}) {
     const clean = prefix.replace(/^\/+|\/+$/g, '');
-    return {
+    const priv = options.privateBucket;
+    // The same bucket twice would put "private" media back where a public read grant reaches it.
+    if (priv && priv.name === bucket.name)
+        throw new Error('the private bucket must be a different bucket from the public one');
+    const assets = {
         async put(id, name, bytes, contentType) {
             const key = `${clean}/${id}/${hashedName(name, bytes)}`;
             const file = bucket.file(key);
@@ -135,36 +142,46 @@ export function createArtifactAssets(bucket, prefix) {
             const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
             return url;
         },
+        async deletePage(id) {
+            // An empty or path-shaped id would make the prefix wider than one page.
+            if (!ARTIFACT_ID_RE.test(id))
+                throw new Error('not an artifact id');
+            let n = 0;
+            for (const b of priv ? [bucket, priv] : [bucket]) {
+                const [files] = await b.getFiles({ prefix: `${clean}/${id}/` });
+                for (const f of files)
+                    await f.delete();
+                n += files.length;
+            }
+            return n;
+        },
+    };
+    if (!priv)
+        return assets;
+    const privateFile = (id, stored) => priv.file(`${clean}/${id}/private/${stored}`);
+    return {
+        ...assets,
         async putPrivate(id, name, bytes, contentType) {
             const stored = hashedName(name, bytes);
-            await bucket.file(`${clean}/${id}/private/${stored}`).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });
+            await privateFile(id, stored).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });
             return `private:${stored}`;
         },
         async signPrivateUpload(id, name, digest, contentType) {
             const stored = storedName(name, digest);
             const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600' };
-            const [uploadUrl] = await bucket.file(`${clean}/${id}/private/${stored}`).getSignedUrl({ version: 'v4', action: 'write', expires: Date.now() + 15 * 60 * 1000, contentType, extensionHeaders: { 'cache-control': headers['cache-control'] } });
+            const [uploadUrl] = await privateFile(id, stored).getSignedUrl({ version: 'v4', action: 'write', expires: Date.now() + 15 * 60 * 1000, contentType, extensionHeaders: { 'cache-control': headers['cache-control'] } });
             return { uploadUrl, headers, url: `private:${stored}` };
         },
         async finishPrivateUpload(id, name, digest) {
             const stored = storedName(name, digest);
-            const [there] = await bucket.file(`${clean}/${id}/private/${stored}`).exists();
+            const [there] = await privateFile(id, stored).exists();
             return there ? `private:${stored}` : null;
         },
         async privateUrl(id, stored) {
             if (!PRIVATE_REF.test(`private:${stored}`))
                 throw new Error('not a private file name');
-            const [url] = await bucket.file(`${clean}/${id}/private/${stored}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            const [url] = await privateFile(id, stored).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + PRIVATE_READ_TTL_MS });
             return url;
         },
-        async deletePage(id) {
-            // An empty or path-shaped id would make the prefix wider than one page.
-            if (!ARTIFACT_ID_RE.test(id))
-                throw new Error('not an artifact id');
-            const [files] = await bucket.getFiles({ prefix: `${clean}/${id}/` });
-            for (const f of files)
-                await f.delete();
-            return files.length;
-        },
     };
 }

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

@@ -6,7 +6,9 @@ import { type Definition } from './definitions.js';
 export type ArtifactMeta = {
     title: string;
     summary: string;
-    template: 'document';
+    /** The page kind. `document` (the default) is the read-along reader; `broadcast` is one message
+     *  card sent to several people, each through their own link (0.37.0). */
+    template: ArtifactKind;
     /** A line under the title. Title, subtitle and summary are three separate fields; the summary
      *  is the teaser, and the unfurl carries the title and the summary. */
     subtitle?: string;
@@ -59,11 +61,21 @@ export type ArtifactMeta = {
     /** Who sees shared comments: `owner` (the default) or every reader (`readers`). */
     commentsVisible?: CommentsVisible;
 };
+/** What a page is. A broadcast is its own kind, not a document with extra flags: it renders as a
+ *  message card, opens only through per-reader links, keeps its media private, has comments off
+ *  and no narration by default, and expires 90 days after publish unless kept. */
+export type ArtifactKind = 'document' | 'broadcast';
+export declare const ARTIFACT_KINDS: readonly ArtifactKind[];
 /** 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): {
+export declare function parseArtifactSource(text: string, 
+/** The kind a file that leaves `template:` out is read as: the stored page's kind on a
+ *  republish, so a broadcast stays one (sticky, like `links:`). Default `document`. */
+opts?: {
+    defaultKind?: ArtifactKind;
+}): {
     ok: true;
     meta: ArtifactMeta;
     body: string;

package/lib/artifacts/front-matter.js

@@ -7,12 +7,23 @@ import { mergeChecklistState, mergeWidgetState, scanWidgets } from './widgets.js
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
+export const ARTIFACT_KINDS = ['document', 'broadcast'];
+/** Any media in a body: an image, a video or an audio clip, written as markdown image syntax. */
+const MEDIA_IN_BODY = /!\[[^\]]*\]\(\s*<?([^)\s>]+)/g;
+/** A reference the publisher uploads before the page is finished: neither a URL, a site path nor
+ *  an already-stored private file. */
+const LOCAL_REF = /^(?![a-z][a-z0-9+.-]*:|\/|#)/i;
+/** A file already stored in the page's private store. */
+const PRIVATE_REF_IN_BODY = /^private:/;
 /** 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', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media']);
-export function parseArtifactSource(text) {
+export function parseArtifactSource(text, 
+/** The kind a file that leaves `template:` out is read as: the stored page's kind on a
+ *  republish, so a broadcast stays one (sticky, like `links:`). Default `document`. */
+opts = {}) {
     const { data, content } = matter(text);
     const d = data;
     for (const k of Object.keys(d)) {
@@ -24,14 +35,24 @@ export function parseArtifactSource(text) {
         if (typeof v !== 'string' || !v.trim())
             return { ok: false, error: `front matter is missing ${k}` };
     }
-    const template = d.template ?? 'document';
-    if (template !== 'document')
-        return { ok: false, error: 'template must be document' };
+    const template = d.template ?? opts.defaultKind ?? 'document';
+    if (!ARTIFACT_KINDS.includes(template))
+        return { ok: false, error: 'template must be document or broadcast' };
     const meta = {
         title: String(d.title).trim(),
         summary: String(d.summary).trim(),
-        template: 'document',
+        template: template,
     };
+    // A broadcast opens only through each person's own link: a door or a shared thread of comments
+    // would make it something else, so those lines are refused in words rather than dropped.
+    if (meta.template === 'broadcast') {
+        if (d.access !== undefined && d.access !== null)
+            return { ok: false, error: 'a broadcast opens only through each person\'s own link: drop access' };
+        if (d.password !== undefined && d.password !== null)
+            return { ok: false, error: 'a broadcast opens only through each person\'s own link: drop password' };
+        if (d.comments_visible === 'readers')
+            return { ok: false, error: 'a broadcast keeps each person\'s comments to the owner: drop comments_visible: readers' };
+    }
     for (const k of ['subtitle', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password']) {
         const v = d[k];
         if (typeof v === 'string' && v)
@@ -106,6 +127,18 @@ export function parseArtifactSource(text) {
             return { ok: false, error: 'comments_visible must be owner or readers' };
         meta.commentsVisible = d.comments_visible;
     }
+    if (meta.template === 'broadcast') {
+        // Per-reader links are what a broadcast is, whatever the file says or leaves out.
+        meta.links = 'per-reader';
+        const refs = [...content.matchAll(MEDIA_IN_BODY)].map((m) => m[1]).filter((r) => LOCAL_REF.test(r) || PRIVATE_REF_IN_BODY.test(r));
+        // The publisher uploads a local file privately only when the file itself says `media: private`,
+        // so a broadcast that would send one up in public is refused before anything is uploaded.
+        if (!meta.privateMedia && refs.some((r) => LOCAL_REF.test(r)))
+            return { ok: false, error: 'a broadcast keeps its media private: add media: private so the publisher uploads it privately' };
+        // A remote URL alone stores nothing here, so only a stored private file or a local one counts.
+        if (refs.length)
+            meta.privateMedia = true;
+    }
     // Only the per-reader page resolves private media, so on any other page it would ship broken.
     if (meta.privateMedia && meta.links !== 'per-reader')
         return { ok: false, error: 'media: private needs links: per-reader' };

package/lib/artifacts/index.d.ts

@@ -1,10 +1,10 @@
-export { parseArtifactSource, type ArtifactMeta } from './front-matter.js';
+export { parseArtifactSource, ARTIFACT_KINDS, type ArtifactMeta, type ArtifactKind } from './front-matter.js';
 export { ArtifactMarkdown, artifactUrlTransform } 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 { 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';
 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 { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, PRIVATE_READ_TTL_MS, type ArtifactAssets, type ArtifactAssetsOptions } 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';
 export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc, type ReaderSummary } from './readers-store.js';

package/lib/artifacts/index.js

@@ -1,10 +1,10 @@
-export { parseArtifactSource } from './front-matter.js';
+export { parseArtifactSource, ARTIFACT_KINDS } from './front-matter.js';
 export { ArtifactMarkdown, artifactUrlTransform } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
-export { createArtifactStore, newArtifactId, cleanNote, MAX_CHANGE_NOTE_CHARS } from './store.js';
+export { createArtifactStore, newArtifactId, cleanNote, kindOf, listOfKind, MAX_CHANGE_NOTE_CHARS } from './store.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 { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, PRIVATE_READ_TTL_MS } 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';
 export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';

package/lib/artifacts/store.d.ts

@@ -1,5 +1,5 @@
 import { type Firestore } from 'firebase-admin/firestore';
-import type { ArtifactMeta } from './front-matter.js';
+import type { ArtifactKind, ArtifactMeta } from './front-matter.js';
 import type { Access } from './reader.js';
 import type { StateConfig } from './state.js';
 import type { ThemeMode } from '../brand/theme.js';
@@ -10,7 +10,8 @@ export type ArtifactRecord = {
     id: string;
     title: string;
     summary: string;
-    template: 'document';
+    /** The page kind; see ArtifactMeta.template. Pages saved before kinds existed carry `document`. */
+    template: ArtifactKind;
     subtitle?: string;
     /** Who the page is for; see ArtifactMeta.to. */
     to?: string;
@@ -74,6 +75,25 @@ export type VersionRecord = VersionEntry & {
 export declare const MAX_CHANGE_NOTE_CHARS = 280;
 export declare function cleanNote(note: unknown): string | undefined;
 export declare function newArtifactId(): string;
+/** One line of the owner's list of pages: no body, no settings. */
+export type ArtifactListItem = {
+    id: string;
+    title: string;
+    summary: string;
+    template: ArtifactKind;
+    createdAt: string;
+    updatedAt: string;
+    views: number;
+};
+/** The kind a stored page is: anything not saved as a broadcast is a document, so pages saved
+ *  before kinds existed list where they always would have. */
+export declare const kindOf: (a: {
+    template?: string;
+}) => ArtifactKind;
+/** The owner's list of one kind, newest first: the same rule every store applies. */
+export declare function listOfKind(pages: Iterable<Partial<ArtifactRecord> & {
+    id: string;
+}>, kind: ArtifactKind): ArtifactListItem[];
 export type SaveResult = {
     id: string;
     version: number;
@@ -107,6 +127,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>;
+    /** 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[]>;
 }
 /** The Firestore-backed store. The instance hands in its own Firestore, so the shell
  *  never knows which project it is writing to; a hosted tenant passes a namespaced one. */

package/lib/artifacts/store.js

@@ -26,6 +26,16 @@ export function newArtifactId() {
         s += ALPHABET[randomInt(ALPHABET.length)];
     return s;
 }
+/** The kind a stored page is: anything not saved as a broadcast is a document, so pages saved
+ *  before kinds existed list where they always would have. */
+export const kindOf = (a) => (a.template === 'broadcast' ? 'broadcast' : 'document');
+/** The owner's list of one kind, newest first: the same rule every store applies. */
+export function listOfKind(pages, kind) {
+    return [...pages]
+        .filter((p) => kindOf(p) === kind)
+        .map((p) => ({ id: p.id, title: p.title ?? '', summary: p.summary ?? '', template: kind, createdAt: p.createdAt ?? '', updatedAt: p.updatedAt ?? '', views: p.views ?? 0 }))
+        .sort((x, y) => y.updatedAt.localeCompare(x.updatedAt) || x.id.localeCompare(y.id));
+}
 /** The Firestore-backed store. The instance hands in its own Firestore, so the shell
  *  never knows which project it is writing to; a hosted tenant passes a namespaced one. */
 export function createArtifactStore(db, collection = 'artifacts') {
@@ -59,6 +69,11 @@ 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),
+        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();
+            return listOfKind(snap.docs.map((d) => ({ ...d.data(), id: d.id })), kind);
+        },
     };
 }
 const vid = (n) => String(n).padStart(6, '0');

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export * from './artifacts/index.js';
 export * from './brand/index.js';
 export * from './gate.js';
-export { createArtifactRoutes, type ArtifactRoutesConfig } from './routes/artifacts.js';
+export { createArtifactRoutes, BROADCAST_TTL_MS, type ArtifactRoutesConfig } from './routes/artifacts.js';
 export { ANON_COOKIE } from './routes/state-routes.js';

package/lib/index.js

@@ -1,5 +1,5 @@
 export * from './artifacts/index.js';
 export * from './brand/index.js';
 export * from './gate.js';
-export { createArtifactRoutes } from './routes/artifacts.js';
+export { createArtifactRoutes, BROADCAST_TTL_MS } from './routes/artifacts.js';
 export { ANON_COOKIE } from './routes/state-routes.js';

package/lib/routes/artifacts.d.ts

@@ -53,6 +53,9 @@ export type ArtifactRoutesConfig = {
     pagePrefix?: string;
     /** Read one request cookie by name. Default reads through next/headers; tests inject one. */
     readCookie?: (name: string) => Promise<string | undefined>;
+    /** Read one request header by name (the per-reader page reads `user-agent`, so an unfurl fetcher
+     *  is never handed a signed media URL). Default reads through next/headers; tests inject one. */
+    readHeader?: (name: string) => Promise<string | undefined>;
     /** The record for gated pages (`access:` in front matter). Without it a gated page stays shut
      *  to everyone, never open: failing closed is the only safe default for a confidential page. */
     readers?: ReadersStore;
@@ -136,6 +139,9 @@ type VersionProps = VersionParams & {
         r?: string | string[];
     }>;
 };
+/** How long a broadcast lives when nobody gave it a date: 90 days from its first publish, unless
+ *  the owner taps Keep (`expires: null` on the recipients route). */
+export declare const BROADCAST_TTL_MS: number;
 export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     dynamic: "force-dynamic";
     maxDuration: number;
@@ -160,6 +166,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         skipped: string[];
         failed: string[];
     }>;
+    forgetReaders: (id: string) => Promise<void>;
     PERSONAL_GET: (req: NextRequest, { params }: {
         params: Promise<{
             id: string;
@@ -210,6 +217,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         error: string;
     }> | NextResponse<{
         warning?: string | undefined;
+        expireAt?: string | null | undefined;
         id: string;
         url: string;
         version: number;
@@ -224,7 +232,34 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         error: string;
     }> | NextResponse<{
         deleted: boolean;
+        files: number;
+    }>>;
+    LIST: (request: NextRequest) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        kind: string;
+        pages: ({
+            views: number;
+            id: string;
+            title: string;
+            summary: string;
+            url: string;
+            createdAt: string;
+            updatedAt: string;
+        } | {
+            expireAt: string | null;
+            keep: boolean;
+            readers: number;
+            revoked: number;
+            id: string;
+            title: string;
+            summary: string;
+            url: string;
+            createdAt: string;
+            updatedAt: string;
+        })[];
     }>>;
+    shutPageResponse: (request: NextRequest) => Promise<Response | null>;
     PUT_ASSET: (request: NextRequest, { params }: {
         params: Promise<{
             id: string;

package/lib/routes/artifacts.js

@@ -3,13 +3,13 @@ import { revalidatePath } from 'next/cache';
 import { notFound, redirect } from 'next/navigation';
 import { NextResponse } from 'next/server';
 import { isPublisherAuthed } from '../artifacts/auth.js';
-import { parseArtifactSource } from '../artifacts/front-matter.js';
+import { ARTIFACT_KINDS, parseArtifactSource } from '../artifacts/front-matter.js';
 import { narrationText } from '../artifacts/narration.js';
 import { ArtifactMarkdown } from '../artifacts/render.js';
 import { CHECKLIST_SLOT } from '../artifacts/checklist.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
-import { cleanNote } from '../artifacts/store.js';
+import { cleanNote, kindOf } from '../artifacts/store.js';
 import { effectiveWriters, shapeChanges } from '../artifacts/state.js';
 import { COMMENTS_SLOT } from '../artifacts/comments.js';
 import { ASSET_DIGEST, ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
@@ -22,7 +22,7 @@ import { CommentLayer } from '../reader/comment-layer.js';
 import { ReaderWatch } from '../reader/reader-watch.js';
 import { UpdatedTime } from '../reader/updated-time.js';
 import { perReaderGate, withPrivateUrls, NO_LINK, UNAVAILABLE } from './per-reader.js';
-import { ridCookieName, mintRenderToken, usableSecret, RID_COOKIE_MAX_AGE } from '../artifacts/recipients.js';
+import { ridCookieName, mintRenderToken, usableSecret, isUnfurlAgent, RID_COOKIE_MAX_AGE } from '../artifacts/recipients.js';
 import { PageMenu } from '../reader/page-menu.js';
 import { COMMENTS_MODES } from '../artifacts/comments.js';
 import { newPageKey } from '../artifacts/settings.js';
@@ -41,10 +41,26 @@ import { createVoiceRoutes } from './voice-routes.js';
 export const ARTIFACT_ID = ARTIFACT_ID_RE;
 /** A version number as it appears in a URL: no zero, no leading zero, so each version has one address. */
 const VERSION_N = /^[1-9]\d{0,5}$/;
+/** How long a broadcast lives when nobody gave it a date: 90 days from its first publish, unless
+ *  the owner taps Keep (`expires: null` on the recipients route). */
+export const BROADCAST_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+/** Media in a body, as markdown image syntax: what an unfurl fetcher's copy of a page leaves out. */
+const MEDIA_MD = /!\[[^\]]*\]\([^)]*\)/g;
+const withoutMedia = (md) => md.replace(MEDIA_MD, '');
+/** A colour from a pack, only if it is plainly a colour: it is written into a raw HTML answer. */
+const SAFE_COLOUR = /^(#[0-9a-f]{3,8}|[a-z]+|rgba?\([0-9.,\s%]+\))$/i;
+/** What a host with no private store answers to private media, in words that say what to set up. */
+const NO_PRIVATE_STORE = 'this host keeps no private store, so media: private is refused and nothing was published. Give createArtifactAssets a privateBucket (its own bucket, never the public one) to keep private media';
 async function defaultReadCookie(name) {
     const { cookies } = await import('next/headers');
     return (await cookies()).get(name)?.value;
 }
+/** A header the request did not send reads as '' (so an agent that sends none is treated as a
+ *  fetcher); a header that cannot be read at all, outside a request, reads as undefined. */
+async function defaultReadHeader(name) {
+    const { headers } = await import('next/headers');
+    return (await headers()).get(name) ?? '';
+}
 export function createArtifactRoutes(config) {
     const { store, siteUrl } = config;
     // The pack as configured draws the share card; the page paints with its theme variables, so a
@@ -280,30 +296,40 @@ export function createArtifactRoutes(config) {
         const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top, reader }));
         if (a.access)
             return GatedPage(a, id, render, n);
-        if (a.links === 'per-reader') {
+        const broadcast = kindOf(a) === 'broadcast';
+        if (a.links === 'per-reader' || broadcast) {
             if (n !== null)
                 notFound(); // a past version of a per-reader page is never served
             const sp = (await searchParams) ?? {};
             const param = Array.isArray(sp.r) ? sp.r[0] : sp.r;
             const readCookie = config.readCookie ?? defaultReadCookie;
             const privateUrl = config.assets?.privateUrl?.bind(config.assets);
+            // An unfurl fetcher (or anything sending no agent at all) gets the card's text and never a
+            // signed media URL: a preview service may cache what it fetched long after a link is revoked.
+            const ua = await (config.readHeader ?? defaultReadHeader)('user-agent').catch(() => undefined);
+            const bot = ua !== undefined && isUnfurlAgent(ua);
+            const media = async (md) => (bot ? withoutMedia(md) : a.privateMedia ? await withPrivateUrls(md, id, privateUrl) : md);
             // A signed-in owner or admin gets through as the owner, with no link and no tracking.
             const me = readerSecret() ? verifyGrant(readerSecret(), await readCookie(GRANT_COOKIE).catch(() => undefined)) : null;
             if (isAdmin(me)) {
-                const markdown = a.privateMedia ? await withPrivateUrls(a.markdown, id, privateUrl) : a.markdown;
-                return _jsx(BrandGround, { pack: pack, mode: a.theme, children: await Body({ ...a, markdown }, { top: true, reader: me }) });
+                const markdown = await media(a.markdown);
+                const page = broadcast ? await BroadcastCard({ ...a, markdown }, { reader: me, bot }) : await Body({ ...a, markdown }, { top: true, reader: me });
+                return _jsx(BrandGround, { pack: pack, mode: a.theme, children: page });
             }
             const secret = usableSecret(config.recipientSecret?.());
             const g = await perReaderGate({ id, param, cookie: await readCookie(ridCookieName(id)).catch(() => undefined), secret, recipients: config.recipients });
             if (g.state === 'shut') {
                 return (_jsx(BrandGround, { pack: pack, mode: a.theme, children: _jsx("p", { "data-per-reader-shut": true, className: "mx-auto max-w-xl px-6 pt-32 text-center text-lg opacity-80", children: g.why === 'no-link' ? NO_LINK : UNAVAILABLE }) }));
             }
-            const token = mintRenderToken(secret, id, g.rid);
-            const remember = g.fromLink
+            // A fetcher is not the reader: it sets no cookie, carries no render token and sees no note.
+            const remember = g.fromLink && !bot
                 ? [pagePath(id), `/api/artifacts/${id}`].map((p) => `document.cookie=${JSON.stringify(`${ridCookieName(id)}=${g.rid}.${g.sig}; Path=${p}; Max-Age=${RID_COOKIE_MAX_AGE}; SameSite=Lax; Secure`)}`).join(';')
                 : null;
-            const markdown = a.privateMedia ? await withPrivateUrls(a.markdown, id, privateUrl) : a.markdown;
-            const body = await Body({ ...a, markdown }, { top: true, reader: null, perReader: { rid: g.rid, sig: g.sig, label: g.label, note: g.note, owner: g.owner, token } });
+            const perReader = bot ? undefined : { rid: g.rid, sig: g.sig, label: g.label, note: g.note, owner: g.owner, token: mintRenderToken(secret, id, g.rid) };
+            const markdown = await media(a.markdown);
+            const body = broadcast
+                ? await BroadcastCard({ ...a, markdown }, { reader: null, perReader, bot })
+                : await Body({ ...a, markdown }, { top: true, reader: null, perReader });
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, body] }));
         }
         // A password shuts the body, never the title: the header stays so the reader knows which
@@ -418,6 +444,21 @@ export function createArtifactRoutes(config) {
         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 }), 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, { n: n, at: v.at })] })), 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 }) })] }));
     }
+    /** 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
+     *  them, then this reader's own note. None of the document's furniture: no table of contents, no
+     *  version line, no read-along (a voice note is its own audio), and no page menu for a reader.
+     *  Comments only when the file turned them on; the quiet view beacon always, for a reader. */
+    async function BroadcastCard(a, { reader, perReader, bot }) {
+        const { brand } = lookOf(a);
+        const mode = !bot && config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
+        const admin = isAdmin(reader);
+        // A photo sent with no other media can ride as the cover; with media in the body it would repeat it.
+        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 })) : 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 }) {
         const { pack, brand } = lookOf(a);
@@ -697,14 +738,34 @@ export function createArtifactRoutes(config) {
         const [sessions, flags, acks] = await Promise.all([config.readers.sessions(id), config.readers.flags(id), config.readers.acks(id)]);
         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' } });
     }
+    /** Whether this host can store and serve private media: both halves come from a private bucket. */
+    const keepsPrivateMedia = () => Boolean(config.assets?.putPrivate && config.assets.privateUrl);
     async function POST(request) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const text = await request.text();
-        const parsed = parseArtifactSource(text);
+        let parsed = parseArtifactSource(text);
         if (!parsed.ok)
             return NextResponse.json({ error: parsed.error }, { status: 400 });
         const id = request.nextUrl.searchParams.get('id') ?? parsed.meta.id ?? undefined;
+        // 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);
+            if (stored && kindOf(stored) === 'broadcast') {
+                const again = parseArtifactSource(text, { defaultKind: 'broadcast' });
+                if (!again.ok)
+                    return NextResponse.json({ error: again.error }, { status: 400 });
+                if (again.meta.template !== 'broadcast')
+                    return NextResponse.json({ error: 'this page is a broadcast and stays one: drop template: document, or publish the document as a new page' }, { status: 409 });
+                parsed = again;
+            }
+        }
+        // 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)))
+            return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         if (id && parsed.meta.state) {
             const existing = await store.get(id);
             const changed = shapeChanges(existing?.state, parsed.meta.state);
@@ -736,9 +797,24 @@ export function createArtifactRoutes(config) {
         const result = await store.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
+        // by an earlier publish) stands, and Keep (expireAt null, keep true) is never undone.
+        let expireAt;
+        if (parsed.meta.template === 'broadcast' && config.recipients) {
+            const rec = await config.recipients.get(result.id);
+            if (rec?.keep)
+                expireAt = null;
+            else if (rec?.expireAt)
+                expireAt = rec.expireAt;
+            else {
+                expireAt = new Date(Date.now() + BROADCAST_TTL_MS).toISOString();
+                await config.recipients.setExpiry(result.id, expireAt);
+            }
+        }
         revalidatePath(pagePath(result.id));
         return NextResponse.json({
             id: result.id, url: pageUrl(result.id), version: result.version,
+            ...(expireAt !== undefined ? { expireAt } : {}),
             ...(parsed.meta.state && !config.state ? { warning: 'this host keeps no answers; state: is stored but inert' } : {}),
         }, { status: result.created ? 201 : 200 });
     }
@@ -759,7 +835,7 @@ export function createArtifactRoutes(config) {
             return NextResponse.json({ error: 'this host does not store assets' }, { status: 501 });
         const priv = request.nextUrl.searchParams.get('private') === '1';
         if (priv && !config.assets.putPrivate)
-            return NextResponse.json({ error: 'this host keeps no private media' }, { status: 501 });
+            return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
@@ -806,7 +882,7 @@ export function createArtifactRoutes(config) {
         const priv = request.nextUrl.searchParams.get('private') === '1';
         if (priv) {
             if (!assets?.signPrivateUpload || !assets.finishPrivateUpload)
-                return NextResponse.json({ error: 'this host keeps no private media' }, { status: 501 });
+                return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         }
         else if (!assets?.signUpload || !assets.finishUpload)
             return NextResponse.json({ error: 'this host does not take direct uploads' }, { status: 501 });
@@ -865,15 +941,97 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ id, versions: await store.history(id) });
     }
+    /** DELETE /api/artifacts/<id>, publish key: the page and every file stored under it, public and
+     *  private. The files go first, so a bucket that fails leaves the record to delete again rather
+     *  than media nobody can find. The id is checked before anything is touched: a path-shaped id
+     *  would widen the bucket prefix past one page. */
     async function DELETE(request, { params }) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
+        if (!ARTIFACT_ID.test(id) || !(await store.get(id)))
+            return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+        let files = 0;
+        if (config.assets?.deletePage) {
+            try {
+                files = await config.assets.deletePage(id);
+            }
+            catch (e) {
+                return NextResponse.json({ error: `the page's files could not be removed, so the page was kept; delete it again: ${e instanceof Error ? e.message : String(e)}` }, { status: 502 });
+            }
+        }
+        // Nothing of the page outlives it: readers, their notes and views, and every comment, kept or not.
+        try {
+            await recipientsRoutes.forgetReaders(id);
+        }
+        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);
         if (!ok)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         revalidatePath(pagePath(id));
-        return NextResponse.json({ deleted: true });
+        return NextResponse.json({ deleted: true, files });
+    }
+    /** GET /api/artifacts?kind=document|broadcast: the owner's list of one kind, newest first, with
+     *  no bodies. Documents and broadcasts are separate lists; `kind` defaults to document, so a
+     *  documents list never carries a broadcast. A broadcast's line adds its expiry, whether it is
+     *  kept, how many people still hold a live link (`readers`) and how many were revoked. The publish key, or the owner or an admin signed in. */
+    async function LIST(request) {
+        const no = (error, status) => NextResponse.json({ error }, { status, headers: { 'cache-control': 'no-store' } });
+        const me = verifyGrant(readerSecret(), request.cookies.get(GRANT_COOKIE)?.value);
+        if (!authed(request) && !isAdmin(me))
+            return no('Unauthorized', 401);
+        const kind = request.nextUrl.searchParams.get('kind') ?? 'document';
+        if (!ARTIFACT_KINDS.includes(kind))
+            return no(`kind must be one of: ${ARTIFACT_KINDS.join(', ')}`, 400);
+        if (!store.list)
+            return no('this store cannot list its pages', 501);
+        const items = await store.list(kind);
+        const pages = await Promise.all(items.map(async (p) => {
+            const line = { id: p.id, title: p.title, summary: p.summary, url: pageUrl(p.id), createdAt: p.createdAt, updatedAt: p.updatedAt };
+            if (kind !== 'broadcast')
+                return { ...line, views: p.views };
+            // A store that fails fails the list: a blank line would read as "kept, sent to nobody".
+            const rec = config.recipients ? await config.recipients.get(p.id) : null;
+            const people = rec ? Object.values(rec.recipients).filter((r) => !r.owner) : [];
+            return { ...line, expireAt: rec?.expireAt ?? null, keep: rec?.keep ?? false, readers: people.filter((r) => !r.revokedAt).length, revoked: people.filter((r) => r.revokedAt).length };
+        }));
+        return NextResponse.json({ kind, pages }, { headers: { 'cache-control': 'no-store' } });
+    }
+    /** For a host's proxy, ahead of the page: a per-reader page whose link was revoked or whose date
+     *  passed answers 410 Gone with the same quiet words the page shows, so a crawler or a preview
+     *  service drops it. Null for everything else (no link at all, a valid link, a document, the
+     *  owner signed in, any other path), which the proxy passes on untouched. Reads nothing unless
+     *  the request carries a reader's link or its cookie. */
+    async function shutPageResponse(request) {
+        const path = request.nextUrl.pathname;
+        if (!path.startsWith(prefix))
+            return null;
+        const id = path.slice(prefix.length);
+        if (!ARTIFACT_ID.test(id))
+            return null;
+        const param = request.nextUrl.searchParams.get('r') ?? undefined;
+        const cookie = request.cookies.get(ridCookieName(id))?.value;
+        if (!param && !cookie)
+            return null;
+        const secret = usableSecret(config.recipientSecret?.());
+        if (!secret || !config.recipients)
+            return null;
+        if (isAdmin(verifyGrant(readerSecret(), request.cookies.get(GRANT_COOKIE)?.value)))
+            return null;
+        const a = await store.get(id);
+        if (!a || a.access || !(a.links === 'per-reader' || kindOf(a) === 'broadcast'))
+            return null;
+        const g = await perReaderGate({ id, param, cookie, secret, recipients: config.recipients });
+        if (g.state !== 'shut' || (g.why !== 'revoked' && g.why !== 'expired'))
+            return null;
+        const look = lookOf(a).pack;
+        const colour = (c, fallback) => (SAFE_COLOUR.test(c) ? c : fallback);
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex, nofollow"><title>${UNAVAILABLE}</title></head>`
+            + `<body style="margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:${colour(look.ground, '#0e0f13')};color:${colour(look.ink, '#ece7dc')};font-family:system-ui,sans-serif">`
+            + `<p data-per-reader-shut style="max-width:36rem;padding:0 1.5rem;text-align:center;font-size:1.125rem;opacity:.8">${UNAVAILABLE}</p></body></html>`;
+        return new Response(html, { status: 410, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'x-robots-tag': 'noindex, nofollow' } });
     }
-    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, SETTINGS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, ...recipientsRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, LIST, shutPageResponse, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, SETTINGS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, ...recipientsRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

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

@@ -30,5 +30,6 @@ export declare function createRecipientsRoutes(given: RecipientsRoutesCtx): {
         skipped: string[];
         failed: string[];
     }>;
+    forgetReaders: (id: string) => Promise<void>;
 };
 export {};

package/lib/routes/recipients-routes.js

@@ -121,6 +121,19 @@ export function createRecipientsRoutes(given) {
         const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, at: e.at, text: String(e.value?.body ?? '') }));
         return json({ id, expireAt: rec.expireAt, keep: rec.keep, recipients: summarizeViews(rec, await ctx.recipients.views(id), comments) });
     }
+    /** Reader text goes with the page: every comment and answer on it, whoever wrote it. */
+    async function clearReaderText(id) {
+        if (ctx.state)
+            for (const key of new Set((await ctx.state.entries(id)).map((e) => e.readerKey)))
+                await ctx.state.removeReader(id, key);
+    }
+    /** Everything a page holds about its readers: their comments and answers, then who it was sent
+     *  to, each person's note and their views. DELETE calls it before removing the page record, so a
+     *  failure leaves the record and the delete can be run again. */
+    async function forgetReaders(id) {
+        await clearReaderText(id);
+        await ctx.recipients?.forget(id);
+    }
     /** The daily sweep: deletes only pages whose recipients record carries an expireAt that is a
      *  well-formed time in the past and is not kept. An unparseable expireAt is never deleted (the
      *  gate already shuts the page); it is reported in `skipped`. A page that fails midway stays
@@ -162,10 +175,7 @@ export function createRecipientsRoutes(given) {
                     log(`sweepExpired: ${id} was kept during the sweep`);
                     continue;
                 }
-                // Reader text expires with the page: every comment and answer, whoever wrote it.
-                if (ctx.state)
-                    for (const key of new Set((await ctx.state.entries(id)).map((e) => e.readerKey)))
-                        await ctx.state.removeReader(id, key);
+                await clearReaderText(id);
                 await ctx.store.delete(id);
                 await ctx.recipients.forget(id);
                 out.pages++;
@@ -178,5 +188,5 @@ export function createRecipientsRoutes(given) {
         }
         return out;
     }
-    return { SEEN, RECIPIENTS, VIEWS, sweepExpired };
+    return { SEEN, RECIPIENTS, VIEWS, sweepExpired, forgetReaders };
 }

package/package.json

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