@supersuit/artifacts 0.33.1 → 0.35.0

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 `@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.35.0
+
+**Per-reader links, private media, video with sound, quiet views, and expiry.** A page can now go
+to several people at once with one link each, revocable one at a time, with a tailored note per
+reader.
+
+- `links: per-reader` in front matter: the page opens only through a link made for one reader
+  (`?r=<rid>.<sig>`, signed with the host's recipient secret). Each link can be revoked alone.
+  `createRecipientsStore(db, base)` and `memoryRecipientsStore()` hold the readers; the routes are
+  `RECIPIENTS` (GET and POST: add, revoke, set a note), `VIEWS` (GET) and `SEEN` (POST).
+- `media: private`: body media is stored under the page's private prefix and served only by signed
+  URL to a valid reader. The cover stays public so the share card works.
+- Video with sound: `![sound: caption](clip.mp4)` renders a clip with controls. `.m4a` voice notes
+  are supported.
+- A quiet view beacon. DETECTOR: an unfurl fetch or a background tab used to count as an open.
+  REMEDY: a view is the page visible for two seconds with a single-use render token; known unfurl
+  agents and the owner are dropped server side. TESTS: `src/routes/seen.test.tsx`,
+  `src/reader/quiet-view.test.tsx`.
+- `sweepExpired()` for dated pages: deletes the page, its media, readers, views and comments, and
+  returns `{ pages, files, skipped, failed }`. Call it daily from a cron route.
+- Config on `createArtifactRoutes`: `recipients` and `recipientSecret` (a function; at least 32
+  characters, shorter is treated as unset).
+
+## 0.34.0
+
+**Commenters hear when their comments are resolved, in one email per page per burst** (Gary,
+2026-10-12: "Can those notifications around resolved comments batch plz"). 0.33.0 let the owner
+resolve threads, but the reader who asked never found out unless someone texted them.
+
+- `createResolveDigests({ store, send, secret, siteUrl, brandName, ownerName?, ownerEmail?, admins?,
+  quietMs?, maxWaitMs? })` returns `onResolve` (the route hook), `flush({ now?, dryRun? })` (run it on
+  a schedule), `STOP` (the stop link's GET and POST) and `stopUrl`. The package composes and batches;
+  the host's `send` delivers.
+- `onResolve` on `createArtifactRoutes` (and the state routes): told after every resolve and reopen
+  with the page, the whole thread, the resolution (null on reopen) and who did it (`actor.email` for
+  a signed-in owner or admin, `actor.publisher` for the key or a pass). Awaited; a throw is logged and
+  the resolve still lands.
+- Who hears: each signed-in writer of a comment in the thread, about their own comments only; never
+  an anonymous reader, the person resolving, the owner or the admins. A burst closes after 10 quiet
+  minutes for that reader on that page (or 6 hours after its first resolution); a reopened thread
+  drops out. Only resolutions recorded through `onResolve` queue anything, so threads resolved before
+  a host wires it never produce an email.
+- Sent once: claim and lease are transactions, and every retry of one digest carries the same
+  `idempotencyKey` for the provider. Every email has a signed stop link (per reader, per page) and
+  `List-Unsubscribe` headers.
+- `createResolveDigestStore(db, base)` (Firestore, beside the state store: `<base>ResolveBursts`,
+  `<base>ResolveDigests`, `<base>ResolveStops`; no composite index) and
+  `createMemoryResolveDigestStore()`.
+- DETECTOR: `createResolveDigests` is not exported, or `createArtifactRoutes` takes no `onResolve`:
+  0.33.1 or earlier. Nothing changes for a host that does not wire it.
+- REMEDY: to turn digests on, build `createResolveDigests` with your store, sender and a stop-link
+  secret, pass `onResolve: digests.onResolve`, add `app/api/resolve-digest/stop/route.ts` (GET and
+  POST = `digests.STOP`), and call `digests.flush()` from a scheduled job (every 5 minutes is plenty).
+  Otherwise update the dependency; nothing else.
+- Tests: `artifacts/resolve-digest.test.ts` (who hears: writer only, replies by others, anonymous,
+  owner, admin and the resolver excluded; three threads make one digest; one per reader per page;
+  resolving again replaces; the quiet window and its restart; the 6-hour cap; a new burst after a
+  claim; reopen drops a thread and an emptied burst sends nothing; double and overlapping flushes send
+  once; a failed send retried with the same idempotency key; an expired lease after a crash; no
+  backfill; the stop link signed, refused when tampered, honoured for that page only, by GET and POST;
+  no secret queues nothing; dry run changes nothing; the email's words, links, escaping and no em
+  dash), `routes/resolve-digest.test.tsx` (the route hands the thread and the actor to `onResolve`,
+  reopen and the publish key too, a throwing hook never costs the resolve, end to end through RESOLVE
+  and flush, nothing for threads resolved before wiring), and `check-packed` (from the tarball: a
+  signed-in comment resolved with the key, nothing due inside the window, the dry run, one digest
+  sent once, its stop link).
+
 ## 0.33.1
 
 **The player bar: the speed button no longer reflows the bar, 2x is a speed, and the narrator

package/README.md

@@ -251,6 +251,8 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `pack` | A brand pack the host registered by name (`packs` in the routes config). An unknown name renders in the host's default pack; a republish without the line goes back to it |
 | `toc` | The table of contents. Absent, it appears once the page has four `##` sections; `false` never; `true` from one |
 | `definitions` | Terms defined inline (below). A republish without it removes 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 |
 
@@ -745,6 +747,48 @@ type Ctx = { params: Promise<{ id: string }> }
 export function POST(request: NextRequest, ctx: Ctx) { return artifacts.RESOLVE(request, ctx) }
 ```
 
+### Telling commenters their comments were resolved (`createResolveDigests`)
+
+When threads are resolved, each signed-in reader whose comments were in them can get ONE email per
+page per burst of resolving, listing every one of their comments resolved in it: the passage it was
+pinned to (or "a box on the page"), their comment trimmed, the resolution note, a link to
+`<page>#comment-<id>`, and one link to the page. Resolve nineteen threads in a sitting and a reader
+gets one email, not nineteen.
+
+- **Who hears:** the signed-in writer of each comment in a resolved thread, about the comments THEY
+  wrote (a reply by someone else is not theirs). Never an anonymous reader (no address), never the
+  person resolving, never `ownerEmail` or `admins` about their own comments.
+- **The burst:** closes after `quietMs` (default 10 minutes) with no new resolution for that reader
+  on that page, or once its first resolution is `maxWaitMs` old (default 6 hours). A thread reopened
+  before then drops out; resolving one again replaces its line.
+- **No backfill:** only resolutions that pass through `onResolve` queue anything, so threads resolved
+  before a host wires it never produce an email.
+- **Sent once:** a due burst is claimed in one transaction (it becomes a digest record and the burst
+  is deleted), and a digest is leased in a transaction before it is sent, so overlapping runs cannot
+  both send it. The message carries `idempotencyKey` (the same on every retry of one digest): hand it
+  to your provider (Resend's `Idempotency-Key`), and a run that died between sending and recording
+  does not deliver twice when the lease expires. A failed send is retried with back-off, at most 5
+  times.
+- **Stop:** every email carries a signed link (`<site>/api/resolve-digest/stop?t=...`, and the RFC 8058
+  `List-Unsubscribe` headers) that ends these emails for that reader on that page. Without `secret`
+  nothing is queued, since no email may go out without one.
+- **Where it waits:** `createResolveDigestStore(db, base)` (Firestore: `<base>ResolveBursts`,
+  `<base>ResolveDigests`, `<base>ResolveStops`; single-field queries only, so no index to create), or
+  `createMemoryResolveDigestStore()` for tests.
+
+```ts
+const digests = createResolveDigests({
+  store: createResolveDigestStore(db, 'artifact'),
+  send: async (m) => sendWithYourProvider(m),     // { to, subject, text, html, headers, idempotencyKey }
+  secret: () => process.env.STOP_LINK_SECRET,     // signs stop links
+  siteUrl: 'https://artifacts.example.com', brandName: 'Example Co', ownerName: 'Ann',
+  ownerEmail, admins,
+})
+createArtifactRoutes({ /* ... */, onResolve: digests.onResolve })
+// app/api/resolve-digest/stop/route.ts:  GET and POST = digests.STOP
+// a scheduled job:                        await digests.flush()   ({ dryRun: true } reports, sends nothing)
+```
+
 ### The comments feed
 
 So the publisher hears about a shared comment without opening every page, one route lists every
@@ -788,6 +832,44 @@ composite index: **`slot` ascending, `at` ascending**, collection scope. Without
 refuses the query and the error names a link that creates the index. A host with its own
 `StateStore` implements `slotSince(slot, after, limit)`; without it the feed answers 501.
 
+## Per-reader links
+
+One page, sent to many people, where every person gets their own link. The link names an opaque reader id and a signature over the page and that id, so a link cannot be guessed or carried to another page. The host knows an opaque id, a label you gave it and that link's views and comments, and nothing else about the reader.
+
+```markdown
+---
+title: The river
+summary: Eleven minutes on the water.
+links: per-reader
+media: private
+---
+![sound: the first night](river.mp4)
+![a voice note, as it came](note.m4a)
+```
+
+`links: per-reader` shuts the page to everyone who does not arrive through a valid, unrevoked, unexpired link. It cannot be combined with `password`, `access` or `comments_visible: readers` (readers never see each other's comments). `media: private` keeps body media under the page's private prefix; `.mp4` and `.m4a` (and `.mp3`) are supported, and `sound:` at the start of a video's alt makes it a clip with controls and sound. Both lines are sticky: republishing a file that leaves them out changes nothing.
+
+Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `VIEWS`, `SEEN`, and `sweepExpired`.
+
+| Route | Who | What |
+|---|---|---|
+| `GET /api/artifacts/<id>/recipients` | publish key | Every reader, with the working link for each |
+| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group? }], revoke?: [rid] or '*', expires?: ISO time or null }`. `add` answers each new reader's link; `expires: null` is Keep |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
+| `POST /api/artifacts/<id>/seen` | the page itself (public) | The reader's own signal, below |
+
+Config, both on `createArtifactRoutes`: `recipients` (a store from `createRecipientsStore(db, '<collection path>')`, or `memoryRecipientsStore()` in tests) and `recipientSecret`, a function returning the signing secret, read on every request. A secret shorter than 32 characters is treated as unset: per-reader pages stay shut and the routes answer 404 or 501. Signing with an empty secret throws.
+
+The `Page` route must stay `force-dynamic` (the package's `dynamic` export says so; re-export it), because the page carries a fresh render token and answers per link.
+
+### What counts as a view
+
+A view is the page rendered in a real browser, visible, for at least 2 seconds. The page then sends one signal carrying a single-use render token minted for that render; the token is spent on first use and expires after a day. Known unfurl fetchers (and any request with no user agent) are ignored, and so is a signal for a revoked or expired reader. The owner's own opens record zero. After the first signal the page sends a beat every few seconds while it stays visible (and a final one on hide, by `sendBeacon`), and a play signal when a clip starts. A signed-in owner or admin opens the page with no link and no tracking, so test a reader's link in a signed-out browser, never in the browser you are signed in to.
+
+### Expiry
+
+`expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,
@@ -839,6 +921,7 @@ the page's pack.
 | your publish key (named by you, read in `publishKey`) | Authorises publish, delete and access changes |
 | `ARTIFACT_PASS_SECRET` (named by you, read in `readerSecret`) | Verifies reader passes and signs grants; shared with your sign-in side |
 | a publisher-pass secret (named by you, read in `publisherSecret`; may be the same one) | Verifies publisher passes; shared with whatever mints them |
+| a recipient secret (named by you, read in `recipientSecret`; at least 32 characters) | Signs per-reader links and render tokens; shorter is treated as unset |
 | Firebase Admin credentials | The store and readers store |
 
 ## Contributing

package/lib/artifacts/assets.d.ts

@@ -25,7 +25,23 @@ export interface ArtifactAssets {
     readAudio?(id: string, path: string): Promise<Buffer | null>;
     /** A signed URL to play the recording, valid for about an hour. */
     audioUrl?(id: string, path: string): Promise<string>;
+    /** Store bytes privately; return `private:<stored name>`. */
+    putPrivate?(id: string, name: string, bytes: Buffer, contentType: string): Promise<string>;
+    /** Like signUpload, to the private key; `url` is `private:<stored name>`. */
+    signPrivateUpload?(id: string, name: string, digest: string, contentType: string): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+        url: string;
+    }>;
+    /** After a signed private upload: `private:<stored name>`, or null if nothing arrived. */
+    finishPrivateUpload?(id: string, name: string, digest: string): Promise<string | null>;
+    /** A signed read URL for a stored private name, valid one hour. */
+    privateUrl?(id: string, stored: string): Promise<string>;
+    /** Delete every object under `<prefix>/<id>/`; returns how many. */
+    deletePage?(id: string): Promise<number>;
 }
+/** A reference to a private file as it appears in a page: `private:<stored name>`. */
+export declare const PRIVATE_REF: RegExp;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export declare const ASSET_DIGEST: RegExp;
 /** Names are one path segment: letters, digits, dot, dash, underscore. */

package/lib/artifacts/assets.js

@@ -4,6 +4,9 @@
 // could do, so every operator gets the same door: PUT bytes with their key, get a URL back.
 import { createHash } from 'node:crypto';
 import { MAX_AUDIO_BYTES } from './audio.js';
+import { ARTIFACT_ID_RE } from '../routes/ids.js';
+/** A reference to a private file as it appears in a page: `private:<stored name>`. */
+export const PRIVATE_REF = /^private:([A-Za-z0-9][A-Za-z0-9._-]{0,140})$/;
 /** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
 export const ASSET_DIGEST = /^[0-9a-f]{8}$/;
 const CACHE_CONTROL = 'public, max-age=31536000, immutable';
@@ -16,6 +19,7 @@ export const ASSET_TYPES = {
     jpeg: 'image/jpeg',
     gif: 'image/gif',
     mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
     mp4: 'video/mp4',
     json: 'application/json',
 };
@@ -131,5 +135,36 @@ export function createArtifactAssets(bucket, prefix) {
             const [url] = await bucket.file(`${clean}/${id}/${path}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
             return url;
         },
+        async putPrivate(id, name, bytes, contentType) {
+            const stored = hashedName(name, bytes);
+            await bucket.file(`${clean}/${id}/private/${stored}`).save(bytes, { contentType, resumable: false, metadata: { cacheControl: 'private, max-age=3600' } });
+            return `private:${stored}`;
+        },
+        async signPrivateUpload(id, name, digest, contentType) {
+            const stored = storedName(name, digest);
+            const headers = { 'content-type': contentType, 'cache-control': 'private, max-age=3600' };
+            const [uploadUrl] = await bucket.file(`${clean}/${id}/private/${stored}`).getSignedUrl({ version: 'v4', action: 'write', expires: Date.now() + 15 * 60 * 1000, contentType, extensionHeaders: { 'cache-control': headers['cache-control'] } });
+            return { uploadUrl, headers, url: `private:${stored}` };
+        },
+        async finishPrivateUpload(id, name, digest) {
+            const stored = storedName(name, digest);
+            const [there] = await bucket.file(`${clean}/${id}/private/${stored}`).exists();
+            return there ? `private:${stored}` : null;
+        },
+        async privateUrl(id, stored) {
+            if (!PRIVATE_REF.test(`private:${stored}`))
+                throw new Error('not a private file name');
+            const [url] = await bucket.file(`${clean}/${id}/private/${stored}`).getSignedUrl({ version: 'v4', action: 'read', expires: Date.now() + 60 * 60 * 1000 });
+            return url;
+        },
+        async deletePage(id) {
+            // An empty or path-shaped id would make the prefix wider than one page.
+            if (!ARTIFACT_ID_RE.test(id))
+                throw new Error('not an artifact id');
+            const [files] = await bucket.getFiles({ prefix: `${clean}/${id}/` });
+            for (const f of files)
+                await f.delete();
+            return files.length;
+        },
     };
 }

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

@@ -31,6 +31,10 @@ export type ArtifactMeta = {
      *  ABSENT CHANGES NOTHING: the level is host-side state, so a republish that omits the line
      *  (or a publisher that strips unknown keys) can never reopen a confidential page. */
     access?: Access | 'public';
+    /** `per-reader`: the page opens only through a link made for one reader (recipients.ts). */
+    links?: 'per-reader';
+    /** `media: private` in the file: body media are stored unlisted and served only to a valid reader. */
+    privateMedia?: true;
     /** What readers may put into the page. Content, like the body: a republish without it removes
      *  the slots from the page and KEEPS the answers already given. */
     state?: StateConfig;

package/lib/artifacts/front-matter.js

@@ -11,7 +11,7 @@ import { parseDefinitions } from './definitions.js';
 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']);
+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) {
     const { data, content } = matter(text);
     const d = data;
@@ -54,6 +54,18 @@ export function parseArtifactSource(text) {
             return { ok: false, error: `access must be one of: public, ${ACCESS_LEVELS.join(', ')}` };
         meta.access = d.access;
     }
+    if (d.links !== undefined && d.links !== null) {
+        if (d.links !== 'per-reader')
+            return { ok: false, error: 'links must be per-reader' };
+        if (meta.password || meta.access)
+            return { ok: false, error: 'per-reader links stand alone: drop password and access' };
+        meta.links = 'per-reader';
+    }
+    if (d.media !== undefined && d.media !== null) {
+        if (d.media !== 'private')
+            return { ok: false, error: 'media must be private' };
+        meta.privateMedia = true;
+    }
     if (d.theme !== undefined) {
         if (!THEME_MODES.includes(d.theme))
             return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };
@@ -94,6 +106,12 @@ export function parseArtifactSource(text) {
             return { ok: false, error: 'comments_visible must be owner or readers' };
         meta.commentsVisible = d.comments_visible;
     }
+    // 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' };
+    // People on one broadcast never see each other's comments, so a per-reader page cannot share them.
+    if (meta.links === 'per-reader' && meta.commentsVisible === 'readers')
+        return { ok: false, error: 'a per-reader page keeps each reader\'s comments to the owner: drop comments_visible: readers' };
     // Widgets declare their own slots, so a notes block (and a checklist with send) is merged into state: here, before the
     // page is stored, and the state API and the republish shape checks see it like any slot.
     // Errors name the line in the FILE: the body's lines are counted after the front matter's.

package/lib/artifacts/index.d.ts

@@ -16,9 +16,13 @@ export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChec
 export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence, type ChecklistBlock, type ChecklistItem, type ChecklistValue } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID, type Anchor, type TextAnchor, type RegionAnchor } from './anchor.js';
+export { createResolveDigests, noticesFor, composeDigest, resolverName, itemsOf, emailKey, burstKey, stopToken, verifyStopToken, maskEmail, RESOLVE_DIGEST_QUIET_MS, RESOLVE_DIGEST_MAX_WAIT_MS, RESOLVE_DIGEST_LEASE_MS, RESOLVE_DIGEST_MAX_ATTEMPTS, RESOLVE_DIGEST_STOP_PATH, DIGEST_BODY_CHARS, DIGEST_QUOTE_CHARS, type ResolveEvent, type DigestItem, type Burst, type Digest, type DigestStatus, type ResolveDigestStore, type DigestMessage, type DigestSender, type ResolveDigestOptions, type ComposeOptions, type FlushReport } from './resolve-digest.js';
+export { createResolveDigestStore, createMemoryResolveDigestStore } from './resolve-digest-store.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment, type CommentsMode, type CommentsVisible, type CommentValue } from './comments.js';
 export { createPersonalStore, createMemoryPersonalStore, validatePersonal, personalAudioDir, MAX_PERSONAL_PER_READER, type PersonalStore, type PersonalNote, type PersonalNoteValue } from './personal-store.js';
 export { deepgramTranscriber, openaiTranscriber, type Transcriber } from './transcribe.js';
 export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey, type DeclaredSettings, type LiveSettings, type SettingsPatch } from './settings.js';
 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';

package/lib/artifacts/index.js

@@ -16,8 +16,13 @@ export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChec
 export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, EMBED_KINDS } from './simulator.js';
 export { CHECKLIST_SLOT, checklistStorageKey, checkChecklistValue, parseChecklistFence } from './checklist.js';
 export { textAnchorFrom, findText, blockId, parseAnchor, CONTEXT_CHARS, MAX_QUOTE_CHARS, BLOCK_ID } from './anchor.js';
+export { createResolveDigests, noticesFor, composeDigest, resolverName, itemsOf, emailKey, burstKey, stopToken, verifyStopToken, maskEmail, RESOLVE_DIGEST_QUIET_MS, RESOLVE_DIGEST_MAX_WAIT_MS, RESOLVE_DIGEST_LEASE_MS, RESOLVE_DIGEST_MAX_ATTEMPTS, RESOLVE_DIGEST_STOP_PATH, DIGEST_BODY_CHARS, DIGEST_QUOTE_CHARS } from './resolve-digest.js';
+export { createResolveDigestStore, createMemoryResolveDigestStore } from './resolve-digest-store.js';
 export { COMMENTS_SLOT, COMMENTS_MODES, COMMENT_TRANSCRIPTS, MAX_COMMENT_CHARS, mergeCommentsState, validateComment } from './comments.js';
 export { createPersonalStore, createMemoryPersonalStore, validatePersonal, personalAudioDir, MAX_PERSONAL_PER_READER } from './personal-store.js';
 export { deepgramTranscriber, openaiTranscriber } from './transcribe.js';
 export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_MEMO_MS, MEMO_NAME, commentAudioPath, isCommentAudioPath, personalAudioPath, isPersonalAudioPath } from './audio.js';
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey } from './settings.js';
+// 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';

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

@@ -0,0 +1,75 @@
+import type { Firestore } from 'firebase-admin/firestore';
+export type Recipient = {
+    rid: string;
+    label: string;
+    note?: string;
+    owner?: true;
+    group?: true;
+    addedAt: string;
+    revokedAt?: string;
+};
+export type RecipientsRecord = {
+    recipients: Record<string, Recipient>;
+    expireAt: string | null;
+    keep: boolean;
+    revokedAll?: string;
+};
+export type ViewDoc = {
+    artifactId: string;
+    rid: string;
+    session: string;
+    device: string;
+    firstAt: string;
+    lastAt: string;
+    activeSeconds: number;
+    plays: Record<string, number>;
+};
+export type RecipientSummary = {
+    rid: string;
+    label: string;
+    group: boolean;
+    revoked: boolean;
+    opened: boolean;
+    firstOpenAt: string | null;
+    cameBack: boolean;
+    activeSeconds: number;
+    plays: number;
+    devices: number;
+    comments: {
+        at: string;
+        text: string;
+    }[];
+};
+export interface RecipientsStore {
+    get(artifactId: string): Promise<RecipientsRecord | null>;
+    add(artifactId: string, input: {
+        label: string;
+        note?: string;
+        owner?: boolean;
+        group?: boolean;
+    }[]): Promise<Recipient[]>;
+    revoke(artifactId: string, rids: string[] | '*'): Promise<string[]>;
+    setExpiry(artifactId: string, expireAt: string | null): Promise<void>;
+    useToken(key: string, expiresAt: number): Promise<boolean>;
+    recordView(v: {
+        artifactId: string;
+        rid: string;
+        session: string;
+        device: string;
+        at: string;
+        addSeconds: number;
+        play?: string;
+    }): Promise<void>;
+    views(artifactId: string): Promise<ViewDoc[]>;
+    expiring(nowIso: string): Promise<string[]>;
+    forget(artifactId: string): Promise<void>;
+}
+export declare const CAME_BACK_MS = 3600000;
+export declare function memoryRecipientsStore(): RecipientsStore;
+export declare function createRecipientsStore(db: Firestore, base: string): RecipientsStore;
+/** One line per reader (never the owner), in the order they were added. */
+export declare function summarizeViews(rec: RecipientsRecord, views: ViewDoc[], comments: {
+    readerKey: string;
+    at: string;
+    text: string;
+}[]): RecipientSummary[];

package/lib/artifacts/recipients-store.js

@@ -0,0 +1,160 @@
+import { newRid } from './recipients.js';
+export const CAME_BACK_MS = 3_600_000;
+const LABEL_MAX = 60;
+const NOTE_MAX = 2000;
+function makeRecipients(input, taken) {
+    const at = new Date().toISOString();
+    return input.map((i) => {
+        const label = String(i.label ?? '').trim().slice(0, LABEL_MAX);
+        if (!label)
+            throw new Error('a reader needs a label');
+        let rid = newRid();
+        while (taken.has(rid))
+            rid = newRid();
+        taken.add(rid);
+        const note = typeof i.note === 'string' && i.note.trim() ? i.note.trim().slice(0, NOTE_MAX) : undefined;
+        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}) };
+    });
+}
+function revokeIn(rec, rids) {
+    const at = new Date().toISOString();
+    const hit = [];
+    for (const r of Object.values(rec.recipients)) {
+        if (r.revokedAt || (rids !== '*' && !rids.includes(r.rid)))
+            continue;
+        r.revokedAt = at;
+        hit.push(r.rid);
+    }
+    if (rids === '*')
+        rec.revokedAll = at;
+    return hit;
+}
+function addView(prev, v) {
+    const doc = prev ? { ...prev, plays: { ...prev.plays } } : { artifactId: v.artifactId, rid: v.rid, session: v.session, device: v.device, firstAt: v.at, lastAt: v.at, activeSeconds: 0, plays: {} };
+    doc.activeSeconds += Math.max(0, Math.min(60, v.addSeconds));
+    if (v.at > doc.lastAt)
+        doc.lastAt = v.at;
+    if (v.play)
+        doc.plays[v.play] = (doc.plays[v.play] ?? 0) + 1;
+    return doc;
+}
+const viewId = (artifactId, rid, session) => `${artifactId}__${rid}__${session}`;
+export function memoryRecipientsStore() {
+    const recs = new Map();
+    const views = new Map();
+    const tokens = new Set();
+    return {
+        async get(id) { const r = recs.get(id); return r ? structuredClone(r) : null; },
+        async add(id, input) {
+            const rec = recs.get(id) ?? { recipients: {}, expireAt: null, keep: false };
+            const out = makeRecipients(input, new Set(Object.keys(rec.recipients)));
+            for (const r of out)
+                rec.recipients[r.rid] = r;
+            recs.set(id, rec);
+            return structuredClone(out);
+        },
+        async revoke(id, rids) { const rec = recs.get(id); return rec ? revokeIn(rec, rids) : []; },
+        async setExpiry(id, expireAt) {
+            const rec = recs.get(id) ?? { recipients: {}, expireAt: null, keep: false };
+            rec.expireAt = expireAt;
+            rec.keep = expireAt === null;
+            recs.set(id, rec);
+        },
+        async useToken(key) { if (tokens.has(key))
+            return false; tokens.add(key); return true; },
+        async recordView(v) { const k = viewId(v.artifactId, v.rid, v.session); views.set(k, addView(views.get(k), v)); },
+        async views(id) { return [...views.values()].filter((v) => v.artifactId === id).map((v) => structuredClone(v)); },
+        async expiring(now) { return [...recs.entries()].filter(([, r]) => r.expireAt && r.expireAt <= now).map(([id]) => id); },
+        async forget(id) { recs.delete(id); for (const k of [...views.keys()])
+            if (k.startsWith(`${id}__`))
+                views.delete(k); },
+    };
+}
+export function createRecipientsStore(db, base) {
+    const recsCol = () => db.collection(`${base}Recipients`);
+    const viewsCol = () => db.collection(`${base}RecipientViews`);
+    const tokensCol = () => db.collection(`${base}RecipientTokens`);
+    const read = async (id) => {
+        const snap = await recsCol().doc(id).get();
+        if (!snap.exists)
+            return null;
+        const d = snap.data();
+        return { recipients: d.recipients ?? {}, expireAt: d.expireAt ?? null, keep: d.keep === true, ...(d.revokedAll ? { revokedAll: d.revokedAll } : {}) };
+    };
+    return {
+        get: read,
+        async add(id, input) {
+            const rec = (await read(id)) ?? { recipients: {}, expireAt: null, keep: false };
+            const out = makeRecipients(input, new Set(Object.keys(rec.recipients)));
+            // Write only the readers: a merge deep-merges the map and leaves expireAt/keep alone, so a
+            // Keep that landed after the read above is never put back to keep:false.
+            const patch = { recipients: Object.fromEntries(out.map((r) => [r.rid, r])) };
+            await recsCol().doc(id).set(patch, { merge: true });
+            return out;
+        },
+        async revoke(id, rids) {
+            const rec = await read(id);
+            if (!rec)
+                return [];
+            const hit = revokeIn(rec, rids);
+            if (!hit.length && rids !== '*')
+                return hit;
+            const patch = { recipients: Object.fromEntries(hit.map((rid) => [rid, { revokedAt: rec.recipients[rid].revokedAt }])) };
+            if (rec.revokedAll)
+                patch.revokedAll = rec.revokedAll;
+            await recsCol().doc(id).set(patch, { merge: true });
+            return hit;
+        },
+        async setExpiry(id, expireAt) {
+            await recsCol().doc(id).set({ expireAt, keep: expireAt === null }, { merge: true });
+        },
+        async useToken(key, expiresAt) {
+            // A Date is a Firestore Timestamp, which is what a TTL policy on `expireAt` reads.
+            try {
+                await tokensCol().doc(key).create({ expireAt: new Date(expiresAt) });
+                return true;
+            }
+            catch (e) {
+                if (e.code === 6)
+                    return false;
+                throw e;
+            }
+        },
+        async recordView(v) {
+            const ref = viewsCol().doc(viewId(v.artifactId, v.rid, v.session));
+            const snap = await ref.get();
+            await ref.set(addView(snap.exists ? snap.data() : undefined, v));
+        },
+        async views(id) {
+            const snap = await viewsCol().where('artifactId', '==', id).get();
+            return snap.docs.map((d) => d.data());
+        },
+        async expiring(now) {
+            const snap = await recsCol().where('expireAt', '<=', now).get();
+            return snap.docs.filter((d) => d.data().expireAt).map((d) => d.id);
+        },
+        async forget(id) {
+            await recsCol().doc(id).delete();
+            const snap = await viewsCol().where('artifactId', '==', id).get();
+            for (const d of snap.docs)
+                await d.ref.delete();
+        },
+    };
+}
+/** One line per reader (never the owner), in the order they were added. */
+export function summarizeViews(rec, views, comments) {
+    return Object.values(rec.recipients).filter((r) => !r.owner).sort((a, b) => a.addedAt.localeCompare(b.addedAt)).map((r) => {
+        const mine = views.filter((v) => v.rid === r.rid).sort((a, b) => a.firstAt.localeCompare(b.firstAt));
+        const firsts = mine.map((v) => Date.parse(v.firstAt));
+        return {
+            rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt,
+            opened: mine.length > 0,
+            firstOpenAt: mine[0]?.firstAt ?? null,
+            cameBack: firsts.length > 1 && firsts[firsts.length - 1] - firsts[0] >= CAME_BACK_MS,
+            activeSeconds: mine.reduce((n, v) => n + v.activeSeconds, 0),
+            plays: mine.reduce((n, v) => n + Object.values(v.plays).reduce((a, b) => a + b, 0), 0),
+            devices: new Set(mine.map((v) => v.device)).size,
+            comments: comments.filter((c) => c.readerKey === `r:${r.rid}`).map((c) => ({ at: c.at, text: c.text })),
+        };
+    });
+}

package/lib/artifacts/recipients.d.ts

@@ -0,0 +1,31 @@
+export declare const RID_RE: RegExp;
+export declare const RID_COOKIE_MAX_AGE = 7776000;
+export declare const VIEW_AFTER_MS = 2000;
+export declare const TOKEN_MAX_AGE_MS = 86400000;
+/** A signing secret shorter than this is treated as unset by the routes: the page shuts. */
+export declare const RECIPIENT_SECRET_MIN = 32;
+export declare function usableSecret(secret: string | null | undefined): string | undefined;
+export declare function newRid(): string;
+export declare function ridSig(secret: string, id: string, rid: string): string;
+export declare function ridLink(pageUrl: string, id: string, rid: string, secret: string): string;
+export declare function parseRidParam(v: string | null | undefined): {
+    rid: string;
+    sig: string;
+} | null;
+export declare function verifyRid(secret: string, id: string, rid: string, sig: string): boolean;
+export declare function ridCookieName(id: string): string;
+/** `<time base36>.<nonce 16 hex>.<mac 16 hex>`, minted once per server render. */
+export declare function mintRenderToken(secret: string, id: string, rid: string, now?: number): string;
+export declare function verifyRenderToken(secret: string, id: string, rid: string, token: string, now?: number): {
+    ok: true;
+    key: string;
+    expiresAt: number;
+} | {
+    ok: false;
+    why: string;
+};
+export declare function beatKey(secret: string, id: string, rid: string, session: string): string;
+/** Messaging apps' and search engines' preview fetchers. Apple's LinkPresentation presents as
+ *  `facebookexternalhit/1.1 Facebot Twitterbot/1.0`. A request with no user agent is treated as one. */
+export declare const UNFURL_AGENTS: RegExp;
+export declare function isUnfurlAgent(ua: string | null | undefined): boolean;