@supersuit/artifacts 0.33.1 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 `@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.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

@@ -745,6 +745,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

package/lib/artifacts/index.d.ts

@@ -16,6 +16,8 @@ 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';

package/lib/artifacts/index.js

@@ -16,6 +16,8 @@ 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';

package/lib/artifacts/resolve-digest-store.d.ts

@@ -0,0 +1,8 @@
+import type { Firestore } from 'firebase-admin/firestore';
+import { type Burst, type Digest, type ResolveDigestStore } from './resolve-digest.js';
+export declare function createResolveDigestStore(db: Firestore, base: string): ResolveDigestStore;
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export declare function createMemoryResolveDigestStore(): ResolveDigestStore & {
+    digests(): Digest[];
+    bursts(): Burst[];
+};

package/lib/artifacts/resolve-digest-store.js

@@ -0,0 +1,194 @@
+// Where resolution digests wait and are recorded (0.34.0). Beside the readers' state, per tenant:
+//
+//   <base>ResolveBursts/<page>__<emailKey>   one reader's open burst on one page; deleted when claimed
+//   <base>ResolveDigests/<burstId>           a claimed burst, frozen: pending, then sent, skipped or failed
+//   <base>ResolveStops/<page>__<emailKey>    the reader followed the stop link for that page
+//
+// Items are stored as a JSON string (`json`), as the state store does, so a quote or a body can
+// never trip Firestore's rules on nested values. Every query is single-field (Firestore indexes
+// those itself), so no composite index is needed.
+//
+// The Firestore implementation has no emulator test here; it is proven on the live host after each
+// release that changes it. The memory implementation carries the contract tests.
+import { randomUUID } from 'node:crypto';
+import { burstKey, itemsOf } from './resolve-digest.js';
+const toBurst = (key, d) => { const { json, ...rest } = d; return { key, ...rest, threads: JSON.parse(json) }; };
+const toDigest = (id, d) => { const { json, ...rest } = d; return { id, ...rest, items: JSON.parse(json) }; };
+const isDue = (b, quietBefore, maxBefore) => b.lastAt <= quietBefore || b.firstAt <= maxBefore;
+const digestOf = (b, now) => ({
+    id: b.burstId, artifactId: b.artifactId, email: b.email, name: b.name, title: b.title, url: b.url,
+    items: itemsOf(b.threads), status: 'pending', createdAt: now, leaseUntil: now, attempts: 0,
+});
+const stopId = (artifactId, key) => `${artifactId}__${key}`;
+export function createResolveDigestStore(db, base) {
+    const bursts = () => db.collection(`${base}ResolveBursts`);
+    const digests = () => db.collection(`${base}ResolveDigests`);
+    const stops = () => db.collection(`${base}ResolveStops`);
+    return {
+        async add({ artifactId, email, name, title, url, threadId, items, at }) {
+            const ref = bursts().doc(burstKey(artifactId, email));
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                const cur = snap.exists ? toBurst(ref.id, snap.data()) : null;
+                const threads = { ...(cur?.threads ?? {}), [threadId]: items };
+                const next = {
+                    burstId: cur?.burstId ?? randomUUID(), artifactId, email, name: name ?? cur?.name ?? null, title, url,
+                    firstAt: cur?.firstAt ?? at, lastAt: cur && cur.lastAt > at ? cur.lastAt : at, json: JSON.stringify(threads),
+                };
+                tx.set(ref, next);
+            });
+        },
+        async dropThread(artifactId, threadId) {
+            const docs = (await bursts().where('artifactId', '==', artifactId).get()).docs;
+            let changed = 0;
+            for (const d of docs) {
+                await db.runTransaction(async (tx) => {
+                    const snap = await tx.get(d.ref);
+                    if (!snap.exists)
+                        return;
+                    const b = toBurst(d.id, snap.data());
+                    if (!(threadId in b.threads))
+                        return;
+                    delete b.threads[threadId];
+                    changed++;
+                    if (!Object.keys(b.threads).length)
+                        tx.delete(d.ref);
+                    else
+                        tx.update(d.ref, { json: JSON.stringify(b.threads) });
+                });
+            }
+            return changed;
+        },
+        async due(quietBefore, maxBefore, limit) {
+            const [quiet, old] = await Promise.all([
+                bursts().where('lastAt', '<=', quietBefore).limit(limit).get(),
+                bursts().where('firstAt', '<=', maxBefore).limit(limit).get(),
+            ]);
+            const out = new Map();
+            for (const d of [...quiet.docs, ...old.docs])
+                out.set(d.id, toBurst(d.id, d.data()));
+            return [...out.values()].slice(0, limit);
+        },
+        async claim({ key, burstId, quietBefore, maxBefore, now }) {
+            const ref = bursts().doc(key);
+            return db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                if (!snap.exists)
+                    return null;
+                const b = toBurst(key, snap.data());
+                if (b.burstId !== burstId || !isDue(b, quietBefore, maxBefore))
+                    return null;
+                const dref = digests().doc(b.burstId);
+                if ((await tx.get(dref)).exists) {
+                    tx.delete(ref);
+                    return null;
+                }
+                const d = digestOf(b, now);
+                const { id: _id, items, ...rest } = d;
+                tx.create(dref, { ...rest, json: JSON.stringify(items) });
+                tx.delete(ref);
+                return d;
+            });
+        },
+        async pending(now, limit) {
+            // Equality only, so no composite index; the lease filter runs here. Pending is small.
+            const docs = (await digests().where('status', '==', 'pending').limit(limit * 4).get()).docs;
+            return docs.map((d) => toDigest(d.id, d.data()))
+                .filter((d) => d.leaseUntil <= now)
+                .sort((x, y) => x.createdAt.localeCompare(y.createdAt))
+                .slice(0, limit);
+        },
+        async lease(id, now, until) {
+            const ref = digests().doc(id);
+            return db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                if (!snap.exists)
+                    return null;
+                const d = toDigest(id, snap.data());
+                if (d.status !== 'pending' || d.leaseUntil > now)
+                    return null;
+                tx.update(ref, { leaseUntil: until, attempts: d.attempts + 1 });
+                return { ...d, leaseUntil: until, attempts: d.attempts + 1 };
+            });
+        },
+        async finish(id, { status, at, reason, providerId }) {
+            await digests().doc(id).update({
+                status, ...(status === 'sent' ? { sentAt: at } : {}), ...(reason ? { reason } : {}), ...(providerId ? { providerId } : {}),
+            });
+        },
+        async release(id, retryAt) {
+            await digests().doc(id).update({ leaseUntil: retryAt });
+        },
+        async stop(artifactId, key, at) {
+            await stops().doc(stopId(artifactId, key)).set({ artifactId, emailKey: key, at });
+        },
+        stopped: async (artifactId, key) => (await stops().doc(stopId(artifactId, key)).get()).exists,
+    };
+}
+/** The same contract in memory: for tests, and for hosts' own tests. */
+export function createMemoryResolveDigestStore() {
+    const bursts = new Map();
+    const digests = new Map();
+    const stopSet = new Set();
+    return {
+        async add({ artifactId, email, name, title, url, threadId, items, at }) {
+            const key = burstKey(artifactId, email);
+            const cur = bursts.get(key);
+            bursts.set(key, {
+                key, burstId: cur?.burstId ?? randomUUID(), artifactId, email, name: name ?? cur?.name ?? null, title, url,
+                firstAt: cur?.firstAt ?? at, lastAt: cur && cur.lastAt > at ? cur.lastAt : at,
+                threads: { ...(cur?.threads ?? {}), [threadId]: structuredClone(items) },
+            });
+        },
+        async dropThread(artifactId, threadId) {
+            let changed = 0;
+            for (const b of [...bursts.values()].filter((b) => b.artifactId === artifactId && threadId in b.threads)) {
+                delete b.threads[threadId];
+                changed++;
+                if (!Object.keys(b.threads).length)
+                    bursts.delete(b.key);
+            }
+            return changed;
+        },
+        due: async (quietBefore, maxBefore, limit) => [...bursts.values()].filter((b) => isDue(b, quietBefore, maxBefore)).slice(0, limit).map((b) => structuredClone(b)),
+        async claim({ key, burstId, quietBefore, maxBefore, now }) {
+            const b = bursts.get(key);
+            if (!b || b.burstId !== burstId || !isDue(b, quietBefore, maxBefore))
+                return null;
+            bursts.delete(key);
+            if (digests.has(b.burstId))
+                return null;
+            const d = digestOf(b, now);
+            digests.set(d.id, d);
+            return structuredClone(d);
+        },
+        pending: async (now, limit) => [...digests.values()].filter((d) => d.status === 'pending' && d.leaseUntil <= now)
+            .sort((x, y) => x.createdAt.localeCompare(y.createdAt)).slice(0, limit).map((d) => structuredClone(d)),
+        async lease(id, now, until) {
+            const d = digests.get(id);
+            if (!d || d.status !== 'pending' || d.leaseUntil > now)
+                return null;
+            d.leaseUntil = until;
+            d.attempts++;
+            return structuredClone(d);
+        },
+        async finish(id, { status, at, reason, providerId }) {
+            const d = digests.get(id);
+            if (!d)
+                return;
+            d.status = status;
+            if (status === 'sent')
+                d.sentAt = at;
+            if (reason)
+                d.reason = reason;
+            if (providerId)
+                d.providerId = providerId;
+        },
+        async release(id, retryAt) { const d = digests.get(id); if (d)
+            d.leaseUntil = retryAt; },
+        async stop(artifactId, key) { stopSet.add(stopId(artifactId, key)); },
+        stopped: async (artifactId, key) => stopSet.has(stopId(artifactId, key)),
+        digests: () => [...digests.values()].map((d) => structuredClone(d)),
+        bursts: () => [...bursts.values()].map((b) => structuredClone(b)),
+    };
+}

package/lib/artifacts/resolve-digest.d.ts

@@ -0,0 +1,236 @@
+import type { CommentResolution } from './comments.js';
+import type { StateEntry } from './state-store.js';
+/** A burst closes after this long with no new resolution for that reader on that page. */
+export declare const RESOLVE_DIGEST_QUIET_MS: number;
+/** A burst that keeps growing is sent anyway once its first resolution is this old. */
+export declare const RESOLVE_DIGEST_MAX_WAIT_MS: number;
+/** A digest leased for sending and not recorded as sent is retried after this long. */
+export declare const RESOLVE_DIGEST_LEASE_MS: number;
+/** After this many attempts a digest is recorded as failed and never tried again. */
+export declare 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 declare const DIGEST_BODY_CHARS = 280;
+export declare const DIGEST_QUOTE_CHARS = 160;
+/** Where the stop link lands, under the host's origin. */
+export declare const RESOLVE_DIGEST_STOP_PATH = "/api/resolve-digest/stop";
+/** What the resolve route tells a host after a thread is resolved or reopened. */
+export type ResolveEvent = {
+    artifactId: string;
+    title: string;
+    /** The page's address, e.g. https://artifacts.example.com/abc23456. */
+    url: string;
+    /** The thread: its top comment's id and every comment in it, top comment first, oldest first. */
+    thread: {
+        id: string;
+        entries: StateEntry[];
+    };
+    /** The resolution just recorded, or null when the thread was reopened. */
+    resolution: CommentResolution | null;
+    /** Who did it: a signed-in owner or admin (their email), or the publish key or a publisher pass. */
+    actor: {
+        email?: string;
+        publisher: boolean;
+    };
+    at: string;
+};
+/** One of a reader's comments in a resolved thread, as the email lists it. */
+export type DigestItem = {
+    entryId: string;
+    threadId: string;
+    /** The passage the thread is pinned to, trimmed; null for a box drawn over the page. */
+    quote: string | null;
+    /** The reader's comment, trimmed. A voice memo with no text says so. */
+    body: string;
+    note: string | null;
+    by: string;
+    resolvedAt: string;
+};
+/** A reader's open burst on one page: the threads resolved so far, waiting for the quiet window. */
+export type Burst = {
+    key: string;
+    burstId: string;
+    artifactId: string;
+    email: string;
+    name: string | null;
+    title: string;
+    url: string;
+    firstAt: string;
+    lastAt: string;
+    threads: Record<string, DigestItem[]>;
+};
+export type DigestStatus = 'pending' | 'sent' | 'skipped' | 'failed';
+/** A claimed burst, frozen: what one email says. Its id is the burst's id, and the idempotency key. */
+export type Digest = {
+    id: string;
+    artifactId: string;
+    email: string;
+    name: string | null;
+    title: string;
+    url: string;
+    items: DigestItem[];
+    status: DigestStatus;
+    createdAt: string;
+    leaseUntil: string;
+    attempts: number;
+    sentAt?: string;
+    reason?: string;
+    providerId?: string;
+};
+export interface ResolveDigestStore {
+    /** Put this thread's items into the reader's open burst on this page (replacing the thread's
+     *  earlier items, if it was resolved again), opening a burst when none is waiting. */
+    add(input: {
+        artifactId: string;
+        email: string;
+        name: string | null;
+        title: string;
+        url: string;
+        threadId: string;
+        items: DigestItem[];
+        at: string;
+    }): Promise<void>;
+    /** Take this thread out of every burst still waiting on this page (it was reopened). A burst
+     *  left with no thread is deleted. Returns how many bursts changed. */
+    dropThread(artifactId: string, threadId: string): Promise<number>;
+    /** Bursts whose last resolution is at or before `quietBefore`, or whose first is at or before
+     *  `maxBefore`. */
+    due(quietBefore: string, maxBefore: string, limit: number): Promise<Burst[]>;
+    /** Atomically turn one due burst into a pending digest and delete the burst. Null when the
+     *  burst is gone, was replaced, or is no longer due (a resolution landed since `due`). */
+    claim(input: {
+        key: string;
+        burstId: string;
+        quietBefore: string;
+        maxBefore: string;
+        now: string;
+    }): Promise<Digest | null>;
+    /** Pending digests whose lease has run out (or was never taken), oldest first. */
+    pending(now: string, limit: number): Promise<Digest[]>;
+    /** Atomically take the lease on one pending digest whose lease has run out: sets `leaseUntil`
+     *  and counts an attempt. Null when it is not pending or another run holds it. */
+    lease(id: string, now: string, until: string): Promise<Digest | null>;
+    /** Record how a leased digest ended. */
+    finish(id: string, outcome: {
+        status: Exclude<DigestStatus, 'pending'>;
+        at: string;
+        reason?: string;
+        providerId?: string;
+    }): Promise<void>;
+    /** A send failed: leave it pending, retried once `retryAt` passes. */
+    release(id: string, retryAt: string): Promise<void>;
+    /** The reader followed the stop link for this page. Keyed by `emailKey`, so no address is stored. */
+    stop(artifactId: string, emailKey: string, at: string): Promise<void>;
+    stopped(artifactId: string, emailKey: string): Promise<boolean>;
+}
+/** One email, ready for a provider. `idempotencyKey` is the same on every retry of one digest. */
+export type DigestMessage = {
+    to: string;
+    subject: string;
+    text: string;
+    html: string;
+    /** List-Unsubscribe and List-Unsubscribe-Post (RFC 8058), pointing at the stop link. */
+    headers: Record<string, string>;
+    idempotencyKey: string;
+};
+/** The host's email provider. Throw to have the digest retried on the next run. */
+export type DigestSender = (m: DigestMessage) => Promise<{
+    id?: string;
+} | void>;
+/** A stable, non-reversible key for an address, used in document ids and stop links. */
+export declare function emailKey(email: string): string;
+export declare const burstKey: (artifactId: string, email: string) => string;
+/** 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 declare function noticesFor(event: ResolveEvent, o?: {
+    ownerEmail?: string;
+    admins?: readonly string[];
+}): {
+    email: string;
+    name: string | null;
+    items: DigestItem[];
+}[];
+/** A digest's items in the order the email lists them: by when each thread was resolved. */
+export declare function itemsOf(threads: Record<string, DigestItem[]>): DigestItem[];
+/** `<artifactId>.<emailKey>.<signature>`: names the page and the reader (by key, not address). */
+export declare function stopToken(secret: string, artifactId: string, email: string): string;
+export declare function verifyStopToken(secret: string | undefined, token: string | null | undefined): {
+    artifactId: string;
+    emailKey: string;
+} | null;
+/** 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 declare function resolverName(items: DigestItem[], fallback: string): string;
+export type ComposeOptions = {
+    /** Whose pages these are, as the email signs off: "Example Co". */
+    brandName: string;
+    /** Who "the publisher" is when an agent resolved: the owner's first name. Default `brandName`. */
+    ownerName?: string;
+    stopUrl: string;
+};
+/** The digest as an email. Plain words, no em dashes, every comment linked to its place. */
+export declare function composeDigest(d: Pick<Digest, 'name' | 'title' | 'url' | 'items'>, o: ComposeOptions): {
+    subject: string;
+    text: string;
+    html: string;
+};
+/** An address as a report shows it: enough to recognise, not enough to collect. */
+export declare function maskEmail(email: string): string;
+export type ResolveDigestOptions = {
+    store: ResolveDigestStore;
+    send: DigestSender;
+    /** Signs stop links. Read at call time. Without it nothing is queued and nothing is sent, since
+     *  every digest must carry a working stop link. */
+    secret: () => string | undefined;
+    /** The host's origin, e.g. https://artifacts.example.com. */
+    siteUrl: string;
+    brandName: string;
+    ownerName?: string;
+    /** Never notified about their own comments, like the person resolving. */
+    ownerEmail?: string;
+    admins?: readonly string[];
+    quietMs?: number;
+    maxWaitMs?: number;
+    /** The page's title for the stop page. Optional. */
+    titleOf?: (artifactId: string) => Promise<string | null>;
+    stopPath?: string;
+};
+export type FlushReport = {
+    now: string;
+    dryRun: boolean;
+    due: number;
+    claimed: number;
+    sent: {
+        id: string;
+        to: string;
+        subject: string;
+        comments: number;
+    }[];
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    /** dryRun only: what a real run would send now. */
+    wouldSend?: {
+        to: string;
+        subject: string;
+        comments: number;
+        artifactId: string;
+        stopped: boolean;
+    }[];
+};
+export declare function createResolveDigests(o: ResolveDigestOptions): {
+    onResolve: (event: ResolveEvent) => Promise<void>;
+    flush: (opts?: {
+        now?: Date;
+        dryRun?: boolean;
+        limit?: number;
+    }) => Promise<FlushReport>;
+    STOP: (req: Request) => Promise<Response>;
+    stopUrl: (artifactId: string, email: string) => string | null;
+    message: (d: Digest) => DigestMessage | null;
+};

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/routes/artifacts.d.ts

@@ -8,6 +8,7 @@ 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,6 +93,11 @@ 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

package/lib/routes/artifacts.js

@@ -89,7 +89,7 @@ export function createArtifactRoutes(config) {
     const stateRoutes = createStateRoutes({
         store, state: config.state, readers: config.readers, readerSecret, publishKey: config.publishKey,
         publisherSecret: config.publisherSecret, publisherHost: config.publisherHost, pageUrl, signInOrigin, siteUrl,
-        clientIp: config.clientIp, ownerEmail: config.ownerEmail, admins: config.admins, audioUrl,
+        clientIp: config.clientIp, ownerEmail: config.ownerEmail, admins: config.admins, audioUrl, onResolve: config.onResolve,
     });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
     const voiceRoutes = createVoiceRoutes({

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

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { type StateStore } from '../artifacts/state-store.js';
 import type { ArtifactStore } from '../artifacts/store.js';
 import type { ReadersStore } from '../artifacts/readers-store.js';
+import type { ResolveEvent } from '../artifacts/resolve-digest.js';
 export declare const ANON_COOKIE = "artifact_anon";
 /** The most comments one feed answer carries. A caller that gets this many moves its cursor to the
  *  last row's `at` and asks again. */
@@ -39,6 +40,10 @@ export type StateRoutesContext = {
     /** A signed URL to play a comment's recording. Called only for `comments/` paths, and only for
      *  comments the asker is already being shown. Without it a recording has no play control. */
     audioUrl?: (id: string, path: string) => Promise<string>;
+    /** Told after a thread is resolved or reopened (0.34.0), with the whole thread and who did it.
+     *  `createResolveDigests(...).onResolve` turns it into resolution emails. Awaited, and anything
+     *  it throws is logged and swallowed: a broken mailer never costs the owner their resolve. */
+    onResolve?: (event: ResolveEvent) => void | Promise<void>;
 };
 type Params = {
     params: Promise<{

package/lib/routes/state-routes.js

@@ -396,6 +396,7 @@ export function createStateRoutes(ctx) {
     async function RESOLVE(req, { params }) {
         const publisher = isPublisherAuthed(req, ctx);
         let by = 'the publisher';
+        let actorEmail;
         if (!publisher) {
             const reader = verifyGrant(ctx.readerSecret(), req.cookies.get(GRANT_COOKIE)?.value);
             if (!reader)
@@ -409,6 +410,7 @@ export function createStateRoutes(ctx) {
             if (!/^application\/json\b/i.test(req.headers.get('content-type') ?? ''))
                 return json({ error: 'send JSON' }, 415);
             by = reader.name?.trim().split(/\s+/)[0] || 'the owner';
+            actorEmail = reader.email;
         }
         const raw = await req.text();
         if (Buffer.byteLength(raw, 'utf8') > 4096)
@@ -461,6 +463,19 @@ export function createStateRoutes(ctx) {
         const r = await ctx.state.setResolved({ artifactId: id, slot: COMMENTS_SLOT, entryId: root.id, resolved: resolution });
         if (!r)
             return json({ error: 'no comment with that id on this page' }, 404);
+        if (ctx.onResolve) {
+            const thread = [r, ...[...all.values()].filter((e) => e.value.parent === root.id)
+                    .sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id))];
+            try {
+                await ctx.onResolve({
+                    artifactId: id, title: a.title, url: ctx.pageUrl(id), thread: { id: root.id, entries: thread }, resolution,
+                    actor: { publisher, ...(actorEmail ? { email: actorEmail } : {}) }, at: resolution?.at ?? new Date().toISOString(),
+                });
+            }
+            catch (err) {
+                console.error('onResolve failed', err);
+            }
+        }
         return json({ id, entry: root.id, resolved: resolution });
     }
     return { STATE_GET, STATE_POST, RESPONSES, COMMENTS_FEED, RESOLVE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",