@supersuit/artifacts 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -3,6 +3,59 @@
 `@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.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
+published a setup page to open on somebody else's laptop, where a paste-in briefing WAS the page,
+and there was nothing to press and nothing readable to select. The block rendered 9,089px wide
+with every line clipped at the right edge, because a fence here usually holds prose written as
+one long line per paragraph and `white-space: pre` does not wrap those.
+
+`render.test.tsx` had a case called *gives fenced code a copy affordance* that only ever checked
+for the `data-artifact-code` attribute the affordance would hang on, so the host shipped with the
+hook and no button and the suite stayed green.
+
+- New client component `CodeCopy` (`reader/code-copy.js`), mounted by `ArtifactMarkdown` only when
+  the markdown holds a fence. It reads the `<code>`, never `pre.textContent`, so its own label
+  does not land in the paste, and it falls back to a hidden textarea where `navigator.clipboard`
+  is undefined, which is any page served over plain http.
+- Fences render `whitespace-pre-wrap [overflow-wrap:anywhere]` with `pr-16` to clear the button.
+  Soft wrapping inserts no characters, so what a reader copies is byte for byte what was written.
+- DETECTOR: open any page with a fenced block. No button in its top-right corner, or a long line
+  running off the right edge, means this version is not deployed.
+- REMEDY: bump.
+- Tests: one copy button per block and it copies that block; the label stays out of the paste;
+  the no-clipboard fallback; nothing added twice and everything removed on unmount; the fence
+  carries `whitespace-pre-wrap`; and the mount happens only when a fence is present. The wrap
+  test is red against 0.18.1.
+
 ## 0.18.1 (2026-09-29)
 
 **On a phone, the Comment button sits at the top of the screen.** It used to appear just under

package/README.md

@@ -215,6 +215,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/artifacts/render.js

@@ -13,6 +13,7 @@ import { unified } from 'unified';
 import { blocksOf, hasNotesWidget, headingsOf } from './widgets.js';
 import { HeadingNotes, NoteToggle, NotesEarlier, NotesProvider } from '../widgets/notes.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
+import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
 import { remarkDefinitions } from './definitions.js';
 // Every colour is a theme variable (brand/theme.ts), so a page follows its light, dark or system mode.
@@ -66,6 +67,9 @@ const VIDEO = /\.mp4(?:[?#].*)?$/i;
  *  nothing until one is pressed. The alt is its caption, shown above the player. */
 const AUDIO = /\.mp3(?:[?#].*)?$/i;
 const VIDEO_IN_MD = /\]\([^)\s]+\.mp4(?:[?#][^)]*)?\)/i;
+// A fenced block, which `links` and `notes` fences are too; mounting for those costs one
+// no-op effect and is cheaper than parsing the markdown twice to find out.
+const CODE_IN_MD = /^```/m;
 const escapeAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 // Written as markup, not JSX: React renders `muted` as a property and leaves it out of server
 // HTML, and iOS refuses to play a video unprompted whose markup is not muted. `playsinline` keeps
@@ -134,7 +138,13 @@ function baseComponents(block, figure) {
             const cls = inner?.props?.className ?? '';
             if (/language-(links|notes)/.test(cls))
                 return _jsx(_Fragment, { children: children });
-            return (_jsx("pre", { ...block(node), "data-artifact-code": true, className: "my-6 overflow-x-auto rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-code)] p-4 text-sm text-[color:var(--a-strong)]", children: children }));
+            return (_jsx("pre", { ...block(node), "data-artifact-code": true, 
+                // whitespace-pre-wrap, because a fence here usually holds PROSE meant to be pasted
+                // somewhere, written as one long line per paragraph. Under `pre` those lines do not
+                // wrap: a 7 KB briefing rendered as a box 9,089px wide with every line clipped at the
+                // right edge (2026-09-30). Soft wrapping inserts no characters, so what the reader
+                // copies is still byte for byte what the author wrote.
+                className: "my-6 overflow-x-auto whitespace-pre-wrap [overflow-wrap:anywhere] rounded-lg border border-[color:var(--a-line)] bg-[color:var(--a-code)] p-4 pr-16 text-sm text-[color:var(--a-strong)]", children: children }));
         },
         blockquote: ({ node, children }) => {
             const t = textOf(children).trim();
@@ -268,5 +278,5 @@ export function ArtifactMarkdown({ markdown, notes, definitions, Section, figure
     const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, children: markdown }));
     return (
     // break-words: a bare URL in prose is one unbreakable word and pushed phones 7px sideways (2026-09-26).
-    _jsxs("div", { className: "break-words text-[17px] text-[color:var(--a-body)]", children: [on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body, VIDEO_IN_MD.test(markdown) ? _jsx(VideoAutoplay, {}) : null, defined ? (_jsxs(_Fragment, { children: [_jsx("style", { children: DEFINED_TERM_CSS }), _jsx(DefinitionLayer, {})] })) : null] }));
+    _jsxs("div", { className: "break-words text-[17px] text-[color:var(--a-body)]", children: [on ? (_jsx(NotesProvider, { artifactId: notes.artifactId, headings: headings.map(({ slug, text }) => ({ slug, text })), accent: notes.accent, children: body })) : body, VIDEO_IN_MD.test(markdown) ? _jsx(VideoAutoplay, {}) : null, CODE_IN_MD.test(markdown) ? _jsx(CodeCopy, {}) : null, defined ? (_jsxs(_Fragment, { children: [_jsx("style", { children: DEFINED_TERM_CSS }), _jsx(DefinitionLayer, {})] })) : null] }));
 }

package/lib/reader/code-copy.d.ts

@@ -0,0 +1 @@
+export declare function CodeCopy(): null;

package/lib/reader/code-copy.js

@@ -0,0 +1,77 @@
+'use client';
+// A copy button on every code block, and it is the point of a code block here rather than a
+// convenience on top of it. This host's fences mostly hold something the reader is meant to
+// PUT somewhere: a command to run, a prompt to paste into their own agent. Until now the only
+// way to take one was to select it by hand, and on a phone, inside a horizontally scrolling
+// box, that is most of a minute of fighting the selection handles.
+//
+// Earned 2026-09-30: an operator published a setup page to open on somebody else's laptop,
+// with the paste-in block as the whole reason the page existed, and there was nothing to press.
+import { useEffect } from 'react';
+const COPY = 'Copy';
+const DONE = 'Copied';
+export function CodeCopy() {
+    useEffect(() => {
+        const pres = Array.from(document.querySelectorAll('pre[data-artifact-code]'));
+        const timers = [];
+        const added = [];
+        for (const pre of pres) {
+            if (pre.querySelector('[data-artifact-copy]'))
+                continue;
+            // The button is positioned against the pre, so the pre becomes the containing block. It
+            // is set here rather than in the class list because the server render must stay valid
+            // with no JavaScript: a page with this component disabled shows a plain block.
+            pre.style.position = 'relative';
+            const btn = document.createElement('button');
+            btn.type = 'button';
+            btn.dataset.artifactCopy = 'true';
+            btn.textContent = COPY;
+            btn.setAttribute('aria-label', 'Copy this block');
+            btn.className =
+                'absolute right-2 top-2 rounded-md border px-2 py-1 text-xs opacity-70 ' +
+                    'transition hover:opacity-100 focus-visible:opacity-100';
+            btn.style.borderColor = 'var(--a-line)';
+            btn.style.color = 'var(--a-strong)';
+            btn.style.background = 'var(--a-code)';
+            btn.addEventListener('click', () => {
+                // The button lives inside the pre, so its own label would be copied with the code.
+                const code = pre.querySelector('code');
+                const text = (code ?? pre).textContent ?? '';
+                const done = () => {
+                    btn.textContent = DONE;
+                    timers.push(setTimeout(() => { btn.textContent = COPY; }, 1600));
+                };
+                // navigator.clipboard is undefined on a page served over plain http, which is every
+                // local preview, so the textarea path is a real fallback rather than old-browser
+                // defensiveness.
+                if (navigator.clipboard?.writeText) {
+                    navigator.clipboard.writeText(text).then(done, () => { btn.textContent = 'Press to select'; });
+                    return;
+                }
+                const ta = document.createElement('textarea');
+                ta.value = text;
+                ta.style.position = 'fixed';
+                ta.style.opacity = '0';
+                document.body.appendChild(ta);
+                ta.select();
+                try {
+                    document.execCommand('copy');
+                    done();
+                }
+                catch {
+                    btn.textContent = 'Press to select';
+                }
+                ta.remove();
+            });
+            pre.appendChild(btn);
+            added.push(btn);
+        }
+        return () => {
+            for (const t of timers)
+                clearTimeout(t);
+            for (const b of added)
+                b.remove();
+        };
+    }, []);
+    return null;
+}

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 = {
@@ -68,6 +69,12 @@ export type ArtifactRoutesConfig = {
      *  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 +200,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 +212,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';
@@ -80,6 +81,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 }) {
@@ -190,8 +243,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 })] }));
@@ -337,7 +396,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 +405,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 +637,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.18.1",
+  "version": "0.20.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",