@supersuit/artifacts 0.49.0 → 0.52.0

package/CHANGELOG.md

@@ -3,6 +3,95 @@
 `@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.52.0 (2026-10-25)
+
+**A render before the send is never counted as the reader opening the page.** A per-reader page
+reported its reader as having opened it (first open 20:32:34Z, 647 active seconds) a minute before
+the text carrying his link was sent (20:33:35Z). The page had been rendered from his link on the
+sender's side while the send waited on approval, in a real browser, so the unfurl filter could not
+see it and the render token treated it as a reader.
+
+- `POST /recipients` takes `sent: { rids: [rid] or '*', at?: ISO }` and answers `sent`, the rids
+  marked. Earliest mark wins; never the owner; a future time is refused (400).
+- `GET /views` counts only sessions on devices that had not rendered the link before `sentAt`, and
+  reports the rest as `beforeSend: { sessions, devices, activeSeconds, firstAt }`; both lines and
+  `GET /recipients` carry `sentAt`. A reader with no `sentAt` reads exactly as before.
+- `RecipientsStore.setSent` (optional; the memory and Firestore stores have it).
+- DETECTOR: a reader whose `firstOpenAt` is earlier than the time the text carrying their link was
+  sent. Any host on 0.51.x has no way to tell such a render from the reader.
+- REMEDY: bump, then have the sender mark each per-reader link sent once delivery is confirmed
+  (Supersuit's send-message does this from the next release). For a page already wrong, mark the
+  link with the true send time: the views reclassify, nothing is deleted.
+- Tests: recipients-store.test.ts (setSent on both stores; summarizeViews leaves out a pre-send
+  session and every later session on its device, keeps the reader's own) and
+  recipients-api.test.tsx (the `sent` mark, its refusals, and the views it changes).
+
+## 0.51.0 (2026-10-23)
+
+**Every page's session replay now masks all text and all inputs, not only a gated page's.** Since
+0.50.0 a public, password or per-reader page recorded its replays with every word readable, so a
+page shared by key or by link sat in full in the analytics provider's copy. `posthog.init` now gets
+`session_recording: { maskAllInputs: true, maskTextSelector: '*' }` on every kind (these client
+options override the PostHog project's own masking setting), and `mask_all_text: true` so
+autocapture stops collecting a clicked element's text. There is no opt-out. Replays still show where
+the reader went, how far and how fast.
+
+- `posthogInitOptions(plan)` and `RECORDING_MASK`, exported: the exact init options, pure.
+- DETECTOR: open a replay of a public or per-reader page in PostHog; readable page text means the
+  host is on 0.50.x. Autocapture events carrying `$el_text` from page body are the same leak.
+- REMEDY: bump. Replays recorded before the bump keep their text; delete them in PostHog (filter
+  recordings by the `artifact_id` / `page_kind` event properties, then delete), and consider
+  deleting old autocapture events' `$el_text` the same way.
+- Tests: page-analytics-recording.test.tsx (mounts the component against a stand-in posthog-js and
+  holds every page kind's init options to the mask; red on 0.50.0 for public, password and
+  per-reader).
+
+**A hub can no longer go live with a dead comments feed without being told.** The feed's Firestore
+query needs a composite index (`<base>State`: `slot` ASC, `at` ASC) that 0.13.0 told hubs to create
+by hand; a hub that never did answered every `GET /api/comments` with a bare 500 for five days.
+
+- `firestoreIndexesFor(stateBases)`: every composite index the Firestore stores need, as the
+  contents of `firestore.indexes.json`, so a hub deploys it with `firebase deploy --only
+  firestore:indexes` and tests that its committed file still carries it.
+- `COMMENTS_FEED` answers **503** `{ error: 'missing_firestore_index', index, create }` (create is
+  Firestore's link) instead of throwing. Any other error still throws.
+- New route `HEALTH` (`GET /api/health`, no key): probes the feed query for one comment after now;
+  200 `{ ok: true, checks }`, or 503 naming the missing index. Another failure reports
+  `query_failed` without its message.
+- `missingIndexOf(err)` and `COMMENTS_FEED_INDEX`, exported for a host's own checks.
+- DETECTOR: `curl <hub>/api/health` is 404 (no route), or 503 with `missing_firestore_index`.
+- REMEDY: bump; add `app/api/health/route.ts` delegating GET to `HEALTH`; commit
+  `firestore.indexes.json` from `firestoreIndexesFor([...your state bases])` with `firebase.json`
+  pointing at it, add a test that the file contains it, and run `firebase deploy --only
+  firestore:indexes --project <project>` once.
+- Tests: firestore-indexes.test.ts, and six in comments-feed.test.tsx (503 with the link, other
+  errors still throw, HEALTH red/green/other-failure/no-store).
+
+## 0.50.0 (2026-10-19)
+
+**Product analytics, with video of each visit.** A host that passes `analytics: { posthogKey,
+posthogHost?, tenant? }` to `createArtifactRoutes` gets PostHog on its pages: session replay (text
+fields masked, PostHog's default), heatmaps, autocapture, and `$pageleave` with scroll depth, plus
+two kinds of reading PostHog cannot see on its own: `section_viewed` (the heading's id and text and
+the visible seconds spent in it, timed by the contents rail's own rule, now `currentSection` in
+`toc-spy.tsx`) and `narration_play` / `narration_pause` / `narration_complete` (the narration
+`<audio>` now carries `data-artifact-narration`). Every event carries `artifact_id`, `page_kind`
+and `tenant`. The rules live in one pure function, `analyticsPlan` (`reader/analytics-plan.ts`):
+no key, no script at all (posthog-js is imported only by `PageAnalytics`, after mount); never the
+owner or an admin, signed in, previewing `?as=reader`, or on the owner's own per-reader link; never
+a link-preview fetcher; never a past version. A reader is identified only where the page already
+knows them: a gated page by the signed-in email, a per-reader link as `recipient:<rid>` with its
+label. Public and password pages stay anonymous, even for a signed-in reader. A gated page also
+masks all text in its replays, because its body is confidential and a replay is a copy of it.
+
+- DETECTOR: a host that wants analytics has none; with no `analytics` config nothing changes and
+  no analytics code is downloaded.
+- REMEDY: pass `analytics` per tenant (a public `phc_` project key). Turn on session replay and
+  heatmaps in the PostHog project's settings, which is where PostHog switches them on.
+- Tests: analytics-plan.test.ts (no key, owner, bot, anonymous kinds, gated and per-reader
+  identity), page-analytics-mount.test.tsx (where it mounts on real routes, and as whom),
+  page-analytics.test.ts (section timing, narration events).
+
 ## 0.49.0 (2026-10-16)
 
 **The default look is Supersuit's, the Maison.** The product the default pack is named for became

package/README.md

@@ -85,6 +85,7 @@ The rest, each exporting the named handler(s) from `artifacts`:
 | `app/api/reader/track/route.ts` | `POST` = `TRACK` |
 | `app/api/artifacts/[id]/resolve/route.ts` | `POST` = `RESOLVE` (see [resolving a thread](#resolving-a-thread)) |
 | `app/api/comments/route.ts` | `GET` = `COMMENTS_FEED` (see [the comments feed](#the-comments-feed)) |
+| `app/api/health/route.ts` | `GET` = `HEALTH` (see [the comments feed](#the-comments-feed)) |
 
 Pages live at `/<id>` by default. Mounting inside a larger site, pass `pagePrefix: '/a/'` and put
 the page at `app/a/[id]/`. One deployment can serve many sites: build one set of routes per
@@ -990,8 +991,21 @@ export function GET(request: NextRequest) { return artifacts.COMMENTS_FEED(reque
 
 On Firestore (`createStateStore`) the query is one range scan over `<base>State` and needs a
 composite index: **`slot` ascending, `at` ascending**, collection scope. Without it Firestore
-refuses the query and the error names a link that creates the index. A host with its own
-`StateStore` implements `slotSince(slot, after, limit)`; without it the feed answers 501.
+refuses the query and the feed answers **503** `{ error: 'missing_firestore_index', index, create }`,
+`create` being Firestore's link that makes the index. A host with its own `StateStore` implements
+`slotSince(slot, after, limit)`; without it the feed answers 501.
+
+**Ship the index as a file, not a step to remember.** `firestoreIndexesFor(bases)` returns every
+composite the stores need, for the bases you pass `createStateStore`, in the shape of
+`firestore.indexes.json`. Commit it, point `firebase.json` at it
+(`{ "firestore": { "indexes": "firestore.indexes.json" } }`), deploy it with
+`firebase deploy --only firestore:indexes --project <project>`, and keep a test asserting the
+committed file still contains `firestoreIndexesFor(...)`, so a release that needs a new index
+fails your tests rather than your readers.
+
+**`HEALTH`** (`GET /api/health`, no key) runs the feed's query for one comment after now and
+answers 200 `{ ok: true, checks }`, or 503 naming the missing index. Call it after every deploy;
+a hub with no index went five days answering every feed request with a bare 500.
 
 ## Per-reader links
 
@@ -1023,8 +1037,8 @@ Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `
 | Route | Who | What |
 |---|---|---|
 | `GET /api/artifacts/<id>/recipients` | publish key | Every reader, with the working link for each |
-| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group?, closes? }], revoke?: [rid] or '*', expires?: ISO time or null, closes?: { rids: [rid] or '*', at: ISO time or null } }`. `add` answers each new reader's link; `expires: null` is Keep; `closes` sets, moves or clears a reader's feedback window |
-| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments. Each comment is `{ id, parent, at, text }` (see Comment ids in /views). A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
+| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group?, closes? }], revoke?: [rid] or '*', expires?: ISO time or null, closes?: { rids: [rid] or '*', at: ISO time or null }, sent?: { rids: [rid] or '*', at?: ISO time } }`. `add` answers each new reader's link; `expires: null` is Keep; `closes` sets, moves or clears a reader's feedback window; `sent` records when links reached their readers (see A render before the send) |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments, `sentAt` and `beforeSend`. Each comment is `{ id, parent, at, text }` (see Comment ids in /views). A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
 | `POST /api/artifacts/<id>/seen` | the page itself (public) | The reader's own signal, below |
 
 Config, both on `createArtifactRoutes`: `recipients` (a store from `createRecipientsStore(db, '<collection path>')`, or `memoryRecipientsStore()` in tests) and `recipientSecret`, a function returning the signing secret, read on every request. A secret shorter than 32 characters is treated as unset: per-reader pages stay shut and the routes answer 404 or 501. Signing with an empty secret throws.
@@ -1035,6 +1049,27 @@ The `Page` route must stay `force-dynamic` (the package's `dynamic` export says
 
 A view is the page rendered in a real browser, visible, for at least 2 seconds. The page then sends one signal carrying a single-use render token minted for that render; the token is spent on first use and expires after a day. Known unfurl fetchers (and any request with no user agent) are ignored, and so is a signal for a revoked or expired reader. The owner's own opens record zero. After the first signal the page sends a beat every few seconds while it stays visible (and a final one on hide, by `sendBeacon`), and a play signal when a clip starts. A signed-in owner or admin opens the page with no link and no tracking, so test a reader's link in a signed-out browser, never in the browser you are signed in to.
 
+### A render before the send (0.52.0)
+
+A view proves a browser rendered the link, not that the reader did. On 2026-10-25 a reader was
+reported as having opened a page a minute before the text carrying his link was sent: the link had
+been opened on the sender's side while the send waited on approval, in a real browser that ran the
+page, so no user-agent rule could have told it apart.
+
+So the sender records the send: `POST /recipients` with `sent: { rids, at }` (`rids` a list or
+`'*'` for every reader but the owner; `at` an ISO time, default now on the host's clock, never in
+the future). The earliest mark stands, so a resend never hides opens between the two sends, and an
+earlier time corrects a mark written late. `sent` answers the reader ids it changed. A host with
+its own `RecipientsStore` needs `setSent`; without it the route answers 501 to a `sent` mark.
+
+`GET /views` then counts, for that reader, only sessions on devices that had not rendered the link
+before `sentAt`: a session that began earlier was not the reader's, nor is any later session on the
+same device. Those are reported apart as `beforeSend: { sessions, devices, activeSeconds, firstAt }`
+(null when no send was recorded). Nothing is refused at record time, so marking a send after the
+fact reclassifies what is already there. A link with no `sentAt` is read exactly as before. The
+cost, stated: a reader who opens the link within the seconds between delivery and the sender's
+mark is counted as before-send; senders mark as soon as delivery is confirmed.
+
 ### Expiry
 
 `expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. With a private bucket configured it deletes from both buckets. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.
@@ -1174,6 +1209,24 @@ export const config = { matcher: ['/:id([a-z0-9]{8})'] }
 
 Any per-reader page served to a known unfurl fetcher (or a request with no user agent) carries its text only: no media, no signed URL, no reader's note, no cookie. `readHeader` on `createArtifactRoutes` reads the agent (default through `next/headers`). `DELETE /api/artifacts/<id>` removes the page's files from both buckets (`deletePage`), then its readers, their notes and views and every comment, before the record, and keeps the record (502) if the files could not go, so it can be run again.
 
+## Product analytics (`analytics`)
+
+Pass `analytics: { posthogKey: 'phc_...', posthogHost?: 'https://us.i.posthog.com', tenant?: 'name' }`
+to `createArtifactRoutes` and the host's pages record visits in PostHog: session replay, heatmaps,
+autocapture, scroll depth on leave, `section_viewed` (heading id, text, seconds) and
+`narration_play` / `narration_pause` / `narration_complete`. Without it no page loads any analytics
+code. Switch session replay and heatmaps on in the PostHog project as well.
+
+Who is recorded, and as whom (`analyticsPlan`, `src/reader/analytics-plan.ts`):
+
+- Never the owner or an admin (signed in, previewing `?as=reader`, or on the owner's own per-reader
+  link), never a link-preview fetcher, never a past version.
+- A gated page identifies the signed-in reader by email.
+- A per-reader link identifies as `recipient:<rid>` with the label the publisher gave it.
+- A public or password page stays anonymous.
+- Every page, whatever its kind, records replays with all text and all inputs masked
+  (`RECORDING_MASK`), and autocapture collects no element text. There is no opt-out.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,

package/lib/artifacts/firestore-indexes.d.ts

@@ -0,0 +1,23 @@
+export type FirestoreIndex = {
+    collectionGroup: string;
+    queryScope: 'COLLECTION';
+    fields: {
+        fieldPath: string;
+        order: 'ASCENDING' | 'DESCENDING';
+    }[];
+};
+export type FirestoreIndexesFile = {
+    indexes: FirestoreIndex[];
+    fieldOverrides: [];
+};
+/** The comments feed's composite in words, for error bodies and health reports. */
+export declare const COMMENTS_FEED_INDEX = "<base>State (collection scope): slot ASC, at ASC";
+/** Every composite index the package's Firestore stores need, for the state-store bases a host
+ *  uses, in the shape of firestore.indexes.json. A Firestore index is keyed by the collection's id
+ *  (the last path segment), so tenants sharing a base under different parents share one entry. */
+export declare function firestoreIndexesFor(stateBases: string[]): FirestoreIndexesFile;
+/** Firestore's missing-index refusal, with the console link it carries to create the index, or
+ *  null for any other error. */
+export declare function missingIndexOf(err: unknown): {
+    create: string | null;
+} | null;

package/lib/artifacts/firestore-indexes.js

@@ -0,0 +1,40 @@
+// The composite indexes the Firestore stores' queries need, and how to read the refusal Firestore
+// throws when one is missing.
+//
+// Firestore serves equality-only queries by merging single-field indexes, so most of the stores'
+// queries need nothing. The exception is an equality on one field plus a range or order on another:
+// that needs a composite, and Firestore refuses the query (gRPC 9, FAILED_PRECONDITION) until it
+// exists. Today there is one, the comments feed's `slotSince` on <base>State.
+//
+// A hub deploys these declaratively: commit `firestoreIndexesFor(<every base it passes to
+// createStateStore>)` as firestore.indexes.json and run `firebase deploy --only firestore:indexes`.
+// A hub that skipped this answered every GET /api/comments with a bare 500 for five days
+// in October 2026, so the feed and HEALTH now name the index instead.
+/** The comments feed's composite in words, for error bodies and health reports. */
+export const COMMENTS_FEED_INDEX = '<base>State (collection scope): slot ASC, at ASC';
+const collectionIdOf = (path) => path.split('/').filter(Boolean).pop() ?? path;
+/** Every composite index the package's Firestore stores need, for the state-store bases a host
+ *  uses, in the shape of firestore.indexes.json. A Firestore index is keyed by the collection's id
+ *  (the last path segment), so tenants sharing a base under different parents share one entry. */
+export function firestoreIndexesFor(stateBases) {
+    const groups = [...new Set(stateBases.map((b) => `${collectionIdOf(b)}State`))];
+    return {
+        indexes: groups.map((collectionGroup) => ({
+            collectionGroup, queryScope: 'COLLECTION',
+            fields: [{ fieldPath: 'slot', order: 'ASCENDING' }, { fieldPath: 'at', order: 'ASCENDING' }],
+        })),
+        fieldOverrides: [],
+    };
+}
+/** Firestore's missing-index refusal, with the console link it carries to create the index, or
+ *  null for any other error. */
+export function missingIndexOf(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const message = String(err.message ?? '');
+    const code = err.code;
+    const precondition = code === 9 || code === 'failed-precondition' || /FAILED_PRECONDITION/.test(message);
+    if (!precondition || !/requires an index/i.test(message))
+        return null;
+    return { create: message.match(/https:\/\/\S+/)?.[0] ?? null };
+}

package/lib/artifacts/index.d.ts

@@ -11,6 +11,7 @@ export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type Flag
 export { readAlertsDue, readSecondsFor, wordCount, localDay, READ_ALERT_KINDS, WORDS_PER_MINUTE, FINISHED_SCROLL, FINISHED_SHARE, QUIET_AFTER_DAYS, QUIET_WINDOW_DAYS, FRESH_HOURS, type ReadAlert, type ReadAlertKind, type ReadAlertInput, type ReaderEvent } from './read-alerts.js';
 export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeChanges, SLOT_NAME, MAX_VALUE_BYTES, MAX_MANY_PER_READER, ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, SHARED_LIMIT, type StateConfig, type SlotDef, type Shape, type Visibility, type Writers } from './state.js';
 export { createStateStore, createMemoryStateStore, readerKeyFor, type StateStore, type StateEntry, type Writer } from './state-store.js';
+export { firestoreIndexesFor, missingIndexOf, COMMENTS_FEED_INDEX, type FirestoreIndex, type FirestoreIndexesFile } from './firestore-indexes.js';
 export { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS, type Heading, type NotesWidget, type NoteValue, type PlacedNote } from './widgets.js';
 export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, fitFrom, FIT_MESSAGE, EMBED_KINDS, type SimulatorBlock, type EmbedBlock, type EmbedKind } from './simulator.js';

package/lib/artifacts/index.js

@@ -11,6 +11,7 @@ export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';
 export { readAlertsDue, readSecondsFor, wordCount, localDay, READ_ALERT_KINDS, WORDS_PER_MINUTE, FINISHED_SCROLL, FINISHED_SHARE, QUIET_AFTER_DAYS, QUIET_WINDOW_DAYS, FRESH_HOURS } from './read-alerts.js';
 export { parseStateConfig, effectiveWriters, slotVisibility, checkValue, shapeChanges, SLOT_NAME, MAX_VALUE_BYTES, MAX_MANY_PER_READER, ANON_WRITES_PER_MINUTE, MAX_ENTRIES_PER_SLOT, SHARED_LIMIT } from './state.js';
 export { createStateStore, createMemoryStateStore, readerKeyFor } from './state-store.js';
+export { firestoreIndexesFor, missingIndexOf, COMMENTS_FEED_INDEX } from './firestore-indexes.js';
 export { stateView, responsesOf, responsesCsv } from './state-view.js';
 export { slugify, headingsOf, blocksOf, scanWidgets, mergeWidgetState, mergeChecklistState, checklistsOf, checklistSendIds, checklistAnswerIds, checklistSyncs, hasNotesWidget, checkNoteValue, placeNotes, NOTES_SLOT, MAX_NOTE_CHARS } from './widgets.js';
 export { parseSimulatorFence, simulatorSrc, parseEmbedFence, embedSrc, fitFrom, FIT_MESSAGE, EMBED_KINDS } from './simulator.js';

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

@@ -1,4 +1,6 @@
 import type { Firestore } from 'firebase-admin/firestore';
+/** `sentAt`: when the sender says the link reached the reader (the publish key marks it). A view
+ *  that began before then was not the reader's, whoever rendered it. */
 export type Recipient = {
     rid: string;
     label: string;
@@ -8,6 +10,7 @@ export type Recipient = {
     addedAt: string;
     revokedAt?: string;
     closesAt?: string | null;
+    sentAt?: string;
 };
 export type RecipientsRecord = {
     recipients: Record<string, Recipient>;
@@ -25,12 +28,22 @@ export type ViewDoc = {
     activeSeconds: number;
     plays: Record<string, number>;
 };
+/** What rendered the link before it was sent: never counted as the reader, shown so a publisher
+ *  can see it happened (usually themselves, checking the page). Null when no send was recorded. */
+export type BeforeSend = {
+    sessions: number;
+    devices: number;
+    activeSeconds: number;
+    firstAt: string | null;
+} | null;
 export type RecipientSummary = {
     rid: string;
     label: string;
     group: boolean;
     revoked: boolean;
     closesAt: string | null;
+    sentAt: string | null;
+    beforeSend: BeforeSend;
     opened: boolean;
     firstOpenAt: string | null;
     cameBack: boolean;
@@ -59,6 +72,10 @@ export interface RecipientsStore {
      *  with '*'. Never the owner's. Returns the rids changed. Optional so a host's own store keeps
      *  working; without it the recipients route answers 501 to a `closes` change. */
     setCloses?(artifactId: string, rids: string[] | '*', closesAt: string | null): Promise<string[]>;
+    /** Mark the named readers' links (or every non-owner's, with '*') as sent at `sentAt`. The
+     *  earliest mark stands: a resend never moves it later. Returns the rids changed. Optional so a
+     *  host's own store keeps working; without it the recipients route answers 501 to a `sent` mark. */
+    setSent?(artifactId: string, rids: string[] | '*', sentAt: string): Promise<string[]>;
     setExpiry(artifactId: string, expireAt: string | null): Promise<void>;
     useToken(key: string, expiresAt: number): Promise<boolean>;
     recordView(v: {

package/lib/artifacts/recipients-store.js

@@ -41,6 +41,20 @@ function closeIn(rec, rids, closesAt) {
     }
     return hit;
 }
+function sentIn(rec, rids, sentAt) {
+    const hit = [];
+    for (const r of Object.values(rec.recipients)) {
+        if (r.owner || (rids !== '*' && !rids.includes(r.rid)))
+            continue;
+        // Earliest wins. A later resend cannot hide opens that happened after the first send, and an
+        // earlier time corrects a mark written late.
+        if (r.sentAt && Date.parse(r.sentAt) <= Date.parse(sentAt))
+            continue;
+        r.sentAt = sentAt;
+        hit.push(r.rid);
+    }
+    return hit;
+}
 function addView(prev, v) {
     const doc = prev ? { ...prev, plays: { ...prev.plays } } : { artifactId: v.artifactId, rid: v.rid, session: v.session, device: v.device, firstAt: v.at, lastAt: v.at, activeSeconds: 0, plays: {} };
     doc.activeSeconds += Math.max(0, Math.min(60, v.addSeconds));
@@ -67,6 +81,7 @@ export function memoryRecipientsStore() {
         },
         async revoke(id, rids) { const rec = recs.get(id); return rec ? revokeIn(rec, rids) : []; },
         async setCloses(id, rids, closesAt) { const rec = recs.get(id); return rec ? closeIn(rec, rids, closesAt) : []; },
+        async setSent(id, rids, sentAt) { const rec = recs.get(id); return rec ? sentIn(rec, rids, sentAt) : []; },
         async setExpiry(id, expireAt) {
             const rec = recs.get(id) ?? { recipients: {}, expireAt: null, keep: false };
             rec.expireAt = expireAt;
@@ -130,6 +145,16 @@ export function createRecipientsStore(db, base) {
             await recsCol().doc(id).set({ recipients: Object.fromEntries(hit.map((rid) => [rid, { closesAt }])) }, { merge: true });
             return hit;
         },
+        async setSent(id, rids, sentAt) {
+            const rec = await read(id);
+            if (!rec)
+                return [];
+            const hit = sentIn(rec, rids, sentAt);
+            if (!hit.length)
+                return hit;
+            await recsCol().doc(id).set({ recipients: Object.fromEntries(hit.map((rid) => [rid, { sentAt }])) }, { merge: true });
+            return hit;
+        },
         async setExpiry(id, expireAt) {
             await recsCol().doc(id).set({ expireAt, keep: expireAt === null }, { merge: true });
         },
@@ -169,10 +194,25 @@ export function createRecipientsStore(db, base) {
 /** One line per reader (never the owner), in the order they were added. */
 export function summarizeViews(rec, views, comments) {
     return Object.values(rec.recipients).filter((r) => !r.owner).sort((a, b) => a.addedAt.localeCompare(b.addedAt)).map((r) => {
-        const mine = views.filter((v) => v.rid === r.rid).sort((a, b) => a.firstAt.localeCompare(b.firstAt));
+        const all = views.filter((v) => v.rid === r.rid).sort((a, b) => a.firstAt.localeCompare(b.firstAt));
+        // A RENDER BEFORE THE SEND IS NEVER THE READER (2026-10-25). The link was opened on the
+        // sender's side while the text waited on approval, and the reader was reported as having
+        // read a page that had not reached them. Nobody can have received a link before it was sent,
+        // so a session that began earlier is someone else's, and so is every session on that same
+        // device: the device had the link before the reader did. This decides by the send, not by
+        // guessing at user agents, so it holds for any renderer (a person checking the page, a
+        // preview that runs scripts) and costs a real reader nothing: their opens come after.
+        // Kept at read time, never by refusing to record, so a send marked late reclassifies.
+        const sentMs = r.sentAt ? Date.parse(r.sentAt) : NaN;
+        const pre = Number.isFinite(sentMs) ? all.filter((v) => Date.parse(v.firstAt) < sentMs) : [];
+        const preDevices = new Set(pre.map((v) => v.device));
+        const early = all.filter((v) => preDevices.has(v.device));
+        const mine = all.filter((v) => !preDevices.has(v.device));
         const firsts = mine.map((v) => Date.parse(v.firstAt));
         return {
             rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null,
+            sentAt: r.sentAt ?? null,
+            beforeSend: Number.isFinite(sentMs) ? { sessions: early.length, devices: preDevices.size, activeSeconds: early.reduce((n, v) => n + v.activeSeconds, 0), firstAt: early[0]?.firstAt ?? null } : null,
             opened: mine.length > 0,
             firstOpenAt: mine[0]?.firstAt ?? null,
             cameBack: firsts.length > 1 && firsts[firsts.length - 1] - firsts[0] >= CAME_BACK_MS,

package/lib/artifacts/toc-spy.d.ts

@@ -1,3 +1,8 @@
+/** How far below the top of the screen a heading may sit and still be the section being read. */
+export declare const READING_LINE = 140;
+/** The section being read: the last heading at or above the reading line, else the first. The
+ *  page analytics times sections by the same rule, so a section's dwell matches the rail. */
+export declare function currentSection(ids: string[], doc?: Document): string | undefined;
 export declare function TocSpy({ slugs }: {
     slugs: string[];
 }): null;

package/lib/artifacts/toc-spy.js

@@ -2,6 +2,19 @@
 // Marks the contents entry for the section being read. Renders nothing: it only sets
 // aria-current on the links the server drew, which is also what styles them.
 import { useEffect } from 'react';
+/** How far below the top of the screen a heading may sit and still be the section being read. */
+export const READING_LINE = 140;
+/** The section being read: the last heading at or above the reading line, else the first. The
+ *  page analytics times sections by the same rule, so a section's dwell matches the rail. */
+export function currentSection(ids, doc = document) {
+    let current = ids[0];
+    for (const id of ids) {
+        const el = doc.getElementById(id);
+        if (el && el.getBoundingClientRect().top <= READING_LINE)
+            current = id;
+    }
+    return current;
+}
 export function TocSpy({ slugs }) {
     const key = slugs.join('|');
     useEffect(() => {
@@ -9,12 +22,7 @@ export function TocSpy({ slugs }) {
         let frame = 0;
         const mark = () => {
             frame = 0;
-            let current = ids[0];
-            for (const id of ids) {
-                const el = document.getElementById(id);
-                if (el && el.getBoundingClientRect().top <= 140)
-                    current = id;
-            }
+            const current = currentSection(ids);
             document.querySelectorAll('a[data-toc-slug]').forEach((a) => {
                 if (a.dataset.tocSlug === current)
                     a.setAttribute('aria-current', 'location');

package/lib/reader/analytics-plan.d.ts

@@ -0,0 +1,41 @@
+export type AnalyticsConfig = {
+    /** A PostHog project API key (the public `phc_...` one, safe in a browser). */
+    posthogKey: string;
+    /** The ingestion host. Default PostHog's US cloud. */
+    posthogHost?: string;
+    /** Sent with every event as `tenant`, so one project can hold several hosts' pages. */
+    tenant?: string;
+};
+export type PageKind = 'public' | 'password' | 'gated' | 'per-reader';
+export type AnalyticsPlan = {
+    key: string;
+    host: string;
+    pageId: string;
+    kind: PageKind;
+    tenant: string | null;
+    /** Who to identify the reader as, or null to keep them anonymous. */
+    identity: {
+        distinctId: string;
+        email?: string;
+        name?: string;
+    } | null;
+};
+export declare const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+export declare function analyticsPlan(input: {
+    config: AnalyticsConfig | null | undefined;
+    pageId: string;
+    kind: PageKind;
+    /** The owner or an admin is looking (signed in, previewing as a reader, or on the owner's own link). */
+    owner: boolean;
+    bot: boolean;
+    /** A gated page's signed-in reader. */
+    reader?: {
+        email: string;
+        name?: string | null;
+    } | null;
+    /** A per-reader link's recipient. */
+    recipient?: {
+        rid: string;
+        label: string;
+    } | null;
+}): AnalyticsPlan | null;

package/lib/reader/analytics-plan.js

@@ -0,0 +1,33 @@
+// Whether a page view is recorded in the host's product analytics, and as whom. Pure, so the route
+// decides on the server and the browser is handed either nothing or exactly what to send.
+//
+// THE RULES (0.50.0):
+//  - A host with no analytics key records nothing, and its pages load no analytics script at all.
+//  - The owner and the host's admins are never recorded, signed in or on their own per-reader link.
+//  - A link-preview fetcher is never handed the script.
+//  - A reader is identified only where the page already knows who they are: a gated page by the
+//    signed-in email, a per-reader link by its opaque recipient id and the label the publisher gave
+//    it (never a phone or an email, which the recipients store does not hold). A public or password
+//    page stays anonymous, even when its reader happens to be signed in.
+export const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com';
+export function analyticsPlan(input) {
+    const key = input.config?.posthogKey?.trim();
+    if (!key || input.owner || input.bot)
+        return null;
+    let identity = null;
+    if (input.kind === 'gated' && input.reader?.email) {
+        const email = input.reader.email.trim().toLowerCase();
+        identity = { distinctId: email, email, ...(input.reader.name ? { name: input.reader.name } : {}) };
+    }
+    else if (input.kind === 'per-reader' && input.recipient?.rid) {
+        identity = { distinctId: `recipient:${input.recipient.rid}`, name: input.recipient.label };
+    }
+    return {
+        key,
+        host: input.config.posthogHost?.trim() || DEFAULT_POSTHOG_HOST,
+        pageId: input.pageId,
+        kind: input.kind,
+        tenant: input.config.tenant ?? null,
+        identity,
+    };
+}

package/lib/reader/artifact-reader.js

@@ -275,7 +275,7 @@ export function ArtifactReader({ src, words, rootId, accent, ground, }) {
         else
             a.pause();
     };
-    return (_jsxs(_Fragment, { children: [_jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => {
+    return (_jsxs(_Fragment, { children: [_jsx("audio", { ref: audioRef, "data-artifact-narration": true, src: src, preload: "metadata", onPlay: () => {
                     startedRef.current = true;
                     playingRef.current = true;
                     setPlaying(true);

package/lib/reader/index.d.ts

@@ -13,3 +13,5 @@ export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom
 export { VoiceRecorder, AudioPlay, hostVoice, pickRecordingType, newMemoId, recognitionCtor, LIVE_LINE, type VoiceHost, type VoiceMemo, type VoiceScope } from './voice-recorder.js';
 export { deviceAudio, isDeviceAudio, type DeviceAudio } from './device-audio.js';
 export { type SavedMemo } from './comment-card.js';
+export { PageAnalytics, trackSections, narrationEvent, MIN_SECTION_SECONDS, posthogInitOptions, RECORDING_MASK } from './page-analytics.js';
+export { analyticsPlan, DEFAULT_POSTHOG_HOST, type AnalyticsConfig, type AnalyticsPlan, type PageKind } from './analytics-plan.js';

package/lib/reader/index.js

@@ -14,3 +14,5 @@ export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDe
 export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom } from './comment-place.js';
 export { VoiceRecorder, AudioPlay, hostVoice, pickRecordingType, newMemoId, recognitionCtor, LIVE_LINE } from './voice-recorder.js';
 export { deviceAudio, isDeviceAudio } from './device-audio.js';
+export { PageAnalytics, trackSections, narrationEvent, MIN_SECTION_SECONDS, posthogInitOptions, RECORDING_MASK } from './page-analytics.js';
+export { analyticsPlan, DEFAULT_POSTHOG_HOST } from './analytics-plan.js';

package/lib/reader/page-analytics.d.ts

@@ -0,0 +1,42 @@
+import type { AnalyticsPlan } from './analytics-plan.js';
+/** Sections read for less than this are passed over, not read. */
+export declare const MIN_SECTION_SECONDS = 2;
+type Capture = (event: string, props?: Record<string, unknown>) => void;
+/** Times the section being read, by the contents rail's own rule, and reports each one as the
+ *  reader leaves it. Only visible time counts. Returns a stop function that flushes the last one. */
+export declare function trackSections(ids: string[], capture: Capture, doc?: Document, now?: () => number): {
+    check: () => void;
+    stop: () => void;
+};
+/** The narration's events: play, pause with where it stopped, complete. */
+export declare function narrationEvent(type: string, audio: {
+    currentTime: number;
+    duration: number;
+    ended?: boolean;
+}): [string, Record<string, unknown>] | null;
+/** How every replay is masked: every text node and every input, on every page kind. The options set
+ *  in `posthog.init` override the PostHog project's own masking setting, so this is the whole rule. */
+export declare const RECORDING_MASK: Readonly<{
+    readonly maskAllInputs: true;
+    readonly maskTextSelector: "*";
+}>;
+/** The options the page hands `posthog.init`. Pure, so a test can hold it to the mask. */
+export declare function posthogInitOptions(plan: Pick<AnalyticsPlan, 'host'>): {
+    api_host: string;
+    person_profiles: "identified_only";
+    capture_pageview: boolean;
+    capture_pageleave: boolean;
+    autocapture: boolean;
+    mask_all_text: boolean;
+    enable_heatmaps: boolean;
+    disable_session_recording: boolean;
+    session_recording: {
+        maskAllInputs: true;
+        maskTextSelector: "*";
+    };
+};
+export declare function PageAnalytics({ plan, rootId }: {
+    plan: AnalyticsPlan;
+    rootId?: string;
+}): null;
+export {};

package/lib/reader/page-analytics.js

@@ -0,0 +1,130 @@
+'use client';
+// The host's product analytics on a page: PostHog, with session replay, heatmaps, autocapture and
+// scroll depth on leave, plus the reading this package knows about and PostHog cannot: which
+// section was read and for how long, and the narration played, paused and finished.
+//
+// The server decides whether this mounts at all and as whom (analytics-plan.ts). posthog-js is
+// imported only here, after mount, so a host with no key never downloads it.
+//
+// EVERY page's replay masks all text and all inputs, whatever its kind (since 0.51.0). A replay is a
+// copy of the page held by a third party, and a page shared by key or by link is no less private
+// than a gated one: the replay still shows where the reader went, how far and how fast, without the
+// words. Autocapture is told not to collect element text for the same reason. There is no opt-out:
+// the options come from posthogInitOptions, which a test holds to RECORDING_MASK for every kind.
+import { useEffect } from 'react';
+import { currentSection } from '../artifacts/toc-spy.js';
+/** Sections read for less than this are passed over, not read. */
+export const MIN_SECTION_SECONDS = 2;
+/** Times the section being read, by the contents rail's own rule, and reports each one as the
+ *  reader leaves it. Only visible time counts. Returns a stop function that flushes the last one. */
+export function trackSections(ids, capture, doc = document, now = Date.now) {
+    let current;
+    let since = null;
+    const visible = () => doc.visibilityState === 'visible';
+    const flush = () => {
+        if (!current || since === null)
+            return;
+        const seconds = Math.round((now() - since) / 1000);
+        if (seconds >= MIN_SECTION_SECONDS) {
+            const heading = doc.getElementById(current)?.textContent?.trim() ?? '';
+            capture('section_viewed', { section_id: current, heading, seconds });
+        }
+        since = null;
+    };
+    const check = () => {
+        if (!visible()) {
+            flush();
+            return;
+        }
+        const next = currentSection(ids, doc);
+        if (next !== current) {
+            flush();
+            current = next;
+        }
+        if (since === null)
+            since = now();
+    };
+    return { check, stop: flush };
+}
+/** The narration's events: play, pause with where it stopped, complete. */
+export function narrationEvent(type, audio) {
+    const at = { position_seconds: Math.round(audio.currentTime), duration_seconds: Number.isFinite(audio.duration) ? Math.round(audio.duration) : null };
+    if (type === 'play')
+        return ['narration_play', at];
+    if (type === 'pause' && !audio.ended)
+        return ['narration_pause', at];
+    if (type === 'ended')
+        return ['narration_complete', at];
+    return null;
+}
+/** How every replay is masked: every text node and every input, on every page kind. The options set
+ *  in `posthog.init` override the PostHog project's own masking setting, so this is the whole rule. */
+export const RECORDING_MASK = Object.freeze({ maskAllInputs: true, maskTextSelector: '*' });
+/** The options the page hands `posthog.init`. Pure, so a test can hold it to the mask. */
+export function posthogInitOptions(plan) {
+    return {
+        api_host: plan.host,
+        person_profiles: 'identified_only',
+        capture_pageview: true,
+        capture_pageleave: true,
+        autocapture: true,
+        // Autocapture records a clicked element's text; on these pages that text is the page.
+        mask_all_text: true,
+        enable_heatmaps: true,
+        disable_session_recording: false,
+        session_recording: { ...RECORDING_MASK },
+    };
+}
+export function PageAnalytics({ plan, rootId = 'artifact-narration-root' }) {
+    const { key, host, pageId, kind, tenant } = plan;
+    const identity = plan.identity ? JSON.stringify(plan.identity) : '';
+    useEffect(() => {
+        let cancelled = false;
+        let cleanup = () => { };
+        void import('posthog-js').then(({ default: posthog }) => {
+            if (cancelled)
+                return;
+            posthog.init(key, posthogInitOptions({ host }));
+            posthog.register({ artifact_id: pageId, page_kind: kind, ...(tenant ? { tenant } : {}) });
+            if (identity) {
+                const who = JSON.parse(identity);
+                posthog.identify(who.distinctId, { ...(who.email ? { email: who.email } : {}), ...(who.name ? { name: who.name } : {}) });
+            }
+            const capture = (e, p) => posthog.capture(e, p);
+            const root = document.getElementById(rootId);
+            const ids = root ? Array.from(root.querySelectorAll('h2[id], h3[id]'), (h) => h.id) : [];
+            const sections = ids.length ? trackSections(ids, capture) : null;
+            let frame = 0;
+            const onScroll = () => { if (sections && !frame)
+                frame = requestAnimationFrame(() => { frame = 0; sections.check(); }); };
+            const onVisibility = () => sections?.check();
+            const onHide = () => sections?.stop();
+            const onMedia = (e) => {
+                const el = e.target;
+                if (!el?.hasAttribute?.('data-artifact-narration'))
+                    return;
+                const ev = narrationEvent(e.type, el);
+                if (ev)
+                    capture(...ev);
+            };
+            sections?.check();
+            window.addEventListener('scroll', onScroll, { passive: true });
+            document.addEventListener('visibilitychange', onVisibility);
+            window.addEventListener('pagehide', onHide);
+            for (const t of ['play', 'pause', 'ended'])
+                document.addEventListener(t, onMedia, true);
+            cleanup = () => {
+                sections?.stop();
+                if (frame)
+                    cancelAnimationFrame(frame);
+                window.removeEventListener('scroll', onScroll);
+                document.removeEventListener('visibilitychange', onVisibility);
+                window.removeEventListener('pagehide', onHide);
+                for (const t of ['play', 'pause', 'ended'])
+                    document.removeEventListener(t, onMedia, true);
+            };
+        }).catch(() => { });
+        return () => { cancelled = true; cleanup(); };
+    }, [key, host, pageId, kind, tenant, identity, rootId]);
+    return null;
+}

package/lib/routes/artifacts.d.ts

@@ -10,6 +10,7 @@ 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 AnalyticsConfig } from '../reader/analytics-plan.js';
 import type { PersonalStore } from '../artifacts/personal-store.js';
 import type { Transcriber } from '../artifacts/transcribe.js';
 export type ArtifactRoutesConfig = {
@@ -121,6 +122,12 @@ export type ArtifactRoutesConfig = {
     recipients?: RecipientsStore;
     /** Signs per-reader links and render tokens. At least 32 characters. Read at request time. */
     recipientSecret?: () => string | undefined;
+    /** Product analytics for this host's pages (0.50.0): PostHog with session replay, heatmaps,
+     *  autocapture, scroll depth on leave, and section_viewed / narration_* events. Without a key no
+     *  page loads any analytics script. Never records the owner or an admin, never a link-preview
+     *  fetcher, never a past version; identifies a reader only on a gated page (their email) or a
+     *  per-reader link (its recipient id and label). See reader/analytics-plan.ts. */
+    analytics?: AnalyticsConfig | null;
 };
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export declare const ARTIFACT_ID: RegExp;
@@ -217,6 +224,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
             id: string;
         }>;
     }) => Promise<NextResponse<unknown>>;
+    HEALTH: (_req: NextRequest) => Promise<NextResponse<unknown>>;
     Page: ({ params, searchParams }: PageProps) => Promise<import("react").JSX.Element>;
     generateMetadata: ({ params }: Params) => Promise<Metadata>;
     VersionPage: ({ params, searchParams }: VersionProps) => Promise<import("react").JSX.Element>;

package/lib/routes/artifacts.js

@@ -36,6 +36,8 @@ import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
 import { createRecipientsRoutes } from './recipients-routes.js';
 import { QuietView } from '../reader/quiet-view.js';
+import { PageAnalytics } from '../reader/page-analytics.js';
+import { analyticsPlan } from '../reader/analytics-plan.js';
 import { createPersonalRoutes } from './personal-routes.js';
 import { createVoiceRoutes } from './voice-routes.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
@@ -317,7 +319,7 @@ export function createArtifactRoutes(config) {
         if (!a)
             notFound();
         const { pack, brand } = lookOf(a);
-        const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top, reader }));
+        const render = (top, reader, untracked = false) => (n === null ? Body(a, { top, reader, untracked }) : VersionBody(a, n, { top, reader }));
         if (a.access)
             return GatedPage(a, id, render, n);
         const broadcast = kindOf(a) === 'broadcast';
@@ -338,7 +340,7 @@ export function createArtifactRoutes(config) {
             if (isAdmin(me)) {
                 const markdown = await media(a.markdown);
                 const viewer = wantsReaderView(sp) ? null : me;
-                const page = broadcast ? await BroadcastCard({ ...a, markdown }, { reader: viewer, bot }) : await Body({ ...a, markdown }, { top: true, reader: viewer });
+                const page = broadcast ? await BroadcastCard({ ...a, markdown }, { reader: viewer, bot, untracked: true }) : await Body({ ...a, markdown }, { top: true, reader: viewer, untracked: true });
                 return _jsxs(BrandGround, { pack: pack, mode: a.theme, children: [viewer ? null : _jsx(ViewingAsReader, { back: pagePath(id) }), page] });
             }
             const secret = usableSecret(config.recipientSecret?.());
@@ -389,7 +391,7 @@ export function createArtifactRoutes(config) {
         // rendered for no one signed in, with a bar back to their own view. Anyone else asking gets the
         // page they already get.
         const asReader = isAdmin(reader) && wantsReaderView(sp);
-        const page = await render(true, asReader ? null : reader);
+        const page = await render(true, asReader ? null : reader, asReader);
         if (n === null && !asReader)
             void store.bumpViews(id);
         return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, asReader ? _jsx(ViewingAsReader, { back: n === null ? pagePath(id) : `${pagePath(id)}/v/${n}` }) : null, page] }));
@@ -481,7 +483,7 @@ export function createArtifactRoutes(config) {
      *  them, then this reader's own note. None of the document's furniture: no table of contents, no
      *  version line, no read-along (a voice note is its own audio), and no page menu for a reader.
      *  Comments only when the file turned them on; the quiet view beacon always, for a reader. */
-    async function BroadcastCard(a, { reader, perReader, bot }) {
+    async function BroadcastCard(a, { reader, perReader, bot, untracked = false }) {
         const { brand } = lookOf(a);
         const mode = !bot && config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
         const admin = isAdmin(reader);
@@ -489,10 +491,10 @@ export function createArtifactRoutes(config) {
         const cover = !bot && a.cover && !/!\[[^\]]*\]\(/.test(a.markdown) ? a.cover : null;
         return (_jsxs(_Fragment, { children: [admin ? (_jsx(PageMenu, { role: roleOf(reader), name: reader ? reader.name ?? reader.email : null, share: null, comments: mode !== 'off', signIn: null, signOut: signOutUrl(a.id), history: null, markdown: null, settings: null })) : null, _jsx("main", { "data-broadcast": true, className: "mx-auto max-w-lg px-4 pt-16 pb-20 sm:pt-24", children: _jsxs("article", { id: "broadcast-root", "data-broadcast-card": true, className: "rounded-2xl border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-5 py-6 sm:px-7 sm:py-8", children: [_jsx("p", { "data-nospeak": true, "data-broadcast-from": true, className: "text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: `From ${owner}` }), _jsx("h1", { className: "mt-3 text-2xl sm:text-3xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), cover ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone', signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null] }));
+                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone', signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked, bot })] }));
     }
     /** The page itself, shared by open and gated pages. */
-    async function Body(a, { top, reader, perReader }) {
+    async function Body(a, { top, reader, perReader, untracked = false }) {
         const { pack, brand } = lookOf(a);
         let words = [];
         if (a.narration && a.timings) {
@@ -517,10 +519,27 @@ export function createArtifactRoutes(config) {
                         return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.closesAt && !perReader.owner ? (_jsx(FeedbackWindow, { owner: owner, label: perReader.label, note: perReader.note, group: perReader.group, closesAt: perReader.closesAt })) : perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, embeds: embeds }) }));
-                    })() }), _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, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
+                    })() }), _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, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked }), 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. */] }));
     }
+    /** The page's analytics, or nothing (analytics-plan.ts has the rules). `untracked` is the owner or
+     *  an admin previewing as a reader, who arrives here with no reader at all. */
+    async function Analytics(a, { reader, perReader, untracked, bot }) {
+        if (!config.analytics?.posthogKey)
+            return null;
+        const ua = bot === undefined ? await (config.readHeader ?? defaultReadHeader)('user-agent').catch(() => undefined) : undefined;
+        const plan = analyticsPlan({
+            config: config.analytics,
+            pageId: a.id,
+            kind: perReader ? 'per-reader' : a.access ? 'gated' : a.password ? 'password' : 'public',
+            owner: untracked || isAdmin(reader) || !!perReader?.owner,
+            bot: bot ?? (ua !== undefined && isUnfurlAgent(ua)),
+            reader: a.access ? reader : null,
+            recipient: perReader ? { rid: perReader.rid, label: perReader.label } : null,
+        });
+        return plan ? _jsx(PageAnalytics, { plan: plan }) : null;
+    }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in
      *  reader. Swaps the five-minute pass for this host's grant and lands them on the page, with

package/lib/routes/recipients-routes.js

@@ -65,7 +65,7 @@ export function createRecipientsRoutes(given) {
         const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
         return {
             id, expireAt: rec.expireAt, keep: rec.keep,
-            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
+            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null, sentAt: r.sentAt ?? null, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
         };
     }
     /** GET and POST /api/artifacts/<id>/recipients: who a per-reader page was sent to (publish key). */
@@ -105,6 +105,22 @@ export function createRecipientsRoutes(given) {
             if (!ctx.recipients.setCloses)
                 return json({ error: 'this host cannot set a feedback window' }, 501);
         }
+        // `sent`: the sender's word that these links reached their readers, at `at` (default: now, on
+        // this host's clock). Views that began earlier are then not the reader's (summarizeViews). A
+        // time in the future is refused: it would hide a real reader's open.
+        const sent = b.sent;
+        let sentAt = null;
+        if (sent !== undefined) {
+            const ridsOk = !!sent && typeof sent === 'object' && (sent.rids === '*' || (Array.isArray(sent.rids) && sent.rids.every((x) => typeof x === 'string' && RID_RE.test(x))));
+            const atMs = sent && typeof sent === 'object' && sent.at !== undefined ? (typeof sent.at === 'string' && ISO.test(sent.at) ? Date.parse(sent.at) : NaN) : Date.now();
+            if (!ridsOk || !Number.isFinite(atMs))
+                return json({ error: 'sent is { rids: [rid] or "*", at: an ISO time (default now) }' }, 400);
+            if (atMs > Date.now() + 60_000)
+                return json({ error: 'sent.at must not be in the future' }, 400);
+            if (!ctx.recipients.setSent)
+                return json({ error: 'this host cannot record a send' }, 501);
+            sentAt = new Date(atMs).toISOString();
+        }
         if (adds.length) {
             const made = await ctx.recipients.add(id, adds.map((x) => ({
                 label: x.label,
@@ -117,11 +133,12 @@ export function createRecipientsRoutes(given) {
         const revoked = b.revoke === '*' || Array.isArray(b.revoke)
             ? await ctx.recipients.revoke(id, b.revoke === '*' ? '*' : b.revoke.filter((x) => typeof x === 'string' && RID_RE.test(x)))
             : [];
+        const marked = sentAt ? await ctx.recipients.setSent(id, b.sent.rids, sentAt) : [];
         const windowed = win ? await ctx.recipients.setCloses(id, win.rids, win.at === null ? null : new Date(win.at).toISOString()) : [];
         if (b.expires === null || typeof b.expires === 'string') {
             await ctx.recipients.setExpiry(id, b.expires === null ? null : new Date(b.expires).toISOString());
         }
-        return json({ ...(await listing(id)), added, revoked, windowed });
+        return json({ ...(await listing(id)), added, revoked, windowed, sent: marked });
     }
     /** GET /api/artifacts/<id>/views: one line per reader, with their comments (publish key). */
     async function VIEWS(req, { params }) {

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

@@ -62,5 +62,6 @@ export declare function createStateRoutes(ctx: StateRoutesContext): {
     COMMENTS_FEED: (req: NextRequest) => Promise<NextResponse<unknown>>;
     RESOLVE: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
     REPLY: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
+    HEALTH: (_req: NextRequest) => Promise<NextResponse<unknown>>;
 };
 export {};

package/lib/routes/state-routes.js

@@ -30,6 +30,7 @@ import { COMMENTS_SLOT, FEEDBACK_CLOSED, MAX_COMMENT_CHARS, MAX_COMMENT_NAME_CHA
 import { MAX_QUOTE_CHARS } from '../artifacts/anchor.js';
 import { isCommentAudioPath } from '../artifacts/audio.js';
 import { readerKeyFor } from '../artifacts/state-store.js';
+import { COMMENTS_FEED_INDEX, missingIndexOf } from '../artifacts/firestore-indexes.js';
 import { NOTES_SLOT, checkNoteValue, checklistAnswerIds, hasNotesWidget } from '../artifacts/widgets.js';
 import { CHECKLIST_SLOT, checkChecklistValue } from '../artifacts/checklist.js';
 import { responsesCsv, responsesOf, stateView } from '../artifacts/state-view.js';
@@ -443,9 +444,20 @@ export function createStateRoutes(ctx) {
         if (only === null && !ctx.state.slotSince)
             return json({ error: 'this host cannot list comments by time' }, 501);
         const now = new Date().toISOString();
-        const entries = only !== null
-            ? (await ctx.state.entries(only)).filter((e) => e.slot === COMMENTS_SLOT && e.at > since).sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id)).slice(0, FEED_MAX)
-            : await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
+        let entries;
+        try {
+            entries = only !== null
+                ? (await ctx.state.entries(only)).filter((e) => e.slot === COMMENTS_SLOT && e.at > since).sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id)).slice(0, FEED_MAX)
+                : await ctx.state.slotSince(COMMENTS_SLOT, since, FEED_MAX);
+        }
+        catch (err) {
+            // Firestore refuses the cross-page query until its composite index exists. Say which index,
+            // rather than a bare 500 the publisher's notifier cannot act on (October 2026).
+            const missing = missingIndexOf(err);
+            if (!missing)
+                throw err;
+            return json({ error: 'missing_firestore_index', index: COMMENTS_FEED_INDEX, create: missing.create }, 503);
+        }
         const pages = new Map();
         const pageOf = (id) => { if (!pages.has(id))
             pages.set(id, ctx.store.get(id)); return pages.get(id); };
@@ -639,5 +651,26 @@ export function createStateRoutes(ctx) {
             return json({ error: 'this thread takes no more replies' }, 409);
         return json({ id, entry: r.id, parent: root.id, existing: false });
     }
-    return { STATE_GET, STATE_POST, RESPONSES, COMMENTS_FEED, RESOLVE, REPLY };
+    /** GET /api/health: whether the queries this host's routes run will be served, today the
+     *  comments feed's composite index. 200 with `ok: true`, or 503 naming what is missing. No key:
+     *  it reveals nothing a public package does not already say, and a deploy check can call it. The
+     *  probe asks for one comment after now, so it reads at most one document. */
+    async function HEALTH(_req) {
+        const checks = [];
+        if (ctx.state?.slotSince) {
+            try {
+                await ctx.state.slotSince(COMMENTS_SLOT, new Date().toISOString(), 1);
+                checks.push({ name: 'comments-feed-index', ok: true });
+            }
+            catch (err) {
+                const missing = missingIndexOf(err);
+                checks.push(missing
+                    ? { name: 'comments-feed-index', ok: false, error: 'missing_firestore_index', index: COMMENTS_FEED_INDEX, create: missing.create }
+                    : { name: 'comments-feed-index', ok: false, error: 'query_failed' });
+            }
+        }
+        const ok = checks.every((c) => c.ok === true);
+        return json({ ok, checks }, ok ? 200 : 503);
+    }
+    return { STATE_GET, STATE_POST, RESPONSES, COMMENTS_FEED, RESOLVE, REPLY, HEALTH };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.49.0",
+  "version": "0.52.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",
@@ -80,6 +80,7 @@
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
+    "posthog-js": "1.438.6",
     "react-markdown": "^9.0.3",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",