@supersuit/artifacts 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 `@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
+Supersuit on 2026-10-14, and its maker's house look, the Maison, became the brand on 2026-10-15.
+`freedomDefault` (the export keeps its name, so no host breaks) now reads "A page from Supersuit"
+and names Supersuit in metadata (`siteName`); paints night `#17171a` with mist `#d8d1c4` and bronze
+`#a8834f` by default and travertine `#e8e0d2` with ink `#1c1a17` and bronze deepened with ink in
+light mode, each text and accent pairing at 4.5:1 or better; and sets DM Serif Display over DM Sans
+by name (Georgia and the system face if a host does not load them; README, "The default look's
+faces"). The default mark (`BrandMark` with no `Mark`) is a short rule in the accent instead of a
+dove: the dove stood for the agent, and no figure stands in for her until her look is designed.
+What a reader reads moves with the name: the confidential door's default line ("the Google account
+your Supersuit account uses"), the member reason ("you are a Supersuit user"), and the share
+sheet's "Any Supersuit account" and "Supersuit accounts get in without being on the list." The
+`freedom` access level keeps its identifier. A pack of a host's own is untouched, and the share
+card keeps the bundled Newsreader so no tracing config changes.
+
+- DETECTOR: a host whose operators have no pack of their own (`freedomDefault`, or a spread of it
+  with only the kicker changed) renders on the night ground with bronze, not the old near-black and
+  gold, and its kicker says Supersuit.
+- REMEDY: nothing required. To draw the default look in its own faces, load DM Serif Display and
+  DM Sans in the host's root layout (README).
+- Tests: pack.test.tsx (the default look: tokens only, 4.5:1 pairings, the house pair, no dove, no
+  Freedom), the default-pages golden regenerated on purpose (palette, faces and kicker only), and
+  the kicker, metadata and door expectations in artifacts, to, extension-points and gated.
+
 ## 0.48.0
 
 **Unpublishing keeps the history.** `POST /api/artifacts?id=<id>&unpublish=1` takes a page off the

package/README.md

@@ -5,7 +5,7 @@ site shell behind that: the store, the route handlers, the read-along reader, br
 password pages, confidential pages with a signed-in reader list, and the share card a link
 unfurls as. You mount it in a Next.js App Router app with a handful of one-line route files.
 
-It is the shell that serves every Freedom operator's `artifacts.<theirname>` page, published
+It is the shell that serves every Supersuit operator's `artifacts.<theirname>` page, published
 openly because none of it is secret and all of it is better with more eyes on it.
 
 ```bash
@@ -23,7 +23,7 @@ Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
 | `createArtifactStore(db, path)` | Firestore store for pages and their version history, under any collection path |
 | `createReadersStore(db, path)` | The record for confidential pages: allowlist, agreements, reading sessions, flags |
 | `createArtifactAssets(bucket, prefix, { privateBucket? })` | Uploaded images for a page, in a Cloud Storage bucket; private media in a separate private bucket |
-| `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
+| `freedomDefault`, `BrandPack` | The default look (Supersuit's, the Maison) and the type any other look implements |
 | `BrandGround`, `BrandMark` | The pack's page backdrop and mark, for your own pages (a home, a 404) |
 | `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing (widget fences included) |
 | `headingsOf`, `scanWidgets`, `placeNotes` | The notes widget's pure parts: heading slugs, fence validation, where each note shows |
@@ -164,7 +164,7 @@ anyone else. `PageMenu`, `roleLine` and `menuItems` are exported from `/reader`.
 The owner and the hub's admins change a page's settings from the menu, with no republish. Each item
 opens a sheet (from the bottom on a phone, under the button on a desk):
 
-- **Share settings.** Who can open it: anyone with the link, any Freedom account (plus the list),
+- **Share settings.** Who can open it: anyone with the link, any Supersuit account (plus the list),
   or only the list. The list itself: add or remove an email. On a page open to anyone, a password
   on or off (on makes a 12-character key). The link to send, with a Copy button: on a password page
   it carries the key. Under them, read-only lines: what a stranger with the bare URL sees and what
@@ -314,7 +314,7 @@ their change alone.
 
 ## A confidential page (`access:`)
 
-`access: freedom` opens the page only to a signed-in reader with an active Freedom account or
+`access: freedom` opens the page only to a signed-in reader with an active Supersuit account or
 on the page's list; `access: invite` opens it only to the list. Everyone else gets the title,
 the summary and a sign-in door; the body never reaches them.
 
@@ -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,
@@ -1181,6 +1197,16 @@ an optional full-page `Wrapper` and `Mark`, and an optional `share` block
 (a font loader and a backdrop) that draws the unfurl card. `freedomDefault` is the default look.
 Keep a pack carrying your own trademark in your own app, not in a pull request here.
 
+**The default look's faces.** Since 0.49.0 `freedomDefault` is Supersuit's own look, the Maison:
+night with mist type and bronze by default, travertine with ink behind the light toggle, every
+colour one of seven stone tokens or a mix of two, and the mark above the kicker a short rule in
+the accent (no dove). It sets DM Serif Display for headings and DM Sans for reading, by name. The
+package does not fetch them, so a host that wants them loads them itself, for example
+`import '@fontsource/dm-serif-display/400.css'` and `import '@fontsource/dm-sans/400.css'` (plus
+500 and 600) in its root layout, which serves the files from the host's own origin. A host that
+does not falls back to Georgia and the system face. The share card still sets its title in the
+bundled Newsreader, so no host's `outputFileTracingIncludes` has to change.
+
 **Light, dark or system.** A pack's `ground`, `ink` and `accent` are its dark palette; `light` is
 the other one (absent, warm paper with the pack's accent), and `mode` is the one a page opens in
 (`dark` by default; a page's `theme:` overrides it). Pages paint with CSS variables

package/lib/artifacts/confidential.d.ts

@@ -25,9 +25,10 @@ export declare function Watermark({ email }: {
 }): import("react").JSX.Element;
 /** Printing shows this and nothing else, whichever way the print dialog was reached. */
 export declare const NO_PRINT_CSS = "@media print { body * { visibility: hidden !important; } body::after { content: \"This page is confidential and cannot be printed.\"; visibility: visible; position: fixed; top: 40%; left: 0; right: 0; text-align: center; font: 16px sans-serif; color: #000; } }";
-/** The door's default line, for a host whose readers sign in with a Freedom account. A host
+/** The door's default line, for a host whose readers sign in with a Supersuit account (the product
+ *  called Freedom until 2026-10-14; the access level keeps its `freedom` identifier). A host
  *  that signs readers in some other way passes `signInNote` to say so in its own words. */
-export declare const DEFAULT_SIGN_IN_NOTE = "This page is confidential. Sign in with the Google account your Freedom account uses, or the address it was shared with.";
+export declare const DEFAULT_SIGN_IN_NOTE = "This page is confidential. Sign in with the Google account your Supersuit account uses, or the address it was shared with.";
 export declare function SignInDoor({ brand, href, note }: {
     brand: BrandPack;
     href?: string;

package/lib/artifacts/confidential.js

@@ -19,9 +19,10 @@ export function Watermark({ email }) {
 }
 /** Printing shows this and nothing else, whichever way the print dialog was reached. */
 export const NO_PRINT_CSS = `@media print { body * { visibility: hidden !important; } body::after { content: "This page is confidential and cannot be printed."; visibility: visible; position: fixed; top: 40%; left: 0; right: 0; text-align: center; font: 16px sans-serif; color: #000; } }`;
-/** The door's default line, for a host whose readers sign in with a Freedom account. A host
+/** The door's default line, for a host whose readers sign in with a Supersuit account (the product
+ *  called Freedom until 2026-10-14; the access level keeps its `freedom` identifier). A host
  *  that signs readers in some other way passes `signInNote` to say so in its own words. */
-export const DEFAULT_SIGN_IN_NOTE = 'This page is confidential. Sign in with the Google account your Freedom account uses, or the address it was shared with.';
+export const DEFAULT_SIGN_IN_NOTE = 'This page is confidential. Sign in with the Google account your Supersuit account uses, or the address it was shared with.';
 export function SignInDoor({ brand, href, note = DEFAULT_SIGN_IN_NOTE }) {
     // No href means the host configured no sign-in authority: the door stays, with no way through.
     if (!href) {

package/lib/artifacts/reader.d.ts

@@ -50,7 +50,7 @@ export type Decision = {
     why: 'not-allowed';
     reader: Reader;
 };
-export declare const MEMBER_REASON = "you are a Freedom user";
+export declare const MEMBER_REASON = "you are a Supersuit user";
 export declare const LISTED_REASON = "you were given access to it by name";
 export declare const STAFF_REASON = "you are its owner or an admin of this hub";
 /** Whether this reader may open a page with this access level. The allowlist opens both

package/lib/artifacts/reader.js

@@ -90,7 +90,7 @@ export function mintGrant(secret, reader, now = Date.now()) {
 export function verifyGrant(secret, grant, now = Date.now()) {
     return decode(secret, 'artifact-grant', 'g1', grant, now);
 }
-export const MEMBER_REASON = 'you are a Freedom user';
+export const MEMBER_REASON = 'you are a Supersuit user';
 export const LISTED_REASON = 'you were given access to it by name';
 export const STAFF_REASON = 'you are its owner or an admin of this hub';
 /** Whether this reader may open a page with this access level. The allowlist opens both

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

@@ -38,7 +38,7 @@ export type BrandPack = {
     };
     /** The small uppercase line above a title, e.g. "From Sam Rivera". */
     kicker: string;
-    /** Unused since 0.33.1: the player bar names no narrator (it read "Read aloud by Freedom").
+    /** Unused since 0.33.1: the player bar names no narrator.
      *  Optional so a pack that still sets it compiles; nothing reads it. */
     narratorLabel?: (voice?: string) => string;
     /** Optional full-page backdrop. Receives the page as children. */
@@ -140,4 +140,19 @@ export type ShareCardAssets = {
      *  a blur or a glow is baked in here; the renderer only sets type. Absent, `ground` fills. */
     backdrop?: () => Promise<string>;
 };
+/**
+ * THE DEFAULT LOOK: Supersuit's own, for every operator with no pack of their own. Named
+ * `freedomDefault` because the product was Freedom until 2026-10-14; the export keeps its name so
+ * no host breaks, and everything a reader sees says Supersuit.
+ *
+ * Since 0.49.0 it is the Maison, the house look of Supersuit's maker: stone, and colour only for
+ * context. Night (#17171a) with mist type and bronze by default; travertine with ink one tap away,
+ * its accent bronze deepened with ink so a link reads at 4.5:1. Every value is one of the house's
+ * seven tokens or a mix of two (night, walnut, travertine, marble, bronze, ink, mist). The dark
+ * palette stays plain hex because the share card draws with it and its renderer has no color-mix().
+ *
+ * Type is the house pair: DM Serif Display to inscribe, DM Sans to read. Both are named, not
+ * fetched: a host loads them (README, "The default look's faces"), and one that does not falls back
+ * to Georgia and the system face rather than asking a font service for them on every page view.
+ */
 export declare const freedomDefault: BrandPack;

package/lib/brand/pack.js

@@ -1,16 +1,31 @@
 import { newsreader } from './default-share.js';
+/**
+ * THE DEFAULT LOOK: Supersuit's own, for every operator with no pack of their own. Named
+ * `freedomDefault` because the product was Freedom until 2026-10-14; the export keeps its name so
+ * no host breaks, and everything a reader sees says Supersuit.
+ *
+ * Since 0.49.0 it is the Maison, the house look of Supersuit's maker: stone, and colour only for
+ * context. Night (#17171a) with mist type and bronze by default; travertine with ink one tap away,
+ * its accent bronze deepened with ink so a link reads at 4.5:1. Every value is one of the house's
+ * seven tokens or a mix of two (night, walnut, travertine, marble, bronze, ink, mist). The dark
+ * palette stays plain hex because the share card draws with it and its renderer has no color-mix().
+ *
+ * Type is the house pair: DM Serif Display to inscribe, DM Sans to read. Both are named, not
+ * fetched: a host loads them (README, "The default look's faces"), and one that does not falls back
+ * to Georgia and the system face rather than asking a font service for them on every page view.
+ */
 export const freedomDefault = {
     id: 'freedom-default',
-    name: 'Freedom',
-    ground: '#0e0f13',
-    ink: '#ece7dc',
-    accent: '#c9a96e',
-    light: { ground: '#f6f1e7', ink: '#1c1a17', accent: '#8a6a2c' },
+    name: 'Supersuit',
+    ground: '#17171a',
+    ink: '#d8d1c4',
+    accent: '#a8834f',
+    light: { ground: '#e8e0d2', ink: '#1c1a17', accent: 'color-mix(in srgb,#a8834f 60%,#1c1a17)' },
     type: {
-        display: 'Georgia, "Iowan Old Style", "Times New Roman", serif',
-        body: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+        display: '"DM Serif Display", Georgia, "Times New Roman", serif',
+        body: '"DM Sans", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
     },
-    kicker: 'A page from Freedom',
+    kicker: 'A page from Supersuit',
     // Pages unfurl as their title on the ground colour. A pack with a backdrop of its own
     // overrides this whole field.
     share: { font: newsreader },

package/lib/brand/wrapper.d.ts

@@ -9,7 +9,8 @@ export declare function BrandGround({ pack, mode, children }: {
     mode?: ThemeMode;
     children: ReactNode;
 }): import("react").JSX.Element;
-/** The mark above the kicker: the pack's own, else a small dove. */
+/** The mark above the kicker: the pack's own, else a short rule in the accent. Not a dove: the dove
+ *  stood for the agent, and no bird or figure stands in for her until her own look is designed. */
 export declare function BrandMark({ pack, className }: {
     pack: BrandPack;
     className?: string;

package/lib/brand/wrapper.js

@@ -15,9 +15,10 @@ export function BrandGround({ pack, mode, children }) {
         // isolation puts the fixed backdrop (z-index -1) above this ground and below the page.
         style: { background: 'var(--a-ground)', color: 'var(--a-ink)', fontFamily: pack.type.body, position: 'relative', isolation: 'isolate' }, children: [css, pack.backdrop?.kind === 'bubbles' ? _jsx(Bubbles, { backdrop: pack.backdrop }) : null, children] }));
 }
-/** The mark above the kicker: the pack's own, else a small dove. */
+/** The mark above the kicker: the pack's own, else a short rule in the accent. Not a dove: the dove
+ *  stood for the agent, and no bird or figure stands in for her until her own look is designed. */
 export function BrandMark({ pack, className }) {
     if (pack.Mark)
         return _jsx(pack.Mark, { className: className });
-    return (_jsx("span", { "data-brand-mark": pack.id, "aria-hidden": true, className: className, style: { color: pack.accent }, children: "\uD83D\uDD4A" }));
+    return (_jsx("span", { "data-brand-mark": pack.id, "aria-hidden": true, className: className, style: { display: 'inline-block', width: 28, height: 1, verticalAlign: 'middle', background: pack.accent } }));
 }

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/reader/settings-sheet.js

@@ -13,7 +13,7 @@ import { useEffect, useRef, useState } from 'react';
 import { NO_ZOOM_FONT } from './no-zoom.js';
 export const ACCESS_LABEL = {
     public: 'Anyone with the link',
-    freedom: 'Any Freedom account',
+    freedom: 'Any Supersuit account',
     invite: 'Only the list',
 };
 export const COMMENTS_LABEL = { anyone: 'Anyone', 'signed-in': 'Signed-in readers', off: 'Nobody' };
@@ -132,7 +132,7 @@ export function SettingsSheet({ kind, settings, phone, vars, onClose, onCopy, sa
     const primary = { ...btn, background: 'var(--a-accent, #111)', borderColor: 'var(--a-accent, #111)', color: 'var(--a-ground, #fff)', fontWeight: 600 };
     const muted = { margin: '4px 0 0', fontSize: 12, opacity: 0.65 };
     const radio = (name, value, current, set, label, note) => (_jsxs("label", { style: choice, "data-settings-choice": `${name}:${value}`, children: [_jsx("input", { type: "radio", name: name, value: value, checked: current === value, onChange: () => set(value), style: { width: 18, height: 18, margin: 0, accentColor: 'var(--a-accent, #111)' } }), _jsxs("span", { children: [label, note ? _jsx("span", { style: { display: 'block', fontSize: 12, opacity: 0.6 }, children: note }) : null] })] }, value));
-    const share = (_jsxs(_Fragment, { children: [_jsxs("fieldset", { style: fieldset, children: [_jsx("legend", { style: legend, children: "Who can open it" }), s.levels.map((l) => radio('access', l, access, setAccess, ACCESS_LABEL[l], l === 'freedom' ? 'Plus anyone on the list' : undefined))] }), access === 'public' ? (_jsxs("fieldset", { style: fieldset, children: [_jsx("legend", { style: legend, children: "Password" }), _jsxs("label", { style: choice, "data-settings-choice": "password", children: [_jsx("input", { type: "checkbox", checked: password, onChange: (e) => setPassword(e.target.checked), style: { width: 18, height: 18, margin: 0, accentColor: 'var(--a-accent, #111)' } }), _jsxs("span", { children: ["Require a password", _jsx("span", { style: { display: 'block', fontSize: 12, opacity: 0.6 }, children: "The link to send carries the key" })] })] })] })) : null, dirty || busy ? (_jsxs("div", { style: { display: 'flex', gap: 8, margin: '0 0 14px' }, children: [_jsx("button", { type: "button", "data-settings-save": true, onClick: () => void save(), disabled: busy, style: primary, children: busy ? 'Saving' : 'Save' }), _jsx("button", { type: "button", onClick: () => { setAccess(s.access); setPassword(s.password); }, disabled: busy, style: btn, children: "Undo" })] })) : null, s.list && s.access !== 'public' ? (_jsxs("fieldset", { style: fieldset, "data-settings-list": true, children: [_jsx("legend", { style: legend, children: `The list (${s.list.length})` }), s.list.length === 0 ? _jsx("p", { style: { ...muted, margin: '0 0 6px' }, children: "Nobody yet." }) : null, _jsx("ul", { style: { listStyle: 'none', margin: '0 0 8px', padding: 0 }, children: s.list.map((e) => (_jsxs("li", { "data-settings-list-entry": e.email, style: { display: 'flex', alignItems: 'center', gap: 8, padding: '4px 0', borderBottom: '1px solid var(--a-line, rgba(127,127,127,0.2))' }, children: [_jsx("span", { style: { flex: 1, minWidth: 0, overflowWrap: 'anywhere' }, children: e.name ? _jsxs(_Fragment, { children: [e.name, _jsx("span", { style: { display: 'block', fontSize: 12, opacity: 0.6 }, children: e.email })] }) : e.email }), _jsx("button", { type: "button", "aria-label": `Remove ${e.email}`, onClick: () => void listChange({ remove: [e.email] }), disabled: busy, style: btn, children: "Remove" })] }, e.email))) }), _jsxs("form", { onSubmit: onAdd, style: { display: 'flex', gap: 8 }, children: [_jsx("input", { type: "email", inputMode: "email", autoComplete: "off", placeholder: "name@example.com", "aria-label": "Email to add", value: email, onChange: (e) => setEmail(e.target.value), style: { flex: 1, minWidth: 0, font: 'inherit', ...NO_ZOOM_FONT, padding: phone ? '8px 10px' : '6px 8px', borderRadius: 8, border: '1px solid var(--a-line, rgba(127,127,127,0.4))', background: 'transparent', color: 'inherit' } }), _jsx("button", { type: "submit", disabled: busy, style: btn, children: "Add" })] }), s.access === 'invite' ? null : _jsx("p", { style: muted, children: "Freedom accounts get in without being on the list." })] })) : null, _jsxs("div", { style: { margin: '0 0 14px' }, "data-settings-link": true, children: [_jsx("p", { style: legend, children: "The link to send" }), _jsxs("div", { style: { display: 'flex', gap: 8, alignItems: 'center' }, children: [_jsx("code", { style: { flex: 1, minWidth: 0, fontSize: 13, overflowWrap: 'anywhere' }, children: s.link }), _jsx("button", { type: "button", onClick: () => void copy(), style: btn, children: "Copy" })] })] }), s.facts.length ? (_jsx("dl", { style: { display: 'grid', gap: 8, margin: 0 }, "data-settings-facts": true, children: s.facts.map((f) => (_jsxs("div", { children: [_jsx("dt", { style: { fontSize: 12, fontWeight: 600, opacity: 0.7 }, children: f.label }), _jsx("dd", { style: { margin: 0, fontSize: 13, opacity: 0.85 }, children: f.text })] }, f.label))) })) : null] }));
+    const share = (_jsxs(_Fragment, { children: [_jsxs("fieldset", { style: fieldset, children: [_jsx("legend", { style: legend, children: "Who can open it" }), s.levels.map((l) => radio('access', l, access, setAccess, ACCESS_LABEL[l], l === 'freedom' ? 'Plus anyone on the list' : undefined))] }), access === 'public' ? (_jsxs("fieldset", { style: fieldset, children: [_jsx("legend", { style: legend, children: "Password" }), _jsxs("label", { style: choice, "data-settings-choice": "password", children: [_jsx("input", { type: "checkbox", checked: password, onChange: (e) => setPassword(e.target.checked), style: { width: 18, height: 18, margin: 0, accentColor: 'var(--a-accent, #111)' } }), _jsxs("span", { children: ["Require a password", _jsx("span", { style: { display: 'block', fontSize: 12, opacity: 0.6 }, children: "The link to send carries the key" })] })] })] })) : null, dirty || busy ? (_jsxs("div", { style: { display: 'flex', gap: 8, margin: '0 0 14px' }, children: [_jsx("button", { type: "button", "data-settings-save": true, onClick: () => void save(), disabled: busy, style: primary, children: busy ? 'Saving' : 'Save' }), _jsx("button", { type: "button", onClick: () => { setAccess(s.access); setPassword(s.password); }, disabled: busy, style: btn, children: "Undo" })] })) : null, s.list && s.access !== 'public' ? (_jsxs("fieldset", { style: fieldset, "data-settings-list": true, children: [_jsx("legend", { style: legend, children: `The list (${s.list.length})` }), s.list.length === 0 ? _jsx("p", { style: { ...muted, margin: '0 0 6px' }, children: "Nobody yet." }) : null, _jsx("ul", { style: { listStyle: 'none', margin: '0 0 8px', padding: 0 }, children: s.list.map((e) => (_jsxs("li", { "data-settings-list-entry": e.email, style: { display: 'flex', alignItems: 'center', gap: 8, padding: '4px 0', borderBottom: '1px solid var(--a-line, rgba(127,127,127,0.2))' }, children: [_jsx("span", { style: { flex: 1, minWidth: 0, overflowWrap: 'anywhere' }, children: e.name ? _jsxs(_Fragment, { children: [e.name, _jsx("span", { style: { display: 'block', fontSize: 12, opacity: 0.6 }, children: e.email })] }) : e.email }), _jsx("button", { type: "button", "aria-label": `Remove ${e.email}`, onClick: () => void listChange({ remove: [e.email] }), disabled: busy, style: btn, children: "Remove" })] }, e.email))) }), _jsxs("form", { onSubmit: onAdd, style: { display: 'flex', gap: 8 }, children: [_jsx("input", { type: "email", inputMode: "email", autoComplete: "off", placeholder: "name@example.com", "aria-label": "Email to add", value: email, onChange: (e) => setEmail(e.target.value), style: { flex: 1, minWidth: 0, font: 'inherit', ...NO_ZOOM_FONT, padding: phone ? '8px 10px' : '6px 8px', borderRadius: 8, border: '1px solid var(--a-line, rgba(127,127,127,0.4))', background: 'transparent', color: 'inherit' } }), _jsx("button", { type: "submit", disabled: busy, style: btn, children: "Add" })] }), s.access === 'invite' ? null : _jsx("p", { style: muted, children: "Supersuit accounts get in without being on the list." })] })) : null, _jsxs("div", { style: { margin: '0 0 14px' }, "data-settings-link": true, children: [_jsx("p", { style: legend, children: "The link to send" }), _jsxs("div", { style: { display: 'flex', gap: 8, alignItems: 'center' }, children: [_jsx("code", { style: { flex: 1, minWidth: 0, fontSize: 13, overflowWrap: 'anywhere' }, children: s.link }), _jsx("button", { type: "button", onClick: () => void copy(), style: btn, children: "Copy" })] })] }), s.facts.length ? (_jsx("dl", { style: { display: 'grid', gap: 8, margin: 0 }, "data-settings-facts": true, children: s.facts.map((f) => (_jsxs("div", { children: [_jsx("dt", { style: { fontSize: 12, fontWeight: 600, opacity: 0.7 }, children: f.label }), _jsx("dd", { style: { margin: 0, fontSize: 13, opacity: 0.85 }, children: f.text })] }, f.label))) })) : null] }));
     const commentSheet = (_jsxs(_Fragment, { children: [_jsxs("fieldset", { style: fieldset, children: [_jsx("legend", { style: legend, children: "Who can comment" }), ['anyone', 'signed-in', 'off'].map((m) => radio('comments', m, comments, setComments, COMMENTS_LABEL[m], m === 'anyone' && s.gated ? 'This page is private, so only signed-in readers it is open to can' : undefined))] }), comments !== 'off' ? (_jsxs("fieldset", { style: fieldset, children: [_jsx("legend", { style: legend, children: "Who can read the comments" }), ['owner', 'readers'].map((v) => radio('visible', v, visible, setVisible, VISIBLE_LABEL[v], v === 'owner' ? 'Each commenter also sees their own' : undefined))] })) : null, dirty || busy ? (_jsxs("div", { style: { display: 'flex', gap: 8 }, children: [_jsx("button", { type: "button", "data-settings-save": true, onClick: () => void save(), disabled: busy, style: primary, children: busy ? 'Saving' : 'Save' }), _jsx("button", { type: "button", onClick: () => { setComments(s.comments); setVisible(s.commentsVisible); }, disabled: busy, style: btn, children: "Undo" })] })) : null] }));
     return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": true, "data-settings-scrim": true, onClick: onClose, style: { position: 'fixed', inset: 0, zIndex: 60, background: phone ? 'rgba(0,0,0,0.28)' : 'transparent' } }), _jsxs("div", { ref: panel, role: "dialog", "aria-modal": "true", "aria-label": kind === 'share' ? 'Share settings' : 'Comment settings', tabIndex: -1, "data-settings-sheet": kind, "data-nospeak": true, "data-comment-ui": true, style: style, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 8 }, children: [_jsx("h2", { style: h, children: kind === 'share' ? 'Share settings' : 'Comment settings' }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close", style: { ...btn, border: 0, padding: '2px 6px', fontSize: 20, lineHeight: 1 }, children: "\u00D7" })] }), kind === 'share' ? share : commentSheet, _jsx("p", { role: "status", "aria-live": "polite", "data-settings-said": true, style: { margin: said ? '10px 0 0' : 0, fontSize: 13, minHeight: 0 }, children: said ?? '' })] })] }));
 }

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.48.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",