@supersuit/artifacts 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,78 @@
 `@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
+line is gone** (Gary, 2026-10-12: "The bottom bar speed dial shouldn't cause reflow when clicked.
+2x should be an option. And read by freedom should be removed."). Ships after 0.33.0, which was
+already tagged when these were asked for.
+
+- **No reflow.** The speed button sized itself to its label, so "1x" (30px) to "1.25x" (48px) made
+  it grow and the seek line beside it shrink by 18px on every tap. It is now a fixed 56px
+  (`w-14`), centred, never wrapping, with tabular figures, and a tap inserts nothing into the bar.
+  Measured in Chromium at 390 and 1280 wide with the bar rendered at every speed: 0.32.0's button
+  was 29.86, 47.56, 40.17 and 31.55px wide and the seek line moved with it; 0.33.1's bar, button
+  and seek line have identical boxes at every speed.
+- **2x.** The button steps 1x, 1.25x, 1.5x, 2x and back to 1x (`RATES`, exported beside
+  `nextRate`).
+- **No "Read aloud by Freedom".** The bar shows no narrator line. `PlayerBar`'s and
+  `ArtifactReader`'s `label` and `BrandPack.narratorLabel` are optional and ignored, so a host or
+  pack that still sets them compiles and shows nothing; `freedomDefault` no longer sets one. The
+  narration itself is unchanged.
+- DETECTOR: on a narrated page, a line above the seek bar reading "Read aloud by ...", or the
+  speed button changing width as you tap it, or no 2x: 0.33.0 or earlier.
+- REMEDY: update the dependency. A host may delete its own `narratorLabel` from its packs (it is
+  ignored either way). Nothing else.
+- Tests: `reader/player-bar.test.tsx` (no narrator text even when a label is passed; the 1, 1.25,
+  1.5, 2 cycle; GUARD: one class list and one node count across every speed, with `w-14`,
+  `whitespace-nowrap`, `tabular-nums` and no horizontal padding). jsdom has no layout, so the
+  measured proof is the Chromium check above, run against the built `lib` with the host's Tailwind.
+
 ## 0.33.0
 
 **A comment thread can be resolved** (Gary, 2026-10-12: "Are you going to resolve the comments at

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
@@ -791,7 +833,7 @@ refuses the query and the error names a link that creates the index. A host with
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,
-the narrator label, an optional full-page `Wrapper` and `Mark`, and an optional `share` block
+an optional full-page `Wrapper` and `Mark`, and an optional `share` block
 (a font loader and a backdrop) that draws the unfurl card. `freedomDefault` is the default look.
 Keep a pack carrying your own trademark in your own app, not in a pull request here.
 

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/brand/pack.d.ts

@@ -38,8 +38,9 @@ export type BrandPack = {
     };
     /** The small uppercase line above a title, e.g. "From Sam Rivera". */
     kicker: string;
-    /** The label under the play button, by narrator voice id. */
-    narratorLabel: (voice?: string) => string;
+    /** Unused since 0.33.1: the player bar names no narrator (it read "Read aloud by Freedom").
+     *  Optional so a pack that still sets it compiles; nothing reads it. */
+    narratorLabel?: (voice?: string) => string;
     /** Optional full-page backdrop. Receives the page as children. */
     Wrapper?: ComponentType<{
         children: ReactNode;

package/lib/brand/pack.js

@@ -11,7 +11,6 @@ export const freedomDefault = {
         body: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
     },
     kicker: 'A page from Freedom',
-    narratorLabel: () => 'Read aloud by Freedom',
     // Pages unfurl as their title on the ground colour. A pack with a backdrop of its own
     // overrides this whole field.
     share: { font: newsreader },

package/lib/reader/artifact-reader.d.ts

@@ -18,12 +18,12 @@ export declare function litWordIndex(words: WordTiming[], now: number, started:
 /** Whether a key press is the reader scrolling the page themselves. Space scrolls only outside a
  *  field that takes text. */
 export declare function isUserScrollKey(key: string, target: EventTarget | null): boolean;
-export declare function ArtifactReader({ src, words, rootId, label, accent, ground, }: {
+export declare function ArtifactReader({ src, words, rootId, accent, ground, }: {
     src: string;
     words: WordTiming[];
     rootId: string;
-    /** The line under the play button; the brand pack decides it from the voice. */
-    label: string;
+    /** Ignored since 0.33.1: the player bar names no narrator. Kept so an older caller compiles. */
+    label?: string;
     accent: string;
     ground: string;
 }): import("react").JSX.Element;

package/lib/reader/artifact-reader.js

@@ -146,8 +146,7 @@ export function isUserScrollKey(key, target) {
 }
 /** The Play from here bar's width, so it can be kept inside the screen. */
 const OFFER_WIDTH = 168;
-export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
-    const narrator = label;
+export function ArtifactReader({ src, words, rootId, accent, ground, }) {
     const audioRef = useRef(null);
     const mapRef = useRef([]);
     const litRef = useRef(null);
@@ -301,7 +300,7 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
                     follow(true);
                 }, onSeeking: () => {
                     startedRef.current = true;
-                }, onPause: () => { playingRef.current = false; setPlaying(false); }, onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), offer ? (_jsxs("div", { ref: offerRef, "data-nospeak": true, "data-play-offer": true, className: "absolute z-50 flex items-center rounded-full font-sans text-[13px] leading-none shadow-lg", style: { top: offer.top, left: offer.left, width: OFFER_WIDTH, whiteSpace: 'nowrap', background: accent, color: ground }, children: [_jsxs("button", { type: "button", "data-play-from-here": true, onClick: () => playFrom(offer.idx), className: "flex flex-1 items-center gap-1.5 rounded-l-full py-2 pl-3 pr-1 font-medium", children: [_jsx("svg", { "aria-hidden": "true", width: "10", height: "11", viewBox: "0 0 10 11", children: _jsx("path", { d: "M1 1l8 4.5L1 10z", fill: "currentColor" }) }), "Play from here"] }), _jsx("button", { type: "button", "aria-label": "Close", onClick: () => setOffer(null), className: "rounded-r-full py-2 pl-1 pr-3 text-base leading-none opacity-70", children: "\u00D7" })] })) : null, playing && !following ? (_jsx("button", { type: "button", "data-follow-voice": true, "data-nospeak": true, onClick: backToVoice, className: "fixed left-1/2 z-50 -translate-x-1/2 rounded-full px-4 py-2 text-sm font-medium shadow-lg", style: { bottom: 'calc(env(safe-area-inset-bottom, 0px) + 5.5rem)', background: accent, color: ground }, children: "Back to the voice" })) : null, _jsx(PlayerBar, { playing: playing, onToggle: toggle, label: narrator, accent: accent, ground: ground, value: t, max: dur, step: 0.1, onSeek: (v) => {
+                }, onPause: () => { playingRef.current = false; setPlaying(false); }, onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), offer ? (_jsxs("div", { ref: offerRef, "data-nospeak": true, "data-play-offer": true, className: "absolute z-50 flex items-center rounded-full font-sans text-[13px] leading-none shadow-lg", style: { top: offer.top, left: offer.left, width: OFFER_WIDTH, whiteSpace: 'nowrap', background: accent, color: ground }, children: [_jsxs("button", { type: "button", "data-play-from-here": true, onClick: () => playFrom(offer.idx), className: "flex flex-1 items-center gap-1.5 rounded-l-full py-2 pl-3 pr-1 font-medium", children: [_jsx("svg", { "aria-hidden": "true", width: "10", height: "11", viewBox: "0 0 10 11", children: _jsx("path", { d: "M1 1l8 4.5L1 10z", fill: "currentColor" }) }), "Play from here"] }), _jsx("button", { type: "button", "aria-label": "Close", onClick: () => setOffer(null), className: "rounded-r-full py-2 pl-1 pr-3 text-base leading-none opacity-70", children: "\u00D7" })] })) : null, playing && !following ? (_jsx("button", { type: "button", "data-follow-voice": true, "data-nospeak": true, onClick: backToVoice, className: "fixed left-1/2 z-50 -translate-x-1/2 rounded-full px-4 py-2 text-sm font-medium shadow-lg", style: { bottom: 'calc(env(safe-area-inset-bottom, 0px) + 5.5rem)', background: accent, color: ground }, children: "Back to the voice" })) : null, _jsx(PlayerBar, { playing: playing, onToggle: toggle, accent: accent, ground: ground, value: t, max: dur, step: 0.1, onSeek: (v) => {
                     if (audioRef.current)
                         audioRef.current.currentTime = v;
                 }, progress: `${fmt(t)} / ${fmt(dur)}`, rate: rate, onRate: () => {

package/lib/reader/player-bar.d.ts

@@ -1,8 +1,8 @@
-export declare function PlayerBar({ playing, onToggle, label, accent, ground, value, max, step, onSeek, progress, rate, onRate, }: {
+export declare function PlayerBar({ playing, onToggle, accent, ground, value, max, step, onSeek, progress, rate, onRate, }: {
     playing: boolean;
     onToggle: () => void;
-    /** The line under the play button. */
-    label: string;
+    /** Ignored since 0.33.1: the bar names no narrator. Kept so an older caller still compiles. */
+    label?: string;
     accent: string;
     ground: string;
     value: number;
@@ -14,5 +14,6 @@ export declare function PlayerBar({ playing, onToggle, label, accent, ground, va
     rate: number;
     onRate: () => void;
 }): import("react").JSX.Element;
-/** The speeds the speed button steps through, in order, wrapping back to 1. */
+/** The speeds the speed button steps through, in order, wrapping back to the first. */
+export declare const RATES: readonly [1, 1.25, 1.5, 2];
 export declare function nextRate(rate: number): number;

package/lib/reader/player-bar.js

@@ -3,14 +3,21 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // The bar at the bottom of a page that can be listened to, shared by the recorded-narration
 // reader and the browser read-aloud, so a page looks the same whichever one is speaking. It is
 // pure chrome: each reader owns its engine and hands the bar what to show and what to call.
-export function PlayerBar({ playing, onToggle, label, accent, ground, value, max, step, onSeek, progress, rate, onRate, }) {
+//
+// No narrator line (0.33.1, Gary: "read by freedom should be removed"): the bar is the play
+// button, the seek line, the progress and the speed. The speed button has a FIXED width wide enough
+// for its longest label ("1.25x"), so stepping 1x -> 1.25x -> 2x never resizes it and never shifts
+// the seek line beside it (Gary: "the bottom bar speed dial shouldn't cause reflow when clicked").
+export function PlayerBar({ playing, onToggle, accent, ground, value, max, step, onSeek, progress, rate, onRate, }) {
     return (_jsxs(_Fragment, { children: [_jsx("style", { children: `
         .artifact-word { border-radius: 3px; transition: background-color 120ms; }
         .artifact-word:hover { background: var(--a-surface-strong, rgba(255,255,255,0.08)); cursor: pointer; }
         .artifact-word-lit { background: color-mix(in srgb, ${accent} 35%, transparent); color: var(--a-strong, #fff); }
-      ` }), _jsx("div", { "data-artifact-player": true, className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: onToggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: label }), _jsx("input", { type: "range", min: 0, max: max || 0, step: step, value: Math.min(value, max || 0), onChange: (e) => onSeek(Number(e.target.value)), "aria-label": "Seek", className: "mt-1 w-full", style: { accentColor: accent } })] }), _jsx("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: progress }), _jsxs("button", { type: "button", onClick: onRate, className: "shrink-0 rounded border border-[color:var(--a-line-strong)] px-2 py-1 text-xs text-[color:var(--a-body)]", "aria-label": "Playback speed", children: [rate, "x"] })] }) }), _jsx("div", { className: "h-20", "aria-hidden": true })] }));
+      ` }), _jsx("div", { "data-artifact-player": true, className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: onToggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsx("div", { className: "min-w-0 flex-1", children: _jsx("input", { type: "range", min: 0, max: max || 0, step: step, value: Math.min(value, max || 0), onChange: (e) => onSeek(Number(e.target.value)), "aria-label": "Seek", className: "block w-full", style: { accentColor: accent } }) }), _jsx("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: progress }), _jsxs("button", { type: "button", onClick: onRate, "data-artifact-rate": true, className: "w-14 shrink-0 whitespace-nowrap rounded border border-[color:var(--a-line-strong)] py-1 text-center text-xs tabular-nums text-[color:var(--a-body)]", "aria-label": `Playback speed, ${rate}x`, children: [rate, "x"] })] }) }), _jsx("div", { className: "h-20", "aria-hidden": true })] }));
 }
-/** The speeds the speed button steps through, in order, wrapping back to 1. */
+/** The speeds the speed button steps through, in order, wrapping back to the first. */
+export const RATES = [1, 1.25, 1.5, 2];
 export function nextRate(rate) {
-    return rate >= 1.5 ? 1 : rate + 0.25;
+    const i = RATES.findIndex((r) => r > rate + 1e-9);
+    return i === -1 ? RATES[0] : RATES[i];
 }

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({
@@ -410,7 +410,7 @@ export function createArtifactRoutes(config) {
                         return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, simulator: config.simulatorEmbed ? { embed: config.simulatorEmbed } : undefined, messages: config.messagesEmbed ? { embed: config.messagesEmbed } : undefined }) }));
-                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
+                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));
     }

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.0",
+  "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",