@supersuit/artifacts 0.50.0 → 0.53.0

package/CHANGELOG.md

@@ -3,6 +3,89 @@
 `@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.53.0 (2026-10-25)
+
+**Every per-reader link can record who minted it, on whose authority, when, and the funnel step it
+was sent for.** Superlinks: when an operator's agent sends a page, the link it makes names the
+person it is for, and the founders asked that it also name who made it ("<person>'s Pluma, on
+<person>'s explicit request, <time>"), so that a funnel move citing the link's opens has
+provenance rather than a typed claim.
+
+- `POST /recipients` `add` entries take `provenance: { actor, authority, at?, link?, funnel?, stage? }`.
+  `at` defaults to now; a missing actor or authority, a malformed time, a non-https link, a funnel
+  that is not a slug, or a stage without its funnel is refused (400) and nothing is added.
+- `add`'s `added`, `GET /recipients` and `GET /views` carry `provenance` per reader (`null` when
+  none). Stored on the reader's row by both stores; `Provenance` is exported with the store types.
+- DETECTOR: a sender that posts `provenance` and reads `added[i].provenance` back as missing or
+  `undefined` is talking to a host on 0.52.x or older, which drops the field.
+- REMEDY: bump. Links made before this carry `provenance: null`; nothing is migrated.
+- Tests: recipients-api.test.tsx (provenance kept and answered by add, the listing and views;
+  stamped now when no time is given; each malformed shape refused with 400).
+
+## 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,

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?, provenance? }], 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 and its `provenance` (see Who minted a 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`, `beforeSend` and `provenance`. 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,41 @@ 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.
+
+### Who minted a link (0.53.0)
+
+Every link can say who made it, on whose authority, and when: `add: [{ label, provenance: { actor,
+authority, at?, link?, funnel?, stage? } }]`. `actor` is a person acting by hand or "<person>'s
+Pluma"; `authority` names what they acted under ("approved by <person> on the send card", "on
+<person>'s explicit request", "under the recurrent <name>"), with `link` to the session or message
+where one exists (https only); `at` defaults to now. `funnel` (a slug) and `stage` (an id, only with
+its funnel) name the funnel step the link was sent for, so a funnel move that cites the link's opens
+has provenance. A provenance with no actor or no authority, or a malformed time, link, funnel or
+stage, is refused (400) and nothing is added. It is kept on the reader's row and answered back by
+`add`, `GET /recipients` and `GET /views` (`null` for a link made without one). A host on 0.52.x
+ignores the field, so a sender that needs it reads it back from `added` and treats `null` as an old
+host.
+
 ### 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.
@@ -1186,9 +1235,11 @@ 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 and masks all text in its replays.
+- 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
 

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';
@@ -25,6 +26,6 @@ export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey, type DeclaredSettings, type LiveSettings, type SettingsPatch } from './settings.js';
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
-export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
+export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary, type Provenance } from './recipients-store.js';
 export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.js';
 export { parseTranscriptFence, scanVoiceNotes, transcriptFenceFromWords, wordsFromWhisperJson, isAudioSrc, TRANSCRIPT_LANG, MAX_TRANSCRIPT_WORDS, type TranscriptParagraphs, type TimedWord, type VoiceNoteBlock } from './voice-note.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,20 @@ export type Recipient = {
     addedAt: string;
     revokedAt?: string;
     closesAt?: string | null;
+    sentAt?: string;
+    provenance?: Provenance;
+};
+/** Who minted a link, on whose authority, and when (a superlink, 0.53.0): `actor` is a person by
+ *  hand or "<person>'s Pluma"; `authority` is the request, recurrent or approval it acted under, with
+ *  `link` to the session or message where one exists; `funnel` and `stage` name the funnel step the
+ *  link was sent to move someone from, so a funnel move citing its opens has provenance. */
+export type Provenance = {
+    actor: string;
+    authority: string;
+    at: string;
+    link?: string;
+    funnel?: string;
+    stage?: string;
 };
 export type RecipientsRecord = {
     recipients: Record<string, Recipient>;
@@ -25,12 +41,23 @@ 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;
+    provenance: Provenance | null;
+    beforeSend: BeforeSend;
     opened: boolean;
     firstOpenAt: string | null;
     cameBack: boolean;
@@ -50,6 +77,7 @@ type NewRecipient = {
     owner?: boolean;
     group?: boolean;
     closesAt?: string;
+    provenance?: Provenance;
 };
 export interface RecipientsStore {
     get(artifactId: string): Promise<RecipientsRecord | null>;
@@ -59,6 +87,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

@@ -15,7 +15,7 @@ function makeRecipients(input, taken) {
         const note = typeof i.note === 'string' && i.note.trim() ? i.note.trim().slice(0, NOTE_MAX) : undefined;
         // The owner never carries a window: setCloses skips them and the page hides the closed state
         // from them, so one stored here would offer Share on their link and then refuse it.
-        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}), ...(typeof i.closesAt === 'string' && !i.owner ? { closesAt: i.closesAt } : {}) };
+        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}), ...(typeof i.closesAt === 'string' && !i.owner ? { closesAt: i.closesAt } : {}), ...(i.provenance ? { provenance: { ...i.provenance } } : {}) };
     });
 }
 function revokeIn(rec, rids) {
@@ -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,26 @@ 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,
+            provenance: r.provenance ?? 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/reader/index.d.ts

@@ -13,5 +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 } from './page-analytics.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,5 +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 } from './page-analytics.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

@@ -14,6 +14,27 @@ export declare function narrationEvent(type: string, audio: {
     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;

package/lib/reader/page-analytics.js

@@ -6,9 +6,11 @@
 // 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.
 //
-// Text fields are masked in replays (PostHog's default). A gated page masks ALL text too, because
-// its body is confidential and a replay is a copy of it held by a third party: the replay still
-// shows where the reader went, how far and how fast, without the words.
+// 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. */
@@ -55,6 +57,24 @@ export function narrationEvent(type, audio) {
         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) : '';
@@ -64,16 +84,7 @@ export function PageAnalytics({ plan, rootId = 'artifact-narration-root' }) {
         void import('posthog-js').then(({ default: posthog }) => {
             if (cancelled)
                 return;
-            posthog.init(key, {
-                api_host: host,
-                person_profiles: 'identified_only',
-                capture_pageview: true,
-                capture_pageleave: true,
-                autocapture: true,
-                enable_heatmaps: true,
-                disable_session_recording: false,
-                session_recording: { maskAllInputs: true, ...(kind === 'gated' ? { maskTextSelector: '*' } : {}) },
-            });
+            posthog.init(key, posthogInitOptions({ host }));
             posthog.register({ artifact_id: pageId, page_kind: kind, ...(tenant ? { tenant } : {}) });
             if (identity) {
                 const who = JSON.parse(identity);

package/lib/routes/artifacts.d.ts

@@ -224,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/recipients-routes.d.ts

@@ -1,5 +1,5 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { type RecipientsStore } from '../artifacts/recipients-store.js';
+import { type Provenance, type RecipientsStore } from '../artifacts/recipients-store.js';
 import type { ArtifactStore } from '../artifacts/store.js';
 import type { StateStore } from '../artifacts/state-store.js';
 import type { ArtifactAssets } from '../artifacts/assets.js';
@@ -20,6 +20,15 @@ export type RecipientsRoutesCtx = {
     /** Where the sweep reports a page it skipped or could not finish. Defaults to console.warn. */
     log?: (message: string) => void;
 };
+/** A reader's provenance as sent, checked: who minted the link, on whose authority, when (default
+ *  now), and the funnel step it serves. -> the clean record, or the reason it is refused. */
+export declare function readProvenance(v: unknown, now?: Date): {
+    ok: true;
+    value: Provenance;
+} | {
+    ok: false;
+    why: string;
+};
 export declare function createRecipientsRoutes(given: RecipientsRoutesCtx): {
     SEEN: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
     RECIPIENTS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;

package/lib/routes/recipients-routes.js

@@ -8,6 +8,38 @@ import { ARTIFACT_ID_RE } from './ids.js';
 const SESSION = /^[a-z0-9]{1,32}$/;
 const MEDIA = /^[A-Za-z0-9][A-Za-z0-9._-]{0,140}$/;
 const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const SLUG = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/** A reader's provenance as sent, checked: who minted the link, on whose authority, when (default
+ *  now), and the funnel step it serves. -> the clean record, or the reason it is refused. */
+export function readProvenance(v, now = new Date()) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return { ok: false, why: 'provenance is { actor, authority, at?, link?, funnel?, stage? }' };
+    const p = v;
+    const text = (x, max) => (typeof x === 'string' && x.trim() ? x.trim().slice(0, max) : '');
+    const actor = text(p.actor, 120), authority = text(p.authority, 300);
+    if (!actor || !authority)
+        return { ok: false, why: 'provenance needs who minted the link (actor) and on whose authority (authority)' };
+    if (p.at !== undefined && (typeof p.at !== 'string' || !ISO.test(p.at)))
+        return { ok: false, why: 'provenance.at must be an ISO time' };
+    let link;
+    if (p.link !== undefined) {
+        try {
+            const u = new URL(String(p.link));
+            if (u.protocol !== 'https:')
+                throw new Error('not https');
+            link = u.toString();
+        }
+        catch {
+            return { ok: false, why: 'provenance.link must be an https address' };
+        }
+    }
+    if (p.funnel !== undefined && (typeof p.funnel !== 'string' || !SLUG.test(p.funnel)))
+        return { ok: false, why: 'provenance.funnel must be a funnel slug' };
+    if (p.stage !== undefined && (typeof p.stage !== 'string' || !SLUG.test(p.stage) || p.funnel === undefined))
+        return { ok: false, why: 'provenance.stage must be a stage id, with its funnel' };
+    const at = typeof p.at === 'string' ? new Date(p.at).toISOString() : now.toISOString();
+    return { ok: true, value: { actor, authority, at, ...(link ? { link } : {}), ...(p.funnel ? { funnel: p.funnel } : {}), ...(p.stage ? { stage: p.stage } : {}) } };
+}
 const none = () => new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
 const json = (b, status = 200) => NextResponse.json(b, { status, headers: { 'cache-control': 'no-store' } });
 export function createRecipientsRoutes(given) {
@@ -65,7 +97,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, provenance: r.provenance ?? 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). */
@@ -96,6 +128,17 @@ export function createRecipientsRoutes(given) {
         const adds = Array.isArray(b.add) ? b.add : [];
         if (adds.some((x) => x.closes !== undefined && (typeof x.closes !== 'string' || Number.isNaN(Date.parse(x.closes)))))
             return json({ error: 'closes must be an ISO time' }, 400);
+        const provenances = [];
+        for (const x of adds) {
+            if (x.provenance === undefined) {
+                provenances.push(undefined);
+                continue;
+            }
+            const p = readProvenance(x.provenance);
+            if (!p.ok)
+                return json({ error: p.why }, 400);
+            provenances.push(p.value);
+        }
         const win = b.closes;
         if (win !== undefined) {
             const ridsOk = !!win && (win.rids === '*' || (Array.isArray(win.rids) && win.rids.every((x) => typeof x === 'string' && RID_RE.test(x))));
@@ -105,23 +148,41 @@ 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) => ({
+            const made = await ctx.recipients.add(id, adds.map((x, i) => ({
                 label: x.label,
                 ...(typeof x.note === 'string' ? { note: x.note } : {}), ...(x.owner === true ? { owner: true } : {}), ...(x.group === true ? { group: true } : {}),
                 // Never for the owner, whatever store the host brought: their link has no window.
                 ...(typeof x.closes === 'string' && x.owner !== true ? { closesAt: new Date(x.closes).toISOString() } : {}),
+                ...(provenances[i] ? { provenance: provenances[i] } : {}),
             })));
-            added = made.map((r) => ({ rid: r.rid, label: r.label, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) }));
+            added = made.map((r) => ({ rid: r.rid, label: r.label, url: ridLink(ctx.pageUrl(id), id, r.rid, secret), provenance: r.provenance ?? null }));
         }
         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.50.0",
+  "version": "0.53.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",