From a71d6ab470784af661f4df003198a572edb3a334 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Fri, 18 Sep 2026 19:24:59 -0700
Subject: [PATCH 1/3] feat(website): report visible engaged time so readers
 stop counting as bounces

posthog-js fires $pageleave only from its pagehide/unload handler, never on
visibilitychange, and PostHog derives session_duration from the span of a
session's events. A visitor who lands, reads, clicks nothing and leaves the tab
open therefore emits one $pageview, records zero seconds, and is scored as a
bounce. Measured over 30 days: 13.6% of desktop and 17.8% of mobile homepage
sessions. The tab-close lands in a rotated session - 67 orphan pageleave-only
sessions, median gap 221 minutes - which is what rules out an ad blocker.

The gap concentrated where nothing passive could fire. marketing:stage_progress
is gated to 1024x720 and fired on 0.0% of mobile sessions; 91% of mobile
sessions emitted nothing but the pageview, so mobile engagement was not
measurable at all. marketing:engaged_time has no viewport gate.

It counts visible time only, pausing while the tab is hidden, so it corrects
the recorded duration rather than inflating it. That distinction is the whole
design: the hidden-time tests are load-bearing, not incidental. 10s matches
PostHog's own bounce cutoff so a genuine ten-second read stops being recorded
as zero.

All 14 assertions mutation-verified: hidden time counted, threshold dedupe
removed, visible-run restarted, cleanup dropped, listener unregistered, and
interval never installed each turn exactly the expected tests red.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/layout.tsx               |   2 +
 .../shared/EngagedTimeSignal.spec.tsx         |  88 ++++++++++++
 .../components/shared/EngagedTimeSignal.tsx   |  57 ++++++++
 apps/website/src/lib/analytics/client.ts      |   8 ++
 .../src/lib/analytics/engaged-time.spec.ts    | 125 ++++++++++++++++++
 .../website/src/lib/analytics/engaged-time.ts |  93 +++++++++++++
 apps/website/src/lib/analytics/events.ts      |   7 +
 docs/gtm/taxonomy.md                          |   1 +
 8 files changed, 381 insertions(+)
 create mode 100644 apps/website/src/components/shared/EngagedTimeSignal.spec.tsx
 create mode 100644 apps/website/src/components/shared/EngagedTimeSignal.tsx
 create mode 100644 apps/website/src/lib/analytics/engaged-time.spec.ts
 create mode 100644 apps/website/src/lib/analytics/engaged-time.ts

diff --git a/apps/website/src/app/layout.tsx b/apps/website/src/app/layout.tsx
index ff38d2d5a..9e7bb6b3d 100644
--- a/apps/website/src/app/layout.tsx
+++ b/apps/website/src/app/layout.tsx
@@ -20,6 +20,7 @@ import {
 } from '../lib/site-metadata';
 import { getFormPolicy } from '../lib/growth/form-policy';
 import { WebsiteSignals } from '../components/shared/WebsiteSignals';
+import { EngagedTimeSignal } from '../components/shared/EngagedTimeSignal';
 import { websiteContentCatalog } from '../lib/growth/website-content';
 
 const display = Archivo_Black({
@@ -97,6 +98,7 @@ export default function RootLayout({
         */}
         <JsonLd data={rootJsonLd()} />
         <WebsiteSignals catalog={websiteContentCatalog()} />
+        <EngagedTimeSignal />
         <Nav />
         <div id="site-content">
           <main>
diff --git a/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx b/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx
new file mode 100644
index 000000000..07457a8ae
--- /dev/null
+++ b/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx
@@ -0,0 +1,88 @@
+import { render, act, cleanup } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EngagedTimeSignal } from './EngagedTimeSignal';
+
+vi.mock('../../lib/analytics/client', () => ({
+  trackEngagedTime: vi.fn(),
+}));
+
+vi.mock('next/navigation', () => ({
+  usePathname: () => '/',
+}));
+
+import { trackEngagedTime } from '../../lib/analytics/client';
+
+const tracked = vi.mocked(trackEngagedTime);
+
+/**
+ * `engaged-time.spec.ts` covers the accounting. These cover the wiring, which
+ * is where this can silently do nothing: an effect that never runs, an
+ * interval that is never installed, or a listener that outlives the component.
+ * The unit tests would stay green through all three.
+ */
+function setVisibility(state: 'visible' | 'hidden') {
+  Object.defineProperty(document, 'visibilityState', {
+    configurable: true,
+    get: () => state,
+  });
+  document.dispatchEvent(new Event('visibilitychange'));
+}
+
+describe('EngagedTimeSignal', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    tracked.mockClear();
+    setVisibility('visible');
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+  });
+
+  it('reports ten engaged seconds after ten visible seconds', () => {
+    render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(10_000);
+    });
+    expect(tracked).toHaveBeenCalledWith(10);
+  });
+
+  it('reports nothing before the first threshold', () => {
+    render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(9_000);
+    });
+    expect(tracked).not.toHaveBeenCalled();
+  });
+
+  it('reports thirty seconds as a second event, not a replacement', () => {
+    render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(30_000);
+    });
+    expect(tracked).toHaveBeenNthCalledWith(1, 10);
+    expect(tracked).toHaveBeenNthCalledWith(2, 30);
+  });
+
+  it('does not accrue engagement while the tab is hidden', () => {
+    render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(3_000);
+      setVisibility('hidden');
+      vi.advanceTimersByTime(120_000);
+    });
+    expect(tracked).not.toHaveBeenCalled();
+  });
+
+  it('stops reporting once unmounted', () => {
+    // A leaked interval would keep attributing engagement to a page the
+    // visitor has already navigated away from.
+    const { unmount } = render(<EngagedTimeSignal />);
+    unmount();
+    act(() => {
+      vi.advanceTimersByTime(60_000);
+    });
+    expect(tracked).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/website/src/components/shared/EngagedTimeSignal.tsx b/apps/website/src/components/shared/EngagedTimeSignal.tsx
new file mode 100644
index 000000000..615aa556b
--- /dev/null
+++ b/apps/website/src/components/shared/EngagedTimeSignal.tsx
@@ -0,0 +1,57 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { createEngagedTimeTracker } from '../../lib/analytics/engaged-time';
+import { trackEngagedTime } from '../../lib/analytics/client';
+
+/**
+ * How often to re-evaluate. The tracker derives elapsed time from a clock
+ * rather than counting ticks, so a browser throttling this interval in a
+ * background tab delays the event but never miscounts it.
+ */
+const TICK_MS = 1_000;
+
+/**
+ * Emits `marketing:engaged_time` once the visitor has genuinely been looking
+ * at the page for 10s, and again at 30s.
+ *
+ * Without this the site has no passive engagement signal on most viewports:
+ * `marketing:stage_progress` is gated to at least 1024x720 and fired on 0.0%
+ * of mobile sessions in the 30 days to 2026-09-18. A visitor who reads and
+ * clicks nothing emitted one `$pageview` and nothing else, which PostHog
+ * scores as a zero-second session and therefore a bounce.
+ *
+ * Re-created per pathname so engaged time is measured per page rather than
+ * per document, matching `capture_pageview: 'history_change'`.
+ */
+export function EngagedTimeSignal() {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    if (typeof document === 'undefined' || typeof window === 'undefined') return;
+
+    const tracker = createEngagedTimeTracker({
+      now: () => Date.now(),
+      startVisible: document.visibilityState === 'visible',
+      onThreshold: (thresholdMs) => trackEngagedTime(Math.round(thresholdMs / 1000)),
+    });
+
+    const onVisibilityChange = () => {
+      tracker.setVisible(document.visibilityState === 'visible');
+      // Re-evaluate immediately: returning to a tab that already passed a
+      // threshold should not wait out another interval.
+      tracker.tick();
+    };
+
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    const intervalId = window.setInterval(() => tracker.tick(), TICK_MS);
+
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      window.clearInterval(intervalId);
+    };
+  }, [pathname]);
+
+  return null;
+}
diff --git a/apps/website/src/lib/analytics/client.ts b/apps/website/src/lib/analytics/client.ts
index 89e9f636d..721145218 100644
--- a/apps/website/src/lib/analytics/client.ts
+++ b/apps/website/src/lib/analytics/client.ts
@@ -50,3 +50,11 @@ export function trackStageProgress(
     ...(beat ? { beat } : {}),
   });
 }
+
+/**
+ * Passive engagement. `engaged_seconds` is visible time only, so it can be
+ * read as real attention rather than a tab left open.
+ */
+export function trackEngagedTime(engaged_seconds: number) {
+  track(analyticsEvents.marketingEngagedTime, { engaged_seconds });
+}
diff --git a/apps/website/src/lib/analytics/engaged-time.spec.ts b/apps/website/src/lib/analytics/engaged-time.spec.ts
new file mode 100644
index 000000000..ecae9f3d4
--- /dev/null
+++ b/apps/website/src/lib/analytics/engaged-time.spec.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createEngagedTimeTracker,
+  ENGAGED_TIME_THRESHOLDS_MS,
+} from './engaged-time';
+
+/**
+ * Why this exists.
+ *
+ * PostHog derives `session_duration` from `max(timestamp) - min(timestamp)`
+ * over a session's events, and `$pageleave` only fires on `pagehide` — never
+ * on `visibilitychange`. A visitor who lands, reads, clicks nothing and leaves
+ * the tab open therefore emits exactly one event, records a duration of zero,
+ * and is classified as a bounce. Measured 2026-09-18: that is 13.6% of desktop
+ * and 17.8% of mobile homepage sessions.
+ *
+ * This tracker exists to make the recorded duration reflect the real one. That
+ * only holds if it counts *visible* time and nothing else — time in a hidden
+ * background tab is not engagement, and counting it would inflate the metric
+ * rather than correct it. The hidden-time tests below are the ones that keep
+ * this honest, so treat them as load-bearing rather than incidental.
+ */
+
+function setup(startVisible = true) {
+  let clock = 1_000;
+  const onThreshold = vi.fn();
+  const tracker = createEngagedTimeTracker({
+    onThreshold,
+    now: () => clock,
+    startVisible,
+  });
+  return {
+    onThreshold,
+    tracker,
+    advance(ms: number) {
+      clock += ms;
+      tracker.tick();
+    },
+    advanceWithoutTick(ms: number) {
+      clock += ms;
+    },
+  };
+}
+
+describe('engaged time thresholds', () => {
+  it('exports 10s and 30s, the first matching PostHog bounce cutoff', () => {
+    // 10s is not arbitrary: PostHog's bounce test is `session_duration >= 10s`.
+    // An event at a genuine 10 visible seconds makes the recorded duration
+    // match reality for a reader who never clicks.
+    expect(ENGAGED_TIME_THRESHOLDS_MS).toEqual([10_000, 30_000]);
+  });
+
+  it('fires the first threshold only once ten visible seconds have passed', () => {
+    const { advance, onThreshold } = setup();
+    advance(9_999);
+    expect(onThreshold).not.toHaveBeenCalled();
+    advance(1);
+    expect(onThreshold).toHaveBeenCalledExactlyOnceWith(10_000);
+  });
+
+  it('fires each threshold exactly once, however many times it is ticked', () => {
+    const { advance, onThreshold } = setup();
+    advance(10_000);
+    advance(1_000);
+    advance(1_000);
+    expect(onThreshold).toHaveBeenCalledExactlyOnceWith(10_000);
+  });
+
+  it('fires the second threshold at thirty visible seconds', () => {
+    const { advance, onThreshold } = setup();
+    advance(30_000);
+    expect(onThreshold).toHaveBeenNthCalledWith(1, 10_000);
+    expect(onThreshold).toHaveBeenNthCalledWith(2, 30_000);
+    expect(onThreshold).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not count time while the page is hidden', () => {
+    // The honesty test. A backgrounded tab accrues wall-clock time but no
+    // engagement; counting it would inflate session duration rather than
+    // correct it.
+    const { advance, tracker, onThreshold } = setup();
+    advance(5_000);
+    tracker.setVisible(false);
+    advance(60_000);
+    expect(onThreshold).not.toHaveBeenCalled();
+    expect(tracker.visibleMs()).toBe(5_000);
+  });
+
+  it('resumes accumulating when the page becomes visible again', () => {
+    const { advance, tracker, onThreshold } = setup();
+    advance(6_000);
+    tracker.setVisible(false);
+    advance(60_000);
+    tracker.setVisible(true);
+    advance(4_000);
+    expect(onThreshold).toHaveBeenCalledExactlyOnceWith(10_000);
+    expect(tracker.visibleMs()).toBe(10_000);
+  });
+
+  it('never fires for a page that starts hidden and is never seen', () => {
+    // A prerendered or background-opened tab must not report engagement.
+    const { advance, onThreshold, tracker } = setup(false);
+    advance(120_000);
+    expect(onThreshold).not.toHaveBeenCalled();
+    expect(tracker.visibleMs()).toBe(0);
+  });
+
+  it('counts time that elapsed between ticks, not tick count', () => {
+    // The production caller ticks on an interval; a throttled background
+    // timer must not under-report time the page was genuinely visible.
+    const { advanceWithoutTick, tracker, onThreshold } = setup();
+    advanceWithoutTick(30_000);
+    tracker.tick();
+    expect(onThreshold).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not double count when told it is visible twice', () => {
+    const { advance, tracker, onThreshold } = setup();
+    advance(5_000);
+    tracker.setVisible(true);
+    advance(4_999);
+    expect(onThreshold).not.toHaveBeenCalled();
+    expect(tracker.visibleMs()).toBe(9_999);
+  });
+});
diff --git a/apps/website/src/lib/analytics/engaged-time.ts b/apps/website/src/lib/analytics/engaged-time.ts
new file mode 100644
index 000000000..bfd4a3006
--- /dev/null
+++ b/apps/website/src/lib/analytics/engaged-time.ts
@@ -0,0 +1,93 @@
+/**
+ * Visible-time accounting for the engagement signal.
+ *
+ * PostHog derives `session_duration` from `max(timestamp) - min(timestamp)`
+ * across a session's events, and posthog-js fires `$pageleave` only from its
+ * `pagehide`/`unload` handler — never on `visibilitychange`. So a visitor who
+ * lands, reads, clicks nothing and leaves the tab open emits exactly one
+ * event, records a duration of zero, and is scored as a bounce. Measured on
+ * 2026-09-18 that was 13.6% of desktop and 17.8% of mobile homepage sessions,
+ * and on mobile it is close to the whole engagement picture: the only other
+ * passive event, `marketing:stage_progress`, is gated to viewports of at least
+ * 1024x720 and fired on 0.0% of mobile sessions.
+ *
+ * The point of this module is to make the recorded duration match the real
+ * one. That only holds while it counts visible time and nothing else — wall
+ * clock accrued in a hidden background tab is not engagement, and counting it
+ * would inflate the metric instead of correcting it. `setVisible` is what
+ * keeps that distinction, so it is not an optimisation to be dropped.
+ *
+ * Deliberately framework-free so it can be tested without React, fake timers,
+ * or a DOM. The caller supplies the clock and drives `tick`.
+ */
+
+/**
+ * 10s is chosen to match PostHog's own bounce cutoff (`session_duration >= 10s`),
+ * so a reader who never clicks stops being recorded as a zero-second visit.
+ * 30s is the "actually read something" signal. Two events per session at most.
+ */
+export const ENGAGED_TIME_THRESHOLDS_MS = [10_000, 30_000] as const;
+
+export type EngagedTimeTracker = {
+  /** Report a visibility transition. Hidden time is never counted. */
+  setVisible(visible: boolean): void;
+  /** Re-evaluate accumulated time and fire any newly crossed thresholds. */
+  tick(): void;
+  /** Milliseconds the page has been visible so far. */
+  visibleMs(): number;
+};
+
+export type EngagedTimeOptions = {
+  /** Called once per threshold, with the threshold in milliseconds. */
+  onThreshold: (thresholdMs: number) => void;
+  /** Monotonic-enough clock. Production passes `Date.now`. */
+  now: () => number;
+  /** Whether the page is visible at construction time. */
+  startVisible: boolean;
+  thresholdsMs?: readonly number[];
+};
+
+export function createEngagedTimeTracker({
+  onThreshold,
+  now,
+  startVisible,
+  thresholdsMs = ENGAGED_TIME_THRESHOLDS_MS,
+}: EngagedTimeOptions): EngagedTimeTracker {
+  let accumulatedMs = 0;
+  // Timestamp the current visible run began, or null while hidden. Elapsed
+  // time is derived from this rather than counted per tick, so a throttled
+  // background interval cannot under-report a genuinely visible page.
+  let visibleSince: number | null = startVisible ? now() : null;
+  const fired = new Set<number>();
+
+  function currentVisibleMs(): number {
+    return visibleSince === null ? accumulatedMs : accumulatedMs + (now() - visibleSince);
+  }
+
+  return {
+    setVisible(visible: boolean) {
+      if (visible) {
+        // Already visible — re-asserting must not restart the run and
+        // silently discard the elapsed time.
+        if (visibleSince === null) visibleSince = now();
+        return;
+      }
+      if (visibleSince !== null) {
+        accumulatedMs += now() - visibleSince;
+        visibleSince = null;
+      }
+    },
+
+    tick() {
+      const elapsed = currentVisibleMs();
+      for (const threshold of thresholdsMs) {
+        if (elapsed >= threshold && !fired.has(threshold)) {
+          fired.add(threshold);
+          onThreshold(threshold);
+        }
+      }
+    },
+
+    visibleMs: currentVisibleMs,
+  };
+}
diff --git a/apps/website/src/lib/analytics/events.ts b/apps/website/src/lib/analytics/events.ts
index 4baa39f0a..44d94292e 100644
--- a/apps/website/src/lib/analytics/events.ts
+++ b/apps/website/src/lib/analytics/events.ts
@@ -29,6 +29,7 @@ export const analyticsEvents = {
   marketingAiCrawlerVisit: 'marketing:ai_crawler_visit',
   marketingAiReferralVisit: 'marketing:ai_referral_visit',
   marketingStageProgress: 'marketing:stage_progress',
+  marketingEngagedTime: 'marketing:engaged_time',
 } as const;
 
 export type AnalyticsEventName = (typeof analyticsEvents)[keyof typeof analyticsEvents];
@@ -142,6 +143,12 @@ export type AnalyticsProperties = {
   ai_crawler?: string;
   ai_source?: string;
   user_agent?: string;
+  /**
+   * Cumulative *visible* seconds on a page (`marketing:engaged_time`).
+   * Hidden background time is excluded by construction — see
+   * `analytics/engaged-time.ts`.
+   */
+  engaged_seconds?: number;
   /** Homepage stage milestones (`marketing:stage_progress`). */
   stage_event?: StageMilestone;
   beat?: StageBeat;
diff --git a/docs/gtm/taxonomy.md b/docs/gtm/taxonomy.md
index 9b1776c22..d4a769ffa 100644
--- a/docs/gtm/taxonomy.md
+++ b/docs/gtm/taxonomy.md
@@ -55,6 +55,7 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces.
 | `docs:workspace_runtime_action` | Explicit runtime action; `capability`, `action`, `state_before`, `outcome`, `surface`. |
 | `docs:workspace_runtime_status_changed` | Runtime status transition; `capability`, `from_state`, `to_state`, optional `elapsed_ms`/`reason_code`, `surface`. |
 | `marketing:stage_progress` | Recorded homepage stage progress; `surface`, `stage_event`, optional `beat`. Not a live developer runtime. |
+| `marketing:engaged_time` | Cumulative **visible** seconds on a page; `engaged_seconds` (10 or 30), `source_page`. Fires on every viewport. Hidden background time is excluded by construction, so it reads as attention rather than a tab left open. |
 
 Current dashboards distinguish website intent, client-observed form acceptance,
 and independent demo milestones. `hero_install` is a copy attempt recorded before

From daf7ac0ec123702992d86bbabf65360c12c430cf Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Fri, 18 Sep 2026 19:24:59 -0700
Subject: [PATCH 2/3] docs(growth): record the cutover and the established
 $pageleave cause

The bounce series broke at 2026-09-19T02:05Z: the pageview fix deployed and
autocapture_opt_out was flipped, verified by $autocapture events arriving and a
soft navigation producing a $pageview. The prediction wording is now past
tense, and the ~2 hour sliver between the pinned table window and the cutover
is called out rather than left to be discovered.

Replaces the "missing across every browser" framing with the actual mechanism.
The uniformity across browsers was the symptom of a behavioural cause - tabs
left open past the 30 minute idle timeout - not evidence of a transport
problem, and the earlier draft read it the wrong way round.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/growth/README.md                         | 62 +++++++++++++------
 ...9-18-posthog-instrumentation-fix-design.md | 29 +++++----
 2 files changed, 61 insertions(+), 30 deletions(-)

diff --git a/docs/growth/README.md b/docs/growth/README.md
index 0d675030d..7e2262a9b 100644
--- a/docs/growth/README.md
+++ b/docs/growth/README.md
@@ -144,30 +144,54 @@ different populations. Dividing the bounce count by **Sessions** instead of
 
 Window pinned 2026-05-01 to 2026-09-18; September is a partial month.
 
-**The series will break once both the pageview fix ships and the project
-setting flips — it has not yet.** Restoring the other two `$is_bounce`
-branches lowers the rate on unchanged traffic, but today neither precondition
-holds: the deployed bundle still ships `capture_pageview: !0` (truthy, not
-`'history_change'`), and the remote config still returns
-`"autocapture_opt_out": true`. The break date is whichever of the two ships
-second, not 2026-09-18. Do not compare across that date once it happens.
+**The series broke at 2026-09-19T02:05Z.** Both preconditions landed together:
+the pageview fix deployed (PR #1110) and `autocapture_opt_out` was set to
+`false` via the Projects API. All three `$is_bounce` branches are now
+reachable, which lowers the rate on unchanged traffic. Verified at the time:
+`$autocapture` events arriving, and a soft navigation producing a `$pageview`
+for the new path. **Do not compare across that instant.** Note the table above
+is pinned to 2026-09-19T00:00Z, so sessions in the ~2 hours before the cutover
+fall outside it.
+
+**A second break follows** when `marketing:engaged_time` reaches production.
+It emits a passive event at 10s and 30s of visible time, which raises recorded
+session duration for readers who click nothing — see below.
 
 **The volume does not support fine comparisons.** At ~160 homepage sessions per
 month a ±8.17pp interval cannot separate 50.0% from 59%. Judging a homepage
 change on this metric needs a much longer accumulation window, or more traffic.
 
-Two limits this baseline exposed. `$pageleave` is missing from 17–20% of
-sessions in the four browsers with samples large enough to read: Chrome
-Desktop (17.2%), Safari Desktop (19.6%), Mobile Safari (20.0%), and Chrome
-Mobile (3 of 16 sessions, 18.8% — a single extra session would move this to
-25.0%). Other
-browsers in the same result set, such as Firefox Desktop (3 of 3 missing) and
-Edge Desktop (0 of 3 missing), have samples too small to read. Those missing
-sessions collapse to zero duration and become automatic bounces; the
-zero-duration share tracks the bounce rate month over month. And 89% of
-homepage entries are Direct (143 of the 161 September sessions, 54.3% bounce)
-against 15 Organic Search sessions at 13.3% bounce, so the headline figure is
-mostly a statement about untagged traffic.
+Two limits this baseline exposed, one of which now has an established cause.
+
+**Zero-duration sessions were a missing engagement signal, not a delivery
+failure.** posthog-js fires `$pageleave` only from its `pagehide`/`unload`
+handler — never on `visibilitychange`. PostHog derives `session_duration` from
+`max(timestamp) - min(timestamp)` across a session's events. So a visitor who
+lands, reads, clicks nothing and leaves the tab open emits exactly one
+`$pageview`, records zero seconds, and is scored as a bounce. When the tab is
+finally closed hours later the session id has long since rotated, so the
+`$pageleave` lands in a *new* session: 67 such orphan sessions in 30 days, all
+with a prior session from the same person, median gap 221 minutes and p75 1486
+minutes. That long-gap signature is what rules out an ad blocker or a browser
+quirk, and it is why the rate looked uniform across browsers.
+
+The distortion concentrated where no passive event could fire:
+
+| Device | Sessions | Zero-duration | Had `stage_progress` | Had any `marketing:*` | Median duration |
+| --- | --- | --- | --- | --- | --- |
+| Desktop | 176 | 13.6% | 11.9% | 44.3% | 11.0s |
+| Mobile | 45 | 17.8% | 0.0% | 8.9% | 3.0s |
+
+`marketing:stage_progress` is gated to viewports of at least 1024x720, so it
+fired on **0.0%** of mobile sessions and 91% of mobile sessions emitted nothing
+but the pageview. `marketing:engaged_time` is the fix and deliberately has no
+viewport gate. Until it shipped, mobile engagement was not measurable at all —
+which also means mobile changes made before it are not measurable retroactively.
+
+**Channel composition remains the larger caveat.** 89% of homepage entries are
+Direct (143 of the 161 September sessions, 54.3% bounce) against 15 Organic
+Search sessions at 13.3% bounce, so the headline figure is mostly a statement
+about untagged traffic.
 
 ## Contributor checks
 
diff --git a/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md b/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md
index c8d38d05a..43c79f7d0 100644
--- a/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md
+++ b/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md
@@ -234,17 +234,24 @@ it.
 
 ### Two findings this baseline surfaced
 
-**`$pageleave` is missing from 17–20% of sessions in the four browsers with
-samples large enough to read:** Chrome Desktop (17.2%), Safari Desktop
-(19.6%), Mobile Safari (20.0%), and Chrome Mobile (3 of 16 sessions, 18.8% —
-a single extra session would move this to 25.0%). Other browsers in the same
-result set,
-such as Firefox Desktop (3 of 3 missing) and Edge Desktop (0 of 3 missing),
-have samples too small to read. Those missing sessions collapse to zero
-duration and become automatic bounces. The zero-duration share tracks the
-bounce rate almost exactly month over month, which makes this leak a material
-contributor rather than a rounding detail. Cause not yet established; out of
-scope here, worth its own investigation.
+**`$pageleave` gaps had an established cause (resolved 2026-09-19).** The
+sessions recording zero duration were not a delivery failure. posthog-js fires
+`$pageleave` only from its `pagehide`/`unload` handler, never on
+`visibilitychange`, so a visitor who lands, reads, clicks nothing and leaves
+the tab open emits one `$pageview` and records zero seconds. The eventual
+close lands in a rotated session: 67 orphan `$pageleave`-only sessions in 30
+days, every one preceded by a session from the same person, median gap 221
+minutes, p75 1486 minutes. The long gaps are what rule out an ad blocker or a
+browser quirk.
+
+The distortion concentrated where no passive event could fire — desktop 13.6%
+zero-duration against mobile 17.8%, with `marketing:stage_progress` (gated to
+1024x720) firing on 0.0% of mobile sessions and 91% of mobile sessions
+emitting nothing but the pageview. Fixed by `marketing:engaged_time`, which
+reports visible-only time at 10s and 30s on every viewport. Note that an
+earlier draft of this document described the gap as uniform "across every
+browser measured"; the uniformity was the symptom of a behavioural cause, not
+evidence of a transport problem.
 
 **Channel composition, homepage entries:** 89% Direct (143 of the 161 September
 sessions, bouncing at 54.3%) against 15 Organic Search sessions bouncing at

From 7557db242ebd833a7d0f34430f921724a01b326f Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Fri, 18 Sep 2026 19:33:46 -0700
Subject: [PATCH 3/3] test(website): assert the never-seen-tab property where
 it is load-bearing

Code review found that `startVisible: document.visibilityState === 'visible'`
could be mutated to `true` with all 14 tests still green. That single argument
IS the production implementation of "a tab nobody looked at reports nothing" -
the exact inflation this design exists to prevent - and it was asserted only in
the tracker unit test, the layer that cannot break it in production. A
regression would let a background tab's throttled interval fire both
thresholds for a page never seen.

Three more surviving mutations closed: a leaked visibilitychange listener
(which would emit engaged_time for every earlier page in the session, breaking
the two-per-pageview bound), the [pathname] effect dependency, and
`accumulatedMs +=` collapsing to `=` (invisible with one hide/show cycle,
wrong from the second onward). All four now fail exactly their own test.

Also stops the 1Hz interval once both thresholds have fired, rather than
waking every second for the life of every page on the site.

Docs: pin the orphan-session definition and window so the figure is
re-derivable, and note that stage_progress is suppressed by
prefers-reduced-motion as well as by viewport.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../shared/EngagedTimeSignal.spec.tsx         | 51 ++++++++++++++++++-
 .../components/shared/EngagedTimeSignal.tsx   |  8 ++-
 .../src/lib/analytics/engaged-time.spec.ts    | 25 +++++++++
 .../website/src/lib/analytics/engaged-time.ts |  6 +++
 docs/growth/README.md                         | 13 +++--
 ...9-18-posthog-instrumentation-fix-design.md | 11 ++--
 6 files changed, 102 insertions(+), 12 deletions(-)

diff --git a/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx b/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx
index 07457a8ae..3bf93f6c6 100644
--- a/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx
+++ b/apps/website/src/components/shared/EngagedTimeSignal.spec.tsx
@@ -6,8 +6,9 @@ vi.mock('../../lib/analytics/client', () => ({
   trackEngagedTime: vi.fn(),
 }));
 
+let pathname = '/';
 vi.mock('next/navigation', () => ({
-  usePathname: () => '/',
+  usePathname: () => pathname,
 }));
 
 import { trackEngagedTime } from '../../lib/analytics/client';
@@ -32,6 +33,7 @@ describe('EngagedTimeSignal', () => {
   beforeEach(() => {
     vi.useFakeTimers();
     tracked.mockClear();
+    pathname = '/';
     setVisibility('visible');
   });
 
@@ -75,6 +77,53 @@ describe('EngagedTimeSignal', () => {
     expect(tracked).not.toHaveBeenCalled();
   });
 
+  it('reports nothing for a tab that was never visible at mount', () => {
+    // THE honesty property, asserted where it is load-bearing. The production
+    // implementation of "a never-seen tab reports nothing" is the single
+    // `startVisible: document.visibilityState === 'visible'` argument; a
+    // regression to `true` would let a background tab's throttled interval
+    // fire both thresholds for a page nobody ever looked at.
+    setVisibility('hidden');
+    render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(120_000);
+    });
+    expect(tracked).not.toHaveBeenCalled();
+  });
+
+  it('ignores visibility changes after unmount', () => {
+    // A leaked listener would let one tab-away emit engaged_time for every
+    // page visited earlier in the session, each stamped with the CURRENT
+    // source_page, breaking the two-events-per-pageview bound.
+    const { unmount } = render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(30_000);
+    });
+    tracked.mockClear();
+    unmount();
+    act(() => {
+      setVisibility('hidden');
+      setVisibility('visible');
+      vi.advanceTimersByTime(60_000);
+    });
+    expect(tracked).not.toHaveBeenCalled();
+  });
+
+  it('starts a fresh budget on each pathname, not once per document', () => {
+    const { rerender } = render(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(30_000);
+    });
+    expect(tracked).toHaveBeenCalledTimes(2);
+    tracked.mockClear();
+    pathname = '/pricing';
+    rerender(<EngagedTimeSignal />);
+    act(() => {
+      vi.advanceTimersByTime(10_000);
+    });
+    expect(tracked).toHaveBeenCalledExactlyOnceWith(10);
+  });
+
   it('stops reporting once unmounted', () => {
     // A leaked interval would keep attributing engagement to a page the
     // visitor has already navigated away from.
diff --git a/apps/website/src/components/shared/EngagedTimeSignal.tsx b/apps/website/src/components/shared/EngagedTimeSignal.tsx
index 615aa556b..3354c5e98 100644
--- a/apps/website/src/components/shared/EngagedTimeSignal.tsx
+++ b/apps/website/src/components/shared/EngagedTimeSignal.tsx
@@ -45,7 +45,13 @@ export function EngagedTimeSignal() {
     };
 
     document.addEventListener('visibilitychange', onVisibilityChange);
-    const intervalId = window.setInterval(() => tracker.tick(), TICK_MS);
+    // Stop waking up once both thresholds have fired. Without this the
+    // interval runs at 1Hz for the life of every page on the site, doing
+    // nothing.
+    const intervalId = window.setInterval(() => {
+      tracker.tick();
+      if (tracker.isComplete()) window.clearInterval(intervalId);
+    }, TICK_MS);
 
     return () => {
       document.removeEventListener('visibilitychange', onVisibilityChange);
diff --git a/apps/website/src/lib/analytics/engaged-time.spec.ts b/apps/website/src/lib/analytics/engaged-time.spec.ts
index ecae9f3d4..de40ef9f4 100644
--- a/apps/website/src/lib/analytics/engaged-time.spec.ts
+++ b/apps/website/src/lib/analytics/engaged-time.spec.ts
@@ -97,6 +97,31 @@ describe('engaged time thresholds', () => {
     expect(tracker.visibleMs()).toBe(10_000);
   });
 
+  it('keeps time from earlier visible runs across repeated hide/show cycles', () => {
+    // One cycle cannot distinguish `accumulatedMs +=` from `accumulatedMs =`,
+    // because the accumulator is still zero. Two can.
+    const { advance, tracker, onThreshold } = setup();
+    advance(4_000);
+    tracker.setVisible(false);
+    advance(60_000);
+    tracker.setVisible(true);
+    advance(4_000);
+    tracker.setVisible(false);
+    advance(60_000);
+    tracker.setVisible(true);
+    advance(2_000);
+    expect(tracker.visibleMs()).toBe(10_000);
+    expect(onThreshold).toHaveBeenCalledExactlyOnceWith(10_000);
+  });
+
+  it('reports completion only once every threshold has fired', () => {
+    const { advance, tracker } = setup();
+    advance(10_000);
+    expect(tracker.isComplete()).toBe(false);
+    advance(20_000);
+    expect(tracker.isComplete()).toBe(true);
+  });
+
   it('never fires for a page that starts hidden and is never seen', () => {
     // A prerendered or background-opened tab must not report engagement.
     const { advance, onThreshold, tracker } = setup(false);
diff --git a/apps/website/src/lib/analytics/engaged-time.ts b/apps/website/src/lib/analytics/engaged-time.ts
index bfd4a3006..050ffa287 100644
--- a/apps/website/src/lib/analytics/engaged-time.ts
+++ b/apps/website/src/lib/analytics/engaged-time.ts
@@ -35,6 +35,8 @@ export type EngagedTimeTracker = {
   tick(): void;
   /** Milliseconds the page has been visible so far. */
   visibleMs(): number;
+  /** True once every threshold has fired and ticking is pointless. */
+  isComplete(): boolean;
 };
 
 export type EngagedTimeOptions = {
@@ -89,5 +91,9 @@ export function createEngagedTimeTracker({
     },
 
     visibleMs: currentVisibleMs,
+
+    isComplete() {
+      return fired.size === thresholdsMs.length;
+    },
   };
 }
diff --git a/docs/growth/README.md b/docs/growth/README.md
index 7e2262a9b..eb6232d32 100644
--- a/docs/growth/README.md
+++ b/docs/growth/README.md
@@ -170,9 +170,11 @@ handler — never on `visibilitychange`. PostHog derives `session_duration` from
 lands, reads, clicks nothing and leaves the tab open emits exactly one
 `$pageview`, records zero seconds, and is scored as a bounce. When the tab is
 finally closed hours later the session id has long since rotated, so the
-`$pageleave` lands in a *new* session: 67 such orphan sessions in 30 days, all
-with a prior session from the same person, median gap 221 minutes and p75 1486
-minutes. That long-gap signature is what rules out an ad blocker or a browser
+`$pageleave` lands in a *new* session: 67 such orphan sessions, all with a
+prior session from the same person, median gap 221 minutes and p75 1486
+minutes. (Orphan = a session with at least one `$pageleave` and zero
+`$pageview`, over `now() - INTERVAL 30 DAY` as at 2026-09-18; a sliding window
+will not reproduce the count exactly.) That long-gap signature is what rules out an ad blocker or a browser
 quirk, and it is why the rate looked uniform across browsers.
 
 The distortion concentrated where no passive event could fire:
@@ -182,8 +184,9 @@ The distortion concentrated where no passive event could fire:
 | Desktop | 176 | 13.6% | 11.9% | 44.3% | 11.0s |
 | Mobile | 45 | 17.8% | 0.0% | 8.9% | 3.0s |
 
-`marketing:stage_progress` is gated to viewports of at least 1024x720, so it
-fired on **0.0%** of mobile sessions and 91% of mobile sessions emitted nothing
+`marketing:stage_progress` is gated to viewports of at least 1024x720 *and*
+suppressed under `prefers-reduced-motion: reduce`, so it fired on **0.0%** of
+mobile sessions and 91% of mobile sessions emitted nothing
 but the pageview. `marketing:engaged_time` is the fix and deliberately has no
 viewport gate. Until it shipped, mobile engagement was not measurable at all —
 which also means mobile changes made before it are not measurable retroactively.
diff --git a/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md b/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md
index 43c79f7d0..5bfb7a665 100644
--- a/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md
+++ b/docs/superpowers/specs/2026-09-18-posthog-instrumentation-fix-design.md
@@ -239,14 +239,15 @@ sessions recording zero duration were not a delivery failure. posthog-js fires
 `$pageleave` only from its `pagehide`/`unload` handler, never on
 `visibilitychange`, so a visitor who lands, reads, clicks nothing and leaves
 the tab open emits one `$pageview` and records zero seconds. The eventual
-close lands in a rotated session: 67 orphan `$pageleave`-only sessions in 30
-days, every one preceded by a session from the same person, median gap 221
-minutes, p75 1486 minutes. The long gaps are what rule out an ad blocker or a
-browser quirk.
+close lands in a rotated session: 67 orphan sessions — at least one
+`$pageleave` and zero `$pageview` — every one preceded by a session from the
+same person, median gap 221 minutes, p75 1486 minutes, measured over
+`now() - INTERVAL 30 DAY` as at 2026-09-18. The long gaps are what rule out an
+ad blocker or a browser quirk.
 
 The distortion concentrated where no passive event could fire — desktop 13.6%
 zero-duration against mobile 17.8%, with `marketing:stage_progress` (gated to
-1024x720) firing on 0.0% of mobile sessions and 91% of mobile sessions
+1024x720 and to non-reduced-motion) firing on 0.0% of mobile sessions and 91% of mobile sessions
 emitting nothing but the pageview. Fixed by `marketing:engaged_time`, which
 reports visible-only time at 10s and 30s on every viewport. Note that an
 earlier draft of this document described the gap as uniform "across every