cursedbelt 5.1.0 → 5.3.0

package/scripts/checkAreaStyles.ts

@@ -29,12 +29,20 @@
  * {@link cascadeFaults}: a base utility after a variant that sets the same property is two sorted
  * Tailwind passes concatenated, and the base wins at every width. Both halves exit 1.
  *
+ * ── …and whether every THEME variable the build reads is defined (5.3.0) ────────────────
+ * {@link undefinedThemeVariables}: a `var(--color-card)` in the built JS or CSS whose `--color-card`
+ * no built stylesheet declares. Tailwind prunes theme variables nothing in its pass names, and a
+ * component that reads one by name from a style prop is invisible to the class check above — the
+ * hole station's frozen DataTable column fell through (F4, 2026-09-23). Exit 1 as well.
+ *
  * Usage, from an app, after its build:
  *   bun node_modules/cursedbelt/scripts/checkAreaStyles.ts dist
- * Exit 0 = complete, 1 = a class is unstyled (listed with its area), 2 = could not measure
+ * Exit 0 = complete, 1 = a class is unstyled (listed with its area), a base utility follows a
+ * variant, or a theme variable read is declared nowhere; 2 = could not measure
  * (no JS or no CSS under the directory — a check that measured nothing has not passed).
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -132,6 +140,25 @@ export function onlyInMergeTables(token: string, js: string): boolean {
   return seen > 0 && [...js.matchAll(bare)].length === seen;
 }
 
+/**
+ * Does `token` occur in the built JS only as a PROPERTY NAME — the left side of an `in` test
+ * (`"invert"in e`, d3's scale check inside recharts) or an object key (`{"invert":…}`)? A className
+ * is always a string VALUE, never either (task 2131, measured on station's build 2026-09-23: the
+ * only false reference left after the tailwind-merge filter, and it demanded the `media` area).
+ * Refused as soon as the token also appears in any class string.
+ */
+export function onlyAsPropertyName(token: string, js: string): boolean {
+  const quoted = new RegExp(`(["'])${escapeRe(token)}\\1`, 'g');
+  let seen = 0;
+  for (const m of js.matchAll(quoted)) {
+    seen++;
+    const after = js.slice((m.index ?? 0) + m[0].length, (m.index ?? 0) + m[0].length + 4);
+    if (!/^\s*(?::|in\b)/.test(after)) return false;
+  }
+  const bare = new RegExp(`(^|[\\s"'\`])${escapeRe(token)}(?=[\\s"'\`]|$)`, 'g');
+  return seen > 0 && [...js.matchAll(bare)].length === seen;
+}
+
 // ── the ORDER check (5.1.0, task 2124) ─────────────────────────────────────────────────
 
 export interface CascadeFault {
@@ -252,6 +279,81 @@ export function cascadeFaults(cssTexts: readonly string[]): CascadeFault[] {
   return faults;
 }
 
+// ── the THEME VARIABLE check (5.3.0) ───────────────────────────────────────────────────
+
+/**
+ * Every custom property an `@theme` block declares (any `@theme inline`/`static`/… form). These — and
+ * only these — are what Tailwind PRUNES: it emits a theme variable into `:root` only when its pass
+ * sees it used. Every other custom property is written down by a stylesheet unconditionally or set
+ * at runtime (`--radix-*`, sonner's `--offset`, a component's `--cb-frozen-bg`), and an area split
+ * cannot lose it — which is why the check is scoped here and needs no allowlist.
+ */
+export function themeVariablesIn(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of code.matchAll(/@theme\b[^{]*\{/g)) {
+    let depth = 1;
+    let i = (m.index ?? 0) + m[0].length;
+    const start = i;
+    for (; i < code.length && depth > 0; i++) {
+      if (code[i] === '{') depth++;
+      else if (code[i] === '}') depth--;
+    }
+    for (const d of code.slice(start, i).matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:\s*([^;}]*)/g)) {
+      // `initial` is Tailwind's "unset" — `--default-font-feature-settings: --theme(--font-sans--…, initial)`
+      // is declared only when the app sets the key it names, and preflight reads it with a fallback.
+      // Measured on station's union build: the four `--default-*-settings` were the only noise.
+      if (/^(?:initial|--theme\([^)]*,\s*initial\))$/.test((d[2] as string).trim())) continue;
+      out.add(d[1] as string);
+    }
+  }
+  return out;
+}
+
+/** Every custom property a stylesheet DECLARES: `--x:` in any block, or `@property --x`. */
+export function variablesDeclared(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of code.matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:/g)) out.add(m[1] as string);
+  for (const m of code.matchAll(/@property\s+(--[\w-]+)/g)) out.add(m[1] as string);
+  return out;
+}
+
+/** Every `var(--x…)` a text reads — a JS bundle's style strings or a stylesheet's values. */
+export function variablesReferenced(text: string): Set<string> {
+  return new Set([...text.matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1] as string));
+}
+
+/**
+ * 🔴 The THEME variables the built JS or CSS reads with `var()` that no built stylesheet declares.
+ * Each one is a value that silently resolves to nothing — `var(--color-card)` as a background is
+ * transparent, not an error. A fallback (`var(--x, red)`) does not excuse one: it renders, but not
+ * as the theme says, which is the same divergence from the union.
+ */
+export function undefinedThemeVariables(input: { js: string[]; css: string[] }, theme: ReadonlySet<string>): string[] {
+  const declared = new Set<string>();
+  for (const css of input.css) for (const name of variablesDeclared(css)) declared.add(name);
+  const read = new Set<string>();
+  for (const text of [...input.js, ...input.css]) for (const name of variablesReferenced(text)) read.add(name);
+  return [...read].filter((name) => theme.has(name) && !declared.has(name)).sort();
+}
+
+/**
+ * The theme a cursedbelt consumer compiles against: this package's `theme.css` and
+ * `styles-static.css`, and Tailwind's own `theme.css` (resolved from this package, which in an app
+ * is the app's copy). 🔴 Throws rather than shrinking the set when Tailwind cannot be found — a
+ * check over half the theme would pass on exactly the variables it cannot see.
+ */
+export function readThemeVariables(src: string | undefined = SRC): Set<string> {
+  if (!src) throw new Error("cursedbelt's src/ is not beside this script — the package is incomplete");
+  const tailwindTheme = createRequire(join(src, '..', 'package.json')).resolve('tailwindcss/theme.css');
+  const out = new Set<string>();
+  for (const file of [join(src, 'theme.css'), join(src, 'styles-static.css'), tailwindTheme]) {
+    for (const name of themeVariablesIn(readFileSync(file, 'utf8'))) out.add(name);
+  }
+  return out;
+}
+
 function filesUnder(dir: string, ext: string, out: string[] = []): string[] {
   for (const entry of readdirSync(dir)) {
     if (entry === 'node_modules') continue;
@@ -271,13 +373,15 @@ export interface AreaCheckResult {
   referenced: number;
   /** {@link cascadeFaults} over the built CSS — base utilities that override a variant. */
   outOfOrder: CascadeFault[];
+  /** {@link undefinedThemeVariables} — theme variables read by `var()` and declared by no built CSS. */
+  undefinedVariables: string[];
 }
 
 /** The measurement, over explicit texts — what the spec drives. */
 export function checkAreaStyles(
   input: { js: string[]; css: string[] },
   belt: { union: string; areas: Record<string, string> },
-): Omit<AreaCheckResult, 'jsFiles' | 'cssFiles' | 'outOfOrder'> {
+): Omit<AreaCheckResult, 'jsFiles' | 'cssFiles' | 'outOfOrder' | 'undefinedVariables'> {
   const union = classesInCss(belt.union);
   const areaOf = new Map<string, string>();
   for (const [area, css] of Object.entries(belt.areas)) {
@@ -290,7 +394,7 @@ export function checkAreaStyles(
   const allJs = input.js.join('\n');
   const missing = [...referenced]
     .filter((name) => !emitted.has(name))
-    .filter((name) => !onlyInMergeTables(name, allJs))
+    .filter((name) => !onlyInMergeTables(name, allJs) && !onlyAsPropertyName(name, allJs))
     .sort()
     .map((className) => ({ className, area: areaOf.get(className) as string }));
   return { missing, referenced: referenced.size };
@@ -313,7 +417,14 @@ export function checkDist(distDir: string): AreaCheckResult {
     readBeltSheets(),
   );
   const cssTexts = cssFiles.map((f) => readFileSync(f, 'utf8'));
-  return { ...result, outOfOrder: cascadeFaults(cssTexts), jsFiles: jsFiles.length, cssFiles: cssFiles.length };
+  const jsTexts = jsFiles.map((f) => readFileSync(f, 'utf8'));
+  return {
+    ...result,
+    outOfOrder: cascadeFaults(cssTexts),
+    undefinedVariables: undefinedThemeVariables({ js: jsTexts, css: cssTexts }, readThemeVariables()),
+    jsFiles: jsFiles.length,
+    cssFiles: cssFiles.length,
+  };
 }
 
 if (import.meta.main) {
@@ -334,11 +445,21 @@ if (import.meta.main) {
     console.error('  Two sorted Tailwind passes were concatenated — cursedbelt ≤ 5.0.x precompiled areas after the app\'s own.');
     console.error('  cursedbelt ≥ 5.1.0 areas are candidates for the app\'s ONE pass: upgrade, and rebuild.');
   }
+  if (result.undefinedVariables.length > 0) {
+    console.error(
+      `✗ ${result.undefinedVariables.length} theme variable(s) the build reads with var() are declared by NO built stylesheet — ` +
+        'each resolves to nothing (a transparent background, an unset size):',
+    );
+    console.error(`    ${result.undefinedVariables.join(' ')}`);
+    console.error('  Tailwind emits a theme variable only when its pass sees it used. cursedbelt ≥ 5.3.0 names every one its');
+    console.error('  components read in styles-areas/core.css — import core, on ≥ 5.3.0. A variable of the app\'s own: name it');
+    console.error('  in a file the app\'s Tailwind pass scans.');
+  }
   if (result.missing.length === 0) {
-    if (result.outOfOrder.length > 0) process.exit(1);
+    if (result.outOfOrder.length > 0 || result.undefinedVariables.length > 0) process.exit(1);
     console.log(
       `✓ belt area styles complete: all ${result.referenced} cursedbelt classes the build references are styled, ` +
-        `and no base utility follows a variant (${result.jsFiles} js, ${result.cssFiles} css).`,
+        `no base utility follows a variant, and every theme variable read is declared (${result.jsFiles} js, ${result.cssFiles} css).`,
     );
     process.exit(0);
   }

package/scripts/generateAreaStyles.ts

@@ -84,7 +84,7 @@
  */
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
 import { classesInCss } from './checkAreaStyles';
-import { UTILITY_INPUT, compileStylesheet } from './generateUtilityStyles';
+import { UTILITY_INPUT, compileStylesheet, themeReadBlock, themeVariablesReadByName } from './generateUtilityStyles';
 import {
 	AREA_DIR,
 	AREAS,
@@ -195,7 +195,7 @@ export const inlineCandidates = async (candidates: readonly string[], area: stri
 	// 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.
+	// prop). It is kept for the proof below, then dropped from what is written — see the return.
 	const kept = writable.filter(
 		(c) => emitted.has(c) || full.includes(`.${cssEscape(c)}`) || (/^--[\w-]+$/.test(c) && full.includes(`${c}:`)),
 	);
@@ -207,7 +207,11 @@ export const inlineCandidates = async (candidates: readonly string[], area: stri
 				'widen the filter rather than lose it.',
 		);
 	}
-	return kept;
+	// …but a `--token` is not WRITTEN: `@source inline` cannot mark a theme variable (tailwindcss
+	// 4.3.3 adds inline candidates without the `--` branch scanned ones take — measured), so one
+	// here would claim a variable the app never gets. `core` carries every one of them instead,
+	// as a `var()` the app's pass does see (`themeReadBlock`, 5.3.0).
+	return kept.filter((c) => !/^--[\w-]+$/.test(c));
 };
 
 /** `CSS.escape` for a class name — what Tailwind writes into a selector. */
@@ -291,6 +295,10 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		raw.set(area.name, await candidatesIn(closures.get(area.name) as Set<string>));
 	}
 
+	// 🔴 The theme variables components read BY NAME go in core, whole: an area is candidates, and
+	// no candidate can make the app's pass emit one (`themeVariablesReadByName` has the measurement).
+	const themeRead = themeReadBlock(await themeVariablesReadByName());
+
 	const built: BuiltArea[] = [];
 	for (const area of AREAS) {
 		const closure = closures.get(area.name) as Set<string>;
@@ -311,7 +319,7 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		}
 		built.push({
 			name: area.name,
-			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}`,
+			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}${area.name === CORE ? themeRead : ''}`,
 			candidates: inline,
 			modules: [...closure].map((f) => f.replace(`${REPO_ROOT}/`, '')).sort(),
 		});

package/scripts/generateUtilityStyles.ts

@@ -58,6 +58,7 @@
 import { compile } from '@tailwindcss/node';
 import { Scanner } from '@tailwindcss/oxide';
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+import { allModules, candidatesIn, nonModuleFiles } from './styleAreas';
 
 export { REPO_ROOT };
 
@@ -124,6 +125,78 @@ export const compileStylesheet = (
 	input: string,
 ): ReturnType<typeof compile> => compile(input, { base: STYLES_BASE, onDependency: noDependency });
 
+// ── Theme variables the components read BY NAME (5.3.0) ─────────────────────────────────
+
+/**
+ * The custom property whose value names every theme variable {@link themeVariablesReadByName}
+ * returns. Nothing reads it; it exists so the app's Tailwind pass sees a `var()` of each.
+ */
+export const THEME_READ_PROPERTY = '--cb-theme-read-by-name';
+
+/** Every theme a consumer imports, and nothing scanned — what decides "Tailwind would prune this". */
+const THEME_PROBE_INPUT = '@import "tailwindcss" source(none);\n@import "./styles-static.css";\n@import "./theme.css";\n';
+
+/** A collapse tripwire, not a ratchet: 9 on the day it was set (tailwindcss 4.3.3). */
+export const MIN_THEME_READ_BY_NAME = 4;
+
+const declaresVariable = (css: string, name: string): boolean =>
+	new RegExp(`(^|[\\s;{])${name.replace(/[-]/g, '\\-')}\\s*:`).test(css);
+
+/**
+ * 🔴 The THEME variables cursedbelt's components read by NAME, which Tailwind emits only when
+ * something in the app's own pass names them.
+ *
+ * `DataTable` sets `--cb-frozen-bg` inline to `var(--color-card)`, `DropIndicator` paints with
+ * `var(--color-accent)`, `focusViewer.css` sizes a caption with `var(--text-caption)`. Tailwind v4
+ * emits a theme variable into `:root` only when it is USED — by a utility, by a `var()` in CSS it
+ * compiles, or by a `--name` token its scanner finds in a source file. The union route scans this
+ * package's tree, so it sees the names; an area is class candidates, so an app on the areas had
+ * NO `--color-card` and station's frozen DataTable column went transparent (F4, 2026-09-23,
+ * `reports/2026-09-23/2026-09-23-f4-station-desk-flix-final-adoption.md`).
+ *
+ * `@source inline("--color-card")` does NOT fix it — measured on tailwindcss 4.3.3: inline
+ * candidates skip the `--` branch the scanner's candidates take, so they mark nothing. A `var()`
+ * in CSS the app's pass compiles does, so {@link themeReadBlock} writes one.
+ *
+ * DERIVED, never listed: every `--token` the scanner finds in a module or hand-written `.css` under
+ * `src/react` that a theme-only compile emits when named and omits when not. A new
+ * `var(--color-ring)` in a component joins the list at the next `bun run build`;
+ * `scripts/checkAreaStyles.ts` is what fails an app build when one is still missing anyway.
+ */
+export const themeVariablesReadByName = async (): Promise<string[]> => {
+	const files = [...allModules(), ...nonModuleFiles().filter((f) => f.endsWith('.css'))];
+	const named = [...(await candidatesIn(files))].filter((c) => /^--[\w-]+$/.test(c)).sort();
+	const bare = (await compileStylesheet(THEME_PROBE_INPUT)).build([]);
+	const marked = (await compileStylesheet(THEME_PROBE_INPUT)).build(named);
+	const pruned = named.filter((v) => declaresVariable(marked, v) && !declaresVariable(bare, v));
+	if (pruned.length < MIN_THEME_READ_BY_NAME) {
+		throw new Error(
+			`only ${pruned.length} theme variable(s) read by name were found (floor ${MIN_THEME_READ_BY_NAME}) — ` +
+				`a collapsed scan of ${files.length} file(s), not a design system that stopped reading them.`,
+		);
+	}
+	return pruned;
+};
+
+/**
+ * The declaration that makes an app's Tailwind pass emit `vars`: one custom property on `:root`
+ * whose value `var()`s each of them. The VALUES stay the theme's, so an app that re-themes a
+ * variable keeps its own; this names them and defines nothing.
+ */
+export const themeReadBlock = (vars: readonly string[]): string => `
+/*
+ * Theme variables cursedbelt's components read BY NAME (\`var(--color-card)\` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a \`var()\` here is
+ * that use — \`@source inline\` cannot mark one. ${vars.length} variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    ${THEME_READ_PROPERTY}: ${vars.map((v) => `var(${v})`).join(' ')};
+  }
+}
+`;
+
 /** The banner the artifact carries, so a reader never mistakes it for a source file. */
 export const BANNER = `/*
  * cursedbelt component utilities — GENERATED BUILD ARTIFACT. Never hand-edit.
@@ -177,7 +250,9 @@ export const buildUtilityStyles = async (): Promise<{ css: string; candidates: s
 				`${STYLES_BASE}/react exists and is not excluded by a .gitignore.`,
 		);
 	}
-	return { css: `${BANNER}${compiled.build(candidates)}`, candidates };
+	// The theme variables components read by name ride along: the pair's consumer scans nothing
+	// of this package either, so it has the areas' hole exactly (see themeVariablesReadByName).
+	return { css: `${BANNER}${compiled.build(candidates)}${themeReadBlock(await themeVariablesReadByName())}`, candidates };
 };
 
 /** The artifact's expected contents and what is on disk right now. */

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/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"]);
+	});
+});