@supersuit/artifacts 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -3,6 +3,69 @@
 `@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.38.0
+
+**Readers' voice memos live in the private bucket.** A memo left on a page (`comments/<memo>`, or a
+reader's own `personal/<dir>/<memo>`) was written to the PUBLIC bucket. Every URL the package handed
+out was signed, but that bucket carries a bucket-wide public read grant, so the memo itself answered
+an unsigned GET to anyone holding its path. Memos are now written to and read from the private
+bucket (`privateBucket`), under the same key. A host with no private bucket defines no memo method,
+so memos stay on the reader's device instead of going anywhere public.
+
+DETECTOR: an unsigned `curl -o /dev/null -w '%{http_code}'` of
+`https://storage.googleapis.com/<public bucket>/<prefix>/<id>/comments/<memo>.webm` answers 200.
+
+REMEDY: take 0.38.0, then move what is already there:
+`node scripts/migrate-memos-private.mjs --public <bucket> --private <bucket> --prefix tenants/<t>/artifacts`
+(copies each memo to the same key in the private bucket, confirms it arrived, then deletes the
+public one; safe to re-run; `--dry-run` lists). Until a memo is moved the package reads it from the
+public bucket, so nothing stops playing during the move. The same unsigned GET then answers 403.
+
+Tests: `assets.test.ts` (memos sign, size, read and play in the private bucket and never touch the
+public one; an unmoved memo is still read; no private bucket, no memo methods),
+`migrate-memos.test.ts` (moves only memos, never deletes a public memo whose copy did not arrive,
+dry run, same bucket refused).
+
+## 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

package/README.md

@@ -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.
 
@@ -673,12 +673,13 @@ recognition, the words appear in the box as the reader speaks. A memo stops at t
 
 Recordings go up through the same `uploads/<name>` route the publisher uses, to
 `<page>/comments/<memo>.<ext>` or, for a signed-in reader's personal note,
-`<page>/personal/<dir>/<memo>.<ext>`. They are never made public: playback is a signed URL
-issued beside the comment or note it belongs to. That needs the four audio methods
-`createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`, `audioUrl`); a host
-with its own `ArtifactAssets` and none of them keeps memos on the reader's device. On a bucket
-with bucket-wide public read, a recording is readable by anyone holding its path (the paths are
-unguessable); keep the bucket per-object public to have the signed-URL guarantee.
+`<page>/personal/<dir>/<memo>.<ext>`, in the PRIVATE bucket (`privateBucket`, the same one
+`media: private` uses). They are never made public: playback is a signed URL, valid about an hour,
+issued beside the comment or note it belongs to, and an unsigned GET is refused (403). That needs the
+four audio methods `createArtifactAssets` provides (`signAudioUpload`, `audioSize`, `readAudio`,
+`audioUrl`), which it defines only when it is given a private bucket; a host without one, or with
+its own `ArtifactAssets` and none of them, keeps memos on the reader's device. Memos recorded before
+0.38.0 sat in the public bucket: `scripts/migrate-memos-private.mjs` moves them (see CHANGELOG).
 
 To transcribe on the server, pass `transcribe` and add the route. The key stays on the server;
 without `transcribe` the route answers 404 and readers keep the browser's live transcript (or an
@@ -878,6 +879,60 @@ A view is the page rendered in a real browser, visible, for at least 2 seconds.
 
 `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
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,

package/lib/artifacts/assets.js

@@ -108,12 +108,44 @@ export function createArtifactAssets(bucket, prefix, options = {}) {
             }
             return `https://storage.googleapis.com/${bucket.name}/${key}`;
         },
+        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}`);
+    // READERS' VOICE MEMOS LIVE IN THE PRIVATE BUCKET (0.38.0). Until then they went to the public
+    // bucket, unlisted and read through signed URLs, but a bucket-wide public read grant served any
+    // memo to anyone holding its path, unsigned. A memo recorded before 0.38.0 is still read from the
+    // public bucket until scripts/migrate-memos-private.mjs moves it; nothing new is written there.
+    const memo = (id, path) => priv.file(`${clean}/${id}/${path}`);
+    const legacyMemo = (id, path) => bucket.file(`${clean}/${id}/${path}`);
+    const memoFile = async (id, path) => {
+        const f = memo(id, path);
+        if ((await f.exists())[0])
+            return f;
+        const old = legacyMemo(id, path);
+        return (await old.exists())[0] ? old : null;
+    };
+    return {
+        ...assets,
         // The size cap rides in the signature (`x-goog-content-length-range`), so the bucket itself
         // refuses an oversize body; the browser must send the returned headers verbatim.
         async signAudioUpload(id, path, contentType) {
             const range = `0,${MAX_AUDIO_BYTES}`;
             const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600', 'x-goog-content-length-range': range };
-            const [uploadUrl] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({
+            const [uploadUrl] = await memo(id, path).getSignedUrl({
                 version: 'v4',
                 action: 'write',
                 expires: Date.now() + 15 * 60 * 1000,
@@ -123,44 +155,24 @@ export function createArtifactAssets(bucket, prefix, options = {}) {
             return { uploadUrl, headers };
         },
         async audioSize(id, path) {
-            const file = bucket.file(`${clean}/${id}/${path}`);
-            const [there] = await file.exists();
-            if (!there)
+            const file = await memoFile(id, path);
+            if (!file)
                 return null;
             const [meta] = await file.getMetadata();
             return Number(meta.size ?? 0);
         },
         async readAudio(id, path) {
-            const file = bucket.file(`${clean}/${id}/${path}`);
-            const [there] = await file.exists();
-            if (!there)
+            const file = await memoFile(id, path);
+            if (!file)
                 return null;
             const [bytes] = await file.download();
             return bytes;
         },
         async audioUrl(id, path) {
-            const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            const file = (await memoFile(id, path)) ?? memo(id, path);
+            const [url] = await file.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 privateFile(id, stored).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });

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,7 +1,7 @@
-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, PRIVATE_READ_TTL_MS, type ArtifactAssets, type ArtifactAssetsOptions } from './assets.js';
@@ -26,3 +26,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
+export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.js';

package/lib/artifacts/index.js

@@ -1,7 +1,7 @@
-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, PRIVATE_READ_TTL_MS } from './assets.js';
@@ -26,3 +26,4 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 // Per-reader links: the host-facing surface only. The signing and token primitives stay internal.
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';
+export { migrateMemosToPrivate, MEMO_KEY } from './migrate-memos.js';

package/lib/artifacts/migrate-memos.d.ts

@@ -0,0 +1,14 @@
+import type { Bucket } from '@google-cloud/storage';
+/** A reader's memo, by key under the prefix: `<id>/comments/<memo>.<ext>` or `<id>/personal/<dir>/<memo>.<ext>`. */
+export declare const MEMO_KEY: RegExp;
+export interface MemoMigration {
+    moved: string[];
+    alreadyPrivate: string[];
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}
+export declare function migrateMemosToPrivate(bucket: Bucket, privateBucket: Bucket, prefix: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<MemoMigration>;

package/lib/artifacts/migrate-memos.js

@@ -0,0 +1,36 @@
+/** A reader's memo, by key under the prefix: `<id>/comments/<memo>.<ext>` or `<id>/personal/<dir>/<memo>.<ext>`. */
+export const MEMO_KEY = /^[^/]+\/(?:comments\/[^/]+|personal\/[^/]+\/[^/]+)\.(?:webm|m4a|mp4|ogg|wav)$/;
+export async function migrateMemosToPrivate(bucket, privateBucket, prefix, { dryRun = false } = {}) {
+    if (privateBucket.name === bucket.name)
+        throw new Error('the private bucket must be a different bucket from the public one');
+    const clean = prefix.replace(/^\/+|\/+$/g, '');
+    const [files] = await bucket.getFiles({ prefix: `${clean}/` });
+    const out = { moved: [], alreadyPrivate: [], failed: [] };
+    for (const f of files) {
+        const rel = f.name.slice(clean.length + 1);
+        if (!MEMO_KEY.test(rel))
+            continue;
+        try {
+            const dest = privateBucket.file(f.name);
+            if ((await dest.exists())[0]) {
+                if (!dryRun)
+                    await f.delete();
+                out.alreadyPrivate.push(f.name);
+                continue;
+            }
+            if (dryRun) {
+                out.moved.push(f.name);
+                continue;
+            }
+            await f.copy(dest);
+            if (!(await dest.exists())[0])
+                throw new Error('the copy did not arrive in the private bucket');
+            await f.delete();
+            out.moved.push(f.name);
+        }
+        catch (e) {
+            out.failed.push({ key: f.name, error: e.message });
+        }
+    }
+    return out;
+}

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,12 +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
@@ -282,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
@@ -420,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);
@@ -705,10 +744,23 @@ export function createArtifactRoutes(config) {
         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.
@@ -745,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 });
     }
@@ -874,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.36.0",
+  "version": "0.38.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",