@supersuit/artifacts 0.59.0 → 0.61.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 `@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.
+
+- DETECTOR: `npm view @supersuit/artifacts@0.60.0` finds nothing.
+- REMEDY: use 0.60.1.
+- TESTS: `unchanged-default.test.tsx`; the full suite ran before the tag.
+
+## 0.60.0 (2026-11-06, tagged, never published)
+
+**Every image and video on a page opens full screen, with pinch to zoom and arrows through the page.** A new client component, `MediaViewer` (`src/reader/media-viewer.tsx`), mounted by `ArtifactMarkdown` and exported from `./reader`; the zoom arithmetic is pure, in `media-zoom.ts`. No new dependency. Body images and covers carry `data-artifact-image`; a pack's images are found through `data-artifact-figure`. The viewer is a portal on `<body>`, so the comment layer's gestures never see it, and it styles itself inline, so it needs nothing from a host's Tailwind build. iOS Safari needed `touch-action: none` and cancelled `touchmove` and `gesture*` events together. Margin taps close with a mouse only, because a near miss on an arrow closed the viewer on an iPhone.
+
+- DETECTOR: tap an image on a page. Nothing happens on an old version.
+- REMEDY: update. Nothing to configure. A host that draws its own `<img>` around the shell adds `data-artifact-image` to include it.
+- TESTS: `media-viewer.test.tsx`, `media-zoom.test.ts`, `render.test.tsx`; `check-packed` asserts the marks reach a served page. Verified by hand in iOS 26.2 Safari in the Simulator with real touches (a two-finger pinch reached 3.3x with `visualViewport.scale` at 1.00; pan, swipe, double tap, arrows, both video kinds) and in desktop Chrome by keyboard. WebDriver touch actions proved unreliable there, even on a plain button; drive the Simulator window with mouse events and a held Option key instead.
+
 ## 0.59.0 (2026-11-02)
 
 **The deployable hub host ships in the package** (supersuit-dev#1630). `template/hub/` is a complete

package/README.md

@@ -211,6 +211,16 @@ as a change for the password and comments (as before, it takes the password off
 off), and never for `access:`, which a file that names none leaves alone. A page last published
 before 0.31.0 has no `declared` and takes its file on its next publish, as every publish did.
 
+## Full screen images and video
+
+Tap any image or video on a page and it fills the screen. `ArtifactMarkdown` mounts this itself, so every page and every host has it with no setting, and a page with no JavaScript stays a plain page. It covers images in the body, a page's cover, an image a brand pack draws, and both kinds of video.
+
+- **Zoom:** pinch, double tap, or (with a mouse) click. A trackpad pinch and the `+`, `-` and `0` keys also work. Drag to look around a zoomed picture.
+- **Move:** arrows on screen, a swipe, or the arrow keys, through every image and video on the page in order.
+- **Close:** the X, a swipe down, Escape, or a mouse click off the picture. A finger off the picture does nothing, because the arrows sit there.
+- **Video:** a silent video loops and behaves like a picture. A `sound:` clip keeps its controls and gets an expand button on the page, because tapping it plays it. It moves to the viewer and comes back at the second it reached. Swipes do not work on it, because its controls take the touch; use the arrows.
+- **Left alone:** an image inside a link stays a link, and is not in the sequence. Drawing a comment box on an image does not open the viewer.
+
 ## Version history
 
 Every page says when it was last updated under the summary, and to its admins that line also names
@@ -301,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) |
 
@@ -1061,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.
 
@@ -1223,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

@@ -21,11 +21,13 @@ import { embedSrc, isEmbedKind, parseEmbedFence, EMBED_KINDS } from './simulator
 import { EmbedFrame } from './embed-frame.js';
 import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
+import { MediaViewer } from '../reader/media-viewer.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
 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) {
@@ -65,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);
 }
@@ -204,11 +211,16 @@ function baseComponents(block, figure, checklists, embeds, voiceNotes) {
             }
             return typeof src === 'string' && VIDEO.test(src) ? (_jsx(InlineVideo, { src: src, label: alt ?? '' })) : typeof src === 'string' && AUDIO.test(src) ? (_jsx(InlineAudio, { src: src, label: alt ?? '' })) : (
             // eslint-disable-next-line @next/next/no-img-element
-            _jsx("img", { src: typeof src === 'string' ? src : undefined, alt: alt ?? '', className: "my-6 w-full rounded-lg border border-[color:var(--a-line)]" }));
+            _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, 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] }));
         },
-        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] })),
         code: ({ node, className, children }) => {
             const lang = /language-(\w+)/.exec(className ?? '')?.[1];
             if (lang === 'links')
@@ -385,5 +397,5 @@ export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Sect
     const body = (_jsx(ReactMarkdown, { remarkPlugins: plugins, components: components, urlTransform: artifactUrlTransform, 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, CODE_IN_MD.test(markdown) ? _jsx(CodeCopy, {}) : 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, _jsx(MediaViewer, {}), defined ? (_jsxs(_Fragment, { children: [_jsx("style", { children: DEFINED_TERM_CSS }), _jsx(DefinitionLayer, {})] })) : null] }));
 }

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/index.d.ts

@@ -2,6 +2,7 @@ export { ArtifactReader, wrapWords, seekableWord, litWordIndex, type WordTiming
 export { begunCount } from './karaoke.js';
 export { PlayerBar } from './player-bar.js';
 export { QuietView } from './quiet-view.js';
+export { MediaViewer } from './media-viewer.js';
 export { CommentLayer } from './comment-layer.js';
 export { PageMenu, roleLine, menuItems, type PageMenuProps, type PageRole } from './page-menu.js';
 export { SettingsSheet, settingsChanges, ACCESS_LABEL, COMMENTS_LABEL, VISIBLE_LABEL, REOPEN_KEY, type PageSettings, type SettingsFact, type SheetKind, type AccessLevel } from './settings-sheet.js';

package/lib/reader/index.js

@@ -4,6 +4,7 @@ export { ArtifactReader, wrapWords, seekableWord, litWordIndex } from './artifac
 export { begunCount } from './karaoke.js';
 export { PlayerBar } from './player-bar.js';
 export { QuietView } from './quiet-view.js';
+export { MediaViewer } from './media-viewer.js';
 export { CommentLayer } from './comment-layer.js';
 export { PageMenu, roleLine, menuItems } from './page-menu.js';
 export { SettingsSheet, settingsChanges, ACCESS_LABEL, COMMENTS_LABEL, VISIBLE_LABEL, REOPEN_KEY } from './settings-sheet.js';

package/lib/reader/media-viewer.d.ts

@@ -0,0 +1 @@
+export declare function MediaViewer(): import("react").ReactPortal | null;