@supersuit/artifacts 0.59.0 → 0.61.0

package/lib/reader/media-viewer.js

@@ -0,0 +1,391 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Tap any image or video on a page and it fills the screen: pinch to zoom, drag to look around,
+// arrows and swipes to move through every picture and video on the page in order.
+//
+// A phone cannot read a screenshot at the width of a column, and until now the page itself was the
+// only thing to pinch, which zooms the words and the bars with it. The viewer sits over the page in
+// a portal on <body>, outside the comment layer's root, so the comment gestures never see it.
+//
+// It adds nothing to the server render: the page is a plain page with this component disabled.
+// All styles are inline because a host's Tailwind build decides which classes exist.
+//
+// iOS Safari is the hard target. `touch-action: none` alone does not always hold there, so the
+// viewer also cancels touchmove and Safari's gesture events; those are what keep a pinch on the
+// picture instead of on the page behind it.
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { clampView, fitted, maxScale, ONE, zoomAt } from './media-zoom.js';
+const ITEMS = 'img[data-artifact-image], [data-artifact-figure] img, video[data-artifact-media]';
+const EXPAND = 'data-artifact-expand';
+/** A press that travelled this far was a drag (a comment box, a scroll), never a tap. */
+const TAP_PX = 10;
+const DOUBLE_TAP_MS = 300;
+const SWIPE_PX = 60;
+const FLICK_PX = 24;
+const FLICK_MS = 250;
+const CLOSE_PX = 90;
+const TAP_ZOOM = 2.5;
+const KEY_ZOOM = 1.5;
+const WHEEL_ZOOM = 0.01;
+const isVideo = (el) => el.tagName === 'VIDEO';
+const scrubbing = (t) => t instanceof Element && !!t.closest('video[controls]');
+/** Every picture and video on the page, in page order. An image inside a link belongs to the link. */
+function pageItems() {
+    return Array.from(document.querySelectorAll(ITEMS))
+        .filter((el) => !el.closest('a[href], button'))
+        .map((el) => ({
+        el,
+        video: isVideo(el),
+        src: el.currentSrc || el.getAttribute('src') || '',
+        alt: (isVideo(el) ? el.getAttribute('aria-label') : el.getAttribute('alt')) ?? '',
+        controls: isVideo(el) && el.controls,
+    }));
+}
+const round = {
+    width: 44, height: 44, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 0,
+    border: 'none', borderRadius: 999, background: 'rgba(0,0,0,0.55)', color: '#fff', cursor: 'pointer',
+};
+function Icon({ d }) {
+    return (_jsx("svg", { width: "22", height: "22", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: d }) }));
+}
+export function MediaViewer() {
+    const [open, setOpen] = useState(null);
+    useEffect(() => {
+        let down = null;
+        const onDown = (e) => { const p = e; down = { x: p.clientX, y: p.clientY }; };
+        const show = (el) => {
+            const items = pageItems();
+            const at = items.findIndex((i) => i.el === el);
+            if (at >= 0)
+                setOpen({ items, at });
+            return at >= 0;
+        };
+        const target = (e) => {
+            const t = e.target;
+            if (!(t instanceof Element))
+                return null;
+            const expand = t.closest(`[${EXPAND}]`);
+            if (expand)
+                return expand.parentElement?.querySelector('video') ?? null;
+            if (scrubbing(t))
+                return null;
+            return t.closest(ITEMS);
+        };
+        const onClick = (e) => {
+            // A second copy of this component on the page has already taken the click.
+            if (e.defaultPrevented)
+                return;
+            const was = down;
+            down = null;
+            if (was && Math.hypot(e.clientX - was.x, e.clientY - was.y) > TAP_PX)
+                return;
+            const el = target(e);
+            if (el && show(el))
+                e.preventDefault();
+        };
+        const onKey = (e) => {
+            if ((e.key !== 'Enter' && e.key !== ' ') || e.defaultPrevented)
+                return;
+            const el = target(e);
+            if (el && show(el))
+                e.preventDefault();
+        };
+        const added = [];
+        const dressed = [];
+        for (const { el, controls } of pageItems()) {
+            if (controls) {
+                const box = el.parentElement;
+                if (!box || box.querySelector(`[${EXPAND}]`))
+                    continue;
+                box.style.position = 'relative';
+                const b = document.createElement('button');
+                b.type = 'button';
+                b.setAttribute(EXPAND, 'true');
+                b.setAttribute('aria-label', 'Open this video full screen');
+                b.innerHTML = '<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 3H3v5M16 3h5v5M21 16v5h-5M3 16v5h5"/></svg>';
+                Object.assign(b.style, { position: 'absolute', top: '8px', right: '8px', width: '36px', height: '36px', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '0', border: 'none', borderRadius: '999px', background: 'rgba(0,0,0,0.55)', color: '#fff', cursor: 'pointer' });
+                box.appendChild(b);
+                added.push(b);
+                continue;
+            }
+            el.style.cursor = 'zoom-in';
+            el.tabIndex = 0;
+            el.setAttribute('role', 'button');
+            el.setAttribute('aria-haspopup', 'dialog');
+            dressed.push(el);
+        }
+        document.addEventListener('pointerdown', onDown, true);
+        document.addEventListener('click', onClick);
+        document.addEventListener('keydown', onKey);
+        return () => {
+            document.removeEventListener('pointerdown', onDown, true);
+            document.removeEventListener('click', onClick);
+            document.removeEventListener('keydown', onKey);
+            for (const b of added)
+                b.remove();
+            for (const el of dressed) {
+                el.style.cursor = '';
+                el.removeAttribute('tabindex');
+                el.removeAttribute('role');
+                el.removeAttribute('aria-haspopup');
+            }
+        };
+    }, []);
+    const close = useCallback(() => setOpen(null), []);
+    return open ? createPortal(_jsx(Viewer, { items: open.items, start: open.at, onClose: close }), document.body) : null;
+}
+function Viewer({ items, start, onClose }) {
+    const [at, setAt] = useState(start);
+    const dir = useRef(0);
+    const item = items[at];
+    const shell = useRef(null);
+    const stage = useRef(null);
+    const media = useRef(null);
+    const view = useRef(ONE);
+    const points = useRef(new Map());
+    const press = useRef(null);
+    const pinch = useRef(null);
+    const lastTap = useRef(null);
+    const multiple = items.length > 1;
+    const stageSize = () => ({ w: stage.current?.clientWidth || window.innerWidth, h: stage.current?.clientHeight || window.innerHeight });
+    const natural = () => {
+        const m = media.current;
+        if (!m)
+            return { w: 0, h: 0 };
+        return isVideo(m) ? { w: m.videoWidth, h: m.videoHeight } : { w: m.naturalWidth, h: m.naturalHeight };
+    };
+    const shownSize = () => fitted(natural(), stageSize());
+    /** A window point, measured from the screen's centre. */
+    const centred = (x, y) => {
+        const r = stage.current?.getBoundingClientRect();
+        const s = stageSize();
+        return { x: x - (r?.left ?? 0) - s.w / 2, y: y - (r?.top ?? 0) - s.h / 2 };
+    };
+    const paint = (v, animate = false) => {
+        if (!media.current)
+            return;
+        media.current.style.transition = animate ? 'transform 0.2s ease-out' : 'none';
+        media.current.style.transform = `translate(${v.x}px, ${v.y}px) scale(${v.s})`;
+        if (shell.current)
+            shell.current.style.background = '#000';
+    };
+    const set = (v, animate = false) => { view.current = v; paint(v, animate); };
+    const zoomBy = (factor, p, animate = false) => set(zoomAt(view.current, factor, p, shownSize(), stageSize(), maxScale(natural(), shownSize())), animate);
+    const go = useCallback((d) => {
+        setAt((n) => {
+            const to = Math.min(items.length - 1, Math.max(0, n + d));
+            if (to !== n)
+                dir.current = d;
+            return to;
+        });
+    }, [items.length]);
+    // Each item opens fitted, sliding in from the side the reader moved toward.
+    useLayoutEffect(() => {
+        view.current = ONE;
+        paint(ONE);
+        const m = media.current;
+        const still = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+        if (dir.current && m && !still)
+            m.animate?.([{ opacity: 0, transform: `translateX(${dir.current * 48}px)` }, { opacity: 1, transform: 'none' }], { duration: 180, easing: 'ease-out' });
+        dir.current = 0;
+        // The next and previous pictures are ready before the reader asks for them.
+        for (const n of [items[at - 1], items[at + 1]])
+            if (n && !n.video)
+                new Image().src = n.src;
+        // A clip with sound moves to the viewer and comes back at the second it reached.
+        const src = items[at];
+        if (!src.controls)
+            return;
+        const inline = src.el;
+        inline.pause?.();
+        const shown = m;
+        return () => { if (shown && shown.currentTime)
+            inline.currentTime = shown.currentTime; };
+        // `paint` reads only refs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [at, items]);
+    useEffect(() => {
+        const root = document.documentElement;
+        const was = root.style.overflow;
+        root.style.overflow = 'hidden';
+        const before = document.activeElement;
+        shell.current?.focus();
+        return () => { root.style.overflow = was; before?.focus?.(); };
+    }, []);
+    useEffect(() => {
+        const onKey = (e) => {
+            const act = {
+                Escape: onClose,
+                ArrowRight: () => go(1),
+                ArrowLeft: () => go(-1),
+                '+': () => zoomBy(KEY_ZOOM, { x: 0, y: 0 }, true),
+                '=': () => zoomBy(KEY_ZOOM, { x: 0, y: 0 }, true),
+                '-': () => zoomBy(1 / KEY_ZOOM, { x: 0, y: 0 }, true),
+                '0': () => set(ONE, true),
+            };
+            if (e.key === 'Tab') {
+                const stops = Array.from(shell.current?.querySelectorAll('button') ?? []);
+                const now = stops.indexOf(document.activeElement);
+                stops[(now + (e.shiftKey ? -1 : 1) + stops.length) % stops.length]?.focus();
+                e.preventDefault();
+                e.stopPropagation();
+                return;
+            }
+            const run = act[e.key];
+            if (!run)
+                return;
+            // Capture on window, and stopped: Escape closes this before a comment card under it.
+            e.preventDefault();
+            e.stopPropagation();
+            run();
+        };
+        window.addEventListener('keydown', onKey, true);
+        return () => window.removeEventListener('keydown', onKey, true);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [go, onClose]);
+    useEffect(() => {
+        const el = shell.current;
+        const box = stage.current;
+        if (!el || !box)
+            return;
+        const noTouch = (e) => { if (!scrubbing(e.target))
+            e.preventDefault(); };
+        const noGesture = (e) => e.preventDefault();
+        const onWheel = (e) => {
+            e.preventDefault();
+            const p = centred(e.clientX, e.clientY);
+            // A trackpad pinch arrives as a wheel with ctrl held.
+            if (e.ctrlKey || view.current.s === 1)
+                return zoomBy(Math.exp(-e.deltaY * WHEEL_ZOOM), p);
+            set(clampView({ ...view.current, x: view.current.x - e.deltaX, y: view.current.y - e.deltaY }, shownSize(), stageSize()));
+        };
+        el.addEventListener('touchmove', noTouch, { passive: false });
+        for (const g of ['gesturestart', 'gesturechange', 'gestureend'])
+            el.addEventListener(g, noGesture);
+        box.addEventListener('wheel', onWheel, { passive: false });
+        return () => {
+            el.removeEventListener('touchmove', noTouch);
+            for (const g of ['gesturestart', 'gesturechange', 'gestureend'])
+                el.removeEventListener(g, noGesture);
+            box.removeEventListener('wheel', onWheel);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const tap = (x, y, mouse) => {
+        const p = centred(x, y);
+        const v = view.current;
+        const shown = shownSize();
+        // Off the picture a mouse closes the viewer. A finger does not: the arrows sit in that black,
+        // and a near miss must not throw the reader back to the page (seen on an iPhone, 2026-11-06).
+        if (Math.abs(p.x - v.x) > (shown.w * v.s) / 2 || Math.abs(p.y - v.y) > (shown.h * v.s) / 2)
+            return mouse ? onClose() : undefined;
+        const t = Date.now();
+        const last = lastTap.current;
+        const twice = !!last && t - last.t < DOUBLE_TAP_MS && Math.hypot(x - last.x, y - last.y) < TAP_PX * 3;
+        lastTap.current = twice ? null : { t, x, y };
+        if (!mouse && !twice)
+            return;
+        if (v.s > 1)
+            set(ONE, true);
+        else
+            zoomBy(TAP_ZOOM, p, true);
+    };
+    const onDown = (e) => {
+        if (scrubbing(e.target) || (e.pointerType === 'mouse' && e.button !== 0))
+            return;
+        e.currentTarget.setPointerCapture?.(e.pointerId);
+        points.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+        const held = Array.from(points.current.values());
+        if (held.length === 1)
+            press.current = { x: e.clientX, y: e.clientY, t: Date.now(), view: view.current, axis: null, pinched: false };
+        if (held.length === 2) {
+            if (press.current)
+                press.current.pinched = true;
+            pinch.current = { dist: Math.hypot(held[0].x - held[1].x, held[0].y - held[1].y), mid: { x: (held[0].x + held[1].x) / 2, y: (held[0].y + held[1].y) / 2 }, view: view.current };
+        }
+    };
+    const onMove = (e) => {
+        if (!points.current.has(e.pointerId))
+            return;
+        points.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+        const held = Array.from(points.current.values());
+        const two = pinch.current;
+        if (held.length >= 2 && two) {
+            const mid = { x: (held[0].x + held[1].x) / 2, y: (held[0].y + held[1].y) / 2 };
+            const dist = Math.hypot(held[0].x - held[1].x, held[0].y - held[1].y);
+            const shown = shownSize();
+            const v = zoomAt(two.view, dist / (two.dist || 1), centred(two.mid.x, two.mid.y), shown, stageSize(), maxScale(natural(), shown));
+            // Two fingers moving together drag the picture while they zoom it.
+            set(clampView({ ...v, x: v.x + mid.x - two.mid.x, y: v.y + mid.y - two.mid.y }, shown, stageSize()));
+            return;
+        }
+        const p = press.current;
+        if (!p)
+            return;
+        const dx = e.clientX - p.x;
+        const dy = e.clientY - p.y;
+        if (view.current.s > 1 || p.pinched) {
+            set(clampView({ ...p.view, x: p.view.x + dx, y: p.view.y + dy }, shownSize(), stageSize()));
+            return;
+        }
+        if (!p.axis && Math.hypot(dx, dy) > TAP_PX)
+            p.axis = Math.abs(dx) > Math.abs(dy) ? 'x' : 'y';
+        if (p.axis === 'x') {
+            // Past either end the picture drags heavily, and lets go back to where it was.
+            const free = (dx < 0 && at < items.length - 1) || (dx > 0 && at > 0);
+            paint({ ...ONE, x: free ? dx : dx * 0.3 });
+        }
+        else if (p.axis === 'y') {
+            paint({ ...ONE, y: dy });
+            if (shell.current && dy > 0)
+                shell.current.style.background = `rgba(0,0,0,${Math.max(0.4, 1 - dy / 400)})`;
+        }
+    };
+    const onEnd = (e, cancelled = false) => {
+        if (!points.current.delete(e.pointerId))
+            return;
+        const left = Array.from(points.current.values());
+        if (left.length === 1) {
+            // One finger stays down after a pinch: it carries on panning from here.
+            pinch.current = null;
+            press.current = { x: left[0].x, y: left[0].y, t: Date.now(), view: view.current, axis: null, pinched: true };
+            return;
+        }
+        if (left.length)
+            return;
+        const p = press.current;
+        press.current = null;
+        pinch.current = null;
+        if (!p || cancelled)
+            return set(view.current, true);
+        if (p.pinched)
+            return;
+        const dx = e.clientX - p.x;
+        const dy = e.clientY - p.y;
+        const ms = Date.now() - p.t;
+        if (view.current.s > 1 && p.axis === null && Math.hypot(dx, dy) > TAP_PX)
+            return;
+        if (p.axis === 'x') {
+            const far = Math.abs(dx) > SWIPE_PX || (Math.abs(dx) > FLICK_PX && ms < FLICK_MS);
+            const d = dx < 0 ? 1 : -1;
+            if (far && items[at + d])
+                return go(d);
+            return set(ONE, true);
+        }
+        if (p.axis === 'y')
+            return dy > CLOSE_PX ? onClose() : set(ONE, true);
+        tap(e.clientX, e.clientY, e.pointerType === 'mouse');
+    };
+    const mediaStyle = { width: '100%', height: '100%', objectFit: 'contain', display: 'block', transformOrigin: 'center', userSelect: 'none', WebkitUserSelect: 'none', willChange: 'transform' };
+    const edge = (side, px) => `calc(env(safe-area-inset-${side}, 0px) + ${px}px)`;
+    const arrow = (side) => ({ ...round, position: 'absolute', top: '50%', marginTop: -22, [side]: edge(side, 10) });
+    return (_jsxs("div", { ref: shell, "data-artifact-viewer": true, "data-nospeak": true, role: "dialog", "aria-modal": "true", "aria-label": "Full screen view", tabIndex: -1, style: { position: 'fixed', inset: 0, zIndex: 2147483000, background: '#000', color: '#fff', outline: 'none', overscrollBehavior: 'contain', fontFamily: 'system-ui, -apple-system, sans-serif' }, children: [_jsx("div", { ref: stage, "data-artifact-viewer-stage": true, onPointerDown: onDown, onPointerMove: onMove, onPointerUp: onEnd, onPointerCancel: (e) => onEnd(e, true), style: { position: 'absolute', inset: 0, overflow: 'hidden', touchAction: 'none' }, children: item.video ? (_jsx("video", { ref: media, src: item.src, "aria-label": item.alt, autoPlay: true, playsInline: true, muted: !item.controls, loop: !item.controls, controls: item.controls, ...(item.controls ? { 'data-artifact-media': item.src.split(/[?#]/)[0].split('/').pop() } : {}), onLoadedMetadata: (e) => { if (item.controls)
+                        e.currentTarget.currentTime = item.el.currentTime; }, style: mediaStyle }, at)) : (
+                // eslint-disable-next-line @next/next/no-img-element
+                _jsx("img", { ref: media, src: item.src, alt: item.alt, draggable: false, style: mediaStyle }, at)) }), multiple ? (
+            // Centred: a clip's own buttons hold the top left corner on iOS.
+            _jsx("div", { style: { position: 'absolute', top: edge('top', 22), left: 0, right: 0, textAlign: 'center', fontSize: 14, opacity: 0.85, pointerEvents: 'none' }, children: `${at + 1} of ${items.length}` })) : null, _jsx("button", { type: "button", "aria-label": "Close", onClick: onClose, style: { ...round, position: 'absolute', top: edge('top', 10), right: edge('right', 10) }, children: _jsx(Icon, { d: "M6 6l12 12M18 6L6 18" }) }), items[at - 1] ? _jsx("button", { type: "button", "aria-label": "Previous", onClick: () => go(-1), style: arrow('left'), children: _jsx(Icon, { d: "M15 5l-7 7 7 7" }) }) : null, items[at + 1] ? _jsx("button", { type: "button", "aria-label": "Next", onClick: () => go(1), style: arrow('right'), children: _jsx(Icon, { d: "M9 5l7 7-7 7" }) }) : null, item.alt ? (
+            // A clip's own controls hold the bottom of the screen, so its caption sits above them.
+            _jsx("div", { style: { position: 'absolute', left: 16, right: 16, bottom: edge('bottom', item.controls ? 76 : 16), textAlign: 'center', fontSize: 14, lineHeight: 1.4, pointerEvents: 'none', textShadow: '0 1px 3px #000' }, children: item.alt })) : null] }));
+}

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

@@ -0,0 +1,23 @@
+export type Size = {
+    w: number;
+    h: number;
+};
+export type Point = {
+    x: number;
+    y: number;
+};
+export type View = {
+    s: number;
+    x: number;
+    y: number;
+};
+export declare const ONE: View;
+/** The size a picture draws at when fitted to the screen. A small picture is blown up to fill it. */
+export declare function fitted(natural: Size, stage: Size): Size;
+/** How far a picture may zoom: far enough to read a large screenshot at twice its own pixels. */
+export declare function maxScale(natural: Size, shown: Size): number;
+/** `v` with its offset held so the zoomed picture never leaves a gap it could cover. */
+export declare function clampView(v: View, shown: Size, stage: Size): View;
+/** `v` zoomed by `factor` about `p`, a point measured from the screen's centre. The picture point
+ *  under `p` stays under `p`, so a pinch zooms what the fingers are on. */
+export declare function zoomAt(v: View, factor: number, p: Point, shown: Size, stage: Size, max: number): View;

package/lib/reader/media-zoom.js

@@ -0,0 +1,30 @@
+export const ONE = { s: 1, x: 0, y: 0 };
+const MIN_MAX_SCALE = 4;
+const MAX_MAX_SCALE = 12;
+/** The size a picture draws at when fitted to the screen. A small picture is blown up to fill it. */
+export function fitted(natural, stage) {
+    if (!natural.w || !natural.h)
+        return stage;
+    const k = Math.min(stage.w / natural.w, stage.h / natural.h);
+    return { w: natural.w * k, h: natural.h * k };
+}
+/** How far a picture may zoom: far enough to read a large screenshot at twice its own pixels. */
+export function maxScale(natural, shown) {
+    const pixels = shown.w ? (2 * natural.w) / shown.w : 0;
+    return Math.min(MAX_MAX_SCALE, Math.max(MIN_MAX_SCALE, pixels));
+}
+/** `v` with its offset held so the zoomed picture never leaves a gap it could cover. */
+export function clampView(v, shown, stage) {
+    const reach = (size, room) => Math.max(0, (size * v.s - room) / 2);
+    const hold = (n, r) => (r === 0 ? 0 : Math.min(r, Math.max(-r, n)));
+    return { s: v.s, x: hold(v.x, reach(shown.w, stage.w)), y: hold(v.y, reach(shown.h, stage.h)) };
+}
+/** `v` zoomed by `factor` about `p`, a point measured from the screen's centre. The picture point
+ *  under `p` stays under `p`, so a pinch zooms what the fingers are on. */
+export function zoomAt(v, factor, p, shown, stage, max) {
+    const s = Math.min(max, Math.max(1, v.s * factor));
+    if (s === 1)
+        return ONE;
+    const k = s / v.s;
+    return clampView({ s, x: p.x - (p.x - v.x) * k, y: p.y - (p.y - v.y) * k }, shown, stage);
+}

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({
@@ -501,7 +501,7 @@ export function createArtifactRoutes(config) {
         const cover = !bot && a.cover && !/!\[[^\]]*\]\(/.test(a.markdown) ? a.cover : null;
         return (_jsxs(_Fragment, { children: [admin ? (_jsx(PageMenu, { role: roleOf(reader), name: reader ? reader.name ?? reader.email : null, share: null, comments: mode !== 'off', signIn: null, signOut: signOutUrl(a.id), history: null, markdown: null, settings: null })) : null, _jsx("main", { "data-broadcast": true, className: "mx-auto max-w-lg px-4 pt-16 pb-20 sm:pt-24", children: _jsxs("article", { id: "broadcast-root", "data-broadcast-card": true, className: "rounded-2xl border border-[color:var(--a-line)] bg-[color:var(--a-surface)] px-5 py-6 sm:px-7 sm:py-8", children: [_jsx("p", { "data-nospeak": true, "data-broadcast-from": true, className: "text-[11px] font-medium uppercase tracking-[0.3em]", style: { color: brand.accent }, children: `From ${owner}` }), _jsx("h1", { className: "mt-3 text-2xl sm:text-3xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), cover ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            _jsx("img", { src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || (effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone' && !(perReader && signInToAct(a, perReader))), signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked, bot })] }));
+                            _jsx("img", { "data-artifact-image": true, src: cover, alt: "", className: "mt-5 w-full rounded-xl border border-[color:var(--a-line)]" })) : null, _jsx("div", { "data-broadcast-body": true, className: "mt-4", children: _jsx(ArtifactMarkdown, { markdown: a.markdown, checklist: { artifactId: a.id, owner, accent: brand.accent }, embeds: embeds }) }), perReader?.note ? (_jsxs("div", { "data-for-reader": true, className: "mt-6 rounded-xl border border-[color:var(--a-line)] px-4 py-3", children: [_jsx("p", { "data-nospeak": true, className: "text-[11px] uppercase tracking-[0.2em] opacity-70", children: `For ${perReader.label}` }), _jsx("p", { className: "mt-1 text-lg", children: perReader.note })] })) : null] }) }), mode !== 'off' ? (_jsx(CommentLayer, { artifactId: a.id, rootId: "broadcast-root", ownerName: owner, comments: mode, canShare: reader !== null || (effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone' && !(perReader && signInToAct(a, perReader))), signedIn: reader !== null, isOwner: admin, version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null })) : null, perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked, bot })] }));
     }
     /** The page itself, shared by open and gated pages. */
     async function Body(a, { top, reader, perReader, untracked = false }) {
@@ -526,7 +526,7 @@ export function createArtifactRoutes(config) {
                         const n = a.version ?? (a.versions?.length ?? 0) + 1;
                         const meta = (_jsxs(_Fragment, { children: [_jsx(VersionLine, { n: n, at: a.updatedAt, numbered: seesHistory(a, reader) }), top && reader ? (_jsxs("p", { "data-nospeak": true, "data-reader-line": true, className: "mt-2 text-xs opacity-60", children: [`Signed in as ${reader.email} · `, _jsx("a", { href: switchUrl(a.id), className: "underline", children: "Use a different account" }), ' · ', _jsx("a", { href: signOutUrl(a.id), className: "underline", children: "Sign out" })] })) : null] }));
                         const header = pack.Cover ? (_jsx(pack.Cover, { title: a.title, subtitle: a.subtitle, summary: a.summary, to: a.to, markdown: a.markdown, kicker: _jsx(Kicker, { to: a.to, brand: brand }), meta: meta, version: n, showVersion: seesHistory(a, reader), updatedAt: a.updatedAt, createdAt: a.createdAt })) : (_jsxs("div", { className: `mx-auto max-w-2xl px-6 ${top ? 'pt-24 sm:pt-28' : 'pt-12'} pb-8 text-center`, children: [_jsx(Kicker, { to: a.to, brand: brand }), _jsx("h1", { className: "text-4xl sm:text-5xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.title }), a.subtitle ? (_jsx("p", { className: "mx-auto mt-4 max-w-xl text-xl sm:text-2xl", style: { fontFamily: brand.type.display, color: brand.ink }, children: a.subtitle })) : null, _jsx("p", { className: "mx-auto mt-6 max-w-xl text-lg italic opacity-80", children: a.summary }), meta] }));
-                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.closesAt && !perReader.owner ? (_jsx(FeedbackWindow, { owner: owner, label: perReader.label, note: perReader.note, group: perReader.group, closesAt: perReader.closesAt })) : perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
+                        return (_jsx(Framed, { pack: pack, toc: toc.length ? _jsx(TocInline, { items: toc }) : null, cover: _jsxs(_Fragment, { children: [perReader?.closesAt && !perReader.owner ? (_jsx(FeedbackWindow, { owner: owner, label: perReader.label, note: perReader.note, group: perReader.group, closesAt: perReader.closesAt })) : perReader?.note ? (_jsx("p", { "data-for-reader": true, className: "mx-auto mt-6 mb-0 max-w-2xl px-6 text-lg", children: `For ${perReader.label}: ${perReader.note}` })) : null, header, a.cover ? (_jsx("div", { className: "mx-auto max-w-2xl px-6 pb-8", children: _jsx("img", { "data-artifact-image": true, src: a.cover, alt: "", className: "w-full rounded-xl border border-[color:var(--a-line)]" }) })) : null] }), children: _jsx(ArtifactMarkdown, { markdown: a.markdown, definitions: a.definitions, notes: config.state && a.state ? { artifactId: a.id, accent: brand.accent } : undefined, 
                                 // Ticks are kept in the reader's browser on any host; Send needs one that keeps answers.
                                 checklist: { artifactId: a.id, send: !!config.state && !!a.state && Object.hasOwn(a.state.slots, CHECKLIST_SLOT), owner, accent: brand.accent }, Section: pack.Section, figure: pack.figure, embeds: embeds }) }));
                     })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || (effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone' && !(perReader && signInToAct(a, perReader)))), signedIn: reader !== null, isOwner: isAdmin(reader), version: a.version ?? (a.versions?.length ?? 0) + 1, accent: brand.accent, ground: brand.ground, signIn: signInOrigin ? signInUrl(signInOrigin, pageUrl(a.id)) : null, closesAt: perReader && !perReader.owner ? perReader.closesAt : null, requireName: a.commentName === 'required' && perReader?.group === true, knownName: a.commentName === 'required' && perReader && !perReader.group && !perReader.owner ? perReader.label : null }), perReader && !perReader.owner ? _jsx(QuietView, { id: a.id, rid: perReader.rid, sig: perReader.sig, token: perReader.token }) : null, await Analytics(a, { reader, perReader, untracked }), a.narration && words.length > 0 ? (_jsx(ArtifactReader, { src: a.narration, words: words, rootId: "artifact-narration-root", accent: brand.accent, ground: brand.ground })) : null /* No recorded narration: no player. Never the browser's own voice (the operator,
@@ -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.59.0",
+  "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",