cursedbelt 1.0.0 → 2.3.0

package/src/react/file-tree/fileTreeGeometry.spec.ts

@@ -4,30 +4,38 @@
  * ── Why a test reads a stylesheet ───────────────────────────────────────────────────────
  * Owner, 2026-09-10: *"We have two sidenav components now. I need updates and we need them
  * in two places because of the copying."* The two are this one and
- * `cursed-embeddable-spreadsheet`'s, and they cannot be merged into one — cb is `private`
- * and unpublished while ces ships on npm, and cb's tree is a deliberate generalisation that
- * has fewer features than ces's, not the same ones. The full reasoning is in the spec file
- * this reads.
+ * `cursed-embeddable-spreadsheet`'s, and they cannot be merged into one — the two ship as
+ * separate published packages, and cb's tree is a deliberate generalisation that has fewer
+ * features than ces's, not the same ones. The full reasoning is in the spec file this reads.
  *
  * So the design is shared and the code is not, and this is the seam that keeps the design
- * shared: **a number changed here without being changed there fails on the next run**,
- * rather than being noticed by eye some months later. Its twin is
+ * shared: **a number changed here without being changed in the design file fails on the next
+ * run**, rather than being noticed by eye some months later. Its twin is
  * `test/ui/tree-geometry.test.ts` over in the spreadsheet.
  *
- * 🔴 The INVARIANTS are asserted unconditionally and the shared numbers only when the fleet
- * checkout is readable. That split is deliberate: the relationships below are properties of
- * this stylesheet alone and must hold in a clone with no fleet beside it, while cross-repo
- * agreement is a fact about this machine.
+ * 🔴 EVERY assertion here runs unconditionally, on any machine. Until 2026-09-13 the shared
+ * numbers were read out of a checkout in the owner's home directory and SKIPPED when it was
+ * missing — in a package that is published to npm. That is a test that passes for one person
+ * and quietly does nothing for everybody else, which is worse than no test: half this file
+ * would have been inert for every installer. The design now lives in
+ * `fileTreeGeometry.fixture.json`, committed beside this spec, and nothing is conditional.
  */
 import { describe, expect, it } from 'bun:test';
 import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { flattenFileTree } from '../../core/file-tree/fileTreeModel';
 
 const CSS = readFileSync(join(import.meta.dir, 'fileTree.css'), 'utf8');
 
-const SPEC_PATH = join(homedir(), '.app-managed/repos/fleet/standards/file-tree-geometry.json');
+/**
+ * The shared design, committed in this repo. Read once — a published package's suite may not
+ * depend on a directory outside its own checkout.
+ */
+const DESIGN = JSON.parse(readFileSync(join(import.meta.dir, 'fileTreeGeometry.fixture.json'), 'utf8')) as {
+  geometry: Record<string, number>;
+  scrollbar: { width: number; thumbInset: number };
+  behaviour: Record<string, { value: boolean }>;
+};
 
 /**
  * A token's value in px, resolved one level through `var()` and `calc(a / 2)`.
@@ -141,15 +149,6 @@ describe('the file tree geometry', () => {
     expect(CSS.indexOf('-webkit-font-smoothing')).toBeGreaterThan(CSS.indexOf(':where(.dark) .cbft {'));
   });
 
-  /*
-   * ── The cross-repo half ───────────────────────────────────────────────────────────────
-   *
-   * Skipped rather than failed when fleet is not beside this checkout, because a clone
-   * without it is a legitimate state and a red suite there would teach people to ignore this
-   * file. On this machine it is the whole point: it is what makes "update it in two places"
-   * something the machine reports instead of something a person has to remember.
-   */
-
   /*
    * ── The shared BEHAVIOUR, not just the numbers ────────────────────────────────────────
    *
@@ -157,26 +156,24 @@ describe('the file tree geometry', () => {
    * never against itself. A test that read `true` out of the JSON and then asserted `true`
    * would pass on a tree that does neither thing — it would gate nothing while looking
    * exactly like a gate. So the flag is the CONDITION and the behaviour is the assertion:
-   * flip the flag in fleet and this suite reds until the code here follows it.
+   * flip the flag in the design file and this suite reds until the code here follows it.
    */
-  const behaviour = (): Record<string, { value: boolean }> | null => {
-    try {
-      return JSON.parse(readFileSync(SPEC_PATH, 'utf8')).behaviour;
-    } catch {
-      return null; // no fleet checkout here — see above
-    }
-  };
+  it('declares every behaviour flag this suite asserts against', () => {
+    // The fixture is the CONDITION for the two tests below, so a missing key would turn
+    // each of them into a silent pass — the exact failure mode that vendoring it fixed.
+    expect(Object.keys(DESIGN.behaviour).sort()).toEqual(
+      ['$comment', 'everyFolderDrawsATwisty', 'mediaRowDrawsItsThumbnail'].sort(),
+    );
+  });
 
   it('draws a twisty on EVERY folder, empty ones included, as the shared design declares', () => {
-    const declared = behaviour()?.everyFolderDrawsATwisty;
-    if (!declared) return;
+    const declared = DESIGN.behaviour.everyFolderDrawsATwisty!;
     const rows = flattenFileTree([{ id: 'empty', name: 'Empty', kind: 'folder', children: [] }], []);
     expect(rows[0]!.expandable).toBe(declared.value);
   });
 
   it('gives a media row a thumbnail slot, as the shared design declares', () => {
-    const declared = behaviour()?.mediaRowDrawsItsThumbnail;
-    if (!declared) return;
+    const declared = DESIGN.behaviour.mediaRowDrawsItsThumbnail!;
     // The three constraints the shared file names, each asserted where it lives:
     //   · one glyph box, never a second track — the box is `--cbft-glyph` wide either way;
     //   · the row height does not move — `.cbft-thumb` declares no height of its own beyond it;
@@ -212,17 +209,8 @@ describe('the file tree geometry', () => {
    * Both APIs are required rather than interchangeable: `scrollbar-width` is the standard
    * property and the `::-webkit-` rules are what Safari and older Chrome read.
    */
-  const scrollbar = (): { width: number; thumbInset: number } | null => {
-    try {
-      return JSON.parse(readFileSync(SPEC_PATH, 'utf8')).scrollbar;
-    } catch {
-      return null; // no fleet checkout here — see above
-    }
-  };
-
   it('draws a very thin gutter, at the width the shared design names', () => {
-    const width = scrollbar()?.width;
-    if (width === undefined) return;
+    const width = DESIGN.scrollbar.width;
     // The standard property first — a stylesheet with only the `-webkit-` half is thin in
     // Firefox and fat in Safari, or the other way round, depending which half went missing.
     expect(CSS).toContain('scrollbar-width: thin;');
@@ -231,9 +219,7 @@ describe('the file tree geometry', () => {
   });
 
   it('keeps the marker FLUSH with the edge — no border, no margin on the thumb', () => {
-    const inset = scrollbar()?.thumbInset;
-    if (inset === undefined) return;
-    expect(inset).toBe(0);
+    expect(DESIGN.scrollbar.thumbInset).toBe(0);
     const thumb = CSS.slice(
       CSS.indexOf('.cbft-scroll::-webkit-scrollbar-thumb {'),
       CSS.indexOf('.cbft-scroll::-webkit-scrollbar-thumb:hover'),
@@ -261,12 +247,7 @@ describe('the file tree geometry', () => {
   });
 
   it('agrees with the shared design the spreadsheet also implements', () => {
-    let spec: { geometry: Record<string, number> };
-    try {
-      spec = JSON.parse(readFileSync(SPEC_PATH, 'utf8'));
-    } catch {
-      return; // no fleet checkout here — see above
-    }
+    const spec = DESIGN;
     expect({
       row: token('cbft-row'),
       pad: token('cbft-pad'),

package/src/react/filter-rail/FilterRail.spec.tsx

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, test } from 'bun:test';
 import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
 import { FilterRail, type FilterRailSection } from './FilterRail';
 import { hoverHint } from '../../testing/tooltip';
+import { TAP_TARGET_ALWAYS } from '../lib/tapTarget';
 
 afterEach(cleanup);
 
@@ -331,7 +332,7 @@ describe('FilterRail — rows that are more than a choice', () => {
     expect(shelf?.className).toContain('group-hover/rail-row:opacity-100');
     expect(shelf?.className).toContain('group-focus-within/rail-row:opacity-100');
     // A phone has no hover at all; without this the control is unreachable by any gesture.
-    expect(shelf?.className).toContain('pointer-coarse:opacity-100');
+    expect(shelf?.className).toContain(TAP_TARGET_ALWAYS);
     // DESIGN.md §5 — a row control is a real tap target, whatever glyph the host put in it.
     expect(shelf?.className).toContain('pointer-coarse:[&_button]:min-h-11');
   });

package/src/react/filter-rail/FilterRail.tsx

@@ -3,6 +3,7 @@ import type { DragEvent, ReactNode } from 'react';
 import { ScrollArea } from '../components/ScrollArea';
 import { cn } from '../lib/cn';
 import { Tooltip } from '../components/Tooltip';
+import { TAP_TARGET, TAP_TARGET_ALWAYS, TAP_TARGET_HEIGHT } from '../lib/tapTarget';
 
 export interface FilterRailItem {
   /** Stable key, and the value handed to `onSelect`. */
@@ -260,7 +261,7 @@ export function FilterRail({
               onClick={() => onCollapsedChange(!collapsed)}
               aria-label={collapsed ? `Expand ${label}` : `Collapse ${label}`}
               aria-expanded={!collapsed}
-              className='grid size-8 place-items-center rounded-md text-muted-foreground transition-colors hover:bg-card-raised hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring pointer-coarse:min-h-11 pointer-coarse:min-w-11 [&_svg]:size-4'
+              className={`grid size-8 place-items-center rounded-md text-muted-foreground transition-colors hover:bg-card-raised hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${TAP_TARGET} [&_svg]:size-4`}
             >
               {collapsed ? <ChevronsRight /> : <ChevronsLeft />}
             </button>
@@ -387,7 +388,7 @@ function FilterRailRow({
             <span
               data-cb-rail-tools={active ? 'solid' : 'quiet'}
               className={cn(
-                'flex shrink-0 items-center gap-px transition-opacity pointer-coarse:opacity-100',
+                `flex shrink-0 items-center gap-px transition-opacity ${TAP_TARGET_ALWAYS}`,
                 // 🔴 A rail row is DENSE, and the shelf is now always visible, so its width
                 // comes straight out of the label's. Measured at 14rem with three tools at
                 // the `sm` control height (32px each): `screencaps` rendered as ":" and a
@@ -486,8 +487,8 @@ function FilterRailButton({
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
           // 44px touch floor on coarse pointers only, so the dense desktop rail stays dense.
           collapsed
-            ? 'size-10 justify-center pointer-coarse:min-h-11 pointer-coarse:min-w-11'
-            : 'px-2.5 py-1.5 pointer-coarse:min-h-11',
+            ? `size-10 justify-center ${TAP_TARGET}`
+            : `px-2.5 py-1.5 ${TAP_TARGET_HEIGHT}`,
           item.disabled && 'cursor-not-allowed opacity-50',
           // 🔴 THREE states, TWO channels — see the component doc. Hover gets a real
           // background rather than a suggestion of one; active steps up again AND takes the

package/src/react/folder-tree/FolderTreeRail.tsx

@@ -33,6 +33,7 @@ import type { FolderNode } from "../../core/folder-tree/tree";
 import { isRowDrag, readRowDrag, type RowDragPayload } from "../components/DataTable/rowDrag";
 import { Tooltip } from '../components/Tooltip';
 import { NewFolderControl } from './NewFolderControl';
+import { TAP_TARGET_HEIGHT } from "../lib/tapTarget";
 
 export interface FolderTreeRailProps {
 	nodes: readonly FolderNode[];
@@ -167,7 +168,7 @@ export function FolderTreeRail({
 							aria-expanded={open}
 							// `pointer-coarse:` only — see FilterRail's twisty for why a finger-sized
 							// box everywhere would re-indent the whole tree for a mouse.
-							className="w-4 shrink-0 self-stretch text-[var(--muted-foreground)] pointer-coarse:min-h-11 pointer-coarse:w-11"
+							className={`w-4 shrink-0 self-stretch text-[var(--muted-foreground)] ${TAP_TARGET_HEIGHT} pointer-coarse:w-11`}
 							onClick={() => toggle(node)}
 						>
 							{open ? "▾" : "▸"}

package/src/react/index.ts

@@ -217,9 +217,6 @@ export {
   EMPTY_FILTER_QUERY,
   evaluateFilterQuery,
   FILTER_OP_LABELS,
-  FilterBuilder,
-  type FilterBuilderColumn,
-  type FilterBuilderProps,
   type FilterCondition,
   type FilterGroup,
   type FilterOp,
@@ -255,6 +252,9 @@ export {
   SortHeader,
   type SortHeaderProps,
   setAssetUrlResolver,
+  TableFilterBuilder,
+  type TableFilterBuilderColumn,
+  type TableFilterBuilderProps,
   TablePagination,
   type TablePaginationProps,
   TableToolbar,
@@ -765,6 +765,16 @@ export { makeFormConfig } from './lib/form';
  *  writing a literal delay; `no-fast-tooltip` fails a build on a smaller one. */
 export { HOVER_HINT_DELAY_MS, HOVER_HINT_INSTANT_MS } from './lib/hoverIntent';
 export { createPersistedStore } from './lib/store';
+/** `DESIGN.md` §5's 44px tap floor, as the four class strings it actually takes —
+ *  import these rather than writing `pointer-coarse:` utilities by hand, so the floor
+ *  moves once when it moves. See `react/lib/tapTarget.ts` for which shape is which. */
+export {
+  TAP_TARGET,
+  TAP_TARGET_ALWAYS,
+  TAP_TARGET_HALO,
+  TAP_TARGET_HEIGHT,
+  TAP_TARGET_SQUARE,
+} from './lib/tapTarget';
 export * from './nav';
 export * from './palette';
 export * from './prompt';

package/src/react/layoutEngine/index.ts

@@ -1,6 +1,6 @@
 // cursedbelt layout engine (React) — the read-only renderer + the from-scratch
 // WYSIWYG drag editor (canvas, inspector, palette, dialog) for the
-// `cursedbelt/layout` model. Generic over the app's field type; the app supplies a
+// `cwip/layout` model (re-exported at `src/core/layout`). Generic over the app's field type; the app supplies a
 // widget registry (how each node type renders) + optionally a custom binding
 // resolver. Built on the design-system primitives (Surface/Grid, Modal/Drawer,
 // Collapsible) and @atlaskit/pragmatic-drag-and-drop. Exported as part of `cursedbelt/react`.

package/src/react/layoutEngine/types.ts

@@ -9,7 +9,7 @@ import type {
 } from '../../core/layout';
 
 // The React widget contract for the layout engine. The pure model + binding
-// resolution live in `cursedbelt/layout`; this adds the rendering + editing side.
+// resolution live in `cwip/layout` (re-exported at `src/core/layout`); this adds the rendering + editing side.
 // Everything is generic over the app's field type `F` (which must extend
 // `LayoutField`), so an app keeps its full column type inside `render`.
 

package/src/react/lib/field.ts

@@ -1,3 +1,5 @@
+import { TAP_TARGET_HEIGHT } from './tapTarget';
+
 /**
  * The single field-control class — driven ENTIRELY by the `--field-*` token layer
  * (see theme.css), so restyling every form control app-wide is a one-block change.
@@ -54,11 +56,11 @@ export const CONTROL_MIN_HEIGHT_CLASS: Record<ControlSize, string> = {
  * line up on the same baseline as every other control at the same `size`.
  */
 export function fieldControlClass(size: ControlSize = 'md'): string {
-  // `pointer-coarse:min-h-11` — the `sm`/`md` tokens (32px/36px) clear a mouse
+  // `TAP_TARGET_HEIGHT` — the `sm`/`md` tokens (32px/36px) clear a mouse
   // pointer's norms but fall short of the 44px WCAG/HIG touch-target floor; widen
   // only on coarse pointers, same pattern as Button (owner orch-host 390px
   // teardown — the orchChat composer's task-type SelectField trigger measured
   // 356×32). Every `fieldControlClass` consumer (Input, SelectField, Date,
   // Combobox, …) inherits the fix for free.
-  return `w-full rounded-field border border-field-border bg-field-bg px-3 ${CONTROL_HEIGHT_CLASS[size]} pointer-coarse:min-h-11 text-base text-field-fg placeholder:text-field-placeholder sm:text-sm focus-visible:border-field-ring focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-field-ring/30 aria-[invalid=true]:border-field-error aria-[invalid=true]:ring-field-error/30 disabled:cursor-not-allowed disabled:opacity-50`;
+  return `w-full rounded-field border border-field-border bg-field-bg px-3 ${CONTROL_HEIGHT_CLASS[size]} ${TAP_TARGET_HEIGHT} text-base text-field-fg placeholder:text-field-placeholder sm:text-sm focus-visible:border-field-ring focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-field-ring/30 aria-[invalid=true]:border-field-error aria-[invalid=true]:ring-field-error/30 disabled:cursor-not-allowed disabled:opacity-50`;
 }

package/src/react/lib/floatingStyles.spec.ts

@@ -6,6 +6,7 @@ import {
   FLOATING_CONTENT_BASE,
   FLOATING_ITEM_BASE,
 } from './floatingStyles';
+import { TAP_TARGET_HEIGHT } from './tapTarget';
 
 const REACT_DIR = join(import.meta.dir, '..');
 
@@ -52,6 +53,6 @@ describe('the floating layer — DESIGN.md §5 containment', () => {
 
   test('a menu row clears 44px on a touch pointer', () => {
     // A mis-tap in a MENU costs the most: the neighbouring row is a different action.
-    expect(FLOATING_ITEM_BASE).toContain('pointer-coarse:min-h-11');
+    expect(FLOATING_ITEM_BASE).toContain(TAP_TARGET_HEIGHT);
   });
 });

package/src/react/lib/floatingStyles.ts

@@ -10,6 +10,8 @@
  * from `tw-animate-css`, which `src/styles.css` imports.
  */
 
+import { TAP_TARGET_HEIGHT } from './tapTarget';
+
 /**
  * The gap a floating panel keeps from every viewport edge, in px.
  *
@@ -44,7 +46,7 @@ export const FLOATING_ITEM_BASE =
   // DESIGN.md §5's 44px floor, on coarse pointers only so the dense desktop menu
   // keeps its rhythm. A 32px menu row is a miss on a phone, and a menu is exactly
   // where a mis-tap costs the most: the neighbouring row is a different action.
-  'pointer-coarse:min-h-11 ' +
+  `${TAP_TARGET_HEIGHT} ` +
   'data-[disabled]:pointer-events-none data-[disabled]:opacity-50 ' +
   'focus:bg-accent/10 focus:text-accent';
 

package/src/react/lib/tapTarget.ts

@@ -0,0 +1,100 @@
+/**
+ * `DESIGN.md` §5's tap floor, written once.
+ *
+ * > *"Every interactive text link, button, or tab on a mobile screen viewport MUST
+ * > maintain a minimum tap footprint of 44px x 44px."*
+ *
+ * ── 🔴 Why `pointer-coarse:` and not a plain `min-h-11` ─────────────────────
+ * The floor is about a FINGER, not about a narrow window. `pointer-coarse:` is a
+ * media query on the INPUT DEVICE, so a 390px-wide desktop window matches none of
+ * these utilities and a phone matches all of them. That is deliberate twice over:
+ * a 44px row of chips on a desktop toolbar is a toolbar that has lost its density
+ * (`DESIGN.md` §2 wants those controls on ONE line), and a mouse does not need the
+ * padding. The corollary is that **a narrow desktop window proves nothing** —
+ * `e2e/touch-targets.spec.ts` runs in a real touch profile, the only configuration
+ * in which any of this is switched on at all.
+ *
+ * ── Why a constant rather than the classes inline ───────────────────────────
+ * Because the floor was written out by hand 48 times across 33 files in this
+ * package, and a floor written 48 times is a floor that moves 47 times the next
+ * time it moves. The hover half below was hand-rolled in 12 separate places, each
+ * of which had to independently re-derive that a control revealed on hover does
+ * not exist on a phone. `apps/flix` then grew its own fourth-generation copy of
+ * all of it, because at the time it could not consume this package.
+ *
+ * Same kind of file, same reasons, as `floatingStyles.ts` next door — which
+ * carries this very floor inside `FLOATING_ITEM_BASE`.
+ *
+ * ── 🔴 Tailwind has to SEE these strings ────────────────────────────────────
+ * The JIT scans source TEXT for candidates; it does not evaluate anything. These
+ * constants therefore have to live under this package's own `@source "."` glob
+ * (declared in `src/styles.css`, rooted at `src/`) and has to spell each utility
+ * out as a literal — a class assembled at runtime from a variable is a class
+ * Tailwind never emits, and the symptom is not a type error or a failed build but
+ * a stylesheet with no `pointer-coarse` utilities in it at all, i.e. the floor
+ * silently gone fleet-wide. `src/tapTargetStylesheet.spec.ts` compiles the real
+ * stylesheet and fails on exactly that.
+ */
+
+/**
+ * The HEIGHT half of the floor, alone — for a control that is already at least
+ * 44px wide by construction: a full-width row, a menu item, a table header, a
+ * text input, a chip with real padding.
+ *
+ * Kept separate from {@link TAP_TARGET} rather than folded into it because a
+ * `min-width` is not free everywhere: on a dense desktop-first control that a
+ * touch device merely needs to make TALLER, forcing 44px of width too is a layout
+ * change on a phone that nothing asked for.
+ */
+export const TAP_TARGET_HEIGHT = 'pointer-coarse:min-h-11';
+
+/**
+ * The floor for a control that sizes itself from its content — a text button, a
+ * chip, a nav tab, an icon button drawn small. Grows the box to 44×44 without
+ * touching padding, so nothing re-flows on a mouse.
+ *
+ * Pair it with `inline-flex items-center justify-center` on anything that is not
+ * already a flex container: a `min-height` on a plain `<button>` leaves the label
+ * riding at the top of the taller box in Firefox and Safari.
+ */
+export const TAP_TARGET = `${TAP_TARGET_HEIGHT} pointer-coarse:min-w-11`;
+
+/**
+ * The floor for a fixed-size ICON button — one that is deliberately a small
+ * square on a desktop (`h-7 w-7`, `h-9 w-9`) and must become a 44×44 target on a
+ * phone without its glyph growing with it.
+ */
+export const TAP_TARGET_SQUARE = 'pointer-coarse:h-11 pointer-coarse:w-11';
+
+/**
+ * The same 44×44, taken out of the surrounding layout.
+ *
+ * A poster's ⋯ trigger is anchored to a corner of the artwork. Growing it from
+ * 28px to 44px in place would push its visible disc 8px in from that corner on a
+ * phone and nowhere else, so the pill moves when you change device. The negative
+ * margin spends the extra 16px OUTWARD instead: the disc stays exactly where the
+ * design put it and the finger gets the other 8px on every side, over the poster
+ * and the gutter, where there is nothing else to hit.
+ *
+ * Use it for a control that is corner-anchored or overlaid on artwork. Do NOT use
+ * it inside a scrolling row or a clipped frame, where the 8px it takes back is
+ * somebody else's overflow.
+ */
+export const TAP_TARGET_HALO = `${TAP_TARGET_SQUARE} pointer-coarse:-m-2`;
+
+/**
+ * 🔴 A control that is only revealed on HOVER does not exist on a phone.
+ *
+ * The ⋯ menu on a poster rests at `opacity-0` and comes back on
+ * `group-hover`/`group-focus-within`. On a touch device there is no hover, and
+ * `:focus-within` needs a tap that has nowhere to land — so the whole tile menu
+ * (save, favorite, mark watched, hide) was measurable, invisible and unreachable
+ * on a phone when `apps/flix` measured it on 2026-09-07. The same fix was already
+ * hand-written at twelve sites in here — `FilterRail`'s action shelf and
+ * `StatTile`'s trend caption among them — which is twelve separate copies of
+ * knowing the trap and no way to find the thirteenth site that forgot.
+ *
+ * Anything that reveals itself on hover must pair that with this; the packaged
+ * version of the whole pattern is `REVEAL_ON_HOVER`.
+ */
+export const TAP_TARGET_ALWAYS = 'pointer-coarse:opacity-100';

package/src/react/media/MaskPainter.tsx

@@ -69,8 +69,8 @@ import {
 import { buildMaskImageData, rgbaToAlpha } from './maskRaster';
 import type { MaskPainterProps, MaskRegionResult } from './types';
 
-// Re-exported so the granular `cursedbelt/react/media/mask-painter` entry carries the
-// prop type without pulling the heavy media barrel (react-photo-album/vidstack/…).
+// Re-exported alongside the component so a consumer of `cursedbelt/react/media` gets
+// the prop type from the same module it imports the component from.
 export type { MaskPainterProps, MaskRegionResult } from './types';
 
 const DEFAULT_BRUSH = 40;

package/src/react/media/VideoTrimmer.tsx

@@ -32,7 +32,7 @@ const QUALITY_OPTIONS = [
  * In-browser trim UI: a native `<video>` preview + a dual-handle range slider (with a
  * mediabunny/`<video>` filmstrip), format + quality choices, and a Trim action. No
  * ffmpeg in the browser — `onTrim` hands the chosen range to the app, which routes it
- * to the server (`cursedbelt/server/media` `trimVideo`). A Spinner overlays while the
+ * to the server (`cursedbelt/server` `trimVideo`). A Spinner overlays while the
  * server trims.
  */
 export function VideoTrimmer({

package/src/react/media/denseGallery.css

@@ -655,9 +655,9 @@
 	}
 }
 
-/* ≥44px touch target on coarse pointers only — mirrors cursedbelt's shared
-   Tailwind `pointer-coarse:min-h-11` convention (STANDARDS.md §4a), hand-rolled
-   here since this is a plain `.cbgd-` CSS file, not a Tailwind className. */
+/* ≥44px touch target on coarse pointers only — mirrors `TAP_TARGET_HEIGHT` from
+   src/react/lib/tapTarget.ts (STANDARDS.md §4a), hand-rolled here since this is a
+   plain `.cbgd-` CSS file, not a Tailwind className. */
 @media (pointer: coarse) {
 	.cbgd-order-btn {
 		min-height: 44px;

package/src/react/media/ffmpegWasm.ts

@@ -1,4 +1,4 @@
-// cursedbelt/react/media/ffmpeg-wasm — the browser executor for core/media
+// src/react/media/ffmpegWasm — the browser executor for core/media
 // render plans. A DEDICATED subpath (like video-player): `@ffmpeg/ffmpeg` +
 // `@ffmpeg/util` are heavy OPTIONAL peers, loaded via dynamic import only when
 // an engine actually loads — apps that never export video bundle nothing.
@@ -83,7 +83,7 @@ export function createFfmpegWasmEngine(config: FfmpegWasmConfig = {}): FfmpegWas
         ]);
       } catch (cause) {
         throw new Error(
-          'cursedbelt/react/media/ffmpeg-wasm needs the optional peers "@ffmpeg/ffmpeg" and "@ffmpeg/util" — install them in your app to export video in the browser.',
+          'cursedbelt/react/media needs the optional peers "@ffmpeg/ffmpeg" and "@ffmpeg/util" to export video in the browser — install them in your app.',
           { cause },
         );
       }

package/src/react/media/videoPlayer.css

@@ -25,3 +25,45 @@
 	width: var(--media-button-icon-size, 80%);
 	height: var(--media-button-icon-size, 80%);
 }
+
+/*
+ * ── 🔴 DESIGN.md §5's 44px tap floor, inside a DEPENDENCY's control bar ──────────────
+ *
+ * Vidstack draws its own buttons, and on a phone they are under the floor:
+ *
+ *   theme.css                --media-button-size            38px   (every layout)
+ *   layouts/video.css:111    --video-sm-button-size         36px   (the small layout)
+ *   theme.css                --media-fullscreen-button-size 42px
+ *   theme.css                --media-sm-fullscreen-button-size 42px
+ *
+ * Measured 2026-09-14 on a Pixel 7 profile: `.vds-menu-button` ("Settings") and
+ * `.vds-fullscreen-button` both rendered 36×36 and reddened
+ * `e2e/touch-targets.spec.ts`. Nothing in this package had ever looked, because the
+ * floor was only ever enforced against controls THIS package draws — and the player
+ * is one of the few surfaces where a third party draws the buttons a thumb aims at.
+ *
+ * 🔴 Set the VARIABLES, never `.vds-button { width }`. Those four names are Vidstack's
+ * published override hooks, declared behind `:where()` so a plain custom property wins
+ * with no specificity war; overriding the box itself would be a second declaration of
+ * the bar's geometry and would drift on the next upgrade — the rule this file opens
+ * with. All four are needed, not just the small one: a tablet in landscape gets the
+ * wide layout (38px) and fullscreen has its own pair (42px). Every one of them is
+ * under 44.
+ *
+ * The glyph is deliberately left proportional (`--media-button-icon-size` stays at its
+ * 70% default) rather than pinned: it keeps `.cbvp-step`'s 80%-of-button relationship
+ * above intact — that rule reads the same variable — and a video control bar is the
+ * one place where a finger-sized target SHOULD carry a finger-sized glyph.
+ *
+ * `(pointer: coarse)`, not a width breakpoint: the floor is about a finger, and a
+ * narrow desktop window must not get a taller control bar. Same reasoning, and the
+ * same media query, as `src/react/lib/tapTarget.ts`.
+ */
+@media (pointer: coarse) {
+	[data-media-player] {
+		--video-sm-button-size: 44px;
+		--media-button-size: 44px;
+		--media-fullscreen-button-size: 44px;
+		--media-sm-fullscreen-button-size: 44px;
+	}
+}

package/src/react/namespace/NamespaceTargetCapsule.tsx

@@ -8,8 +8,8 @@ export interface NamespaceTargetOption {
   /** `null` = the General pool (no namespace). */
   id: string | null;
   label: string;
-  /** Colorway seed (0-359), same convention as `cursedbelt/namespace`'s
-   *  `Namespace.hue`. Omitted (e.g. General) renders a neutral dot. */
+  /** Colorway seed (0-359), hue-on-a-colour-wheel. Omitted (e.g. General)
+   *  renders a neutral dot. */
   hue?: number;
 }
 

package/src/react/nav/BreadcrumbTrail.tsx

@@ -57,6 +57,7 @@ import {
   planOverflow,
 } from './breadcrumbModel';
 import { NavLink, type NavNavigationProps } from './navShared';
+import { TAP_TARGET } from '../lib/tapTarget';
 
 /** Fallback width for the `…` trigger before one has ever been rendered. */
 const ESTIMATED_TRIGGER_WIDTH = 36;
@@ -552,7 +553,7 @@ const Crumb = memo(function Crumb({
     'flex min-w-0 items-center gap-1.5 rounded px-0.5 text-muted-foreground transition-colors ' +
     'hover:text-foreground hover:underline hover:decoration-border hover:underline-offset-4 ' +
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ' +
-    'pointer-coarse:min-h-11 pointer-coarse:min-w-11';
+    TAP_TARGET;
 
   const body = isLeaf ? (
     <span
@@ -651,7 +652,7 @@ function PivotTrigger({ node }: { node: BreadcrumbTrailNode }) {
   );
   const buttonClass =
     'h-6 w-6 shrink-0 rounded p-0 text-muted-foreground hover:text-foreground ' +
-    'pointer-coarse:min-h-11 pointer-coarse:min-w-11';
+    TAP_TARGET;
 
   if (isAsyncAction(action)) {
     const trigger = (
@@ -732,7 +733,7 @@ function OverflowMenu({
           onPointerEnter={onPointerEnter}
           onFocus={onFocus}
           onClick={onClick}
-          className='h-6 w-8 shrink-0 rounded p-0 text-muted-foreground hover:text-foreground pointer-coarse:min-h-11 pointer-coarse:min-w-11'
+          className={`h-6 w-8 shrink-0 rounded p-0 text-muted-foreground hover:text-foreground ${TAP_TARGET}`}
         >
           <MoreHorizontal className='size-4' />
         </Button>

package/src/react/nav/HubTileGrid.tsx

@@ -27,6 +27,7 @@ import {
 } from './navShared';
 
 import { Tooltip } from '../components/Tooltip';
+import { TAP_TARGET } from '../lib/tapTarget';
 export interface HubTileGridProps extends NavNavigationProps {
   /** The domain whose items become tiles. */
   domain: NavDomain;
@@ -223,7 +224,7 @@ function Tile({
               // tabIndex AFTER the spread so it overrides dnd-kit's tabIndex=0 — the grip
               // is a pointer affordance only, never a Tab stop.
               tabIndex={-1}
-              className={`inline-flex size-7 cursor-grab items-center justify-center rounded-md bg-background/80 text-muted-foreground backdrop-blur hover:text-foreground ${'pointer-coarse:min-h-11 pointer-coarse:min-w-11'}`}
+              className={`inline-flex size-7 cursor-grab items-center justify-center rounded-md bg-background/80 text-muted-foreground backdrop-blur hover:text-foreground ${TAP_TARGET}`}
             >
               <GripVertical className='size-4' />
             </button>

package/src/react/nav/SideNav.tsx

@@ -23,6 +23,7 @@ import {
   rankBySavedOrder,
   renderIcon,
 } from './navShared';
+import { TAP_TARGET, TAP_TARGET_HEIGHT } from '../lib/tapTarget';
 
 /**
  * 🔴 Lazy on purpose, and the number is why: drag-to-reorder pulls three
@@ -335,14 +336,14 @@ function DomainRow({
         // A place that cannot work on THIS host stays VISIBLE and reads as
         // unavailable — never hidden. See `NavHostLimit`.
         limited && 'opacity-55',
-        // `pointer-coarse:min-h-11`/`min-w-11` — a 36px-tall row (icon + `py-2`) or a
+        // `TAP_TARGET`/`TAP_TARGET_HEIGHT` — a 36px-tall row (icon + `py-2`) or a
         // 40px collapsed icon square both clear desktop mouse-target norms but fall
         // short of the 44px WCAG/HIG touch-target floor; widen only on coarse
         // pointers so the dense desktop rail keeps its compact rows (owner orch-host
         // 390px mobile-drawer teardown — sidenav rows measured 223×36).
         collapsed
-          ? 'size-10 justify-center pointer-coarse:min-h-11 pointer-coarse:min-w-11'
-          : 'w-full gap-3 px-3 py-2 pointer-coarse:min-h-11',
+          ? `size-10 justify-center ${TAP_TARGET}`
+          : `w-full gap-3 px-3 py-2 ${TAP_TARGET_HEIGHT}`,
         active ? 'bg-muted text-foreground' : 'text-foreground hover:bg-muted',
       )}
     >