@supersuit/artifacts 0.34.0 → 0.35.0

package/lib/artifacts/state-store.js

@@ -17,6 +17,7 @@ import { MAX_MANY_PER_READER } from './state.js';
 export const readerKeyFor = {
     signedIn: (uid) => `u:${uid}`,
     anonymous: (id) => `a:${id}`,
+    recipient: (rid) => `r:${rid}`,
 };
 const writerOf = (w) => ({
     ...(w.uid ? { uid: w.uid } : {}), ...(w.email ? { email: w.email } : {}), name: w.name, anonymous: w.anonymous,

package/lib/artifacts/store.d.ts

@@ -22,6 +22,10 @@ export type ArtifactRecord = {
     narrationHash?: string;
     password?: string;
     access?: Access;
+    /** `per-reader`: opens only through a link made for one reader. */
+    links?: 'per-reader';
+    /** Body media are stored unlisted and served only to a valid reader. */
+    privateMedia?: true;
     state?: StateConfig;
     theme?: ThemeMode;
     /** The brand pack the page asked for by name; see ArtifactMeta.pack. */

package/lib/artifacts/store.js

@@ -193,6 +193,10 @@ async function saveArtifact(col, input) {
         const to = input.meta.to ? {} : { to: FieldValue.delete() };
         // How the page looks is content too: a line the file no longer carries goes back to the default.
         const look = {
+            // Who may open the page is a door, not content: like `access`, a file that leaves these lines
+            // out changes nothing, so a publisher that strips unknown keys can never reopen the page.
+            ...(input.meta.links ? { links: input.meta.links } : {}),
+            ...(input.meta.privateMedia ? { privateMedia: true } : {}),
             ...(input.meta.theme ? {} : { theme: FieldValue.delete() }),
             ...(input.meta.pack ? {} : { pack: FieldValue.delete() }),
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
@@ -219,6 +223,8 @@ async function saveArtifact(col, input) {
         ...fields,
         ...(live.access ? { access: live.access } : {}),
         ...(live.password ? { password: live.password } : {}),
+        ...(input.meta.links ? { links: input.meta.links } : {}),
+        ...(input.meta.privateMedia ? { privateMedia: true } : {}),
         ...(live.state ? { state: live.state } : {}),
         ...(live.comments ? { comments: live.comments } : {}),
         ...(live.commentsVisible ? { commentsVisible: live.commentsVisible } : {}),
@@ -238,6 +244,9 @@ async function deleteArtifact(col, id) {
     const snap = await ref.get();
     if (!snap.exists)
         return false;
+    // Every prior body lives in the versions subcollection and outlives the page doc unless it goes too.
+    const past = await ref.collection('versions').get();
+    await Promise.all(past.docs.map((d) => ref.collection('versions').doc(d.id).delete()));
     await ref.delete();
     return true;
 }

package/lib/reader/index.d.ts

@@ -1,5 +1,6 @@
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex, type WordTiming } from './artifact-reader.js';
 export { PlayerBar } from './player-bar.js';
+export { QuietView } from './quiet-view.js';
 export { CommentLayer } from './comment-layer.js';
 export { PageMenu, roleLine, menuItems, type PageMenuProps, type PageRole } from './page-menu.js';
 export { SettingsSheet, settingsChanges, ACCESS_LABEL, COMMENTS_LABEL, VISIBLE_LABEL, REOPEN_KEY, type PageSettings, type SettingsFact, type SheetKind, type AccessLevel } from './settings-sheet.js';

package/lib/reader/index.js

@@ -2,6 +2,7 @@
 // own 'use client'; this barrel is plain re-exports so it can be imported from either side.
 export { ArtifactReader, wrapWords, seekableWord, litWordIndex } from './artifact-reader.js';
 export { PlayerBar } from './player-bar.js';
+export { QuietView } from './quiet-view.js';
 export { CommentLayer } from './comment-layer.js';
 export { PageMenu, roleLine, menuItems } from './page-menu.js';
 export { SettingsSheet, settingsChanges, ACCESS_LABEL, COMMENTS_LABEL, VISIBLE_LABEL, REOPEN_KEY } from './settings-sheet.js';

package/lib/reader/quiet-view.d.ts

@@ -0,0 +1,7 @@
+export declare function QuietView({ id, rid, sig, token, endpoint }: {
+    id: string;
+    rid: string;
+    sig: string;
+    token: string;
+    endpoint?: string;
+}): null;

package/lib/reader/quiet-view.js

@@ -0,0 +1,118 @@
+'use client';
+// The page's own word that a person looked at it. Silent: it renders nothing and never tells the
+// reader (the publisher chose that). It waits until the page is actually on screen for two
+// seconds, which a link preview fetcher never does because it never runs the page.
+import { useEffect } from 'react';
+const VIEW_AFTER_MS = 2000;
+const BEAT_MS = 15_000;
+const ALPHA = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const rand = (n) => Array.from(crypto.getRandomValues(new Uint8Array(n)), (b) => ALPHA[b % 36]).join('');
+function deviceId() {
+    try {
+        let d = localStorage.getItem('artifact_device');
+        if (!d || !/^[a-z0-9]{16}$/.test(d)) {
+            d = rand(16);
+            localStorage.setItem('artifact_device', d);
+        }
+        return d;
+    }
+    catch {
+        return rand(16);
+    }
+}
+export function QuietView({ id, rid, sig, token, endpoint }) {
+    useEffect(() => {
+        const url = endpoint ?? `/api/artifacts/${id}/seen`;
+        const session = rand(16);
+        const device = deviceId();
+        const base = { rid, sig, session, device };
+        let beat = null;
+        let viewSent = false;
+        let wait = null;
+        let tick = null;
+        let since = 0;
+        const post = async (body) => {
+            try {
+                const r = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ...base, ...body }), keepalive: true });
+                return r.ok ? (await r.json().catch(() => ({}))) : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const visible = () => document.visibilityState === 'visible' && !document.prerendering;
+        const flush = (useBeacon) => {
+            if (!beat || !since)
+                return;
+            const seconds = Math.round((Date.now() - since) / 1000);
+            since = 0;
+            if (seconds <= 0)
+                return;
+            if (useBeacon && typeof navigator.sendBeacon === 'function') {
+                navigator.sendBeacon(url, new Blob([JSON.stringify({ ...base, event: 'beat', beat, seconds })], { type: 'application/json' }));
+            }
+            else
+                void post({ event: 'beat', beat, seconds });
+        };
+        const startBeats = () => {
+            since = Date.now();
+            tick = setInterval(() => { flush(false); since = Date.now(); }, BEAT_MS);
+        };
+        const arm = () => {
+            if (!visible())
+                return;
+            if (beat) {
+                if (!tick)
+                    startBeats();
+                return;
+            }
+            // One render token, one view: once it is sent, a later show never sends another.
+            if (viewSent || wait)
+                return;
+            wait = setTimeout(async () => {
+                wait = null;
+                if (!visible())
+                    return;
+                viewSent = true;
+                const r = await post({ event: 'view', token });
+                if (r?.beat && visible()) {
+                    beat = r.beat;
+                    startBeats();
+                }
+                else if (r?.beat)
+                    beat = r.beat;
+            }, VIEW_AFTER_MS);
+        };
+        const disarm = () => {
+            if (wait) {
+                clearTimeout(wait);
+                wait = null;
+            }
+            if (tick) {
+                clearInterval(tick);
+                tick = null;
+                flush(true);
+            }
+        };
+        const onVisibility = () => (visible() ? arm() : disarm());
+        const onPlay = (e) => {
+            const el = e.target;
+            const media = el?.getAttribute?.('data-artifact-media');
+            if (media && beat)
+                void post({ event: 'play', beat, media });
+        };
+        document.addEventListener('visibilitychange', onVisibility);
+        document.addEventListener('prerenderingchange', onVisibility);
+        document.addEventListener('play', onPlay, true);
+        window.addEventListener('pagehide', disarm);
+        arm();
+        return () => {
+            document.removeEventListener('visibilitychange', onVisibility);
+            document.removeEventListener('prerenderingchange', onVisibility);
+            document.removeEventListener('play', onPlay, true);
+            window.removeEventListener('pagehide', disarm);
+            disarm();
+        };
+    }, [id, rid, sig, token, endpoint]);
+    return null;
+}

package/lib/routes/artifacts.d.ts

@@ -4,6 +4,7 @@ import { type ArtifactRecord, type ArtifactStore, type VersionEntry } from '../a
 import type { StateStore } from '../artifacts/state-store.js';
 import { type ArtifactAssets } from '../artifacts/assets.js';
 import type { BrandPack } from '../brand/pack.js';
+import type { RecipientsStore } from '../artifacts/recipients-store.js';
 import type { PageSettings, SettingsFact } from '../reader/settings-sheet.js';
 import { type Access, type AllowEntry } from '../artifacts/reader.js';
 import { type ReadersStore } from '../artifacts/readers-store.js';
@@ -104,6 +105,11 @@ export type ArtifactRoutesConfig = {
      *  bare URL sees, and search engines). Called only for the owner and admins; a throw falls back
      *  to the package's rows. */
     shareFacts?: (artifact: ArtifactRecord) => SettingsFact[] | Promise<SettingsFact[]>;
+    /** Who each per-reader page was sent to (recipients-store.ts). Without it, or without
+     *  `recipientSecret`, a `links: per-reader` page is shut to everyone. */
+    recipients?: RecipientsStore;
+    /** Signs per-reader links and render tokens. At least 32 characters. Read at request time. */
+    recipientSecret?: () => string | undefined;
 };
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export declare const ARTIFACT_ID: RegExp;
@@ -115,6 +121,7 @@ type Params = {
 type PageProps = Params & {
     searchParams?: Promise<{
         key?: string | string[];
+        r?: string | string[];
     }>;
 };
 type VersionParams = {
@@ -126,11 +133,33 @@ type VersionParams = {
 type VersionProps = VersionParams & {
     searchParams?: Promise<{
         key?: string | string[];
+        r?: string | string[];
     }>;
 };
 export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     dynamic: "force-dynamic";
     maxDuration: number;
+    SEEN: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    RECIPIENTS: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    VIEWS: (req: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+        }>;
+    }) => Promise<NextResponse<unknown>>;
+    sweepExpired: (now?: Date) => Promise<{
+        pages: number;
+        files: number;
+        skipped: string[];
+        failed: string[];
+    }>;
     PERSONAL_GET: (req: NextRequest, { params }: {
         params: Promise<{
             id: string;

package/lib/routes/artifacts.js

@@ -21,6 +21,8 @@ import { ArtifactReader } from '../reader/artifact-reader.js';
 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 { PageMenu } from '../reader/page-menu.js';
 import { COMMENTS_MODES } from '../artifacts/comments.js';
 import { newPageKey } from '../artifacts/settings.js';
@@ -31,6 +33,8 @@ import { readSecondsFor, wordCount } from '../artifacts/read-alerts.js';
 import { AckDoor, ConfidentialBanner, NO_PRINT_CSS, NotAllowedDoor, SignInDoor, Watermark, ackText } from '../artifacts/confidential.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
+import { createRecipientsRoutes } from './recipients-routes.js';
+import { QuietView } from '../reader/quiet-view.js';
 import { createPersonalRoutes } from './personal-routes.js';
 import { createVoiceRoutes } from './voice-routes.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
@@ -87,10 +91,14 @@ export function createArtifactRoutes(config) {
     const publishAuth = { publishKey: config.publishKey, publisherSecret: config.publisherSecret, publisherHost: config.publisherHost };
     const authed = (request) => isPublisherAuthed(request, publishAuth);
     const stateRoutes = createStateRoutes({
-        store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey,
+        store, state: config.state, readers: config.readers, readerSecret, recipients: config.recipients, recipientSecret: config.recipientSecret, publishKey: config.publishKey,
         publisherSecret: config.publisherSecret, publisherHost: config.publisherHost, pageUrl, signInOrigin, siteUrl,
         clientIp: config.clientIp, ownerEmail: config.ownerEmail, admins: config.admins, audioUrl, onResolve: config.onResolve,
     });
+    const recipientsRoutes = createRecipientsRoutes({
+        store, recipients: config.recipients, recipientSecret: config.recipientSecret, publishKey: config.publishKey,
+        state: config.state, assets: config.assets, pageUrl, authed,
+    });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
     const voiceRoutes = createVoiceRoutes({
         store, state: config.state, personal: config.personal, readers: config.readers, assets: config.assets, transcribe: config.transcribe,
@@ -272,6 +280,32 @@ 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') {
+            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);
+            // 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 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
+                ? [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 } });
+            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
         // page they were sent, and the unfurl (generateMetadata) keeps reading as the page.
         const sp = (await searchParams) ?? {};
@@ -385,7 +419,7 @@ export function createArtifactRoutes(config) {
         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 }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
-    async function Body(a, { top, reader }) {
+    async function Body(a, { top, reader, perReader }) {
         const { pack, brand } = lookOf(a);
         let words = [];
         if (a.narration && a.timings) {
@@ -407,10 +441,10 @@ export function createArtifactRoutes(config) {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
                         const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { n: n, at: a.updatedAt }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), meta] }));
-                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
+                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }));
-                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
+                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));
     }
@@ -523,6 +557,8 @@ export function createArtifactRoutes(config) {
         if (request.method === 'GET')
             return NextResponse.json({ id, access: a.access ?? null, readers: await config.readers.allowList(id) });
         const b = (await request.json().catch(() => null));
+        if (a.links === 'per-reader' && b?.access !== undefined)
+            return NextResponse.json({ error: 'a per-reader page opens only from its own links, so its access and password cannot be changed' }, { status: 409 });
         let access = a.access ?? null;
         if (b?.access !== undefined) {
             if (b.access !== 'public' && !ACCESS_LEVELS.includes(b.access))
@@ -587,6 +623,8 @@ export function createArtifactRoutes(config) {
         }
         if (!b || typeof b !== 'object' || Array.isArray(b))
             return no('the body is an object', 400);
+        if (a.links === 'per-reader' && (b.access !== undefined || b.password !== undefined))
+            return no('a per-reader page opens only from its own links, so its access and password cannot be changed', 409);
         const KEYS = ['access', 'password', 'comments', 'commentsVisible', 'add', 'remove'];
         const unknown = Object.keys(b).filter((k) => !KEYS.includes(k));
         if (unknown.length)
@@ -719,6 +757,9 @@ export function createArtifactRoutes(config) {
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         if (!config.assets)
             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 });
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
@@ -734,7 +775,7 @@ export function createArtifactRoutes(config) {
             return NextResponse.json({ error: 'empty body' }, { status: 400 });
         if (bytes.length > 16 * 1024 * 1024)
             return NextResponse.json({ error: 'asset over 16 MiB' }, { status: 413 });
-        const url = await config.assets.put(id, name, bytes, type);
+        const url = priv ? await config.assets.putPrivate(id, name, bytes, type) : await config.assets.put(id, name, bytes, type);
         return NextResponse.json({ id, name, url }, { status: 201 });
     }
     /**
@@ -762,7 +803,12 @@ export function createArtifactRoutes(config) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const assets = config.assets;
-        if (!assets?.signUpload || !assets.finishUpload)
+        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 });
+        }
+        else if (!assets?.signUpload || !assets.finishUpload)
             return NextResponse.json({ error: 'this host does not take direct uploads' }, { status: 501 });
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
@@ -778,12 +824,13 @@ export function createArtifactRoutes(config) {
         if (!ASSET_DIGEST.test(digest))
             return NextResponse.json({ error: 'digest must be the first 8 hex of the sha256 of the bytes' }, { status: 400 });
         if (body.done === true) {
-            const url = await assets.finishUpload(id, name, digest);
+            const url = priv ? await assets.finishPrivateUpload(id, name, digest) : await assets.finishUpload(id, name, digest);
             if (!url)
                 return NextResponse.json({ error: 'nothing was uploaded to that url' }, { status: 409 });
             return NextResponse.json({ id, name, url }, { status: 201 });
         }
-        return NextResponse.json({ id, name, ...(await assets.signUpload(id, name, digest, type)) }, { status: 201 });
+        const signed = priv ? await assets.signPrivateUpload(id, name, digest, type) : await assets.signUpload(id, name, digest, type);
+        return NextResponse.json({ id, name, ...signed }, { status: 201 });
     }
     /** GET /<id>/share.png: the page's title card. 404 when the pack draws none, so a
      *  tenant on the static default never serves a half-styled card. */
@@ -828,5 +875,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    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, dynamic: 'force-dynamic', maxDuration: 30 };
+    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 };
 }

package/lib/routes/per-reader.d.ts

@@ -0,0 +1,25 @@
+import type { RecipientsStore } from '../artifacts/recipients-store.js';
+export type PerReaderOpen = {
+    state: 'open';
+    rid: string;
+    sig: string;
+    label: string;
+    note: string | null;
+    owner: boolean;
+    fromLink: boolean;
+};
+export type PerReaderShut = {
+    state: 'shut';
+    why: 'no-link' | 'revoked' | 'expired' | 'closed';
+};
+export declare const UNAVAILABLE = "This page is no longer available.";
+export declare const NO_LINK = "This page opens from the link it was sent with.";
+export declare function perReaderGate(o: {
+    id: string;
+    param: string | undefined;
+    cookie: string | undefined;
+    secret: string | undefined;
+    recipients: RecipientsStore | undefined;
+    now?: number;
+}): Promise<PerReaderOpen | PerReaderShut>;
+export declare function withPrivateUrls(markdown: string, id: string, privateUrl: ((id: string, stored: string) => Promise<string>) | undefined): Promise<string>;

package/lib/routes/per-reader.js

@@ -0,0 +1,38 @@
+// Who is reading a `links: per-reader` page, decided before anything of the page is rendered.
+// Every refusal is the same quiet page; a revoked or expired reader learns only that it is gone.
+import { parseRidParam, verifyRid } from '../artifacts/recipients.js';
+import { PRIVATE_REF } from '../artifacts/assets.js';
+export const UNAVAILABLE = 'This page is no longer available.';
+export const NO_LINK = 'This page opens from the link it was sent with.';
+export async function perReaderGate(o) {
+    // An unset or empty secret verifies nothing: fail closed before any signature is compared.
+    if (!o.secret || !o.recipients)
+        return { state: 'shut', why: 'closed' };
+    const fromParam = parseRidParam(o.param);
+    const fromCookie = parseRidParam(o.cookie);
+    const pick = fromParam && verifyRid(o.secret, o.id, fromParam.rid, fromParam.sig) ? { ...fromParam, fromLink: true }
+        : fromCookie && verifyRid(o.secret, o.id, fromCookie.rid, fromCookie.sig) ? { ...fromCookie, fromLink: false } : null;
+    if (!pick)
+        return { state: 'shut', why: 'no-link' };
+    const rec = await o.recipients.get(o.id);
+    const r = rec?.recipients[pick.rid];
+    if (!rec || !r)
+        return { state: 'shut', why: 'no-link' };
+    if (r.revokedAt)
+        return { state: 'shut', why: 'revoked' };
+    // A malformed expireAt parses to NaN: treat it as expired, never as no expiry.
+    if (rec.expireAt && !(Date.parse(rec.expireAt) > (o.now ?? Date.now())))
+        return { state: 'shut', why: 'expired' };
+    return { state: 'open', rid: pick.rid, sig: pick.sig, label: r.label, note: r.note ?? null, owner: r.owner === true, fromLink: pick.fromLink };
+}
+const REF_IN_MD = /\]\((private:[A-Za-z0-9][A-Za-z0-9._-]{0,140})\)/g;
+export async function withPrivateUrls(markdown, id, privateUrl) {
+    const refs = [...new Set([...markdown.matchAll(REF_IN_MD)].map((m) => m[1]))];
+    let out = markdown;
+    for (const ref of refs) {
+        const stored = PRIVATE_REF.exec(ref)?.[1];
+        const url = stored && privateUrl ? await privateUrl(id, stored) : '#';
+        out = out.split(`](${ref})`).join(`](${url})`);
+    }
+    return out;
+}

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

@@ -0,0 +1,34 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { type RecipientsStore } from '../artifacts/recipients-store.js';
+import type { ArtifactStore } from '../artifacts/store.js';
+import type { StateStore } from '../artifacts/state-store.js';
+import type { ArtifactAssets } from '../artifacts/assets.js';
+type Params = {
+    params: Promise<{
+        id: string;
+    }>;
+};
+export type RecipientsRoutesCtx = {
+    store: ArtifactStore;
+    recipients?: RecipientsStore;
+    recipientSecret?: () => string | undefined;
+    publishKey: () => string | undefined;
+    state?: StateStore;
+    assets?: ArtifactAssets;
+    pageUrl: (id: string) => string;
+    authed: (r: Request) => boolean;
+    /** Where the sweep reports a page it skipped or could not finish. Defaults to console.warn. */
+    log?: (message: string) => void;
+};
+export declare function createRecipientsRoutes(given: RecipientsRoutesCtx): {
+    SEEN: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    RECIPIENTS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    VIEWS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    sweepExpired: (now?: Date) => Promise<{
+        pages: number;
+        files: number;
+        skipped: string[];
+        failed: string[];
+    }>;
+};
+export {};