cursedbelt 0.0.0 → 2.3.0

package/src/styles.css

@@ -5,6 +5,33 @@
  *   @import "cursedbelt/theme.css";
  * This `@source` makes Tailwind v4 scan cursedbelt's source files so the utility
  * classes used by its components are generated in the app's stylesheet.
+ *
+ * ── Two entry points, and which one an app wants ─────────────────────────────
+ * `@source "."` is the expensive half: it points Tailwind's JIT at cursedbelt's
+ * ENTIRE source tree, so the app emits the union of the whole design system
+ * (113 KB / 846 selectors, measured in the previous generation) whether it
+ * renders three components or eighty. Everything else in this file is CSS the
+ * components genuinely need and no app can do without.
+ *
+ * A CSS `@import` takes the whole file, so the split is a second subpath:
+ *
+ *   cursedbelt/styles.css         this file — the real CSS + the `@source` scan
+ *   cursedbelt/styles-static.css  the same file MINUS the `@source` line
+ *
+ * The static one is for an app that pays for its own scanning — it gets the
+ * tooltip pointer-events fix, the Progress keyframes, the lightbox bridge, the
+ * ambient/glass layer and `tw-animate-css`, and emits none of cursedbelt's
+ * utility classes, so whatever component utilities it needs must come from
+ * sources IT registers. Do not hand-list cursedbelt's component files to get
+ * them back: a relative `@source` reaching into this package's source tree is a
+ * `file:` dependency wearing a stylesheet's clothes, and it is the thing the
+ * previous generation's 29-line-per-app arrangement is remembered for.
+ *
+ * 🔴 This header is in BOTH files, because one is generated from the other and a
+ * test holds them byte-identical apart from the `@source` line. Always edit
+ * `src/styles.css`; never `src/styles-static.css`, which
+ * `scripts/generateStaticStyles.ts` rewrites on every `bun run build` and
+ * `src/stylesStaticMatches.spec.ts` fails on when it is stale.
  */
 
 /* Animation utilities (animate-in/out, fade/zoom/slide-in-from-*) consumed by the
@@ -16,6 +43,67 @@
 
 @source ".";
 
+/*
+ * Typography utilities (task cbux-41) — theme-token-based replacements for the
+ * `uppercase tracking-wide text-muted-foreground text-xs` / `font-mono bg-…` clusters
+ * that were hand-rolled per call site. One class each, so a future restyle of "how a
+ * section header reads" or "how inline code reads" is a two-rule change here.
+ */
+
+/* Category / section header label: small, bold, uppercase, wide tracking, muted.
+   Use for group headers, panel eyebrows, table section labels — anywhere a
+   "SECTION" style caption sits above real content. */
+.cb-meta-label {
+  /* 🔴 12px, not the 11px this was until 2026-08-19 (unit 11). DESIGN.md §4 states a
+     FLOOR for secondary metadata and this class IS the fleet's section-label style, so
+     11px here was the law being broken by the design system's own stylesheet — in a file
+     the `micro-typography-floor` lint did not scan, because the rule ran over `src/react`
+     only. It scans this file now too. */
+  font-size: 0.75rem; /* 12px */
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--muted-foreground);
+  /* 🔴 NOT `user-select: none`, which this carried until 2026-08-23 (owner report:
+     *"I cannot highlight text on the card"* — the KPI tiles on orch's Insights board).
+     This class is the label of every stat tile, table section and panel eyebrow in the
+     fleet, i.e. the TOP-LEFT of a card and the natural place a drag-select starts.
+     Chrome refuses to begin a selection whose anchor is in an unselectable node, so one
+     declaration here made whole cards feel unselectable even though the value beside the
+     label never was. A label is content — it is what tells you what the number you are
+     copying MEANS — so it is selectable like everything else. Unselectable text belongs
+     on things that are gestures rather than content: a drag handle, a menu item, a
+     slider, a line-number gutter. */
+}
+
+/* Inline/block monospace "code" surface: mono font on the sunken-surface token
+   (never a hardcoded dark-slate box) — used for code snippets, IDs, hashes, and
+   other literal/technical values that want to read as data, not prose. */
+.cb-code {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  font-size: 0.75rem; /* 12px */
+  line-height: 1.5;
+  background-color: var(--surface-sunken);
+  color: var(--foreground);
+  border-radius: var(--radius-sm);
+  padding: 0.5rem 0.625rem;
+}
+
+/* Indeterminate sweep for the Progress bar (no `value`): the 1/3-width fill slides
+   across the track on loop. Registered as a Tailwind theme animation so the
+   `animate-progress-indeterminate` utility is generated in consuming apps. */
+@theme {
+  --animate-progress-indeterminate: progress-indeterminate 1.2s ease-in-out infinite;
+}
+@keyframes progress-indeterminate {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(300%);
+  }
+}
+
 /*
  * Media subsystem (task 19) theme bridge — map the design tokens onto the CSS custom
  * properties of yet-another-react-lightbox so the lightbox reads as part of the app
@@ -25,13 +113,13 @@
  * controls stay light; only the surfaces + accents derive from tokens.
  */
 .yarl__root.yarl__root {
-  --yarl__color_backdrop: color-mix(in srgb, #000 90%, var(--background));
-  --yarl__color_button: rgb(255 255 255 / 0.78);
-  --yarl__color_button_active: #ffffff;
-  --yarl__color_button_disabled: rgb(255 255 255 / 0.35);
+  --yarl__color_backdrop: color-mix(in srgb, #000 90%, var(--background)); /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
+  --yarl__color_button: rgb(255 255 255 / 0.78); /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
+  --yarl__color_button_active: #ffffff; /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
+  --yarl__color_button_disabled: rgb(255 255 255 / 0.35); /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
   --yarl__slide_icon_loading_color: var(--accent);
   --yarl__slide_icon_error_color: var(--destructive);
-  --yarl__counter_color: rgb(255 255 255 / 0.75);
+  --yarl__counter_color: rgb(255 255 255 / 0.75); /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
 
   /* Thumbnails strip → token surfaces + accent active border. */
   --yarl__thumbnails_container_background_color: transparent;
@@ -39,7 +127,7 @@
   --yarl__thumbnails_thumbnail_border_color: var(--border-strong);
   --yarl__thumbnails_thumbnail_active_border_color: var(--accent-solid);
   --yarl__thumbnails_thumbnail_border_radius: var(--radius-md);
-  --yarl__thumbnails_thumbnail_icon_color: #ffffff;
+  --yarl__thumbnails_thumbnail_icon_color: #ffffff; /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
 
   /* Captions → translucent token-tinted bar. */
   --yarl__slide_captions_container_background: color-mix(
@@ -47,6 +135,259 @@
     var(--background) 55%,
     transparent
   );
-  --yarl__slide_title_color: #ffffff;
-  --yarl__slide_description_color: rgb(255 255 255 / 0.8);
+  --yarl__slide_title_color: #ffffff; /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
+  --yarl__slide_description_color: rgb(255 255 255 / 0.8); /* guardrails-ignore no-hardcoded-colors: third-party yarl lightbox library CSS custom properties require literal color values */
+}
+
+/*
+ * Tooltip bubbles are transient hints and must NEVER be pointer targets: a
+ * focus-opened tooltip (e.g. a discard prompt auto-focusing its safe default
+ * button) otherwise hovers over the adjacent control and eats the user's click.
+ * The Content element carries `pointer-events-none`, but Radix positions it inside
+ * a transparent `data-radix-popper-content-wrapper` div that hit-tests on its own,
+ * so the wrapper must be neutralized too — scoped via :has() to tooltip bubbles
+ * only (popovers/menus/selects share the same popper wrapper and stay interactive).
+ */
+[data-radix-popper-content-wrapper]:has(> [data-cb-tooltip]) {
+  pointer-events: none;
+}
+/* !important: when a modal dialog disables body pointer events, Radix's
+   DismissableLayer re-enables the tooltip layer with an INLINE `pointer-events:
+   auto` — exactly the case (tooltip inside an open modal) this rule exists for. */
+[data-cb-tooltip] {
+  pointer-events: none !important;
+}
+
+/*
+ * ══════════════════════════ The ambient / glass layer ══════════════════════════
+ *
+ * The decorative half of the design language, as three plain component classes so
+ * they cost nothing to adopt: a scoped stylesheet gets them through the static
+ * import, with no per-component `@source` line to remember (the silent failure
+ * mode `cursed-satellites/scripts/cssSources.test.ts` exists for).
+ *
+ * All three read TOKENS — `--ambient-1..3`, `--ambient-strength`, `--glass-*`,
+ * `--accent-gradient` (theme.css) — never literals, so an app re-brands its whole
+ * atmosphere by overriding variables and every surface follows. That is the point:
+ * this began life as `.cb-auth-aurora`, a one-off welded to the sign-in card and
+ * to the marketing palette, and could not be reused by anything. Nothing here
+ * knows the word "aurora"; the aurora theme is just the first caller.
+ */
+
+/* ── AmbientBackdrop ─────────────────────────────────────────────────────────
+   The lit field a page floats on: a soft wash from the top plus three big blurred
+   color blobs, screen-blended so they ADD light rather than paint over content.
+   `isolation` on the host is what keeps `mix-blend-mode: screen` blending against
+   this stack instead of punching through to whatever is behind the app. */
+.cb-ambient-host {
+  position: relative;
+  isolation: isolate;
+}
+
+.cb-ambient {
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  overflow: hidden;
+  pointer-events: none;
+  background: radial-gradient(
+    ellipse 120% 60% at 50% -10%,
+    color-mix(in srgb, var(--ambient-2) calc(var(--ambient-strength) * 100%), transparent),
+    transparent 60%
+  );
+}
+
+/* `position: fixed` variant — the backdrop stays put while the app scrolls, which
+   is what makes a long page feel like it sits IN a space rather than on a
+   repeating texture. Separate class rather than a prop-driven inline style so the
+   value stays in CSS with the rest of the layer. */
+.cb-ambient--fixed {
+  position: fixed;
+}
+
+.cb-ambient__blob {
+  position: absolute;
+  border-radius: 999px;
+  /* The blur is what turns three circles into weather. Below ~60px they read as
+     circles; the compositor cost is flat in radius, so this is free. */
+  filter: blur(90px);
+  mix-blend-mode: screen;
+  will-change: transform;
+}
+
+/* Each blob's alpha is `--ambient-strength` scaled by its own weight, so a theme
+   (or the component's `intensity` prop) tunes the whole field with one number and
+   the three hues keep their relative balance. */
+.cb-ambient__blob--a {
+  width: 60vw;
+  height: 60vw;
+  min-width: 460px;
+  min-height: 460px;
+  left: -16vw;
+  top: -20vw;
+  background: radial-gradient(
+    circle at 35% 35%,
+    color-mix(in srgb, var(--ambient-1) calc(var(--ambient-strength) * 200%), transparent),
+    transparent 62%
+  );
+}
+.cb-ambient__blob--b {
+  width: 52vw;
+  height: 52vw;
+  min-width: 420px;
+  min-height: 420px;
+  right: -18vw;
+  top: -12vw;
+  background: radial-gradient(
+    circle at 60% 40%,
+    color-mix(in srgb, var(--ambient-2) calc(var(--ambient-strength) * 215%), transparent),
+    transparent 64%
+  );
+}
+.cb-ambient__blob--c {
+  width: 42vw;
+  height: 42vw;
+  min-width: 360px;
+  min-height: 360px;
+  left: 28vw;
+  bottom: -22vw;
+  background: radial-gradient(
+    circle at 50% 50%,
+    color-mix(in srgb, var(--ambient-3) calc(var(--ambient-strength) * 100%), transparent),
+    transparent 62%
+  );
+}
+
+/* Drift only when the visitor hasn't asked for reduced motion. Minute-scale
+   periods, all mutually prime-ish, so the field never visibly loops. */
+@media (prefers-reduced-motion: no-preference) {
+  .cb-ambient__blob--a {
+    animation: cb-ambient-drift-a 46s ease-in-out infinite alternate;
+  }
+  .cb-ambient__blob--b {
+    animation: cb-ambient-drift-b 58s ease-in-out infinite alternate;
+  }
+  .cb-ambient__blob--c {
+    animation: cb-ambient-drift-c 70s ease-in-out infinite alternate;
+  }
+}
+@keyframes cb-ambient-drift-a {
+  from { transform: translate3d(0, 0, 0) scale(1); }
+  to { transform: translate3d(6vw, 5vh, 0) scale(1.12); }
+}
+@keyframes cb-ambient-drift-b {
+  from { transform: translate3d(0, 0, 0) scale(1.08); }
+  to { transform: translate3d(-5vw, 6vh, 0) scale(0.96); }
+}
+@keyframes cb-ambient-drift-c {
+  from { transform: translate3d(0, 0, 0); }
+  to { transform: translate3d(8vw, -4vh, 0); }
+}
+
+/* Fine grain over the whole field. Big soft gradients BAND on 8-bit displays —
+   this is the standard dither, and it is an inline SVG so it costs no request. */
+.cb-ambient__grain {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  opacity: 0.045;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2'/%3E%3C/filter%3E%3Crect width='160' height='160' filter='url(%23n)' opacity='0.6'/%3E%3C/svg%3E");
+}
+
+/* ── Glass ───────────────────────────────────────────────────────────────────
+   `Surface level="glass"`. A translucent fill, a 1px light edge and a backdrop
+   blur, so the ambient field reads THROUGH the panel. In the default LIGHT theme
+   the fill is a near-opaque white frost — glass over white is white — so a glass
+   Surface is never a legibility regression on an app that never opted into a
+   theme. `backdrop-filter` degrades to a plain translucent fill where it is
+   unsupported, which is the correct failure. */
+.cb-glass {
+  background: var(--glass-bg);
+  border: 1px solid var(--glass-edge);
+  box-shadow: var(--glass-shadow);
+  backdrop-filter: blur(var(--glass-blur)) saturate(140%);
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(140%);
+}
+
+/* Chrome glass: the fill + blur ONLY — no edge, no shadow. For app chrome that owns
+   its own directional border (a header's `border-b`, a nav rail's `border-r`); the
+   full `.cb-glass` would draw a box around it. */
+.cb-glass-chrome {
+  background: var(--glass-bg-strong);
+  backdrop-filter: blur(var(--glass-blur)) saturate(140%);
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(140%);
+}
+
+/* The heavier fill, for a surface that has to hold dense text (a sidebar, a
+   sticky header) where maximum see-through would cost legibility. */
+.cb-glass-strong {
+  background: var(--glass-bg-strong);
+  border: 1px solid var(--glass-edge);
+  box-shadow: var(--glass-shadow);
+  backdrop-filter: blur(var(--glass-blur)) saturate(140%);
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(140%);
+}
+
+/* ── Brand gradient ──────────────────────────────────────────────────────────
+   Text in the accent ramp (a product wordmark, a hero headline). Deliberately NOT
+   offered for body copy: gradient text has no single contrast ratio to audit. */
+.cb-gradient-text {
+  background: var(--accent-gradient);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+/* A filled surface in the accent ramp — the "this is the one action" treatment.
+   The `.cb-gradient-fill` class carries its own white label because a gradient
+   has no token to derive an on-fill foreground from; every ramp this is used with
+   is saturated enough for white to clear AA (the same contract
+   `--accent-solid-foreground` makes for the flat solid). */
+.cb-gradient-fill {
+  background: var(--accent-gradient);
+  color: #ffffff; /* guardrails-ignore no-hardcoded-colors: white label on the saturated accent gradient — the fill's own on-surface foreground, mode-independent by the same contract as --accent-solid-foreground */
+  border: 0;
+  transition:
+    filter var(--duration-fast, 120ms) ease,
+    box-shadow var(--duration-fast, 120ms) ease;
+}
+.cb-gradient-fill:hover:not(:disabled) {
+  background: var(--accent-gradient);
+  filter: brightness(1.08);
+}
+
+/*
+ * Aurora front door — the logged-out sign-in / register surface.
+ *
+ * Now just a THIN composition over the layer above: the aurora theme scope
+ * (`.cb-aurora` in theme.css) supplies the palette, `AmbientBackdrop` paints the
+ * field, `Surface level="glass"` is the card, `.cb-gradient-text` is the title.
+ * What remains here is the two things that are genuinely about this surface: it
+ * fills the viewport with the canvas color, and its submit button is the
+ * gradient action. Scoped under `.cb-auth-aurora` (AuthCard's `aurora` prop) so
+ * the product's own in-app chrome — including the EMBEDDED AuthCard in the
+ * account panel — is untouched.
+ */
+.cb-auth-aurora {
+  position: relative;
+  isolation: isolate;
+  background-color: var(--background);
+  color: var(--foreground);
+  overflow: hidden;
+}
+
+/* Primary action carries the accent gradient instead of the flat solid.
+   Specificity (one class + the attribute-qualified element) clears Tailwind's
+   single-class `bg-accent-solid`. */
+.cb-auth-aurora button[type="submit"] {
+  background: var(--accent-gradient);
+  color: #ffffff; /* guardrails-ignore no-hardcoded-colors: white label on the saturated accent gradient — the button's own on-fill foreground, mode-independent */
+  border: 0;
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--ambient-1) 20%, transparent);
+  transition: filter var(--duration-fast, 120ms) ease, box-shadow var(--duration-fast, 120ms) ease;
+}
+.cb-auth-aurora button[type="submit"]:hover:not(:disabled) {
+  background: var(--accent-gradient);
+  filter: brightness(1.08);
+  box-shadow: 0 10px 28px color-mix(in srgb, var(--ambient-2) 30%, transparent);
 }

package/src/stylesStaticMatches.spec.ts

@@ -0,0 +1,134 @@
+/**
+ * `src/styles-static.css` is `src/styles.css` minus its `@source` line — and
+ * nothing else (2026-09-14).
+ *
+ * ## What this exists to prevent
+ *
+ * The scoped entry point has to be a SECOND FILE, because a CSS `@import` takes
+ * the whole of the one it is given: an app cannot ask for `styles.css` without
+ * `@source "."`, and `@source "."` is what makes every consumer emit the union
+ * of the entire design system.
+ *
+ * The previous generation's second file was `satellite-kit/styles/belt-static.css`
+ * — a hand-kept copy with the one line deleted and nothing comparing the two.
+ * That is a file that drifts, and drifts SILENTLY: the day someone adds a rule to
+ * `styles.css` and not to the copy, every scoped app quietly loses it. The loss is
+ * invisible in review (the diff looks complete), invisible to `tsc` (it is CSS),
+ * and invisible to Biome (nothing is wrong with either file). It shows up as a
+ * tooltip eating a click, or a Progress bar that never animates, in one app, weeks
+ * later.
+ *
+ * So the copy is OUTPUT — `scripts/generateStaticStyles.ts`, which `bun run build`
+ * runs before it compiles — and this spec is the gate that makes that true rather
+ * than merely intended. `bun run verify` builds before it tests, so a forgotten
+ * regeneration self-heals there; editing `styles.css` and running `bun test src`
+ * alone is where this goes red.
+ *
+ * The assertions deliberately come at it from both sides: one compares the file on
+ * disk to what the generator produces (is the checked-in output current?), and the
+ * rest compare it to `styles.css` DIRECTLY (is the generator still doing only what
+ * it claims?). A spec that only asked the generator to agree with itself would pass
+ * a generator that had started dropping real rules.
+ *
+ * 🔴 `Bun.file`, NOT node:fs — this package's test preload virtualizes node:fs, so
+ * a `readFileSync` here would read MOCK data and pass against files it never
+ * opened. Same trap as `src/publishShape.spec.ts`; see its header.
+ */
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+import {
+	REPO_ROOT,
+	SOURCE_DIRECTIVE,
+	STATIC_STYLESHEET,
+	readStylesheets,
+	staticStylesFrom,
+} from '../scripts/generateStaticStyles';
+
+const { source, expected, onDisk } = await readStylesheets();
+
+/** The command every failure below is fixed by, as a line the owner can paste. */
+const REGENERATE = `cd ${REPO_ROOT} && bun run styles:static`;
+
+const lines = (css: string): string[] => css.split('\n');
+const directives = (css: string): string[] => lines(css).filter((l) => SOURCE_DIRECTIVE.test(l));
+
+describe('styles-static.css is a generated, gated copy of styles.css', () => {
+	it('is checked in and byte-identical to what the generator produces', () => {
+		expect(onDisk, `${STATIC_STYLESHEET} is missing. It is generated:\n  ${REGENERATE}`).not.toBeNull();
+		expect(
+			onDisk,
+			`${STATIC_STYLESHEET} is stale — src/styles.css changed and the static variant was not\n` +
+				'regenerated, so every app importing `cursedbelt/styles-static.css` is missing the\n' +
+				`difference. Run:\n  ${REGENERATE}`,
+		).toBe(expected);
+	});
+
+	it('drops the `@source` line and keeps every other line, in order', () => {
+		// The independent half: compared against styles.css itself, not against the
+		// generator's output. Blank lines are excluded from the sequence check only
+		// because the dropped directive takes its trailing blank line with it; the
+		// exact line-count assertion below is what pins that down.
+		const kept = lines(source).filter((l) => l.trim() !== '' && !SOURCE_DIRECTIVE.test(l));
+		expect(lines(expected).filter((l) => l.trim() !== '')).toEqual(kept);
+	});
+
+	it('removes exactly the directive and the blank line it leaves behind', () => {
+		expect(
+			directives(source),
+			'src/styles.css must carry exactly the one `@source "."` this whole split is about',
+		).toEqual(['@source ".";']);
+		expect(directives(expected), 'the static variant must carry no `@source` at all').toEqual([]);
+		// 2 = the directive + the now-orphaned blank line after it. A third line
+		// going missing means the transform grew a second job.
+		expect(lines(source).length - lines(expected).length).toBe(2);
+	});
+
+	it('is not a pointless duplicate', () => {
+		// If `@source "."` ever leaves styles.css, the two files become identical and
+		// the static subpath is dead weight — but worse, the FULL entry point has
+		// stopped scanning and every consuming app emits no cursedbelt utilities.
+		expect(expected).not.toBe(source);
+	});
+
+	it('is exported as a subpath that resolves into a directory `files` ships', () => {
+		const exports = (pkg as { exports: Record<string, unknown> }).exports;
+		expect(exports['./styles-static.css']).toBe(`./${STATIC_STYLESHEET}`);
+		// It must resolve out of `src/`, exactly like its sibling: `./styles.css`
+		// points at the SOURCE tree (not dist) because `@source "."` has to resolve
+		// relative to the files it is meant to scan, and a pair of app-facing
+		// stylesheets served from two different directories is a difference nobody
+		// can see in CSS.
+		expect(exports['./styles.css']).toBe('./src/styles.css');
+		// `files` ships whole directories, so `src` is what actually puts both of
+		// them in the tarball. publishShape.spec.ts proves the general rule; this is
+		// the one line that makes THIS subpath's failure legible.
+		expect((pkg as { files: string[] }).files).toContain('src');
+	});
+
+	it('resolves as `cursedbelt/styles-static.css` through the real resolver', () => {
+		// The assertions above read the manifest; this one RESOLVES the specifier the
+		// way a consumer's bundler does, through the package's own `exports` map (bun
+		// honours a self-reference by package name). An export entry pointing at a
+		// path that does not exist satisfies every string comparison in this file and
+		// fails here — which is the failure `belt-static.css` would have been.
+		expect(Bun.resolveSync(`${pkg.name}/styles-static.css`, REPO_ROOT)).toBe(
+			`${REPO_ROOT}/${STATIC_STYLESHEET}`,
+		);
+	});
+
+	it('is regenerated by the build, so a stale copy cannot be published', () => {
+		// `prepublishOnly` → `verify` → `build`, so the tarball's copy is always the
+		// one this repo's current styles.css produces. Without this step in `build`,
+		// the only thing standing between a drifted copy and a publish is a person
+		// remembering to run a script.
+		expect((pkg as { scripts: Record<string, string> }).scripts.build).toContain(
+			'scripts/generateStaticStyles.ts',
+		);
+	});
+
+	it('exposes the transform as a pure function', () => {
+		// Cheap guard on the one behaviour every assertion above leans on.
+		expect(staticStylesFrom('a\n@source ".";\n\nb\n')).toBe('a\nb\n');
+		expect(staticStylesFrom('a\nb\n')).toBe('a\nb\n');
+	});
+});

package/src/tapTargetStylesheet.spec.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'bun:test';
+import { Scanner } from '@tailwindcss/oxide';
+import { compile } from 'tailwindcss';
+import {
+	TAP_TARGET,
+	TAP_TARGET_ALWAYS,
+	TAP_TARGET_HALO,
+	TAP_TARGET_HEIGHT,
+	TAP_TARGET_SQUARE,
+} from './react/lib/tapTarget';
+
+/**
+ * 🔴 THE TAP FLOOR SURVIVES THE JIT.
+ *
+ * `src/react/lib/tapTarget.ts` collapsed 48 hand-written copies of `DESIGN.md`
+ * §5's 44px floor — and 12 of the hover-reveal fix that goes with it — into five
+ * constants. That refactor has one failure mode, and it is silent: **Tailwind's
+ * JIT scans source TEXT, it does not evaluate code.** A
+ * class that stops being a literal inside this package's own `@source "."` glob —
+ * moved to a file the glob does not cover, assembled from a variable, split
+ * across a template it cannot read — is a class Tailwind never emits. Nothing
+ * reds. The types are fine, the build is fine, every component still carries the
+ * class name in its `className`, and the rule it names simply does not exist in
+ * the stylesheet any more. Every tap target on every phone in the fleet quietly
+ * loses its floor.
+ *
+ * So this compiles the REAL `src/styles.css` — its own `@source` directive, its
+ * own scan of this package's tree, Tailwind's own candidate extractor — and
+ * asserts the emitted CSS still carries a rule for every utility the constants
+ * name. It is the one check that can tell "the constant is exported" apart from
+ * "the constant does anything".
+ *
+ * 🔴 NOTHING IN THIS FILE MAY SPELL A TAP UTILITY OUT. The `@source` glob covers
+ * `src/`, and a spec is source: the first draft of this header quoted the height
+ * class in its own prose, and that comment alone kept the class in the candidate
+ * set after the constant had been broken. The check passed against a stylesheet
+ * held up by a sentence about the check. Utilities come from the imports above
+ * and from nowhere else in here.
+ *
+ * Verified failing, 2026-09-14, before it was trusted — each probe applied,
+ * observed and removed again:
+ *   · `TAP_TARGET_HEIGHT` rewritten as a template that interpolates its `11`
+ *       → both the extraction test and "utilities the emitted stylesheet has no
+ *         rule for: <the height class>". `TAP_TARGET` composes the same constant,
+ *         so every button in the package loses the floor from this one edit.
+ *   · `TAP_TARGET_HEIGHT` truncated to its scale-less prefix (the trailing `11`
+ *     dropped) → same failure, which is the anchored-selector half. A plain
+ *     `includes()` would have PASSED this one: the truncated name is a substring
+ *     of the rule the untruncated class emits elsewhere in the same stylesheet.
+ *     🔴 Truncating by one DIGIT instead does not fail, and should not — the
+ *     result is another real Tailwind utility with a real rule; what would be
+ *     broken there is the design, not the pipeline this file measures.
+ *   · the `@source` line removed from `src/styles.css` → "scanned no candidates",
+ *     the guard below that stops every other assertion passing vacuously.
+ *
+ * ~1.5s: one Tailwind compile of ~118 KB over ~25k candidates.
+ */
+
+const REPO_ROOT = import.meta.dir.replace(/\/src$/, '');
+
+/** Directory half of an absolute path — `node:path` is virtualized by the test preload. */
+const dirOf = (path: string): string => path.slice(0, path.lastIndexOf('/'));
+
+/**
+ * Resolve a CSS `@import` the way a bundler would.
+ *
+ * 🔴 `Bun.file`, never `node:fs`: this package's test preload virtualizes node
+ * builtins, so a `readFileSync` here would read MOCK data and the whole
+ * measurement would be of nothing (same trap as `publishShape.spec.ts`). A CSS
+ * package announces its entry through the `style` condition, not `main`.
+ */
+const loadStylesheet = async (
+	id: string,
+	base: string,
+): Promise<{ path: string; base: string; content: string }> => {
+	const read = async (path: string) => ({
+		path,
+		base: dirOf(path),
+		content: await Bun.file(path).text(),
+	});
+	if (id.startsWith('.')) return read(`${base}/${id}`);
+	const packageDir = `${REPO_ROOT}/node_modules/${id}`;
+	const manifest = (await Bun.file(`${packageDir}/package.json`).json()) as {
+		exports?: { '.'?: { style?: string } };
+		style?: string;
+		main?: string;
+	};
+	const entry = manifest.exports?.['.']?.style ?? manifest.style ?? manifest.main;
+	if (!entry) throw new Error(`no stylesheet entry for "${id}"`);
+	return read(`${packageDir}/${entry.replace(/^\.\//, '')}`);
+};
+
+/** Every utility the five constants name, deduped — the thing that must survive. */
+const UTILITIES = [
+	...new Set(
+		[TAP_TARGET_HEIGHT, TAP_TARGET, TAP_TARGET_SQUARE, TAP_TARGET_HALO, TAP_TARGET_ALWAYS]
+			.join(' ')
+			.split(/\s+/)
+			.filter(Boolean),
+	),
+];
+
+const emitted = await (async () => {
+	// An app imports Tailwind first, then this package's stylesheet — exactly the
+	// two lines `src/styles.css`'s own header tells a consumer to write.
+	const source = await Bun.file(`${REPO_ROOT}/src/styles.css`).text();
+	const compiler = await compile(`@import "tailwindcss";\n${source}`, {
+		base: `${REPO_ROOT}/src`,
+		loadStylesheet,
+	});
+	const candidates = new Scanner({ sources: compiler.sources }).scan();
+	return { candidates, css: compiler.build(candidates) };
+})();
+
+describe('the tap floor reaches the stylesheet', () => {
+	it('scanned this package for candidates at all', () => {
+		// Guards every assertion below: with no `@source` directive the scan returns
+		// nothing, `build([])` emits no utilities, and "the rule is missing" would be
+		// indistinguishable from "the refactor broke it".
+		expect(emitted.candidates.length).toBeGreaterThan(1000);
+	});
+
+	it('names utilities Tailwind actually extracted from the source text', () => {
+		// The JIT half: each class is a literal in a file the `@source` glob covers.
+		expect(UTILITIES.filter((u) => !emitted.candidates.includes(u))).toEqual([]);
+	});
+
+	it('emits a CSS rule for every utility the tap-target constants name', () => {
+		// A `:` is backslash-escaped inside a selector, so the class `a:b` is written
+		// `.a\:b` in the output — and a candidate that survived extraction but
+		// generated no rule (a utility Tailwind does not know) still fails here.
+		//
+		// 🔴 Anchored on the END of the class name, not a substring: a class truncated
+		// by one character is a prefix of the rule its untruncated self emits, so a
+		// plain `includes()` would have found it in a stylesheet that never had it.
+		const missing = UTILITIES.filter((u) => {
+			// The utility → its escaped selector text → a regex matching that text, with
+			// the CSS backslash itself escaped a second time for the regex.
+			const selectorText = `.${u.replace(/:/g, '\\:')}`;
+			const anchored = new RegExp(
+				`${selectorText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w\\\\-])`,
+			);
+			return !anchored.test(emitted.css);
+		});
+		expect(
+			missing,
+			`utilities the emitted stylesheet has no rule for: ${missing.join(', ')}`,
+		).toEqual([]);
+	});
+});