cursedbelt 5.0.1 → 5.2.0

package/scripts/generateAreaStyles.ts

@@ -1,7 +1,25 @@
 #!/usr/bin/env bun
 /**
- * Generate `src/styles-areas/*.css` — cursedbelt's utilities, PRECOMPILED PER AREA,
- * so a consuming app pays for the components it renders instead of for the union.
+ * Generate `src/styles-areas/*.css` — cursedbelt's utility CANDIDATES, per area, so a
+ * consuming app pays for the components it renders instead of for the union.
+ *
+ * ── 🔴 Candidates, not compiled CSS (5.1.0, task 2124) ───────────────────────
+ * Until 5.1.0 each area was a PRECOMPILED, sorted utilities sheet. Tailwind emits one sorted
+ * utilities pass — every base utility, then every variant — so a variant always follows the
+ * base it overrides; two sorted passes concatenated are not sorted. The app's own pass came
+ * first, the areas after, and an area's `.hidden{display:none}` landed after the app's
+ * `.sm\:flex` at the same specificity: flix's desktop nav vanished at 1440 px and the phone
+ * row appeared (task 2124, measured 2026-09-23), and station hit the same on ten rules.
+ * Import order cannot fix it — areas first breaks cursedbelt's own `hidden sm:flex` whenever
+ * the app also uses `hidden`.
+ *
+ * So an area is now `@source inline("…")` of its candidates: the app's ONE Tailwind pass
+ * generates the area's utilities together with its own, in one sort, and the ordering bug
+ * cannot be written. The candidates are exactly what the precompiled sheets were built from,
+ * so the rules are the same rules (`src/stylesAreas.spec.ts` still proves every area together
+ * equals the union, rule by rule), and duplicates across areas cost nothing — one pass
+ * dedupes them. `scripts/checkAreaStyles.ts` fails an app build that still has a base utility
+ * after a variant, for whatever causes it next.
  *
  * ── The number this exists to move ──────────────────────────────────────────
  * `cursedbelt/styles.css` and the `styles-static.css` + `styles-utilities.css`
@@ -65,6 +83,7 @@
  *   bun run styles:areas --check    # exit 1 if any is stale, write nothing
  */
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+import { classesInCss } from './checkAreaStyles';
 import { UTILITY_INPUT, compileStylesheet } from './generateUtilityStyles';
 import {
 	AREA_DIR,
@@ -93,6 +112,12 @@ export const areaSubpath = (name: string): string => `./${AREA_DIR.replace(/^src
  */
 export const MIN_CORE_CANDIDATES = 1_000;
 
+/**
+ * …and the floor on what survives as UTILITIES once the scanner's non-class tokens are dropped
+ * (5.1.0 writes only those). 705 on the day it was set; a core of a few dozen is a broken filter.
+ */
+export const MIN_CORE_UTILITIES = 400;
+
 const banner = (area: Area, candidates: number, subtracted: boolean): string => {
 	const needs = transitiveNeeds(area.name);
 	const imports = [CORE, ...needs, ...(subtracted ? [area.name] : [])]
@@ -100,14 +125,14 @@ const banner = (area: Area, candidates: number, subtracted: boolean): string =>
 		.map((n) => ` *   @import "cursedbelt/styles-areas/${n}.css";`)
 		.join('\n');
 	return `/*
- * cursedbelt — the \`${area.name}\` area. GENERATED BUILD ARTIFACT. Never hand-edit.
+ * cursedbelt — the \`${area.name}\` area's utility candidates. GENERATED BUILD ARTIFACT. Never hand-edit.
  *
  * ${area.why}.
  *
  * ${
 		subtracted
 			? `Every Tailwind utility the modules in this area's import closure use, MINUS the\n * ones ${[CORE, ...needs].map((n) => `\`styles-areas/${n}.css\``).join(' and ')} already ship${needs.length > 0 ? '' : 's'}. 🔴 Import ALL of these, in\n * this order — this file alone is incomplete:`
-			: 'Every Tailwind utility the primitives and their plumbing use. Import it first,\n * before any other area:'
+			: 'Every Tailwind utility the primitives and their plumbing use. Every app imports it:'
 	}
  *
  *   @import "tailwindcss";
@@ -115,9 +140,12 @@ const banner = (area: Area, candidates: number, subtracted: boolean): string =>
 ${imports}
  *   @import "cursedbelt/theme.css";
  *
- * An app that imports every area gets exactly what \`cursedbelt/styles-utilities.css\`
- * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. ${candidates} candidate(s) scanned.
+ * These are CANDIDATES (\`@source inline\`), not CSS: the app's own Tailwind pass generates
+ * them, sorted together with the app's utilities, so an area can never put a base utility
+ * after an app's responsive variant (task 2124). An app that imports every area gets exactly
+ * what \`cursedbelt/styles-utilities.css\` emits — proved rule by rule in
+ * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
+ * ${candidates} candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (\`bun run styles:areas\`), which
  * \`bun run build\` runs. The map of what is in which area, and why the areas are
@@ -126,6 +154,95 @@ ${imports}
 `;
 };
 
+/**
+ * How a candidate can be written into `@source inline(…)`: inside double quotes, inside single
+ * quotes (one that itself holds a `"`, e.g. `before:content-[""]` — measured: Tailwind does NOT
+ * unescape `\"`, so a single-quoted string is the only spelling that round-trips), or not at all
+ * (a brace would be brace-EXPANDED, a backslash or space would split or mangle it).
+ */
+export const inlineQuote = (candidate: string): '"' | "'" | null => {
+	if (/[{}\\\s]/.test(candidate)) return null;
+	if (!candidate.includes('"')) return '"';
+	return candidate.includes("'") ? null : "'";
+};
+
+/**
+ * The candidates worth writing: every one that can be quoted. 🔴 One that cannot is dropped only
+ * if it compiles to nothing — a scanner token like \`{a,b}\` is noise, but a real utility the
+ * string cannot carry would be a rule an app silently loses, so that throws.
+ */
+export const inlineCandidates = async (candidates: readonly string[], area: string): Promise<string[]> => {
+	const unsafe = candidates.filter((c) => inlineQuote(c) === null);
+	if (unsafe.length > 0) {
+		const empty = (await compileStylesheet(UTILITY_INPUT)).build([]);
+		const withUnsafe = (await compileStylesheet(UTILITY_INPUT)).build(unsafe);
+		if (withUnsafe !== empty) {
+			const real: string[] = [];
+			for (const c of unsafe) if ((await compileStylesheet(UTILITY_INPUT)).build([c]) !== empty) real.push(c);
+			throw new Error(
+				`area \`${area}\`: ${real.length} utility candidate(s) cannot be written into @source inline(…) —\n` +
+					`  ${real.join('\n  ')}\n  An app on the areas would lose their rules. Spell the class without a brace, backslash or both quote kinds.`,
+			);
+		}
+	}
+	// Only the candidates that ARE a utility: the scanner hands over every token (`---`, `!source`,
+	// prop names), and the precompiled sheets simply ignored them. Keep a candidate when its own
+	// class is a selector subject of the compiled output — then PROVE the filter dropped nothing
+	// by compiling both sets and requiring identical CSS.
+	const writable = candidates.filter((c) => inlineQuote(c) !== null);
+	const full = (await compileStylesheet(UTILITY_INPUT)).build(writable);
+	const emitted = classesInCss(full);
+	// Tailwind escapes a selector the CSS.escape way; a candidate whose escaped form is in the
+	// output is kept even when unescaping would not round-trip it (a `…` from a doc comment did not).
+	// A `--token` candidate is a THEME VARIABLE the modules read (\`var(--text-sm)\` in a style
+	// prop): Tailwind emits it into \`:root\` only because the scan saw it, so it stays too.
+	const kept = writable.filter(
+		(c) => emitted.has(c) || full.includes(`.${cssEscape(c)}`) || (/^--[\w-]+$/.test(c) && full.includes(`${c}:`)),
+	);
+	const trimmed = (await compileStylesheet(UTILITY_INPUT)).build(kept);
+	if (trimmed !== full) {
+		throw new Error(
+			`area \`${area}\`: keeping only candidates that name an emitted class changed the compiled CSS ` +
+				`(${full.length} B → ${trimmed.length} B). Some candidate emits a rule under another selector; ` +
+				'widen the filter rather than lose it.',
+		);
+	}
+	return kept;
+};
+
+/** `CSS.escape` for a class name — what Tailwind writes into a selector. */
+export const cssEscape = (name: string): string =>
+	[...name]
+		.map((ch, i) => {
+			if (/[a-zA-Z0-9_-]/.test(ch) || ch.codePointAt(0)! >= 0x80) {
+				return i === 0 && /[0-9]/.test(ch) ? `\\${ch.codePointAt(0)!.toString(16)} ` : ch;
+			}
+			return `\\${ch}`;
+		})
+		.join('');
+
+/** `@source inline(…)` lines, ~100 columns each, so a diff shows which candidates moved. */
+export const inlineSource = (candidates: readonly string[]): string => {
+	const out: string[] = [];
+	for (const quote of ['"', "'"] as const) {
+		let line: string[] = [];
+		let width = 0;
+		const flush = () => {
+			if (line.length > 0) out.push(`@source inline(${quote}${line.join(' ')}${quote});\n`);
+			line = [];
+			width = 0;
+		};
+		for (const c of candidates) {
+			if (inlineQuote(c) !== quote) continue;
+			if (width + c.length > 96) flush();
+			line.push(c);
+			width += c.length + 1;
+		}
+		flush();
+	}
+	return out.join('');
+};
+
 export interface BuiltArea {
 	readonly name: string;
 	readonly css: string;
@@ -188,11 +305,14 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		// the first a superset of the ones before it — and each file would still look
 		// plausible on its own. Found by measuring; the symptom was areas growing
 		// monotonically in the order they were compiled.
-		const compiled = await compileStylesheet(UTILITY_INPUT);
+		const inline = await inlineCandidates(only, area.name);
+		if (area.name === CORE && inline.length < MIN_CORE_UTILITIES) {
+			throw new Error(`core kept ${inline.length} utility candidates (floor ${MIN_CORE_UTILITIES}) — the filter, not the design system, shrank.`);
+		}
 		built.push({
 			name: area.name,
-			css: `${banner(area, only.length, area.name !== CORE)}${compiled.build(only)}`,
-			candidates: only,
+			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}`,
+			candidates: inline,
 			modules: [...closure].map((f) => f.replace(`${REPO_ROOT}/`, '')).sort(),
 		});
 	}

package/scripts/paths.ts

@@ -70,7 +70,7 @@ function viaWorktree(from: string): string | null {
 		});
 		if (git.status !== 0) return null;
 		const gitDir = (git.stdout ?? "").trim();
-		if (!gitDir || !gitDir.startsWith("/")) return null;
+		if (!gitDir?.startsWith("/")) return null;
 		// `<primary>/.git` → `<primary>`, then the ordinary walk up.
 		return findForgeRoot(dirname(gitDir));
 	} catch {

package/scripts/styleAreas.ts

@@ -130,6 +130,8 @@ export const AREAS: readonly Area[] = [
 			'colorScheme',
 			'constants',
 			'layout',
+			// The engagement beacon draws nothing; it is here because every app beacons (5.2.0).
+			'engagement',
 			'namespace',
 			'portal',
 			'slots',

package/src/react/components/ActionBar.spec.tsx

@@ -104,6 +104,7 @@ describe('FooterSlot — a footer can no longer render without chrome', () => {
     const { container } = render(
       <FooterSlot
         footer={
+          // biome-ignore lint/complexity/noUselessFragments: the fragment IS the case under test
           <>
             <ActionBar primary={<Button tooltip='Save'>Save</Button>} />
           </>

package/src/react/engagement/beacon.tsx

@@ -0,0 +1,63 @@
+/**
+ * The React adapter over `beaconClient.ts` — one hook, one component.
+ *
+ * Separate file from the plain-JS half so an app with no React (or a test with
+ * no DOM) can import `reportPlace` without pulling React in, and so the app's
+ * own router stays the thing that decides what "a place" is.
+ */
+import { useEffect } from "react";
+import { type ReportPlaceOptions, reportPlace, startLocationBeacon } from "./beaconClient.js";
+
+/**
+ * Report `place` whenever it changes.
+ *
+ * `place` should be the app's own route-manifest id — the same string the
+ * server resolves against. Pass `null` while the route is unresolved (a lazy
+ * view still loading, a signed-out shell) rather than a placeholder: a
+ * placeholder becomes a real row in the console.
+ */
+export function useEngagementBeacon(place: string | null, options: ReportPlaceOptions = {}): void {
+	const basePath = options.basePath;
+	useEffect(() => {
+		if (!place) return;
+		// Fire and forget; `reportPlace` never rejects. Not awaited on purpose —
+		// a route change must not wait on telemetry.
+		void reportPlace(place, basePath ? { basePath } : {});
+	}, [place, basePath]);
+}
+
+/**
+ * Report wherever the browser IS, and keep reporting as it moves.
+ *
+ * This is the form every app should use, and it is why adoption is one line
+ * rather than a per-app mapping: the client sends its LOCATION and the server
+ * resolves it against that app's own route manifest (`policy.ts:resolvePlace`).
+ * A `route.view → place id` table written in twelve app shells would be twelve
+ * places for the names to drift, and a drifted name reads on the board as a
+ * page nobody opens — a wrong answer, not a gap.
+ *
+ * Listens to `hashchange` and `popstate`, which between them cover both kinds of
+ * router — hash-routed apps like this one, and a pushState app. `reportPlace`
+ * de-duplicates, so a re-render costs nothing.
+ */
+export function useLocationBeacon(options: ReportPlaceOptions = {}): void {
+	const basePath = options.basePath;
+	// Delegates to the plain-JS starter so there is ONE implementation of the
+	// listener set. Most apps call `startLocationBeacon()` from `main.tsx`
+	// instead; this exists for a shell that would rather own the lifetime.
+	useEffect(() => startLocationBeacon(basePath ? { basePath } : {}), [basePath]);
+}
+
+/**
+ * The location beacon as an element, for a shell that mounts declaratively.
+ *
+ * Deliberately takes no `place` prop. Offering both would mean two callers of
+ * one module-level de-duplication memory, and an app that passed a place would
+ * silently suppress the location half or vice versa — use
+ * {@link useEngagementBeacon} directly when an app really does know its own
+ * place ids.
+ */
+export function EngagementBeacon(props: { basePath?: string }): null {
+	useLocationBeacon(props.basePath ? { basePath: props.basePath } : {});
+	return null;
+}

package/src/react/engagement/beaconClient.spec.ts

@@ -0,0 +1,138 @@
+/**
+ * The beacon's SILENCE contract.
+ *
+ * `beacon.client.ts` says failure is silence, and on 2026-08-14 that turned out
+ * to be true only of the JavaScript. A `fetch` that comes back 401 leaves the
+ * browser's own *"Failed to load resource"* in the console however carefully the
+ * promise is handled — so a beacon fired from a sign-in card put an error on the
+ * front door of every private satellite, and `music`'s and `learn`'s signed-out
+ * route health failed on it against live prod with nothing else wrong.
+ *
+ * These tests are about the request that is NOT made. `window` is deliberately
+ * untouched: `reportPlace` is the whole mechanism and needs no DOM, which is why
+ * this file runs in the package's plain `bun test`.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import { reportPlace, resetEngagementBeacon, SESSION_PATH } from "./beaconClient.js";
+
+/** A `fetch` that records every call and answers from a script. */
+function recordingFetch(answers: Record<string, { status?: number; body?: unknown }>) {
+	const calls: string[] = [];
+	const impl = (async (input: string) => {
+		const url = String(input);
+		calls.push(url);
+		const answer = answers[url] ?? { status: 404 };
+		const status = answer.status ?? 200;
+		return {
+			ok: status >= 200 && status < 300,
+			status,
+			json: async () => answer.body ?? {},
+		};
+	}) as unknown as typeof fetch;
+	return { impl, calls };
+}
+
+const SIGNED_IN = { body: { authenticated: true } };
+const SIGNED_OUT = { body: { authenticated: false } };
+
+beforeEach(() => {
+	resetEngagementBeacon();
+});
+
+describe("signed out, the beacon makes no gated request at all", () => {
+	test("it asks the public session probe and then stays quiet", async () => {
+		const { impl, calls } = recordingFetch({ [SESSION_PATH]: SIGNED_OUT });
+
+		expect(await reportPlace("/#/hub", { fetchImpl: impl })).toBe(false);
+
+		// The probe, and nothing else. A POST to the gated recorder is exactly the
+		// request that produced the console line.
+		expect(calls).toEqual([SESSION_PATH]);
+	});
+
+	test("🔴 it does not consume the de-duplication slot", async () => {
+		// The bug this ordering prevents: a signed-out arrival at `/#/hub` marking
+		// `/#/hub` as already-reported, so the FIRST real view after signing in —
+		// which lands on that same place — is dropped forever as a duplicate.
+		const out = recordingFetch({ [SESSION_PATH]: SIGNED_OUT });
+		expect(await reportPlace("/#/hub", { fetchImpl: out.impl })).toBe(false);
+
+		resetEngagementBeacon(); // what a full page load (the SSO callback) does
+		const inn = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+		expect(await reportPlace("/#/hub", { fetchImpl: inn.impl })).toBe(true);
+		expect(inn.calls).toContain("/api/engagement/view");
+	});
+});
+
+describe("signed in, nothing that used to be counted stops being counted", () => {
+	test("the view is reported, after the probe", async () => {
+		const { impl, calls } = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+
+		expect(await reportPlace("/#/stats", { fetchImpl: impl })).toBe(true);
+		expect(calls).toEqual([SESSION_PATH, "/api/engagement/view"]);
+	});
+
+	test("the probe is asked ONCE per page load, not once per navigation", async () => {
+		const { impl, calls } = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+
+		await reportPlace("/#/hub", { fetchImpl: impl });
+		await reportPlace("/#/stats", { fetchImpl: impl });
+		await reportPlace("/#/archive", { fetchImpl: impl });
+
+		expect(calls.filter((url) => url === SESSION_PATH)).toHaveLength(1);
+		expect(calls.filter((url) => url === "/api/engagement/view")).toHaveLength(3);
+	});
+
+	test("a repeated place is still one view — the old rule is untouched", async () => {
+		const { impl, calls } = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+
+		await reportPlace("/#/hub", { fetchImpl: impl });
+		expect(await reportPlace("/#/hub", { fetchImpl: impl })).toBe(false);
+		expect(calls.filter((url) => url === "/api/engagement/view")).toHaveLength(1);
+	});
+});
+
+describe("the probe fails CLOSED", () => {
+	// One uncounted view is cheap. A false positive is the console line on the
+	// front door, which is the whole thing this path exists to prevent.
+	test.each([
+		["the probe itself errors", null],
+		["the probe answers non-2xx", { status: 500 }],
+		["the body carries no verdict", { body: {} }],
+		["the body says authenticated is a string", { body: { authenticated: "yes" } }],
+	])("%s → nothing is sent", async (_name, answer) => {
+		const impl = (async (input: string) => {
+			if (answer === null) throw new Error("network down");
+			const status = (answer as { status?: number }).status ?? 200;
+			return {
+				ok: status >= 200 && status < 300,
+				status,
+				json: async () => (answer as { body?: unknown }).body ?? {},
+				_url: input,
+			};
+		}) as unknown as typeof fetch;
+
+		expect(await reportPlace("/#/hub", { fetchImpl: impl })).toBe(false);
+	});
+});
+
+describe("a caller that already knows may skip the probe", () => {
+	test("assumeSignedIn reports with no second answer to the same question", async () => {
+		const { impl, calls } = recordingFetch({ "/api/engagement/view": { status: 200 } });
+
+		expect(await reportPlace("/#/hub", { fetchImpl: impl, assumeSignedIn: true })).toBe(true);
+		expect(calls).toEqual(["/api/engagement/view"]);
+	});
+});

package/src/react/engagement/beaconClient.ts

@@ -0,0 +1,228 @@
+/**
+ * `cursedbelt/react/engagement-beacon` — the engagement beacon's plain-JS half (no React). Lifted
+ * 2026-09-23 (cursedbelt 5.2.0, task 098-280's browser half) from `src/kit/engagement/beacon.client.ts`,
+ * identical in collections, family, music and roms (auth's differed only in a comment). The
+ * server half is `cursedbelt-server/engagement`.
+ *
+ * The browser half — report which PLACE the user is on, once per arrival.
+ *
+ * ── Why an explicit beacon and not the request log ──────────────────────────
+ * Most satellites are SPA-routed: moving from Notes' Files page to its Ask page
+ * fires zero navigations and, on a warm cache, zero HTTP requests. So the
+ * request metrics already in `metrics/` can tell you an app is used and cannot
+ * tell you which of its pages are — which is exactly the question the owner
+ * asked ("notes is used but its slideshow is not"). One small event, sent by
+ * the router, is the only thing that can answer it.
+ *
+ * ── It is ONE implementation, adopted; never per-app ────────────────────────
+ * Eleven hand-rolled beacons would be eleven different place vocabularies, and
+ * the console would be comparing strings that mean different things. Apps call
+ * `reportPlace` (or mount `useEngagementBeacon`) and send an id from their own
+ * route manifest; the server resolves it against that same manifest.
+ *
+ * ── What it does NOT send ───────────────────────────────────────────────────
+ * No path, no query, no title, no referrer, no identifiers of any kind — just
+ * `{ place }`. The account comes from the session cookie the request already
+ * carries, server-side. There is nothing in the payload that could carry a note
+ * id, a ROM title or a search string, which is the property that makes this
+ * safe to run inside private apps at all. See `policy.ts`.
+ *
+ * ── Failure is silence ──────────────────────────────────────────────────────
+ * Every call is fire-and-forget and swallows its error. Telemetry that can
+ * surface an error toast, block a route change, or reject an unhandled promise
+ * is telemetry that makes the app worse than having none.
+ *
+ * 🔴 …and "silence" includes the BROWSER's console, which is why the beacon
+ * asks whether there is a session before it reports (`SESSION_PATH` below).
+ * Swallowing the rejection in JS is not enough: a `fetch` that comes back 401
+ * leaves the browser's own *"Failed to load resource: the server responded with
+ * a status of 401"* in the console no matter what the caller does with the
+ * promise. Measured 2026-08-14 against live prod — `music` and `learn` both
+ * failed their signed-out route-health check on exactly this, with a correctly
+ * rendered sign-in card on screen and nothing else wrong. `apps/roms`' App.tsx
+ * already wrote the rule down for the feedback provider: *"an app that logs an
+ * error on its front door is an app nobody can tell apart from a broken one."*
+ * The recorder's 401 is deliberate and stays — `api.ts` mounts it AFTER the
+ * session gate on purpose, because the gate is what puts the user where
+ * `resolveUser` can read them — so the fix belongs on this side.
+ *
+ * It is also the semantically right answer, not merely a quieter one: the
+ * recorder attributes a view to an account, so a signed-out arrival could never
+ * have been recorded. Nothing that used to be counted stops being counted.
+ */
+
+/** Where the recorder is mounted. Apps that remount it pass `basePath`. */
+export const ENGAGEMENT_BASE_PATH = "/api/engagement";
+
+/**
+ * The public session probe every satellite serves
+ * (`ssoConsumer.server.ts` → `{ authenticated, user?, accountsUrl }`).
+ *
+ * Deliberately NOT session-gated on the server, which is what makes it usable
+ * here: asking it costs one small same-origin GET and can never itself produce
+ * the console line this exists to avoid.
+ */
+export const SESSION_PATH = "/api/auth/session";
+
+export interface ReportPlaceOptions {
+	basePath?: string;
+	/** Injected in tests; defaults to the global. */
+	fetchImpl?: typeof fetch;
+	/** Override the session probe. Apps that remount the consumer elsewhere. */
+	sessionPath?: string;
+	/**
+	 * Skip the session probe and report unconditionally.
+	 *
+	 * For a caller that ALREADY knows there is a session — a React tree below the
+	 * authenticated branch, say — where the probe would be a second answer to a
+	 * question already asked. Never set it from `main.tsx`, which runs before
+	 * anything knows.
+	 */
+	assumeSignedIn?: boolean;
+}
+
+/**
+ * The last place reported, so a router that re-renders does not re-report.
+ *
+ * A React router re-runs its effects on every state change that touches the
+ * route object, and a beacon per keystroke in a search box would turn one visit
+ * into forty views — inflating exactly the number the console reads as
+ * "interest". De-duplicating on the place id is what keeps a view meaning "an
+ * arrival".
+ */
+let lastReported: string | null = null;
+
+/**
+ * Where the browser is, as a string the server can resolve.
+ *
+ * The hash when there is one (every satellite but roms routes on it), else the
+ * pathname. Never the search string: `normalizePlaceId` strips one anyway, and
+ * not sending it in the first place means user text does not travel at all.
+ */
+export function currentLocationPlace(): string {
+	const { hash, pathname } = window.location;
+	const raw = hash && hash !== "#" ? hash : pathname;
+	return raw.split("?")[0] ?? "/";
+}
+
+/**
+ * The answer to "is anyone signed in?", remembered for this page load.
+ *
+ * One probe per load, not one per navigation: the answer cannot change without
+ * a navigation that replaces the document (the SSO callback is a full page
+ * load), and re-asking on every hash change would trade one wasted request for
+ * dozens.
+ */
+let sessionAnswer: Promise<boolean> | null = null;
+
+/** Reset the de-duplication memory. Tests, and a sign-out. */
+export function resetEngagementBeacon(): void {
+	lastReported = null;
+	sessionAnswer = null;
+}
+
+/**
+ * Is there a session? Silent, cached, and false on any doubt.
+ *
+ * Fails CLOSED — a probe that throws, answers non-2xx or returns a body this
+ * cannot read means "do not report". The cost of a false negative is one
+ * uncounted view; the cost of a false positive is the console line on the front
+ * door that this whole path exists to prevent.
+ */
+async function hasSession(options: ReportPlaceOptions): Promise<boolean> {
+	const doFetch = options.fetchImpl ?? globalThis.fetch;
+	if (typeof doFetch !== "function") return false;
+	try {
+		const res = await doFetch(options.sessionPath ?? SESSION_PATH, {
+			credentials: "same-origin",
+		});
+		if (!res.ok) return false;
+		const body = (await res.json()) as { authenticated?: unknown } | null;
+		return body?.authenticated === true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Report an arrival at `place`. Returns whether anything was sent.
+ *
+ * Not awaited by callers in practice — the promise is returned so a test can
+ * settle it without a timer.
+ */
+export async function reportPlace(
+	place: string,
+	options: ReportPlaceOptions = {},
+): Promise<boolean> {
+	if (!place || place === lastReported) return false;
+	const doFetch = options.fetchImpl ?? globalThis.fetch;
+	if (typeof doFetch !== "function") return false;
+
+	// 🔴 BEFORE the de-duplication is committed, not after. A signed-out arrival
+	// must leave no trace at all — recording it as `lastReported` would mean the
+	// view that happens once the visitor signs in and lands back on this same
+	// place is silently dropped as a duplicate.
+	if (options.assumeSignedIn !== true) {
+		sessionAnswer ??= hasSession(options);
+		if (!(await sessionAnswer)) return false;
+	}
+
+	if (place === lastReported) return false;
+	lastReported = place;
+	try {
+		await doFetch(`${options.basePath ?? ENGAGEMENT_BASE_PATH}/view`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			// Same-origin credentials: the session cookie is the only identity
+			// this request carries, and it is the only one it may carry.
+			credentials: "same-origin",
+			body: JSON.stringify({ place }),
+			keepalive: true,
+		});
+		return true;
+	} catch {
+		// See the header: telemetry never becomes the user's problem.
+		return false;
+	}
+}
+
+/** Detaches the listeners `startLocationBeacon` installed. */
+export type StopBeacon = () => void;
+
+let running: StopBeacon | null = null;
+
+/**
+ * Start reporting wherever the browser is, and keep reporting as it moves.
+ *
+ * The form every app adopts, called once from `main.tsx` beside
+ * `initColorScheme()` — one line, no React, and no per-app mapping from a
+ * router's internal view name to a place id. The server resolves the LOCATION
+ * against that app's own `routes.manifest.json` (`policy.ts:resolvePlace`),
+ * which is the list the app already maintains and already gates on.
+ *
+ * `hashchange` and `popstate` between them cover both kinds of router, which is
+ * why BOTH are listened for when `collections` — hash-routed — only needs the
+ * first. The census that settled it was the previous generation's twelve apps:
+ * eleven hash routers and one pushState app. Keeping the second listener costs
+ * a no-op call, and losing it would be silent.
+ *
+ * Idempotent — a second call replaces the first rather than doubling every
+ * view, which matters because React 18 StrictMode mounts twice in development
+ * and a doubled count is a wrong number rather than a visible fault.
+ */
+export function startLocationBeacon(options: ReportPlaceOptions = {}): StopBeacon {
+	running?.();
+	const send = (): void => {
+		void reportPlace(currentLocationPlace(), options);
+	};
+	send();
+	window.addEventListener("hashchange", send);
+	window.addEventListener("popstate", send);
+	const stop: StopBeacon = () => {
+		window.removeEventListener("hashchange", send);
+		window.removeEventListener("popstate", send);
+		if (running === stop) running = null;
+	};
+	running = stop;
+	return stop;
+}

package/src/react/engagement/index.ts

@@ -0,0 +1,13 @@
+// `cursedbelt/react/engagement-beacon` — the engagement beacon: `reportPlace` and
+// `startLocationBeacon` (plain JS, no React) and the React hooks over them.
+export {
+	ENGAGEMENT_BASE_PATH,
+	type ReportPlaceOptions,
+	reportPlace,
+	resetEngagementBeacon,
+	SESSION_PATH,
+	type StopBeacon,
+	startLocationBeacon,
+	currentLocationPlace,
+} from './beaconClient.js';
+export { EngagementBeacon, useEngagementBeacon, useLocationBeacon } from './beacon.js';