@supersuit/artifacts 0.33.1 → 0.35.0

package/lib/artifacts/resolve-digest.js

@@ -0,0 +1,282 @@
+// Resolution digests (0.34.0): when the owner, an admin or the publisher resolves comment threads,
+// each signed-in reader whose comments were in them hears about it, in ONE email per page per burst
+// of resolving, rather than one email per thread.
+//
+//   resolve  -> onResolve(event)   queues a notice for every signed-in writer of a comment in the
+//                                  thread, except the person resolving, the page's owner and its
+//                                  admins; anonymous writers have no address and get nothing
+//   reopen   -> onResolve(event)   drops the thread from every burst still waiting on that page
+//   cron     -> flush()            a burst whose last resolution is QUIET_MS old (or whose first is
+//                                  MAX_WAIT_MS old) becomes one digest, sent once
+//
+// Only resolutions recorded through the route after a host wires `onResolve` queue anything: there
+// is no backfill, so threads resolved before a host turned digests on never produce an email.
+//
+// Sent once, by construction. A due burst is CLAIMED in one transaction that turns it into a digest
+// record and deletes the burst, so two overlapping runs cannot both claim it. A digest is then
+// LEASED in a transaction before it is sent, so two runs cannot both send it. A run that dies after
+// the send and before recording it leaves the lease to expire; the retry carries the same
+// idempotency key (the digest id), which the sender passes to its provider (Resend keeps one for 24
+// hours), so a retry does not deliver twice.
+//
+// Every digest carries a signed stop link that ends these emails for that reader on that page.
+// The package knows nothing about where an email goes: the host hands it a `send` function.
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+/** A burst closes after this long with no new resolution for that reader on that page. */
+export const RESOLVE_DIGEST_QUIET_MS = 10 * 60_000;
+/** A burst that keeps growing is sent anyway once its first resolution is this old. */
+export const RESOLVE_DIGEST_MAX_WAIT_MS = 6 * 3_600_000;
+/** A digest leased for sending and not recorded as sent is retried after this long. */
+export const RESOLVE_DIGEST_LEASE_MS = 15 * 60_000;
+/** After this many attempts a digest is recorded as failed and never tried again. */
+export const RESOLVE_DIGEST_MAX_ATTEMPTS = 5;
+/** How much of a reader's comment, and of the passage it is pinned to, the email quotes. */
+export const DIGEST_BODY_CHARS = 280;
+export const DIGEST_QUOTE_CHARS = 160;
+/** Where the stop link lands, under the host's origin. */
+export const RESOLVE_DIGEST_STOP_PATH = '/api/resolve-digest/stop';
+const norm = (e) => e.trim().toLowerCase();
+/** A stable, non-reversible key for an address, used in document ids and stop links. */
+export function emailKey(email) {
+    return createHash('sha256').update(norm(email)).digest('hex').slice(0, 24);
+}
+export const burstKey = (artifactId, email) => `${artifactId}__${emailKey(email)}`;
+const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
+const trim = (s, n) => { const t = oneLine(s); return t.length > n ? `${t.slice(0, n - 3).trimEnd()}...` : t; };
+/** The notices one resolve event queues: per signed-in writer with an address, the comments in
+ *  the thread that THEY wrote. Never the person resolving, the page's owner or its admins, never
+ *  an anonymous writer, and never a comment somebody else wrote. A reopen queues nothing. Pure. */
+export function noticesFor(event, o = {}) {
+    const r = event.resolution;
+    if (!r)
+        return [];
+    const skip = new Set([o.ownerEmail, ...(o.admins ?? []), event.actor.email].filter((e) => !!e && !!e.trim()).map(norm));
+    const root = event.thread.entries.find((e) => e.id === event.thread.id);
+    const anchor = root?.value?.anchor;
+    const quote = anchor?.kind === 'text' && anchor.quote ? trim(anchor.quote, DIGEST_QUOTE_CHARS) : null;
+    const by = new Map();
+    for (const e of event.thread.entries) {
+        const w = e.writer;
+        if (w.anonymous || !w.email || !w.email.trim())
+            continue;
+        const email = norm(w.email);
+        if (skip.has(email))
+            continue;
+        const v = e.value;
+        const body = v.body && v.body.trim() ? trim(v.body, DIGEST_BODY_CHARS) : 'a voice memo';
+        const item = { entryId: e.id, threadId: event.thread.id, quote, body, note: r.note ?? null, by: r.by, resolvedAt: r.at };
+        const n = by.get(email) ?? { email, name: w.name?.trim() || null, items: [] };
+        n.items.push(item);
+        by.set(email, n);
+    }
+    return [...by.values()];
+}
+/** A digest's items in the order the email lists them: by when each thread was resolved. */
+export function itemsOf(threads) {
+    return Object.values(threads).flat().sort((x, y) => x.resolvedAt.localeCompare(y.resolvedAt));
+}
+// ---- Stop links
+const stopSig = (secret, artifactId, key) => createHmac('sha256', secret).update(`resolve-digest-stop|${artifactId}|${key}`).digest('base64url').slice(0, 32);
+/** `<artifactId>.<emailKey>.<signature>`: names the page and the reader (by key, not address). */
+export function stopToken(secret, artifactId, email) {
+    const key = emailKey(email);
+    return `${artifactId}.${key}.${stopSig(secret, artifactId, key)}`;
+}
+export function verifyStopToken(secret, token) {
+    if (!secret || !token)
+        return null;
+    const m = /^([A-Za-z0-9]{1,32})\.([a-f0-9]{24})\.([A-Za-z0-9_-]{32})$/.exec(token.trim());
+    if (!m)
+        return null;
+    const want = Buffer.from(stopSig(secret, m[1], m[2]));
+    const got = Buffer.from(m[3]);
+    return got.length === want.length && timingSafeEqual(got, want) ? { artifactId: m[1], emailKey: m[2] } : null;
+}
+// ---- The email
+const GENERIC_BY = new Set(['', 'the publisher', 'the owner']);
+const join = (names) => names.length <= 1 ? names[0] ?? '' : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/** Who resolved, as a person reads it: the names on the resolutions, with "the publisher" read as
+ *  the page's owner (an agent resolving with the publish key is resolving on the owner's behalf). */
+export function resolverName(items, fallback) {
+    const names = [];
+    for (const i of items) {
+        const n = GENERIC_BY.has(i.by.trim().toLowerCase()) ? fallback : i.by.trim();
+        if (!names.includes(n))
+            names.push(n);
+    }
+    return join(names) || fallback;
+}
+/** The digest as an email. Plain words, no em dashes, every comment linked to its place. */
+export function composeDigest(d, o) {
+    const title = oneLine(d.title) || 'your page';
+    const who = resolverName(d.items, o.ownerName?.trim() || o.brandName);
+    const n = d.items.length;
+    const yours = n === 1 ? 'your comment' : `${n} of your comments`;
+    const subject = `${who} resolved ${yours} on ${title}`;
+    const first = d.name?.trim().split(/\s+/)[0];
+    const hello = first ? `Hi ${first},` : 'Hi,';
+    const lead = n === 1
+        ? `${who} resolved the comment you left on "${title}".`
+        : `${who} resolved ${n} of the comments you left on "${title}".`;
+    const link = (i) => `${d.url}#comment-${i.entryId}`;
+    const where = (i) => i.quote ? `On "${i.quote}"` : 'On a box on the page';
+    const host = (() => { try {
+        return new URL(d.url).host;
+    }
+    catch {
+        return '';
+    } })();
+    const why = 'You are getting this because you left these comments on the page while signed in.';
+    const text = [
+        hello, '', lead, '',
+        ...d.items.flatMap((i, k) => [
+            `${k + 1}. ${where(i)}`,
+            `   You wrote: "${i.body}"`,
+            ...(i.note ? [`   What changed: ${i.note}`] : []),
+            `   See it: ${link(i)}`,
+            '',
+        ]),
+        `Read the page: ${d.url}`, '',
+        `${o.brandName}${host ? `, ${host}` : ''}`, '',
+        why,
+        `Stop these emails for this page: ${o.stopUrl}`,
+    ].join('\n');
+    const p = 'margin:0 0 14px';
+    const html = [
+        '<div style="font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif;font-size:15px;line-height:1.5;color:#1a1a1a;max-width:560px">',
+        `<p style="${p}">${esc(hello)}</p>`,
+        `<p style="${p}">${esc(lead)}</p>`,
+        ...d.items.map((i) => [
+            '<div style="margin:0 0 18px;padding:0 0 0 12px;border-left:3px solid #d0d0d0">',
+            i.quote ? `<p style="margin:0 0 6px;color:#555">On &ldquo;${esc(i.quote)}&rdquo;</p>` : '<p style="margin:0 0 6px;color:#555">On a box on the page</p>',
+            `<p style="margin:0 0 6px">You wrote: &ldquo;${esc(i.body)}&rdquo;</p>`,
+            i.note ? `<p style="margin:0 0 6px"><strong>What changed:</strong> ${esc(i.note)}</p>` : '',
+            `<p style="margin:0"><a href="${esc(link(i))}">See it on the page</a></p>`,
+            '</div>',
+        ].join('')),
+        `<p style="${p}"><a href="${esc(d.url)}">Read the page</a></p>`,
+        `<p style="${p};color:#555">${esc(o.brandName)}${host ? `, ${esc(host)}` : ''}</p>`,
+        `<p style="margin:0;font-size:13px;color:#777">${esc(why)} <a href="${esc(o.stopUrl)}" style="color:#777">Stop these emails for this page</a>.</p>`,
+        '</div>',
+    ].join('');
+    return { subject, text, html };
+}
+/** An address as a report shows it: enough to recognise, not enough to collect. */
+export function maskEmail(email) {
+    const [user, domain] = norm(email).split('@');
+    return domain ? `${user.slice(0, 1)}***@${domain}` : '***';
+}
+export function createResolveDigests(o) {
+    const quietMs = o.quietMs ?? RESOLVE_DIGEST_QUIET_MS;
+    const maxWaitMs = o.maxWaitMs ?? RESOLVE_DIGEST_MAX_WAIT_MS;
+    const origin = o.siteUrl.replace(/\/+$/, '');
+    const stopPath = o.stopPath ?? RESOLVE_DIGEST_STOP_PATH;
+    function stopUrl(artifactId, email) {
+        const secret = o.secret();
+        return secret ? `${origin}${stopPath}?t=${stopToken(secret, artifactId, email)}` : null;
+    }
+    /** The resolve route's hook. Swallows nothing: the route catches. */
+    async function onResolve(event) {
+        if (!event.resolution) {
+            await o.store.dropThread(event.artifactId, event.thread.id);
+            return;
+        }
+        if (!o.secret())
+            return;
+        for (const n of noticesFor(event, { ownerEmail: o.ownerEmail, admins: o.admins })) {
+            if (await o.store.stopped(event.artifactId, emailKey(n.email)))
+                continue;
+            await o.store.add({ artifactId: event.artifactId, email: n.email, name: n.name, title: event.title, url: event.url, threadId: event.thread.id, items: n.items, at: event.at });
+        }
+    }
+    function message(d) {
+        const stop = stopUrl(d.artifactId, d.email);
+        if (!stop)
+            return null;
+        const m = composeDigest(d, { brandName: o.brandName, ownerName: o.ownerName, stopUrl: stop });
+        return {
+            to: d.email, ...m, idempotencyKey: `resolve-digest/${d.id}`,
+            headers: { 'List-Unsubscribe': `<${stop}>`, 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click' },
+        };
+    }
+    /** Send every digest that is due. Run it on a schedule. `dryRun` changes nothing and sends
+     *  nothing: it reports what a real run would send now. */
+    async function flush(opts = {}) {
+        const at = opts.now ?? new Date();
+        const now = at.toISOString();
+        const limit = opts.limit ?? 50;
+        const quietBefore = new Date(at.getTime() - quietMs).toISOString();
+        const maxBefore = new Date(at.getTime() - maxWaitMs).toISOString();
+        const report = { now, dryRun: !!opts.dryRun, due: 0, claimed: 0, sent: [], skipped: [], failed: [] };
+        const due = await o.store.due(quietBefore, maxBefore, limit);
+        report.due = due.length;
+        if (opts.dryRun) {
+            report.wouldSend = [];
+            for (const b of due) {
+                const items = itemsOf(b.threads);
+                const m = composeDigest({ ...b, items }, { brandName: o.brandName, ownerName: o.ownerName, stopUrl: '' });
+                report.wouldSend.push({ to: maskEmail(b.email), subject: m.subject, comments: items.length, artifactId: b.artifactId, stopped: await o.store.stopped(b.artifactId, emailKey(b.email)) });
+            }
+            return report;
+        }
+        if (!o.secret())
+            return report;
+        for (const b of due)
+            if (await o.store.claim({ key: b.key, burstId: b.burstId, quietBefore, maxBefore, now }))
+                report.claimed++;
+        for (const p of await o.store.pending(now, limit)) {
+            const d = await o.store.lease(p.id, now, new Date(at.getTime() + RESOLVE_DIGEST_LEASE_MS).toISOString());
+            if (!d)
+                continue;
+            if (d.attempts > RESOLVE_DIGEST_MAX_ATTEMPTS) {
+                await o.store.finish(d.id, { status: 'failed', at: now, reason: 'too many attempts' });
+                report.failed.push({ id: d.id, error: 'too many attempts' });
+                continue;
+            }
+            if (!d.items.length) {
+                await o.store.finish(d.id, { status: 'skipped', at: now, reason: 'empty' });
+                report.skipped.push({ id: d.id, reason: 'empty' });
+                continue;
+            }
+            if (await o.store.stopped(d.artifactId, emailKey(d.email))) {
+                await o.store.finish(d.id, { status: 'skipped', at: now, reason: 'stopped' });
+                report.skipped.push({ id: d.id, reason: 'stopped' });
+                continue;
+            }
+            const m = message(d);
+            if (!m) {
+                await o.store.release(d.id, now);
+                continue;
+            }
+            try {
+                const r = await o.send(m);
+                await o.store.finish(d.id, { status: 'sent', at: new Date().toISOString(), ...(r && r.id ? { providerId: r.id } : {}) });
+                report.sent.push({ id: d.id, to: maskEmail(d.email), subject: m.subject, comments: d.items.length });
+            }
+            catch (err) {
+                // Back off a little more each attempt: 5, 10, 20, 40 minutes.
+                const wait = 5 * 60_000 * 2 ** Math.max(0, d.attempts - 1);
+                await o.store.release(d.id, new Date(at.getTime() + wait).toISOString());
+                report.failed.push({ id: d.id, error: err?.message ?? 'send failed' });
+            }
+        }
+        return report;
+    }
+    const page = (title, body, status = 200) => new Response(`<!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"><title>${esc(title)}</title></head>` +
+        `<body style="font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif;max-width:480px;margin:15vh auto;padding:0 20px;line-height:1.5;color:#1a1a1a"><h1 style="font-size:20px">${esc(title)}</h1><p>${body}</p></body></html>`, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } });
+    /** GET or POST <stopPath>?t=<token>: one click ends resolution emails for that reader on that
+     *  page. POST answers the mail client's one-click unsubscribe (RFC 8058). */
+    async function STOP(req) {
+        const t = new URL(req.url).searchParams.get('t');
+        const v = verifyStopToken(o.secret(), t);
+        if (!v)
+            return page('That link does not work', 'It may have been copied only in part. Open it again from the email.', 400);
+        await o.store.stop(v.artifactId, v.emailKey, new Date().toISOString());
+        if (req.method === 'POST')
+            return new Response(null, { status: 204 });
+        const title = o.titleOf ? await o.titleOf(v.artifactId).catch(() => null) : null;
+        return page('Done', `You will get no more emails about resolved comments on ${title ? `&ldquo;${esc(title)}&rdquo;` : 'this page'}.`);
+    }
+    return { onResolve, flush, STOP, stopUrl, message };
+}

package/lib/artifacts/state-store.d.ts

@@ -81,6 +81,7 @@ export interface StateStore {
 export declare const readerKeyFor: {
     signedIn: (uid: string) => string;
     anonymous: (id: string) => string;
+    recipient: (rid: string) => string;
 };
 export declare function createStateStore(db: Firestore, base: string): StateStore;
 /** The same contract in memory: for tests, and for hosts' own tests. */

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,10 +4,12 @@ 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';
 import { type ReaderEvent } from '../artifacts/read-alerts.js';
+import type { ResolveEvent } from '../artifacts/resolve-digest.js';
 import type { PersonalStore } from '../artifacts/personal-store.js';
 import type { Transcriber } from '../artifacts/transcribe.js';
 export type ArtifactRoutesConfig = {
@@ -92,12 +94,22 @@ export type ArtifactRoutesConfig = {
      *  event into the alerts worth sending). Awaited, and anything it throws is swallowed: a broken
      *  sink never costs a reader their page or their record. Without it nothing extra is read. */
     onReaderEvent?: (event: ReaderEvent) => void | Promise<void>;
+    /** Told after a comment thread is resolved or reopened (0.34.0): the page, the whole thread, the
+     *  resolution (null on reopen) and who did it. Pass `createResolveDigests(...).onResolve` to email
+     *  each signed-in commenter one digest per burst of resolving. Awaited; anything it throws is
+     *  logged and swallowed, so the resolve itself always lands. */
+    onResolve?: (event: ResolveEvent) => void | Promise<void>;
     /** The read-only lines under the controls in the page menu's Share settings sheet (0.31.0), for
      *  a host that knows more than the package about how its pages are found: its robots.txt, who
      *  its sign-in admits. Given, its rows REPLACE the package's own two (what a stranger with the
      *  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;
@@ -109,6 +121,7 @@ type Params = {
 type PageProps = Params & {
     searchParams?: Promise<{
         key?: string | string[];
+        r?: string | string[];
     }>;
 };
 type VersionParams = {
@@ -120,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;