@supersuit/artifacts 0.60.1 → 0.61.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 `@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.61.0 (2026-11-08)
+
+**Send outcomes: one success indicator for any send** (issue #12, item 1, and outcomes). A page declares a `goal` (`read` by default, `respond`, `ack`, or `{ click: <cta id> }`); a link titled `cta:<id>` is a CTA whose press the page records through `POST /seen` (`event: click`, under the beat, refused for an id the page does not carry); and every reader's line in `GET /views` and `summarizeViews` gains `lastOpenAt`, `sessions`, `opens`, `clicks`, `goal`, `outcome` (`not-opened`, `opened`, `read`, `returned`, `acted`), `succeeded` and `daysSinceSent`, all under the before-send rule. Thresholds are exported (`OUTCOME_READ_SECONDS` 30, `OUTCOME_RETURN_GAP_MS` one hour) and a host overrides them with `outcomeThresholds` on the routes, `summarizeViews`'s fourth argument, or `?readSeconds=` on `/views`. `ack` is new: the only acknowledgement before was the confidential page's agreement, keyed to a signed-in email, which a per-reader page cannot carry, so `ack` is a press of the CTA named `ack`. `GET /api/artifacts/<id>` answers `goal`. Existing fields are unchanged; a page with no goal reads as `read`; a view stored before clicks reads as none.
+
+- DETECTOR: `GET /views` rows carry no `outcome`; `goal:` in front matter is refused as an unknown key.
+- REMEDY: update. Nothing to configure. Add `goal:` to a page, and `"cta:<id>"` titles to the links that are its CTAs.
+- TESTS: `src/artifacts/outcomes.test.ts` (goal parsing and refusals, thresholds, clicks stored, a render before the send never counted, a second session on a known device counted as returned, each goal reaching and missing success, host thresholds), `src/routes/outcomes.test.tsx` (the click signal and its refusals, `/views` fields and thresholds by config and query, `GET` goal, the CTA link markup), `store.test.ts` (goal persisted and cleared), `quiet-view.test.tsx` (the page sends clicks, waiting for the beat), `index.test.ts` (exports). `seen.test.tsx`'s unknown-event case now uses `hover`, since `click` is known.
+
 ## 0.60.1 (2026-11-06)
 
 **The golden default page carries the viewer's image mark.** The 0.60.0 tag never reached npm: its publish run failed on `unchanged-default.test.tsx`, because every image now carries `data-artifact-image`. That attribute is the only difference in the regenerated golden. 0.60.1 is the first published version with the full screen viewer below.

package/README.md

@@ -311,6 +311,7 @@ summary: Three bets, what each costs, and what we stop doing to afford them.
 | `comment_name` | `required`: on a per-reader page, a comment through a group link needs a typed first name, and each browser on a group link is its own reader (see Per-reader links). Needs `links: per-reader` |
 | `forward` | `off`, `signed-in` or `open`: whether a reader of a per-reader page may make a link to pass it on (see Forward links). Absent is `off`. Needs `links: per-reader`. Sticky like `links` |
 | `history` | `everyone` or `admins`: who sees this page's version number and past versions, overriding the host's `history` for this one page (see Version history). Absent, the host decides. Refused as `everyone` on a per-reader page |
+| `goal` | What a send of the page is for: `read` (the default), `respond`, `ack`, or `click: <cta id>` (see Send outcomes). A republish without the line goes back to `read` |
 | `change` | One line saying what this version changed (see Version history) |
 | `template` | `document` (the default, the read-along reader) or `broadcast` (one message card sent to several people; see Broadcasts) |
 
@@ -1071,8 +1072,8 @@ Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `
 |---|---|---|
 | `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?, 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 |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments, `sentAt`, `beforeSend` and `provenance`, plus each send's outcome (see Send outcomes). 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: a view, beats, plays, and CTA clicks |
 
 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.
 
@@ -1233,6 +1234,74 @@ any stored entry in any slot, and a browser that removes its only entry and writ
 one shared reader, and every note left per browser stops being shown to its writer: the notes stay with
 the publisher, under their per-browser keys.
 
+### Send outcomes (Unreleased)
+
+One send is one page to one reader. Every reader's line in `GET /views` (and every row
+`summarizeViews` returns) says how far that send got, on one ladder that works for any page, so a
+host can draw each send in the column where it landed without reimplementing anything.
+
+**The page says what a send is for**, in front matter:
+
+```markdown
+---
+title: Next week
+summary: Two times that work.
+links: per-reader
+goal:
+  click: book-call
+---
+Pick one: [Book a call](https://cal.example.com/robin "cta:book-call").
+```
+
+| `goal:` | The send succeeded when |
+|---|---|
+| `read` (the default, and what a page without the line is) | the reader read it: at least `readSeconds` active seconds |
+| `respond` | the reader left a comment (a page needs `comments:` on for this to happen) |
+| `ack` | the reader pressed the page's ack CTA, a link titled `cta:ack`, e.g. `[Got it](#got-it "cta:ack")` |
+| `{ click: <cta id> }` | the reader pressed the CTA with that id |
+
+**A CTA is a link whose title is `cta:<id>`** (lowercase letters, digits, dashes, underscores, up to
+64). The title is never shown: the link renders with `data-artifact-cta="<id>"`, and an in-page CTA
+(`#...`) does not open a tab. On a reader's own link, a press sends `{ event: "click", beat, cta }`
+to `POST /seen`, under the same signature, render token and beat as every other signal (a press
+before the view lands waits for it). The route refuses a click without the beat (403), a malformed
+id or an id the page does not carry (400), and a revoked or expired reader (410); the owner's records
+nothing. Each session keeps up to 50 clicks. Publishing refuses a `goal` it does not know (`goal must be read, respond, ack, or { click:
+<cta id> }`), a click goal whose CTA the body does not carry, `goal: ack` with no `cta:ack` link, and
+a `cta:` title whose id could never be recorded.
+
+**`ack` is new.** The package's only acknowledgement before this was the confidential page's
+agreement (`POST /api/reader/ack`), which is keyed to a signed-in email on an `access:` page, and a
+per-reader page cannot carry `access:`. So `ack` is the smallest thing that is the reader's own
+word: a press of the CTA named `ack`.
+
+Each reader's line gains, every field under the before-send rule (a render before the recorded
+send is never the reader, nor anything later on its device; a comment written before the send is
+not their response):
+
+| Field | What it is |
+|---|---|
+| `lastOpenAt` | When the reader's latest session began, or null |
+| `sessions` | How many sessions the reader had |
+| `opens` | `[{ at, activeSeconds, device }]`, one per session, oldest first |
+| `clicks` | `[{ cta, at }]`, every CTA the reader pressed, oldest first |
+| `goal` | The page's goal (`read` when it has none) |
+| `outcome` | The highest rung reached: `not-opened`, `opened`, `read` (at least `readSeconds` active), `returned` (a second session at least `returnGapMs` after the first, on any device, the known one included), `acted` (the goal's action: a comment for `respond`, the `ack` CTA for `ack`, that CTA for a click goal; never for `read`) |
+| `succeeded` | Whether the send reached the goal: for `read`, reading; for every other goal, acting |
+| `daysSinceSent` | Whole days from `sentAt` to now, or null with no recorded send, for drawing age |
+
+`sentAt` was already on the line. The response also carries the page's `goal` and the `thresholds`
+it measured by. Every field that was there before is unchanged.
+
+**The thresholds are exported**: `OUTCOME_READ_SECONDS` (30: a skim of a short page, about what a
+phone reader gives a sent link), `OUTCOME_RETURN_GAP_MS` (an hour, the line `cameBack` already
+draws, so two tabs in one sitting are not a return), together `OUTCOME_THRESHOLDS`. A host passes
+its own as `outcomeThresholds: { readSeconds?, returnGapMs? }` on `createArtifactRoutes`, as
+`summarizeViews(rec, views, comments, { goal, thresholds, now })`, or for one request as
+`GET /views?readSeconds=<n>`. `OUTCOMES` lists the rungs in order; `parseGoal`, `ctasIn` and
+`outcomeThresholds` are exported for hosts that check a page themselves. `GET /api/artifacts/<id>`
+answers the page's `goal` too.
+
 ## Broadcasts (`template: broadcast`)
 
 A broadcast is its own page kind, not a document with extra flags. It is one message sent to several people, each through their own link, and it renders as one card: the sender's words at the top, then the media in the order the words put it (a video with sound and controls, photos, a voice note's player, link cards), then that person's own note. None of the document's furniture: no table of contents, no version line, no read-along, and no page menu for a reader.

package/lib/artifacts/front-matter.d.ts

@@ -3,6 +3,7 @@ import { type StateConfig } from './state.js';
 import { type CommentsMode, type CommentsVisible } from './comments.js';
 import { type ThemeMode } from '../brand/theme.js';
 import { type Definition } from './definitions.js';
+import { type ArtifactGoal } from './goal.js';
 export type ArtifactMeta = {
     title: string;
     summary: string;
@@ -72,6 +73,10 @@ export type ArtifactMeta = {
      *  link to pass it on, and whether they must sign in first. Absent is off. A door like `links:`,
      *  so sticky: a republish that leaves the line out changes nothing. */
     forward?: ForwardMode;
+    /** `goal: read | respond | ack | { click: <cta id> }` (issue #12): what a send of this page is
+     *  for, so each reader's outcome says whether the send succeeded. Absent is `read`. Content, like
+     *  `toc:`: a republish without the line goes back to read. */
+    goal?: ArtifactGoal;
 };
 export declare const FORWARD_MODES: readonly ["off", "signed-in", "open"];
 export type ForwardMode = (typeof FORWARD_MODES)[number];

package/lib/artifacts/front-matter.js

@@ -7,6 +7,7 @@ import { mergeChecklistState, mergeWidgetState, scanWidgets } from './widgets.js
 import { COMMENTS_MODES, mergeCommentsState } from './comments.js';
 import { THEME_MODES } from '../brand/theme.js';
 import { parseDefinitions } from './definitions.js';
+import { parseGoal, checkGoalAgainstBody } from './goal.js';
 export const FORWARD_MODES = ['off', 'signed-in', 'open'];
 export const PAGE_HISTORY = ['admins', 'everyone'];
 export const ARTIFACT_KINDS = ['document', 'broadcast'];
@@ -21,7 +22,7 @@ const PRIVATE_REF_IN_BODY = /^private:/;
 export const PACK_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** The longest `to:` a page may carry: a name or two, never a sentence. */
 export const MAX_TO_CHARS = 60;
-const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media', 'comment_name', 'history', 'forward']);
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'to', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access', 'state', 'theme', 'pack', 'toc', 'definitions', 'change', 'comments', 'comments_visible', 'links', 'media', 'comment_name', 'history', 'forward', 'goal']);
 export function parseArtifactSource(text, 
 /** The kind a file that leaves `template:` out is read as: the stored page's kind on a
  *  republish, so a broadcast stays one (sticky, like `links:`). Default `document`. */
@@ -99,6 +100,17 @@ opts = {}) {
             return { ok: false, error: 'forward must be off, signed-in or open' };
         meta.forward = d.forward;
     }
+    if (d.goal !== undefined && d.goal !== null) {
+        const g = parseGoal(d.goal);
+        if (!g.ok)
+            return { ok: false, error: g.error };
+        meta.goal = g.goal;
+    }
+    {
+        const why = checkGoalAgainstBody(meta.goal, content);
+        if (why)
+            return { ok: false, error: why };
+    }
     if (d.theme !== undefined) {
         if (!THEME_MODES.includes(d.theme))
             return { ok: false, error: `theme must be one of: ${THEME_MODES.join(', ')}` };

package/lib/artifacts/goal.d.ts

@@ -0,0 +1,47 @@
+/** `read` (the default): the reader spent OUTCOME_READ_SECONDS on the page. `respond`: the reader
+ *  left a comment. `ack`: the reader pressed the page's ack CTA (a link titled "cta:ack").
+ *  `{ click }`: the reader pressed the CTA with that id. */
+export type ArtifactGoal = 'read' | 'respond' | 'ack' | {
+    click: string;
+};
+export declare const GOAL_KINDS: readonly ["read", "respond", "ack"];
+export declare const DEFAULT_GOAL: ArtifactGoal;
+/** A CTA id: lowercase letters, digits, dashes, underscores, up to 64. */
+export declare const CTA_ID: RegExp;
+/** The CTA id `goal: ack` counts. */
+export declare const ACK_CTA = "ack";
+/** A link title that marks the link as a CTA: `[Book a call](https://... "cta:book-call")`. */
+export declare const CTA_TITLE: RegExp;
+/** Clicks kept per session; a page that sends more is not a reader pressing a button. */
+export declare const MAX_CLICKS_PER_SESSION = 50;
+export type Outcome = 'not-opened' | 'opened' | 'read' | 'returned' | 'acted';
+/** The rungs, lowest first. A send's outcome is the highest one it reached. */
+export declare const OUTCOMES: readonly Outcome[];
+/** Active seconds that make an open a read. Thirty seconds is a skim of a short page, which is
+ *  as much as a phone reader gives a sent link; a host with long pages passes its own. */
+export declare const OUTCOME_READ_SECONDS = 30;
+/** A second open at least this long after the first is a return: an hour, the same line the
+ *  summary's `cameBack` draws, so two tabs in one sitting are never a return. */
+export declare const OUTCOME_RETURN_GAP_MS = 3600000;
+export type OutcomeThresholds = {
+    readSeconds: number;
+    returnGapMs: number;
+};
+export declare const OUTCOME_THRESHOLDS: Readonly<OutcomeThresholds>;
+/** A host's own thresholds over the defaults; anything not a finite non-negative number is ignored. */
+export declare function outcomeThresholds(over?: Partial<OutcomeThresholds>): OutcomeThresholds;
+/** The front matter's `goal:` value, checked. Does not look at the body; parseArtifactSource does. */
+export declare function parseGoal(v: unknown): {
+    ok: true;
+    goal: ArtifactGoal;
+} | {
+    ok: false;
+    error: string;
+};
+/** The CTA id `goal` counts, or null for read and respond. */
+export declare function goalCta(goal: ArtifactGoal): string | null;
+/** The CTA ids a page carries, each once, in order. */
+export declare function ctasIn(markdown: string): string[];
+/** A body's CTAs and its goal, checked together: a CTA id that could never be recorded, and a goal
+ *  whose CTA the page does not carry, are refused rather than shipped. */
+export declare function checkGoalAgainstBody(goal: ArtifactGoal | undefined, markdown: string): string | null;

package/lib/artifacts/goal.js

@@ -0,0 +1,70 @@
+// What a send is for, and how far one reader got toward it (issue #12). A page declares one `goal`;
+// each per-reader send then lands on one rung of OUTCOMES, computed under the before-send rule in
+// summarizeViews, so a host can draw every send in the column where it landed.
+export const GOAL_KINDS = ['read', 'respond', 'ack'];
+export const DEFAULT_GOAL = 'read';
+/** A CTA id: lowercase letters, digits, dashes, underscores, up to 64. */
+export const CTA_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/** The CTA id `goal: ack` counts. */
+export const ACK_CTA = 'ack';
+/** A link title that marks the link as a CTA: `[Book a call](https://... "cta:book-call")`. */
+export const CTA_TITLE = /^cta:\s*(.*)$/;
+/** Clicks kept per session; a page that sends more is not a reader pressing a button. */
+export const MAX_CLICKS_PER_SESSION = 50;
+/** The rungs, lowest first. A send's outcome is the highest one it reached. */
+export const OUTCOMES = ['not-opened', 'opened', 'read', 'returned', 'acted'];
+/** Active seconds that make an open a read. Thirty seconds is a skim of a short page, which is
+ *  as much as a phone reader gives a sent link; a host with long pages passes its own. */
+export const OUTCOME_READ_SECONDS = 30;
+/** A second open at least this long after the first is a return: an hour, the same line the
+ *  summary's `cameBack` draws, so two tabs in one sitting are never a return. */
+export const OUTCOME_RETURN_GAP_MS = 3_600_000;
+export const OUTCOME_THRESHOLDS = Object.freeze({ readSeconds: OUTCOME_READ_SECONDS, returnGapMs: OUTCOME_RETURN_GAP_MS });
+/** A host's own thresholds over the defaults; anything not a finite non-negative number is ignored. */
+export function outcomeThresholds(over = {}) {
+    const ok = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+    return { readSeconds: ok(over.readSeconds) ? over.readSeconds : OUTCOME_READ_SECONDS, returnGapMs: ok(over.returnGapMs) ? over.returnGapMs : OUTCOME_RETURN_GAP_MS };
+}
+const GOAL_ERROR = 'goal must be read, respond, ack, or { click: <cta id> }';
+/** The front matter's `goal:` value, checked. Does not look at the body; parseArtifactSource does. */
+export function parseGoal(v) {
+    if (typeof v === 'string')
+        return GOAL_KINDS.includes(v) ? { ok: true, goal: v } : { ok: false, error: GOAL_ERROR };
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+        const keys = Object.keys(v);
+        const cta = v.click;
+        if (keys.length === 1 && keys[0] === 'click' && typeof cta === 'string' && CTA_ID.test(cta))
+            return { ok: true, goal: { click: cta } };
+    }
+    return { ok: false, error: GOAL_ERROR };
+}
+/** The CTA id `goal` counts, or null for read and respond. */
+export function goalCta(goal) {
+    return goal === 'ack' ? ACK_CTA : typeof goal === 'object' ? goal.click : null;
+}
+const LINK_TITLE = /\]\(\s*<?[^\s)>]*>?\s+(?:"([^"]*)"|'([^']*)')\s*\)/g;
+/** Every link title in a body that starts `cta:`, as written (the id may be malformed). */
+function ctaTitles(markdown) {
+    const out = [];
+    for (const m of markdown.matchAll(LINK_TITLE)) {
+        const t = CTA_TITLE.exec((m[1] ?? m[2] ?? '').trim());
+        if (t)
+            out.push(t[1].trim());
+    }
+    return out;
+}
+/** The CTA ids a page carries, each once, in order. */
+export function ctasIn(markdown) {
+    return [...new Set(ctaTitles(markdown).filter((id) => CTA_ID.test(id)))];
+}
+/** A body's CTAs and its goal, checked together: a CTA id that could never be recorded, and a goal
+ *  whose CTA the page does not carry, are refused rather than shipped. */
+export function checkGoalAgainstBody(goal, markdown) {
+    const bad = ctaTitles(markdown).find((id) => !CTA_ID.test(id));
+    if (bad !== undefined)
+        return `a CTA id is lowercase letters, digits, dashes and underscores: "cta:${bad}" is not one`;
+    const cta = goal ? goalCta(goal) : null;
+    if (!cta || ctasIn(markdown).includes(cta))
+        return null;
+    return goal === 'ack' ? `goal: ack needs a link marked "cta:${ACK_CTA}" for the reader to press` : `goal names a CTA the page does not carry: ${cta} (mark a link with "cta:${cta}")`;
+}

package/lib/artifacts/index.d.ts

@@ -26,6 +26,7 @@ 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, type Provenance } from './recipients-store.js';
+export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary, type SummarizeOptions, type Provenance } from './recipients-store.js';
+export { parseGoal, goalCta, ctasIn, outcomeThresholds, GOAL_KINDS, DEFAULT_GOAL, CTA_ID, ACK_CTA, MAX_CLICKS_PER_SESSION, OUTCOMES, OUTCOME_READ_SECONDS, OUTCOME_RETURN_GAP_MS, OUTCOME_THRESHOLDS, type ArtifactGoal, type Outcome, type OutcomeThresholds } from './goal.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

@@ -27,5 +27,6 @@ export { settleOnPublish, applySettingsPatch, withComments, declaredOf, password
 // Per-reader links: the host-facing surface only. The signing and token primitives stay internal.
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
 export { createRecipientsStore, memoryRecipientsStore, summarizeViews } from './recipients-store.js';
+export { parseGoal, goalCta, ctasIn, outcomeThresholds, GOAL_KINDS, DEFAULT_GOAL, CTA_ID, ACK_CTA, MAX_CLICKS_PER_SESSION, OUTCOMES, OUTCOME_READ_SECONDS, OUTCOME_RETURN_GAP_MS, OUTCOME_THRESHOLDS } from './goal.js';
 export { migrateMemosToPrivate, MEMO_KEY } from './migrate-memos.js';
 export { parseTranscriptFence, scanVoiceNotes, transcriptFenceFromWords, wordsFromWhisperJson, isAudioSrc, TRANSCRIPT_LANG, MAX_TRANSCRIPT_WORDS } from './voice-note.js';

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

@@ -1,4 +1,5 @@
 import type { Firestore } from 'firebase-admin/firestore';
+import { type ArtifactGoal, type Outcome, type OutcomeThresholds } from './goal.js';
 /** `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 = {
@@ -44,6 +45,8 @@ export type RecipientsRecord = {
     keep: boolean;
     revokedAll?: string;
 };
+/** `clicks` (issue #12): each CTA the reader pressed in this session, in order. Absent on a view
+ *  recorded before clicks existed, which reads as none. */
 export type ViewDoc = {
     artifactId: string;
     rid: string;
@@ -53,6 +56,10 @@ export type ViewDoc = {
     lastAt: string;
     activeSeconds: number;
     plays: Record<string, number>;
+    clicks?: {
+        cta: string;
+        at: string;
+    }[];
 };
 /** 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. */
@@ -62,6 +69,10 @@ export type BeforeSend = {
     activeSeconds: number;
     firstAt: string | null;
 } | null;
+/** One reader's line. The fields from `lastOpenAt` on (issue #12) are the send's outcome, every one
+ *  of them under the before-send rule: `opens` is each of the reader's sessions, `clicks` each CTA
+ *  they pressed, `outcome` the highest rung of OUTCOMES the send reached, `succeeded` whether it
+ *  reached the page's `goal`, and `daysSinceSent` whole days from `sentAt` (null with no send). */
 export type RecipientSummary = {
     rid: string;
     label: string;
@@ -85,6 +96,28 @@ export type RecipientSummary = {
         at: string;
         text: string;
     }[];
+    lastOpenAt: string | null;
+    sessions: number;
+    opens: {
+        at: string;
+        activeSeconds: number;
+        device: string;
+    }[];
+    clicks: {
+        cta: string;
+        at: string;
+    }[];
+    goal: ArtifactGoal;
+    outcome: Outcome;
+    succeeded: boolean;
+    daysSinceSent: number | null;
+};
+/** What summarizeViews measures outcomes by: the page's goal (default read), the thresholds (default
+ *  OUTCOME_THRESHOLDS) and the clock `daysSinceSent` counts to (default now). */
+export type SummarizeOptions = {
+    goal?: ArtifactGoal;
+    thresholds?: Partial<OutcomeThresholds>;
+    now?: Date;
 };
 type NewRecipient = {
     label: string;
@@ -110,6 +143,7 @@ export interface RecipientsStore {
     setSent?(artifactId: string, rids: string[] | '*', sentAt: string): Promise<string[]>;
     setExpiry(artifactId: string, expireAt: string | null): Promise<void>;
     useToken(key: string, expiresAt: number): Promise<boolean>;
+    /** `click` (issue #12): a CTA id the reader pressed, kept on the session with its time. */
     recordView(v: {
         artifactId: string;
         rid: string;
@@ -118,6 +152,7 @@ export interface RecipientsStore {
         at: string;
         addSeconds: number;
         play?: string;
+        click?: string;
     }): Promise<void>;
     views(artifactId: string): Promise<ViewDoc[]>;
     expiring(nowIso: string): Promise<string[]>;
@@ -133,5 +168,5 @@ export declare function summarizeViews(rec: RecipientsRecord, views: ViewDoc[],
     parent?: string | null;
     at: string;
     text: string;
-}[]): RecipientSummary[];
+}[], opts?: SummarizeOptions): RecipientSummary[];
 export {};

package/lib/artifacts/recipients-store.js

@@ -1,4 +1,5 @@
 import { newRid, ridOfReaderKey } from './recipients.js';
+import { DEFAULT_GOAL, MAX_CLICKS_PER_SESSION, goalCta, outcomeThresholds } from './goal.js';
 export const CAME_BACK_MS = 3_600_000;
 const LABEL_MAX = 60;
 const NOTE_MAX = 2000;
@@ -56,12 +57,14 @@ function sentIn(rec, rids, sentAt) {
     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: {} };
+    const doc = prev ? { ...prev, plays: { ...prev.plays }, ...(prev.clicks ? { clicks: [...prev.clicks] } : {}) } : { 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));
     if (v.at > doc.lastAt)
         doc.lastAt = v.at;
     if (v.play)
         doc.plays[v.play] = (doc.plays[v.play] ?? 0) + 1;
+    if (v.click && (doc.clicks?.length ?? 0) < MAX_CLICKS_PER_SESSION)
+        doc.clicks = [...(doc.clicks ?? []), { cta: v.click, at: v.at }];
     return doc;
 }
 const viewId = (artifactId, rid, session) => `${artifactId}__${rid}__${session}`;
@@ -192,7 +195,11 @@ export function createRecipientsStore(db, base) {
     };
 }
 /** One line per reader (never the owner), in the order they were added. */
-export function summarizeViews(rec, views, comments) {
+export function summarizeViews(rec, views, comments, opts = {}) {
+    const goal = opts.goal ?? DEFAULT_GOAL;
+    const t = outcomeThresholds(opts.thresholds);
+    const nowMs = (opts.now ?? new Date()).getTime();
+    const cta = goalCta(goal);
     return Object.values(rec.recipients).filter((r) => !r.owner).sort((a, b) => a.addedAt.localeCompare(b.addedAt)).map((r) => {
         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
@@ -209,6 +216,15 @@ export function summarizeViews(rec, views, comments) {
         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));
+        const activeSeconds = mine.reduce((n, v) => n + v.activeSeconds, 0);
+        const theirs = comments.filter((c) => ridOfReaderKey(c.readerKey) === r.rid);
+        const clicks = mine.flatMap((v) => v.clicks ?? []).sort((a, b) => a.at.localeCompare(b.at));
+        // The outcome, by the same rule: a comment written before the send was not the reader's either.
+        const responded = theirs.some((c) => !Number.isFinite(sentMs) || !(Date.parse(c.at) < sentMs));
+        const acted = goal === 'respond' ? responded : cta !== null && clicks.some((c) => c.cta === cta);
+        const read = mine.length > 0 && activeSeconds >= t.readSeconds;
+        const returned = firsts.length > 1 && firsts[firsts.length - 1] - firsts[0] >= t.returnGapMs;
+        const outcome = acted ? 'acted' : returned ? 'returned' : read ? 'read' : mine.length ? 'opened' : 'not-opened';
         return {
             rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null,
             sentAt: r.sentAt ?? null,
@@ -219,10 +235,18 @@ export function summarizeViews(rec, views, comments) {
             opened: mine.length > 0,
             firstOpenAt: mine[0]?.firstAt ?? null,
             cameBack: firsts.length > 1 && firsts[firsts.length - 1] - firsts[0] >= CAME_BACK_MS,
-            activeSeconds: mine.reduce((n, v) => n + v.activeSeconds, 0),
+            activeSeconds,
             plays: mine.reduce((n, v) => n + Object.values(v.plays).reduce((a, b) => a + b, 0), 0),
             devices: new Set(mine.map((v) => v.device)).size,
-            comments: comments.filter((c) => ridOfReaderKey(c.readerKey) === r.rid).map((c) => ({ id: c.id ?? null, parent: c.parent ?? null, at: c.at, text: c.text })),
+            comments: theirs.map((c) => ({ id: c.id ?? null, parent: c.parent ?? null, at: c.at, text: c.text })),
+            lastOpenAt: mine[mine.length - 1]?.firstAt ?? null,
+            sessions: mine.length,
+            opens: mine.map((v) => ({ at: v.firstAt, activeSeconds: v.activeSeconds, device: v.device })),
+            clicks,
+            goal, outcome,
+            // `read` succeeds on reading; every other goal only on its action.
+            succeeded: goal === 'read' ? read : acted,
+            daysSinceSent: Number.isFinite(sentMs) ? Math.max(0, Math.floor((nowMs - sentMs) / 86_400_000)) : null,
         };
     });
 }

package/lib/artifacts/render.js

@@ -27,6 +27,7 @@ import { remarkDefinitions } from './definitions.js';
 import { remarkLetterBreaks } from './letter-breaks.js';
 import { AUDIO_SRC, remarkVoiceNotes, TRANSCRIPT_LANG } from './voice-note.js';
 import { VoiceNote } from '../widgets/voice-note.js';
+import { CTA_ID, CTA_TITLE } from './goal.js';
 // Every colour is a theme variable (brand/theme.ts), so a page follows its light, dark or system mode.
 const GOLD = 'var(--a-accent)';
 function hostOf(url) {
@@ -66,6 +67,11 @@ const CALLOUT = /^\[!(note|warning)\]\s*/i;
 // else is a path on the author's disk (../meeting-transcripts/x.md), which the
 // publisher never uploads, so the anchor would 404. Those render as their text.
 const REACHABLE = /^(?:[a-z][a-z0-9+.-]*:|\/|#)/i;
+/** The CTA id a link's title marks, or null. */
+function ctaOf(title) {
+    const m = typeof title === 'string' ? CTA_TITLE.exec(title.trim()) : null;
+    return m && CTA_ID.test(m[1].trim()) ? m[1].trim() : null;
+}
 export function isReachableHref(href) {
     return typeof href === 'string' && REACHABLE.test(href);
 }
@@ -207,9 +213,14 @@ function baseComponents(block, figure, checklists, embeds, voiceNotes) {
             // eslint-disable-next-line @next/next/no-img-element
             _jsx("img", { "data-artifact-image": true, src: typeof src === 'string' ? src : undefined, alt: alt ?? '', className: "my-6 w-full rounded-lg border border-[color:var(--a-line)]" }));
         },
-        a: ({ href, children }) => !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, 
-            // A phone link opens an app, not a tab.
-            target: PHONE_LINK.test(href) ? undefined : '_blank', rel: "noopener noreferrer", className: "text-[color:var(--a-strong)] underline decoration-[color:var(--a-line-strong)] underline-offset-4 hover:decoration-[color:var(--a-strong)]", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-[color:var(--a-muted)]", children: ["(", hostOf(href), ")"] })) : null] })),
+        a: ({ href, children, title }) => {
+            // A link titled `cta:<id>` is a CTA (issue #12): the page records a press of it for a
+            // per-reader link, and the title, which is markup for this, is never shown.
+            const cta = ctaOf(title);
+            return !isReachableHref(href) ? (_jsx("span", { children: children })) : (_jsxs("a", { href: href, 
+                // A phone link opens an app, not a tab, and an in-page CTA (an ack) stays on the page.
+                target: PHONE_LINK.test(href) || (cta && href.startsWith('#')) ? undefined : '_blank', ...(cta ? { 'data-artifact-cta': cta } : {}), rel: "noopener noreferrer", className: "text-[color:var(--a-strong)] underline decoration-[color:var(--a-line-strong)] underline-offset-4 hover:decoration-[color:var(--a-strong)]", children: [children, href && hostOf(href) ? (_jsxs("span", { "data-nospeak": true, className: "ml-1 text-xs text-[color:var(--a-muted)]", children: ["(", hostOf(href), ")"] })) : null] }));
+        },
         code: ({ node, className, children }) => {
             const lang = /language-(\w+)/.exec(className ?? '')?.[1];
             if (lang === 'links')

package/lib/artifacts/store.d.ts

@@ -1,5 +1,6 @@
 import { type Firestore } from 'firebase-admin/firestore';
 import type { ArtifactKind, ArtifactMeta, ForwardMode } from './front-matter.js';
+import type { ArtifactGoal } from './goal.js';
 import type { Access } from './reader.js';
 import type { StateConfig } from './state.js';
 import type { ThemeMode } from '../brand/theme.js';
@@ -35,6 +36,8 @@ export type ArtifactRecord = {
     commentName?: 'required';
     /** Whether a reader may make a forward link (front-matter `forward:`); absent is off. */
     forward?: ForwardMode;
+    /** What a send of this page is for (front-matter `goal:`); absent is `read`. */
+    goal?: ArtifactGoal;
     /** The page's own `history:` line; absent, the host's setting decides. */
     history?: 'admins' | 'everyone';
     definitions?: Definition[];

package/lib/artifacts/store.js

@@ -172,6 +172,7 @@ async function saveArtifact(col, input) {
         ...(input.meta.toc !== undefined ? { toc: input.meta.toc } : {}),
         ...(input.meta.commentName ? { commentName: input.meta.commentName } : {}),
         ...(input.meta.forward ? { forward: input.meta.forward } : {}),
+        ...(input.meta.goal ? { goal: input.meta.goal } : {}),
         ...(input.meta.history ? { history: input.meta.history } : {}),
         ...(input.meta.definitions?.length ? { definitions: input.meta.definitions } : {}),
     };
@@ -227,6 +228,7 @@ async function saveArtifact(col, input) {
             ...(input.meta.toc !== undefined ? {} : { toc: FieldValue.delete() }),
             ...(input.meta.commentName ? {} : { commentName: FieldValue.delete() }),
             ...(input.meta.history ? {} : { history: FieldValue.delete() }),
+            ...(input.meta.goal ? {} : { goal: FieldValue.delete() }),
             ...(input.meta.definitions?.length ? {} : { definitions: FieldValue.delete() }),
         };
         // `voice: none` is the page declaring it has no audio. An update merges, so the recording it

package/lib/reader/quiet-view.js

@@ -31,6 +31,11 @@ export function QuietView({ id, rid, sig, token, endpoint }) {
         let wait = null;
         let tick = null;
         let since = 0;
+        // CTAs pressed before the view earned its beat: sent once it lands (issue #12).
+        let pending = [];
+        const sendClicks = () => { if (!beat)
+            return; for (const cta of pending)
+            void post({ event: 'click', beat, cta }); pending = []; };
         const post = async (body) => {
             try {
                 const r = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ...base, ...body }), keepalive: true });
@@ -81,6 +86,7 @@ export function QuietView({ id, rid, sig, token, endpoint }) {
                 }
                 else if (r?.beat)
                     beat = r.beat;
+                sendClicks();
             }, VIEW_AFTER_MS);
         };
         const disarm = () => {
@@ -101,6 +107,17 @@ export function QuietView({ id, rid, sig, token, endpoint }) {
             if (media && beat)
                 void post({ event: 'play', beat, media });
         };
+        // A press of anything marked data-artifact-cta (a link titled `cta:<id>`) is the reader taking
+        // that CTA. keepalive carries it through the new tab a link opens.
+        const onClick = (e) => {
+            const el = e.target?.closest?.('[data-artifact-cta]');
+            const cta = el?.getAttribute('data-artifact-cta');
+            if (!cta)
+                return;
+            pending.push(cta);
+            sendClicks();
+        };
+        document.addEventListener('click', onClick, true);
         document.addEventListener('visibilitychange', onVisibility);
         document.addEventListener('prerenderingchange', onVisibility);
         document.addEventListener('play', onPlay, true);
@@ -110,6 +127,7 @@ export function QuietView({ id, rid, sig, token, endpoint }) {
             document.removeEventListener('visibilitychange', onVisibility);
             document.removeEventListener('prerenderingchange', onVisibility);
             document.removeEventListener('play', onPlay, true);
+            document.removeEventListener('click', onClick, true);
             window.removeEventListener('pagehide', disarm);
             disarm();
         };

package/lib/routes/artifacts.d.ts

@@ -11,6 +11,7 @@ import { type Access, type AllowEntry } from '../artifacts/reader.js';
 import { type ReadersStore } from '../artifacts/readers-store.js';
 import { type ReaderEvent } from '../artifacts/read-alerts.js';
 import type { ResolveEvent } from '../artifacts/resolve-digest.js';
+import type { OutcomeThresholds } from '../artifacts/goal.js';
 import { type AnalyticsConfig } from '../reader/analytics-plan.js';
 import type { PersonalStore } from '../artifacts/personal-store.js';
 import type { Transcriber } from '../artifacts/transcribe.js';
@@ -123,6 +124,9 @@ export type ArtifactRoutesConfig = {
     recipients?: RecipientsStore;
     /** Signs per-reader links and render tokens. At least 32 characters. Read at request time. */
     recipientSecret?: () => string | undefined;
+    /** The thresholds `GET /views` measures each send's outcome by (issue #12), over the package's
+     *  OUTCOME_THRESHOLDS: `readSeconds` (default 30) and `returnGapMs` (default an hour). */
+    outcomeThresholds?: Partial<OutcomeThresholds>;
     /** Product analytics for this host's pages (0.50.0): PostHog with session replay, heatmaps,
      *  autocapture, scroll depth on leave, and section_viewed / narration_* events. Without a key no
      *  page loads any analytics script. Never records the owner or an admin, never a link-preview
@@ -260,6 +264,7 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         markdown: string;
         version: number;
         updatedAt: string;
+        goal: import("../index.js").ArtifactGoal;
         share: {
             links: string;
             forward: "signed-in" | "off" | "open";

package/lib/routes/artifacts.js

@@ -140,7 +140,7 @@ export function createArtifactRoutes(config) {
     });
     const recipientsRoutes = createRecipientsRoutes({
         store, recipients: config.recipients, recipientSecret: config.recipientSecret, publishKey: config.publishKey,
-        state: config.state, assets: config.assets, pageUrl, authed, readerSecret, signInOrigin, siteUrl,
+        state: config.state, assets: config.assets, pageUrl, authed, readerSecret, signInOrigin, siteUrl, outcomes: config.outcomeThresholds,
     });
     const personalRoutes = createPersonalRoutes({ store, personal: config.personal, readers: config.readers, readerSecret, pageUrl, signInOrigin, siteUrl, audioUrl });
     const voiceRoutes = createVoiceRoutes({
@@ -909,6 +909,8 @@ export function createArtifactRoutes(config) {
             text: narrationText({ title: a.title, subtitle: a.subtitle, summary: a.summary, markdown: a.markdown }),
             title: a.title, ...(a.subtitle ? { subtitle: a.subtitle } : {}), summary: a.summary, ...(a.to ? { to: a.to } : {}),
             markdown: a.markdown, version: a.version ?? 1, updatedAt: a.updatedAt,
+            // What a send of the page is for (issue #12): the goal each reader's outcome is measured by.
+            goal: a.goal ?? 'read',
             // What a link to this page lets its reader do (0.57.0), so a sender can say so before the
             // reader's link exists: the send card is approved before anything is minted.
             share: {

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

@@ -1,5 +1,6 @@
 import { NextResponse, type NextRequest } from 'next/server';
 import { type Provenance, type RecipientsStore } from '../artifacts/recipients-store.js';
+import { type OutcomeThresholds } from '../artifacts/goal.js';
 import type { ArtifactStore } from '../artifacts/store.js';
 import type { StateStore } from '../artifacts/state-store.js';
 import type { ArtifactAssets } from '../artifacts/assets.js';
@@ -24,6 +25,9 @@ export type RecipientsRoutesCtx = {
     readerSecret?: () => string | undefined;
     signInOrigin?: string;
     siteUrl?: string;
+    /** The outcome thresholds `GET /views` measures by (issue #12), over OUTCOME_THRESHOLDS. A caller
+     *  may move `readSeconds` per request with `?readSeconds=<n>`. */
+    outcomes?: Partial<OutcomeThresholds>;
 };
 /** How many forward links one reader may make on one page in a day. */
 export declare const FORWARDS_PER_DAY = 20;

package/lib/routes/recipients-routes.js

@@ -5,6 +5,7 @@ import { GRANT_COOKIE, signInUrl, verifyGrant } from '../artifacts/reader.js';
 import { perReaderGate } from './per-reader.js';
 import { summarizeViews } from '../artifacts/recipients-store.js';
 import { COMMENTS_SLOT } from '../artifacts/comments.js';
+import { CTA_ID, ctasIn, outcomeThresholds } from '../artifacts/goal.js';
 import { ARTIFACT_ID_RE } from './ids.js';
 /** How many forward links one reader may make on one page in a day. */
 export const FORWARDS_PER_DAY = 20;
@@ -98,7 +99,21 @@ export function createRecipientsRoutes(given) {
             await ctx.recipients.recordView({ artifactId: id, rid, session, device, at, addSeconds: seconds, ...(media ? { play: media } : {}) });
             return json({});
         }
-        return json({ error: 'event must be view, beat or play' }, 400);
+        // A CTA the reader pressed (issue #12): the same beat as any other signal after the view, and
+        // only an id the page itself carries, so a click is never recorded for a button nobody drew.
+        if (event === 'click') {
+            if (str(b?.beat) !== beatKey(secret, id, rid, session))
+                return json({ error: 'forbidden' }, 403);
+            const cta = str(b?.cta);
+            if (!CTA_ID.test(cta))
+                return json({ error: 'cta must be a CTA id' }, 400);
+            const page = await ctx.store.get(id);
+            if (!page || !ctasIn(page.markdown ?? '').includes(cta))
+                return json({ error: 'this page carries no such CTA' }, 400);
+            await ctx.recipients.recordView({ artifactId: id, rid, session, device, at, addSeconds: 0, click: cta });
+            return json({});
+        }
+        return json({ error: 'event must be view, beat, play or click' }, 400);
     }
     const unauth = () => json({ error: 'publish key required' }, 401);
     async function listing(id) {
@@ -207,7 +222,10 @@ export function createRecipientsRoutes(given) {
         const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
         const entries = ctx.state ? await ctx.state.entries(id) : [];
         const comments = entries.filter((e) => e.slot === COMMENTS_SLOT && e.readerKey.startsWith('r:')).map((e) => ({ readerKey: e.readerKey, id: e.id, parent: typeof e.value?.parent === 'string' ? e.value.parent : null, at: e.at, text: String(e.value?.body ?? '') }));
-        return json({ id, expireAt: rec.expireAt, keep: rec.keep, recipients: summarizeViews(rec, await ctx.recipients.views(id), comments) });
+        const q = req.nextUrl.searchParams.get('readSeconds');
+        const thresholds = outcomeThresholds({ ...ctx.outcomes, ...(q !== null && /^\d{1,6}$/.test(q) ? { readSeconds: Number(q) } : {}) });
+        const goal = a.goal ?? 'read';
+        return json({ id, expireAt: rec.expireAt, keep: rec.keep, goal, thresholds, recipients: summarizeViews(rec, await ctx.recipients.views(id), comments, { goal, thresholds }) });
     }
     /** Reader text goes with the page: every comment and answer on it, whoever wrote it. */
     async function clearReaderText(id) {

package/package.json

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

package/template/hub/package.json

@@ -12,7 +12,7 @@
     "@fontsource/dm-sans": "^5.3.0",
     "@fontsource/dm-serif-display": "^5.3.0",
     "@google-cloud/storage": "^7.22.0",
-    "@supersuit/artifacts": "0.60.1",
+    "@supersuit/artifacts": "0.61.0",
     "firebase": "^12.19.0",
     "firebase-admin": "^13.7.0",
     "next": "^16.0.1",