@supersuit/artifacts 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 `@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.21.0 (2026-10-08)
+
+**A page's past versions are for its admins.** Every reader who could open a page could also open
+its History and read every earlier version at `/<id>/v/<n>`, so a passage edited out of a page
+(a name taken out, a figure corrected) stayed readable one click away.
+
+- New config `admins` (sign-in emails) and `history: 'admins' | 'everyone'`. The default,
+  `'admins'`, shows the History control and serves `/<id>/v/<n>` only to a signed-in reader whose
+  email is `ownerEmail` or in `admins`, compared without case. To everyone else the control is
+  absent and a past version is not found. "Version N · Updated <minute>" still shows to everyone.
+- DETECTOR: after the bump, a reader who is not an admin no longer sees "History" under a page's
+  summary. A host that configures neither `ownerEmail` nor `admins` hides history from everyone.
+- REMEDY: pass `admins` (and `ownerEmail`) for the people who should keep seeing history, or
+  `history: 'everyone'` to keep the 0.20.0 behaviour.
+- Tests: signed out, a signed-in non-admin, the owner in another case and a listed admin, a past
+  version 404ing for non-admins, nobody configured, and `'everyone'` restoring the old page. The
+  earlier version and golden tests pin `history: 'everyone'`, so they still prove 0.20.0's page.
+
+## 0.20.0 (2026-10-07)
+
+**A host can hear when a confidential page is read.** The reader record answered `GET /reads`
+when asked and told nobody when it changed. One generic hook and one pure function close that,
+and the package still sends nothing anywhere.
+
+- New config `onReaderEvent(event)`: called after a reading heartbeat is recorded (`visit`),
+  after a signed-in person is refused at the door (`refused`, after the refusal is on the
+  record), and for every listed reader of every gated page when the host calls the new
+  `routes.sweepReaders()` (`sweep`, for a daily job). The event carries the page, the reader,
+  their `summary`, their list `entry` (with `addedAt`), and the page's `words` and `readSeconds`.
+  Awaited; anything it throws is swallowed.
+- New pure `readAlertsDue(...)` and helpers (`readSecondsFor`, `wordCount`, `localDay`, the
+  thresholds as constants): first-open, refused, finished (90% scroll AND a third of the reading
+  time at 230 wpm), came-back (a later local day), quiet (listed 3 to 14 days ago, never opened),
+  each once per reader per page, never for `ignore`d addresses. First-open and came-back only
+  fire within a day of the visit, so a host turning alerts on over old history is not flooded.
+- `ReaderSummary` gains `lastStarted`; `ReadersStore` gains optional `listed()` (the Firestore
+  store implements it), so a store written earlier still type-checks.
+- DETECTOR: a host that passes `onReaderEvent` and gets a type error is on 0.19.x.
+- REMEDY: bump. Nothing changes for a host that does not pass the hook: no extra reads, and a
+  refusal is recorded exactly as before.
+- Tests: every alert rule, its once-only guard, the ignore list, the local-day zone, the quiet
+  window; the hook's payload for a beat, a refusal (ordered after the flag) and a sweep; a
+  throwing or rejecting sink costs the reader nothing; no extra reads without the hook. Each rule
+  was broken on purpose and went red.
+
 ## 0.19.0 (2026-09-30)
 
 **A code block has a copy button, and it wraps.** Both were found on one page: an operator

package/README.md

@@ -123,6 +123,17 @@ phone, a side panel on a desk), so opening it moves no text. Each past version i
 the same password or confidential door as the page itself. A version that does not exist is a
 404; on a shut page the door comes first, so it never says which versions exist.
 
+**Past versions are for admins by default (0.21.0).** An earlier draft can hold what the current
+one was edited to remove, so only the page's admins see the History control or open
+`/<id>/v/<n>`: the reader signed in as `ownerEmail` or any address in `admins` (case does not
+matter). Everyone else still sees "Version N · Updated <minute>", and a past version is a 404 to
+them. With neither configured, nobody does. `history: 'everyone'` in the config restores the old
+behaviour, where every reader who can open the page reads its history.
+
+```ts
+createArtifactRoutes({ ..., ownerEmail: 'owner@example.com', admins: ['editor@example.com'] })
+```
+
 **Do not write a "Version history" section in the markdown.** Say what changed when you publish:
 
 - `POST /api/artifacts?id=<id>&note=<one line>`, or a `change:` line in the front matter. The query
@@ -215,6 +226,32 @@ name, says why they can read it, tiles their address as a faint watermark, and r
 time, scroll depth, and attempts to print, copy at length, or save. Refused sign-ins are
 recorded too, which is how a forwarded link shows up.
 
+### Knowing when it is read (`onReaderEvent`, `readAlertsDue`)
+
+The record answers when asked; `onReaderEvent` is how a host hears that it changed. It is called
+after a reading heartbeat is recorded (`kind: 'visit'`), after a signed-in person is refused at
+the door (`'refused'`, with the account they tried), and for every listed reader when the host
+calls `routes.sweepReaders()` from a daily job (`'sweep'`, so a host can notice a page nobody
+opened). Each event carries the page (id, title, url), the reader, their totals (`summary`, or
+null), their list entry (with `addedAt`), and the page's `words` and `readSeconds` at 230 words a
+minute. It is awaited and anything it throws is swallowed, so a broken sink never costs a reader
+their page. Without it nothing extra is read.
+
+The package sends nothing anywhere. `readAlertsDue({ sent, email, summary, refusedAttempt,
+readSeconds, now, addedAt, timeZone, ignore })` turns one event into the alerts worth sending,
+each at most once per reader per page (pass back what you already sent):
+
+| Kind | When |
+| --- | --- |
+| `first-open` | their first visit, within the last day |
+| `refused` | a refusal at the door, with the account tried |
+| `finished` | scrolled to 90% AND read for a third of the page's reading time |
+| `came-back` | a visit that began on a later local day (in `timeZone`) than the first |
+| `quiet` | listed 3 to 14 days ago and never opened |
+
+Addresses in `ignore` (the publisher's own) never alert. Where an alert goes, and how a host
+remembers what it sent, is the host's business.
+
 ### The reader pass (the contract with your sign-in side)
 
 This package does not sign anyone in. It sends readers to your sign-in authority and trusts a

package/lib/artifacts/index.d.ts

@@ -7,7 +7,8 @@ export { mintPublisherPass, verifyPublisherPass, PUBLISHER_PASS_TTL_SECONDS, typ
 export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS, type Access, type Reader, type AllowEntry, type Decision } from './reader.js';
-export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc } from './readers-store.js';
+export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc, type ReaderSummary } 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, 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 { stateView, responsesOf, responsesCsv, type SlotView, type Tally, type SharedEntry, type Response as StateResponse } from './state-view.js';

package/lib/artifacts/index.js

@@ -8,6 +8,7 @@ export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAM
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS } from './reader.js';
 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 { stateView, responsesOf, responsesCsv } from './state-view.js';

package/lib/artifacts/read-alerts.d.ts

@@ -0,0 +1,87 @@
+import type { ReaderSummary } from './readers-store.js';
+export declare const READ_ALERT_KINDS: readonly ["first-open", "refused", "finished", "came-back", "quiet"];
+export type ReadAlertKind = (typeof READ_ALERT_KINDS)[number];
+/** A normal adult reading pace, used to turn a page's word count into its reading time. */
+export declare const WORDS_PER_MINUTE = 230;
+/** How far down counts as reaching the end, in percent of the page. */
+export declare const FINISHED_SCROLL = 90;
+/** The share of the page's reading time a reader must actually spend for "finished". */
+export declare const FINISHED_SHARE: number;
+/** Days after a reader is listed before an unopened page earns one nudge. */
+export declare const QUIET_AFTER_DAYS = 3;
+/** Past this many days after listing, a never-opened page stays silent: a sweep run for the first
+ *  time over an old list must not nudge about pages everyone has long forgotten. */
+export declare const QUIET_WINDOW_DAYS = 14;
+/** First-open and came-back describe something that just happened. A record older than this
+ *  (a host turning alerts on over months of history) is not news, and does not alert. */
+export declare const FRESH_HOURS = 24;
+/** Words a reader reads: whitespace-separated tokens. */
+export declare function wordCount(text: string): number;
+/** Seconds a page takes to read at `wpm`. */
+export declare function readSecondsFor(words: number, wpm?: number): number;
+/** The calendar day an instant falls on in `timeZone`, as YYYY-MM-DD. An unknown zone reads as UTC
+ *  rather than throwing, because a bad zone must never swallow an alert. */
+export declare function localDay(at: string | Date, timeZone?: string): string;
+export type ReadAlertInput = {
+    /** The kinds already sent for this reader on this page. */
+    sent: Iterable<ReadAlertKind>;
+    /** The reader the record is about: the account that read, or the account that was refused. */
+    email: string;
+    /** Their totals on this page (from `summarize`), or null when they have never opened it. */
+    summary?: Pick<ReaderSummary, 'sessions' | 'activeSeconds' | 'maxScroll' | 'firstSeen' | 'lastSeen'> & {
+        lastStarted?: string;
+    } | null;
+    /** True when this evaluation is for a refusal at the door that just happened. */
+    refusedAttempt?: boolean;
+    /** The page's reading time in seconds (`readSecondsFor`). Zero or absent: reaching the end is enough. */
+    readSeconds?: number;
+    now: string | Date;
+    /** When the reader was put on the page's list (AllowEntry.addedAt). Needed for quiet. */
+    addedAt?: string;
+    /** The zone "a later day" is judged in. Default UTC. */
+    timeZone?: string;
+    /** Addresses whose reads never alert: the publisher, the owners. Compared case-insensitively. */
+    ignore?: Iterable<string>;
+    quietAfterDays?: number;
+};
+export type ReadAlert = {
+    kind: ReadAlertKind;
+    email: string;
+    sessions: number;
+    activeSeconds: number;
+    maxScroll: number;
+    /** quiet only: whole days since the reader was listed. */
+    daysSinceAdded?: number;
+};
+/** The alerts due for one reader on one page, given what was already sent. Pure. */
+export declare function readAlertsDue(input: ReadAlertInput): ReadAlert[];
+/** What `onReaderEvent` hands a host: one reader's state on one gated page, just after it changed.
+ *
+ *  - `visit`: a reading heartbeat was recorded (`summary` is their record so far).
+ *  - `refused`: a signed-in person was turned away at the door (`reader` is the account tried).
+ *  - `sweep`: a listed reader, visited by `sweepReaders()` (a daily job) whether or not anything
+ *    changed, so a host can notice what did NOT happen (quiet). */
+export type ReaderEvent = {
+    kind: 'visit' | 'refused' | 'sweep';
+    artifactId: string;
+    title: string;
+    /** The page's address, e.g. https://artifacts.example.com/abc23456. */
+    url: string;
+    reader: {
+        email: string;
+        name: string | null;
+    };
+    /** Their totals on this page, or null when they have never opened it. */
+    summary: ReaderSummary | null;
+    /** Their list entry on this page, or null (a member reading by membership, or a refusal). */
+    entry: {
+        email: string;
+        name?: string;
+        addedAt?: string;
+    } | null;
+    /** Words a reader reads on the page, and the seconds that takes at WORDS_PER_MINUTE. */
+    words: number;
+    readSeconds: number;
+    /** When the event happened, ISO. */
+    at: string;
+};

package/lib/artifacts/read-alerts.js

@@ -0,0 +1,75 @@
+export const READ_ALERT_KINDS = ['first-open', 'refused', 'finished', 'came-back', 'quiet'];
+/** A normal adult reading pace, used to turn a page's word count into its reading time. */
+export const WORDS_PER_MINUTE = 230;
+/** How far down counts as reaching the end, in percent of the page. */
+export const FINISHED_SCROLL = 90;
+/** The share of the page's reading time a reader must actually spend for "finished". */
+export const FINISHED_SHARE = 1 / 3;
+/** Days after a reader is listed before an unopened page earns one nudge. */
+export const QUIET_AFTER_DAYS = 3;
+/** Past this many days after listing, a never-opened page stays silent: a sweep run for the first
+ *  time over an old list must not nudge about pages everyone has long forgotten. */
+export const QUIET_WINDOW_DAYS = 14;
+/** First-open and came-back describe something that just happened. A record older than this
+ *  (a host turning alerts on over months of history) is not news, and does not alert. */
+export const FRESH_HOURS = 24;
+const DAY_MS = 86_400_000;
+const HOUR_MS = 3_600_000;
+/** Words a reader reads: whitespace-separated tokens. */
+export function wordCount(text) {
+    const t = text.trim();
+    return t ? t.split(/\s+/).length : 0;
+}
+/** Seconds a page takes to read at `wpm`. */
+export function readSecondsFor(words, wpm = WORDS_PER_MINUTE) {
+    return words > 0 ? Math.round((words / wpm) * 60) : 0;
+}
+/** The calendar day an instant falls on in `timeZone`, as YYYY-MM-DD. An unknown zone reads as UTC
+ *  rather than throwing, because a bad zone must never swallow an alert. */
+export function localDay(at, timeZone = 'UTC') {
+    const d = typeof at === 'string' ? new Date(at) : at;
+    try {
+        return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(d);
+    }
+    catch {
+        return d.toISOString().slice(0, 10);
+    }
+}
+/** The alerts due for one reader on one page, given what was already sent. Pure. */
+export function readAlertsDue(input) {
+    const email = input.email.trim().toLowerCase();
+    const ignore = new Set([...(input.ignore ?? [])].map((e) => e.trim().toLowerCase()).filter(Boolean));
+    if (!email || ignore.has(email))
+        return [];
+    const sent = new Set(input.sent);
+    const now = (typeof input.now === 'string' ? new Date(input.now) : input.now).getTime();
+    const s = input.summary && input.summary.sessions > 0 ? input.summary : null;
+    const base = { email, sessions: s?.sessions ?? 0, activeSeconds: s?.activeSeconds ?? 0, maxScroll: s?.maxScroll ?? 0 };
+    const fresh = (at) => !!at && now - new Date(at).getTime() <= FRESH_HOURS * HOUR_MS;
+    const out = [];
+    if (input.refusedAttempt) {
+        if (!sent.has('refused'))
+            out.push({ kind: 'refused', ...base });
+        return out;
+    }
+    if (s) {
+        if (!sent.has('first-open') && fresh(s.firstSeen))
+            out.push({ kind: 'first-open', ...base });
+        const started = s.lastStarted;
+        const zone = input.timeZone ?? 'UTC';
+        if (!sent.has('came-back') && started && fresh(started) && localDay(started, zone) > localDay(s.firstSeen, zone))
+            out.push({ kind: 'came-back', ...base });
+        const need = (input.readSeconds ?? 0) * FINISHED_SHARE;
+        if (!sent.has('finished') && s.maxScroll >= FINISHED_SCROLL && s.activeSeconds >= need)
+            out.push({ kind: 'finished', ...base });
+        return out;
+    }
+    // Never opened. One nudge, once, inside the window, and never after any open has been told.
+    if (input.addedAt && !sent.has('quiet') && !sent.has('first-open')) {
+        const days = (now - new Date(input.addedAt).getTime()) / DAY_MS;
+        const after = input.quietAfterDays ?? QUIET_AFTER_DAYS;
+        if (days >= after && days < QUIET_WINDOW_DAYS)
+            out.push({ kind: 'quiet', ...base, daysSinceAdded: Math.floor(days) });
+    }
+    return out;
+}

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

@@ -61,6 +61,12 @@ export interface ReadersStore {
     }): Promise<void>;
     sessions(artifactId: string): Promise<SessionDoc[]>;
     flags(artifactId: string): Promise<FlagDoc[]>;
+    /** Every page that has a list, with its list: what a daily sweep walks. Optional, so a store
+     *  written before 0.20.0 still satisfies the interface; without it the sweep finds nothing. */
+    listed?(): Promise<{
+        artifactId: string;
+        readers: AllowEntry[];
+    }[]>;
 }
 export declare function createReadersStore(db: Firestore, base: string): ReadersStore;
 export type ReaderSummary = {
@@ -72,6 +78,8 @@ export type ReaderSummary = {
     maxScroll: number;
     firstSeen: string;
     lastSeen: string;
+    /** When their most recent visit began. Later than `firstSeen`'s day means they came back. */
+    lastStarted: string;
     flags: {
         kind: FlagKind;
         at: string;

package/lib/artifacts/readers-store.js

@@ -104,6 +104,10 @@ export function createReadersStore(db, base) {
             const snap = await flags().where('artifactId', '==', artifactId).get();
             return snap.docs.map((d) => d.data());
         },
+        async listed() {
+            const snap = await access().get();
+            return snap.docs.map((d) => ({ artifactId: d.id, readers: listOf(d.data()) })).filter((p) => p.readers.length > 0);
+        },
     };
 }
 /** Per-reader totals for one page, most recently seen first, plus everyone refused at the door. */
@@ -112,7 +116,7 @@ export function summarize(sessionDocs, flagDocs) {
     for (const s of sessionDocs) {
         const r = by.get(s.email) ?? {
             email: s.email, name: s.name, member: s.member, sessions: 0, activeSeconds: 0, maxScroll: 0,
-            firstSeen: s.startedAt, lastSeen: s.lastAt, flags: [],
+            firstSeen: s.startedAt, lastSeen: s.lastAt, lastStarted: s.startedAt, flags: [],
         };
         r.sessions += 1;
         r.activeSeconds += s.activeSeconds ?? 0;
@@ -121,6 +125,8 @@ export function summarize(sessionDocs, flagDocs) {
             r.firstSeen = s.startedAt;
         if (s.lastAt > r.lastSeen)
             r.lastSeen = s.lastAt;
+        if (s.startedAt > r.lastStarted)
+            r.lastStarted = s.startedAt;
         by.set(s.email, r);
     }
     const refused = new Map();

package/lib/routes/artifacts.d.ts

@@ -6,6 +6,7 @@ import { type ArtifactAssets } from '../artifacts/assets.js';
 import type { BrandPack } from '../brand/pack.js';
 import { type Access } from '../artifacts/reader.js';
 import { type ReadersStore } from '../artifacts/readers-store.js';
+import { type ReaderEvent } from '../artifacts/read-alerts.js';
 import type { PersonalStore } from '../artifacts/personal-store.js';
 import type { Transcriber } from '../artifacts/transcribe.js';
 export type ArtifactRoutesConfig = {
@@ -63,11 +64,26 @@ export type ArtifactRoutesConfig = {
      *  its writer's name, whatever `comments_visible:` says. Without it nobody is the owner, and
      *  the publisher reads comments through /responses. */
     ownerEmail?: string;
+    /** Sign-in emails, besides `ownerEmail`, of the people who administer this host's pages. They
+     *  see a page's version history; with `history: 'admins'` (the default) nobody else does. */
+    admins?: readonly string[];
+    /** Who sees a page's past versions: the History control under the summary and every
+     *  `/<id>/v/<n>`. `'admins'` (default): only `ownerEmail` and `admins`, signed in; to everyone
+     *  else the History control is absent and a past version is not found, because an earlier draft
+     *  can hold what the current one was edited to remove. `'everyone'`: every reader who can open
+     *  the page, which was the only behaviour before 0.21.0. */
+    history?: 'admins' | 'everyone';
     /** Turns a reader's voice memo into text on the server, so the service's key never reaches a
      *  browser: `deepgramTranscriber(key)` or `openaiTranscriber(key)` from `./artifacts`, or your
      *  own. Without it the transcribe route answers 404 and readers get the browser's live
      *  transcript, or an empty box to type into. */
     transcribe?: Transcriber;
+    /** Told when a reader's state on a gated page changes: after a reading heartbeat is recorded,
+     *  after a signed-in person is refused at the door, and for every listed reader when the host
+     *  runs `sweepReaders()`. The host decides what, if anything, to do (`readAlertsDue` turns an
+     *  event into the alerts worth sending). Awaited, and anything it throws is swallowed: a broken
+     *  sink never costs a reader their page or their record. Without it nothing extra is read. */
+    onReaderEvent?: (event: ReaderEvent) => void | Promise<void>;
 };
 /** 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;
@@ -193,7 +209,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
             name: string | null;
             at: string;
         }[];
-        readers: import("../artifacts/readers-store.js").ReaderSummary[];
+        readers: import("../index.js").ReaderSummary[];
         refused: {
             email: string;
             name: string | null;
@@ -205,6 +221,10 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         access: Access | null;
         views: number;
     }>>;
+    sweepReaders: () => Promise<{
+        pages: number;
+        readers: number;
+    }>;
     TRANSCRIBE: (req: NextRequest, { params }: {
         params: Promise<{
             id: string;

package/lib/routes/artifacts.js

@@ -23,6 +23,7 @@ import { UpdatedTime } from '../reader/updated-time.js';
 import { VersionHistory } from '../reader/version-history.js';
 import { ACCESS_LEVELS, GRANT_COOKIE, GRANT_TTL_SECONDS, decide, firstName, mintGrant, safeReturnPath, signInUrl, verifyGrant, verifyPass, } from '../artifacts/reader.js';
 import { FLAG_KINDS, summarize } from '../artifacts/readers-store.js';
+import { readSecondsFor, wordCount } from '../artifacts/read-alerts.js';
 import { AckDoor, ConfidentialBanner, NO_PRINT_CSS, NotAllowedDoor, SignInDoor, Watermark, ackText } from '../artifacts/confidential.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
@@ -59,6 +60,9 @@ export function createArtifactRoutes(config) {
     const signInOrigin = config.signInOrigin;
     const owner = config.owner ?? brand.name;
     const ownerEmail = config.ownerEmail?.trim().toLowerCase();
+    const admins = new Set([ownerEmail, ...(config.admins ?? []).map((e) => e.trim().toLowerCase())].filter((e) => !!e));
+    /** Whether this reader may see a page's past versions (config `history`). */
+    const seesHistory = (reader) => config.history === 'everyone' || (!!reader && admins.has(reader.email.trim().toLowerCase()));
     const readerSecret = () => config.readerSecret?.();
     const signOutUrl = (id) => `/api/reader/leave?to=${encodeURIComponent(pagePath(id))}`;
     // Signing out alone cannot change the account: the authority still holds the Google session
@@ -80,6 +84,58 @@ export function createArtifactRoutes(config) {
         store, state: config.state, personal: config.personal, readers: config.readers, assets: config.assets, transcribe: config.transcribe,
         readerSecret, pageUrl, signInOrigin, siteUrl, clientIp: config.clientIp,
     });
+    // ---- Reader events (onReaderEvent). Nothing here runs, and nothing extra is read, without it.
+    const wordsCache = new Map();
+    /** Words a reader reads on the page, cached per version so a heartbeat does not re-parse it. */
+    function wordsOf(a) {
+        const c = wordsCache.get(a.id);
+        if (c && c.updatedAt === a.updatedAt)
+            return c.words;
+        const words = wordCount(narrationText(a));
+        wordsCache.set(a.id, { updatedAt: a.updatedAt, words });
+        return words;
+    }
+    const same = (x, y) => x.trim().toLowerCase() === y.trim().toLowerCase();
+    async function emitReaderEvent(e, a) {
+        if (!config.onReaderEvent)
+            return;
+        try {
+            const words = wordsOf(a);
+            await config.onReaderEvent({ ...e, artifactId: a.id, title: a.title, url: pageUrl(a.id), words, readSeconds: readSecondsFor(words), at: new Date().toISOString() });
+        }
+        catch {
+            // A broken sink never costs a reader their page or their record.
+        }
+    }
+    /** One reader's record on one page, read fresh, for an event. */
+    async function readerSummary(id, email) {
+        const [sessions, flags] = await Promise.all([config.readers.sessions(id), config.readers.flags(id)]);
+        return summarize(sessions, flags).readers.find((r) => same(r.email, email)) ?? null;
+    }
+    /** Tell `onReaderEvent` about every listed reader of every gated page, opened or not, so a host
+     *  can notice what has NOT happened (a page nobody opened). Run it from a daily job. Needs a
+     *  readers store with `listed()`; without one, or without the hook, it does nothing. */
+    async function sweepReaders() {
+        const readers = config.readers;
+        if (!config.onReaderEvent || !readers?.listed)
+            return { pages: 0, readers: 0 };
+        let pages = 0;
+        let count = 0;
+        for (const p of await readers.listed()) {
+            const a = ARTIFACT_ID.test(p.artifactId) ? await store.get(p.artifactId) : null;
+            if (!a?.access)
+                continue;
+            pages += 1;
+            const [sessions, flags] = await Promise.all([readers.sessions(a.id), readers.flags(a.id)]);
+            const sums = summarize(sessions, flags).readers;
+            for (const entry of p.readers) {
+                const summary = sums.find((r) => same(r.email, entry.email)) ?? null;
+                await emitReaderEvent({ kind: 'sweep', reader: { email: entry.email, name: entry.name ?? summary?.name ?? null }, summary, entry }, a);
+                count += 1;
+            }
+        }
+        return { pages, readers: count };
+    }
     /** The kicker over every title: the pack's line, then who the page is for. Never spoken: the
      *  whole paragraph is data-nospeak, and narrationText has no `to` to read. */
     function Kicker({ to, brand }) {
@@ -142,7 +198,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 }));
+        const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top, reader }));
         if (a.access)
             return GatedPage(a, id, render, n);
         // A password shuts the body, never the title: the header stays so the reader knows which
@@ -190,8 +246,14 @@ export function createArtifactRoutes(config) {
         const d = config.readers ? decide(a.access, reader, allow) : { open: false, why: 'signed-out' };
         const header = (_jsxs("div", { className: "mx-auto max-w-2xl px-6 pt-24 pb-8 text-center sm:pt-28", children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary })] }));
         if (!d.open) {
-            if (d.why === 'not-allowed' && config.readers)
-                void config.readers.flag({ artifactId: id, reader: d.reader, kind: 'refused' }).catch(() => { });
+            if (d.why === 'not-allowed' && config.readers) {
+                const flagged = config.readers.flag({ artifactId: id, reader: d.reader, kind: 'refused' }).catch(() => { });
+                // Told after the refusal is on the record, so a sink that reads it back finds it.
+                if (config.onReaderEvent)
+                    await flagged.then(() => emitReaderEvent({ kind: 'refused', reader: { email: d.reader.email, name: d.reader.name }, summary: null, entry: null }, a));
+                else
+                    void flagged;
+            }
             return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [header, d.why === 'not-allowed'
                         ? _jsx(NotAllowedDoor, { brand: brand, reader: d.reader, signOutUrl: switchUrl(id) })
                         : _jsx(SignInDoor, { brand: brand, href: signInOrigin ? signInUrl(signInOrigin, here) : undefined, note: config.signInNote })] }));
@@ -214,8 +276,8 @@ export function createArtifactRoutes(config) {
         return store.history(id).catch(() => null);
     }
     /** "Version N · Updated <minute> · History": the line under the summary. */
-    function VersionLine({ a, n, at, history }) {
-        return (_jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-60", children: [`Version ${n} · Updated `, _jsx(UpdatedTime, { iso: at }), history && history.length > 1 ? (_jsxs(_Fragment, { children: [' · ', _jsx(VersionHistory, { items: history, base: pagePath(a.id), viewing: n })] })) : null] }));
+    function VersionLine({ a, n, at, history, reader }) {
+        return (_jsxs("p", { "data-nospeak": true, className: "mt-4 text-xs opacity-60", children: [`Version ${n} · Updated `, _jsx(UpdatedTime, { iso: at }), history && history.length > 1 && seesHistory(reader) ? (_jsxs(_Fragment, { children: [' · ', _jsx(VersionHistory, { items: history, base: pagePath(a.id), viewing: n })] })) : null] }));
     }
     /** The title block and the body, in the pack's Article when it has one. Without one this is
      *  exactly the markup every page had before packs could frame it. */
@@ -225,8 +287,11 @@ export function createArtifactRoutes(config) {
         return (_jsxs(_Fragment, { children: [cover, _jsxs("article", { className: "mx-auto max-w-2xl px-6 pb-24", children: [toc, children] })] }));
     }
     /** A past version: its own body and title, read-only (no narration, no answers), under a banner. */
-    async function VersionBody(a, n, { top }) {
+    async function VersionBody(a, n, { top, reader }) {
         const { pack, brand } = lookOf(a);
+        // Past versions are for admins unless the host says otherwise: to anyone else none exists.
+        if (!seesHistory(reader))
+            notFound();
         const v = store.version ? await store.version(a.id, n) : null;
         if (!v)
             notFound();
@@ -237,7 +302,7 @@ export function createArtifactRoutes(config) {
         const title = v.title ?? a.title;
         const summary = v.summary ?? a.summary;
         const toc = showToc(v.markdown, a.toc) ? tocOf(v.markdown) : [];
-        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions, Section: pack.Section, figure: pack.figure }) })] }));
+        return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { "data-nospeak": true, className: `mx-auto max-w-2xl px-6 ${top ? 'pt-20 sm:pt-24' : 'pt-8'}`, children: _jsxs("p", { "data-version-banner": true, role: "status", className: "rounded-lg border px-4 py-3 text-sm", style: { borderColor: brand.accent }, children: [`You are reading version ${n} of ${of}. `, _jsx("a", { href: pagePath(a.id), className: "underline underline-offset-4", style: { color: brand.accent }, children: "Read the current version" })] }) }), _jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: pack.Cover ? (_jsx(pack.Cover, { title: title, subtitle: v.subtitle, summary: summary, to: v.to, markdown: v.markdown, kicker: _jsx(Kicker, { to: v.to, brand: brand }), meta: _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader }), version: n, updatedAt: v.at, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-10 sm:pt-12' : 'pt-10'} pb-8 text-center`, children: [_jsx(Kicker, { to: v.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: title }), v.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: v.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: summary }), _jsx(VersionLine, { a: a, n: n, at: v.at, history: history, reader: reader })] })), children: _jsx(ArtifactMarkdown, { markdown: v.markdown, definitions: a.definitions, Section: pack.Section, figure: pack.figure }) })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader }) {
@@ -258,7 +323,7 @@ export function createArtifactRoutes(config) {
         const mode = config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
         return (_jsxs(_Fragment, { children: [toc.length ? _jsx(TocRail, { items: toc }) : null, _jsx("div", { id: "artifact-narration-root", children: await (async () => {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
-                        const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { a: a, n: n, at: a.updatedAt, history: await historyOf(a.id) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
+                        const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { a: a, n: n, at: a.updatedAt, history: await historyOf(a.id), reader: reader }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), meta] }));
                         return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, Section: pack.Section, figure: pack.figure }) }));
                     })() }), _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: !!reader && !!ownerEmail && reader.email === ownerEmail, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", label: brand.narratorLabel(a.voice), accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
@@ -337,7 +402,8 @@ export function createArtifactRoutes(config) {
         const a = await store.get(id);
         if (!a?.access)
             return new NextResponse(null, { status: 404 });
-        if (!decide(a.access, reader, await config.readers.allowList(id)).open)
+        const allow = await config.readers.allowList(id);
+        if (!decide(a.access, reader, allow).open)
             return new NextResponse(null, { status: 403 });
         const country = request.headers.get('x-vercel-ip-country') ?? undefined;
         if (b.kind === 'beat') {
@@ -345,6 +411,11 @@ export function createArtifactRoutes(config) {
             const scroll = Math.max(0, Math.min(100, Math.round(Number(b.scroll) || 0)));
             const device = /Mobi|Android|iPhone|iPad/i.test(request.headers.get('user-agent') ?? '') ? 'mobile' : 'desktop';
             await config.readers.touchSession({ artifactId: id, session, reader, addSeconds: add, scroll, device, country });
+            if (config.onReaderEvent) {
+                const summary = await readerSummary(id, reader.email).catch(() => null);
+                const entry = allow.find((e) => same(e.email, reader.email)) ?? null;
+                await emitReaderEvent({ kind: 'visit', reader: { email: reader.email, name: reader.name }, summary, entry }, a);
+            }
             return new NextResponse(null, { status: 204 });
         }
         if (b.kind === 'flag' && FLAG_KINDS.includes(b.flag) && b.flag !== 'refused') {
@@ -572,5 +643,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.19.0",
+  "version": "0.21.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",