@supersuit/artifacts 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 `@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.50.0 (2026-10-19)
+
+**Product analytics, with video of each visit.** A host that passes `analytics: { posthogKey,
+posthogHost?, tenant? }` to `createArtifactRoutes` gets PostHog on its pages: session replay (text
+fields masked, PostHog's default), heatmaps, autocapture, and `$pageleave` with scroll depth, plus
+two kinds of reading PostHog cannot see on its own: `section_viewed` (the heading's id and text and
+the visible seconds spent in it, timed by the contents rail's own rule, now `currentSection` in
+`toc-spy.tsx`) and `narration_play` / `narration_pause` / `narration_complete` (the narration
+`<audio>` now carries `data-artifact-narration`). Every event carries `artifact_id`, `page_kind`
+and `tenant`. The rules live in one pure function, `analyticsPlan` (`reader/analytics-plan.ts`):
+no key, no script at all (posthog-js is imported only by `PageAnalytics`, after mount); never the
+owner or an admin, signed in, previewing `?as=reader`, or on the owner's own per-reader link; never
+a link-preview fetcher; never a past version. A reader is identified only where the page already
+knows them: a gated page by the signed-in email, a per-reader link as `recipient:<rid>` with its
+label. Public and password pages stay anonymous, even for a signed-in reader. A gated page also
+masks all text in its replays, because its body is confidential and a replay is a copy of it.
+
+- DETECTOR: a host that wants analytics has none; with no `analytics` config nothing changes and
+  no analytics code is downloaded.
+- REMEDY: pass `analytics` per tenant (a public `phc_` project key). Turn on session replay and
+  heatmaps in the PostHog project's settings, which is where PostHog switches them on.
+- Tests: analytics-plan.test.ts (no key, owner, bot, anonymous kinds, gated and per-reader
+  identity), page-analytics-mount.test.tsx (where it mounts on real routes, and as whom),
+  page-analytics.test.ts (section timing, narration events).
+
 ## 0.49.0 (2026-10-16)
 
 **The default look is Supersuit's, the Maison.** The product the default pack is named for became

package/README.md

@@ -1174,6 +1174,22 @@ export const config = { matcher: ['/:id([a-z0-9]{8})'] }
 
 Any per-reader page served to a known unfurl fetcher (or a request with no user agent) carries its text only: no media, no signed URL, no reader's note, no cookie. `readHeader` on `createArtifactRoutes` reads the agent (default through `next/headers`). `DELETE /api/artifacts/<id>` removes the page's files from both buckets (`deletePage`), then its readers, their notes and views and every comment, before the record, and keeps the record (502) if the files could not go, so it can be run again.
 
+## Product analytics (`analytics`)
+
+Pass `analytics: { posthogKey: 'phc_...', posthogHost?: 'https://us.i.posthog.com', tenant?: 'name' }`
+to `createArtifactRoutes` and the host's pages record visits in PostHog: session replay, heatmaps,
+autocapture, scroll depth on leave, `section_viewed` (heading id, text, seconds) and
+`narration_play` / `narration_pause` / `narration_complete`. Without it no page loads any analytics
+code. Switch session replay and heatmaps on in the PostHog project as well.
+
+Who is recorded, and as whom (`analyticsPlan`, `src/reader/analytics-plan.ts`):
+
+- Never the owner or an admin (signed in, previewing `?as=reader`, or on the owner's own per-reader
+  link), never a link-preview fetcher, never a past version.
+- A gated page identifies the signed-in reader by email and masks all text in its replays.
+- A per-reader link identifies as `recipient:<rid>` with the label the publisher gave it.
+- A public or password page stays anonymous.
+
 ## Brand packs
 
 A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,

package/lib/artifacts/toc-spy.d.ts

@@ -1,3 +1,8 @@
+/** How far below the top of the screen a heading may sit and still be the section being read. */
+export declare const READING_LINE = 140;
+/** The section being read: the last heading at or above the reading line, else the first. The
+ *  page analytics times sections by the same rule, so a section's dwell matches the rail. */
+export declare function currentSection(ids: string[], doc?: Document): string | undefined;
 export declare function TocSpy({ slugs }: {
     slugs: string[];
 }): null;

package/lib/artifacts/toc-spy.js

@@ -2,6 +2,19 @@
 // Marks the contents entry for the section being read. Renders nothing: it only sets
 // aria-current on the links the server drew, which is also what styles them.
 import { useEffect } from 'react';
+/** How far below the top of the screen a heading may sit and still be the section being read. */
+export const READING_LINE = 140;
+/** The section being read: the last heading at or above the reading line, else the first. The
+ *  page analytics times sections by the same rule, so a section's dwell matches the rail. */
+export function currentSection(ids, doc = document) {
+    let current = ids[0];
+    for (const id of ids) {
+        const el = doc.getElementById(id);
+        if (el && el.getBoundingClientRect().top <= READING_LINE)
+            current = id;
+    }
+    return current;
+}
 export function TocSpy({ slugs }) {
     const key = slugs.join('|');
     useEffect(() => {
@@ -9,12 +22,7 @@ export function TocSpy({ slugs }) {
         let frame = 0;
         const mark = () => {
             frame = 0;
-            let current = ids[0];
-            for (const id of ids) {
-                const el = document.getElementById(id);
-                if (el && el.getBoundingClientRect().top <= 140)
-                    current = id;
-            }
+            const current = currentSection(ids);
             document.querySelectorAll('a[data-toc-slug]').forEach((a) => {
                 if (a.dataset.tocSlug === current)
                     a.setAttribute('aria-current', 'location');

package/lib/reader/analytics-plan.d.ts

@@ -0,0 +1,41 @@
+export type AnalyticsConfig = {
+    /** A PostHog project API key (the public `phc_...` one, safe in a browser). */
+    posthogKey: string;
+    /** The ingestion host. Default PostHog's US cloud. */
+    posthogHost?: string;
+    /** Sent with every event as `tenant`, so one project can hold several hosts' pages. */
+    tenant?: string;
+};
+export type PageKind = 'public' | 'password' | 'gated' | 'per-reader';
+export type AnalyticsPlan = {
+    key: string;
+    host: string;
+    pageId: string;
+    kind: PageKind;
+    tenant: string | null;
+    /** Who to identify the reader as, or null to keep them anonymous. */
+    identity: {
+        distinctId: string;
+        email?: string;
+        name?: string;
+    } | null;
+};
+export declare const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+export declare function analyticsPlan(input: {
+    config: AnalyticsConfig | null | undefined;
+    pageId: string;
+    kind: PageKind;
+    /** The owner or an admin is looking (signed in, previewing as a reader, or on the owner's own link). */
+    owner: boolean;
+    bot: boolean;
+    /** A gated page's signed-in reader. */
+    reader?: {
+        email: string;
+        name?: string | null;
+    } | null;
+    /** A per-reader link's recipient. */
+    recipient?: {
+        rid: string;
+        label: string;
+    } | null;
+}): AnalyticsPlan | null;

package/lib/reader/analytics-plan.js

@@ -0,0 +1,33 @@
+// Whether a page view is recorded in the host's product analytics, and as whom. Pure, so the route
+// decides on the server and the browser is handed either nothing or exactly what to send.
+//
+// THE RULES (0.50.0):
+//  - A host with no analytics key records nothing, and its pages load no analytics script at all.
+//  - The owner and the host's admins are never recorded, signed in or on their own per-reader link.
+//  - A link-preview fetcher is never handed the script.
+//  - A reader is identified only where the page already knows who they are: a gated page by the
+//    signed-in email, a per-reader link by its opaque recipient id and the label the publisher gave
+//    it (never a phone or an email, which the recipients store does not hold). A public or password
+//    page stays anonymous, even when its reader happens to be signed in.
+export const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com';
+export function analyticsPlan(input) {
+    const key = input.config?.posthogKey?.trim();
+    if (!key || input.owner || input.bot)
+        return null;
+    let identity = null;
+    if (input.kind === 'gated' && input.reader?.email) {
+        const email = input.reader.email.trim().toLowerCase();
+        identity = { distinctId: email, email, ...(input.reader.name ? { name: input.reader.name } : {}) };
+    }
+    else if (input.kind === 'per-reader' && input.recipient?.rid) {
+        identity = { distinctId: `recipient:${input.recipient.rid}`, name: input.recipient.label };
+    }
+    return {
+        key,
+        host: input.config.posthogHost?.trim() || DEFAULT_POSTHOG_HOST,
+        pageId: input.pageId,
+        kind: input.kind,
+        tenant: input.config.tenant ?? null,
+        identity,
+    };
+}

package/lib/reader/artifact-reader.js

@@ -275,7 +275,7 @@ export function ArtifactReader({ src, words, rootId, accent, ground, }) {
         else
             a.pause();
     };
-    return (_jsxs(_Fragment, { children: [_jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => {
+    return (_jsxs(_Fragment, { children: [_jsx("audio", { ref: audioRef, "data-artifact-narration": true, src: src, preload: "metadata", onPlay: () => {
                     startedRef.current = true;
                     playingRef.current = true;
                     setPlaying(true);

package/lib/reader/index.d.ts

@@ -13,3 +13,5 @@ export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom
 export { VoiceRecorder, AudioPlay, hostVoice, pickRecordingType, newMemoId, recognitionCtor, LIVE_LINE, type VoiceHost, type VoiceMemo, type VoiceScope } from './voice-recorder.js';
 export { deviceAudio, isDeviceAudio, type DeviceAudio } from './device-audio.js';
 export { type SavedMemo } from './comment-card.js';
+export { PageAnalytics, trackSections, narrationEvent, MIN_SECTION_SECONDS } from './page-analytics.js';
+export { analyticsPlan, DEFAULT_POSTHOG_HOST, type AnalyticsConfig, type AnalyticsPlan, type PageKind } from './analytics-plan.js';

package/lib/reader/index.js

@@ -14,3 +14,5 @@ export { deviceNotes, deviceNotesKey, addDeviceNote, replaceDeviceNote, removeDe
 export { indexText, offsetAt, rangeOf, headingAt, placeAnchor, boxOf, regionFrom } from './comment-place.js';
 export { VoiceRecorder, AudioPlay, hostVoice, pickRecordingType, newMemoId, recognitionCtor, LIVE_LINE } from './voice-recorder.js';
 export { deviceAudio, isDeviceAudio } from './device-audio.js';
+export { PageAnalytics, trackSections, narrationEvent, MIN_SECTION_SECONDS } from './page-analytics.js';
+export { analyticsPlan, DEFAULT_POSTHOG_HOST } from './analytics-plan.js';

package/lib/reader/page-analytics.d.ts

@@ -0,0 +1,21 @@
+import type { AnalyticsPlan } from './analytics-plan.js';
+/** Sections read for less than this are passed over, not read. */
+export declare const MIN_SECTION_SECONDS = 2;
+type Capture = (event: string, props?: Record<string, unknown>) => void;
+/** Times the section being read, by the contents rail's own rule, and reports each one as the
+ *  reader leaves it. Only visible time counts. Returns a stop function that flushes the last one. */
+export declare function trackSections(ids: string[], capture: Capture, doc?: Document, now?: () => number): {
+    check: () => void;
+    stop: () => void;
+};
+/** The narration's events: play, pause with where it stopped, complete. */
+export declare function narrationEvent(type: string, audio: {
+    currentTime: number;
+    duration: number;
+    ended?: boolean;
+}): [string, Record<string, unknown>] | null;
+export declare function PageAnalytics({ plan, rootId }: {
+    plan: AnalyticsPlan;
+    rootId?: string;
+}): null;
+export {};

package/lib/reader/page-analytics.js

@@ -0,0 +1,119 @@
+'use client';
+// The host's product analytics on a page: PostHog, with session replay, heatmaps, autocapture and
+// scroll depth on leave, plus the reading this package knows about and PostHog cannot: which
+// section was read and for how long, and the narration played, paused and finished.
+//
+// The server decides whether this mounts at all and as whom (analytics-plan.ts). posthog-js is
+// imported only here, after mount, so a host with no key never downloads it.
+//
+// Text fields are masked in replays (PostHog's default). A gated page masks ALL text too, because
+// its body is confidential and a replay is a copy of it held by a third party: the replay still
+// shows where the reader went, how far and how fast, without the words.
+import { useEffect } from 'react';
+import { currentSection } from '../artifacts/toc-spy.js';
+/** Sections read for less than this are passed over, not read. */
+export const MIN_SECTION_SECONDS = 2;
+/** Times the section being read, by the contents rail's own rule, and reports each one as the
+ *  reader leaves it. Only visible time counts. Returns a stop function that flushes the last one. */
+export function trackSections(ids, capture, doc = document, now = Date.now) {
+    let current;
+    let since = null;
+    const visible = () => doc.visibilityState === 'visible';
+    const flush = () => {
+        if (!current || since === null)
+            return;
+        const seconds = Math.round((now() - since) / 1000);
+        if (seconds >= MIN_SECTION_SECONDS) {
+            const heading = doc.getElementById(current)?.textContent?.trim() ?? '';
+            capture('section_viewed', { section_id: current, heading, seconds });
+        }
+        since = null;
+    };
+    const check = () => {
+        if (!visible()) {
+            flush();
+            return;
+        }
+        const next = currentSection(ids, doc);
+        if (next !== current) {
+            flush();
+            current = next;
+        }
+        if (since === null)
+            since = now();
+    };
+    return { check, stop: flush };
+}
+/** The narration's events: play, pause with where it stopped, complete. */
+export function narrationEvent(type, audio) {
+    const at = { position_seconds: Math.round(audio.currentTime), duration_seconds: Number.isFinite(audio.duration) ? Math.round(audio.duration) : null };
+    if (type === 'play')
+        return ['narration_play', at];
+    if (type === 'pause' && !audio.ended)
+        return ['narration_pause', at];
+    if (type === 'ended')
+        return ['narration_complete', at];
+    return null;
+}
+export function PageAnalytics({ plan, rootId = 'artifact-narration-root' }) {
+    const { key, host, pageId, kind, tenant } = plan;
+    const identity = plan.identity ? JSON.stringify(plan.identity) : '';
+    useEffect(() => {
+        let cancelled = false;
+        let cleanup = () => { };
+        void import('posthog-js').then(({ default: posthog }) => {
+            if (cancelled)
+                return;
+            posthog.init(key, {
+                api_host: host,
+                person_profiles: 'identified_only',
+                capture_pageview: true,
+                capture_pageleave: true,
+                autocapture: true,
+                enable_heatmaps: true,
+                disable_session_recording: false,
+                session_recording: { maskAllInputs: true, ...(kind === 'gated' ? { maskTextSelector: '*' } : {}) },
+            });
+            posthog.register({ artifact_id: pageId, page_kind: kind, ...(tenant ? { tenant } : {}) });
+            if (identity) {
+                const who = JSON.parse(identity);
+                posthog.identify(who.distinctId, { ...(who.email ? { email: who.email } : {}), ...(who.name ? { name: who.name } : {}) });
+            }
+            const capture = (e, p) => posthog.capture(e, p);
+            const root = document.getElementById(rootId);
+            const ids = root ? Array.from(root.querySelectorAll('h2[id], h3[id]'), (h) => h.id) : [];
+            const sections = ids.length ? trackSections(ids, capture) : null;
+            let frame = 0;
+            const onScroll = () => { if (sections && !frame)
+                frame = requestAnimationFrame(() => { frame = 0; sections.check(); }); };
+            const onVisibility = () => sections?.check();
+            const onHide = () => sections?.stop();
+            const onMedia = (e) => {
+                const el = e.target;
+                if (!el?.hasAttribute?.('data-artifact-narration'))
+                    return;
+                const ev = narrationEvent(e.type, el);
+                if (ev)
+                    capture(...ev);
+            };
+            sections?.check();
+            window.addEventListener('scroll', onScroll, { passive: true });
+            document.addEventListener('visibilitychange', onVisibility);
+            window.addEventListener('pagehide', onHide);
+            for (const t of ['play', 'pause', 'ended'])
+                document.addEventListener(t, onMedia, true);
+            cleanup = () => {
+                sections?.stop();
+                if (frame)
+                    cancelAnimationFrame(frame);
+                window.removeEventListener('scroll', onScroll);
+                document.removeEventListener('visibilitychange', onVisibility);
+                window.removeEventListener('pagehide', onHide);
+                for (const t of ['play', 'pause', 'ended'])
+                    document.removeEventListener(t, onMedia, true);
+            };
+        }).catch(() => { });
+        return () => { cancelled = true; cleanup(); };
+    }, [key, host, pageId, kind, tenant, identity, rootId]);
+    return null;
+}

package/lib/routes/artifacts.d.ts

@@ -10,6 +10,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 AnalyticsConfig } from '../reader/analytics-plan.js';
 import type { PersonalStore } from '../artifacts/personal-store.js';
 import type { Transcriber } from '../artifacts/transcribe.js';
 export type ArtifactRoutesConfig = {
@@ -121,6 +122,12 @@ export type ArtifactRoutesConfig = {
     recipients?: RecipientsStore;
     /** Signs per-reader links and render tokens. At least 32 characters. Read at request time. */
     recipientSecret?: () => string | undefined;
+    /** 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
+     *  fetcher, never a past version; identifies a reader only on a gated page (their email) or a
+     *  per-reader link (its recipient id and label). See reader/analytics-plan.ts. */
+    analytics?: AnalyticsConfig | null;
 };
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export declare const ARTIFACT_ID: RegExp;

package/lib/routes/artifacts.js

@@ -36,6 +36,8 @@ import { ARTIFACT_ID_RE } from './ids.js';
 import { createStateRoutes } from './state-routes.js';
 import { createRecipientsRoutes } from './recipients-routes.js';
 import { QuietView } from '../reader/quiet-view.js';
+import { PageAnalytics } from '../reader/page-analytics.js';
+import { analyticsPlan } from '../reader/analytics-plan.js';
 import { createPersonalRoutes } from './personal-routes.js';
 import { createVoiceRoutes } from './voice-routes.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
@@ -317,7 +319,7 @@ export function createArtifactRoutes(config) {
         if (!a)
             notFound();
         const { pack, brand } = lookOf(a);
-        const render = (top, reader) => (n === null ? Body(a, { top, reader }) : VersionBody(a, n, { top, reader }));
+        const render = (top, reader, untracked = false) => (n === null ? Body(a, { top, reader, untracked }) : VersionBody(a, n, { top, reader }));
         if (a.access)
             return GatedPage(a, id, render, n);
         const broadcast = kindOf(a) === 'broadcast';
@@ -338,7 +340,7 @@ export function createArtifactRoutes(config) {
             if (isAdmin(me)) {
                 const markdown = await media(a.markdown);
                 const viewer = wantsReaderView(sp) ? null : me;
-                const page = broadcast ? await BroadcastCard({ ...a, markdown }, { reader: viewer, bot }) : await Body({ ...a, markdown }, { top: true, reader: viewer });
+                const page = broadcast ? await BroadcastCard({ ...a, markdown }, { reader: viewer, bot, untracked: true }) : await Body({ ...a, markdown }, { top: true, reader: viewer, untracked: true });
                 return _jsxs(BrandGround, { pack: pack, mode: a.theme, children: [viewer ? null : _jsx(ViewingAsReader, { back: pagePath(id) }), page] });
             }
             const secret = usableSecret(config.recipientSecret?.());
@@ -389,7 +391,7 @@ export function createArtifactRoutes(config) {
         // rendered for no one signed in, with a bar back to their own view. Anyone else asking gets the
         // page they already get.
         const asReader = isAdmin(reader) && wantsReaderView(sp);
-        const page = await render(true, asReader ? null : reader);
+        const page = await render(true, asReader ? null : reader, asReader);
         if (n === null && !asReader)
             void store.bumpViews(id);
         return (_jsxs(BrandGround, { pack: pack, mode: a.theme, children: [remember ? _jsx("script", { dangerouslySetInnerHTML: { __html: remember } }) : null, asReader ? _jsx(ViewingAsReader, { back: n === null ? pagePath(id) : `${pagePath(id)}/v/${n}` }) : null, page] }));
@@ -481,7 +483,7 @@ export function createArtifactRoutes(config) {
      *  them, then this reader's own note. None of the document's furniture: no table of contents, no
      *  version line, no read-along (a voice note is its own audio), and no page menu for a reader.
      *  Comments only when the file turned them on; the quiet view beacon always, for a reader. */
-    async function BroadcastCard(a, { reader, perReader, bot }) {
+    async function BroadcastCard(a, { reader, perReader, bot, untracked = false }) {
         const { brand } = lookOf(a);
         const mode = !bot && config.state && a.state && a.comments && a.comments !== 'off' && a.state.slots[COMMENTS_SLOT] ? a.comments : 'off';
         const admin = isAdmin(reader);
@@ -489,10 +491,10 @@ 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', 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] }));
+                            _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', 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 }) {
+    async function Body(a, { top, reader, perReader, untracked = false }) {
         const { pack, brand } = lookOf(a);
         let words = [];
         if (a.narration && a.timings) {
@@ -517,10 +519,27 @@ export function createArtifactRoutes(config) {
                         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, 
                                 // 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'), 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, 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,
+                    })() }), _jsx(CommentLayer, { artifactId: a.id, rootId: "artifact-narration-root", ownerName: owner, comments: mode, canShare: mode !== 'off' && (reader !== null || effectiveWriters(a.state, a.access, COMMENTS_SLOT) === 'anyone'), signedIn: reader !== null, isOwner: 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,
                   2026-09-29: "NEVER PUT DEFAULT SAFARI VOICE DICTATION"); the audio is Kokoro or ElevenLabs,
                   recorded at publish, or there is none. */] }));
     }
+    /** The page's analytics, or nothing (analytics-plan.ts has the rules). `untracked` is the owner or
+     *  an admin previewing as a reader, who arrives here with no reader at all. */
+    async function Analytics(a, { reader, perReader, untracked, bot }) {
+        if (!config.analytics?.posthogKey)
+            return null;
+        const ua = bot === undefined ? await (config.readHeader ?? defaultReadHeader)('user-agent').catch(() => undefined) : undefined;
+        const plan = analyticsPlan({
+            config: config.analytics,
+            pageId: a.id,
+            kind: perReader ? 'per-reader' : a.access ? 'gated' : a.password ? 'password' : 'public',
+            owner: untracked || isAdmin(reader) || !!perReader?.owner,
+            bot: bot ?? (ua !== undefined && isUnfurlAgent(ua)),
+            reader: a.access ? reader : null,
+            recipient: perReader ? { rid: perReader.rid, label: perReader.label } : null,
+        });
+        return plan ? _jsx(PageAnalytics, { plan: plan }) : null;
+    }
     const cookieLine = (value, maxAge) => `${GRANT_COOKIE}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
     /** GET /api/reader/enter?pass=<pass>&to=/<id>: where the sign-in authority sends a signed-in
      *  reader. Swaps the five-minute pass for this host's grant and lands them on the page, with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.49.0",
+  "version": "0.50.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",
@@ -80,6 +80,7 @@
   },
   "dependencies": {
     "gray-matter": "^4.0.3",
+    "posthog-js": "1.438.6",
     "react-markdown": "^9.0.3",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",