cursedbelt 5.45.0 → 5.45.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.45.0",
+	"version": "5.45.1",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -141,6 +141,12 @@
 			"source": "./src/react/components/Button.tsx",
 			"import": "./dist/react/components/Button.js"
 		},
+		"./react/canvas-hud": {
+			"types": "./dist/react/canvas-hud/index.d.ts",
+			"bun": "./src/react/canvas-hud/index.ts",
+			"source": "./src/react/canvas-hud/index.ts",
+			"import": "./dist/react/canvas-hud/index.js"
+		},
 		"./react/charts": {
 			"types": "./dist/react/charts/index.d.ts",
 			"bun": "./src/react/charts/index.ts",
@@ -537,6 +543,7 @@
 		"./styles-areas/auth.css": "./src/styles-areas/auth.css",
 		"./styles-areas/calendar.css": "./src/styles-areas/calendar.css",
 		"./styles-areas/chart-table.css": "./src/styles-areas/chart-table.css",
+		"./styles-areas/canvas-hud.css": "./src/styles-areas/canvas-hud.css",
 		"./styles-areas/charts.css": "./src/styles-areas/charts.css",
 		"./styles-areas/chat.css": "./src/styles-areas/chat.css",
 		"./styles-areas/clipboard.css": "./src/styles-areas/clipboard.css",

package/scripts/generateAreaStyles.ts

@@ -91,8 +91,10 @@ import {
 	type Area,
 	CORE,
 	areaClosures,
+	buildLazyGraph,
 	candidatesIn,
 	coverageFault,
+	lazyImportFault,
 	transitiveNeeds,
 } from './styleAreas';
 
@@ -274,7 +276,7 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		);
 	}
 	const { closures } = await areaClosures();
-	const fault = coverageFault(closures);
+	const fault = coverageFault(closures) ?? lazyImportFault(closures, await buildLazyGraph());
 	if (fault) throw new Error(fault);
 
 	const coreClosure = closures.get(CORE) as Set<string>;

package/scripts/styleAreas.ts

@@ -179,6 +179,7 @@ export const AREAS: readonly Area[] = [
 			'components/Modal.tsx',
 			'components/OnlineDot.tsx',
 			'components/Page.tsx',
+			'components/PageGuidePopover.tsx',
 			'components/PanelSeparator.tsx',
 			'components/PathText.tsx',
 			'components/Popover.tsx',
@@ -220,6 +221,7 @@ export const AREAS: readonly Area[] = [
 		roots: ['components/auth', 'AuthGate.tsx'],
 	},
 	{ name: 'calendar', why: 'the date-picker family: a calendar grid is a whole layout nothing else shares', roots: ['components/calendar'] },
+	{ name: 'canvas-hud', why: 'the pan-and-zoom canvas HUD — zoom keys, minimap, find pill, node menu', roots: ['canvas-hud'] },
 	{ name: 'charts', why: 'the recharts wrappers — an app with no dashboard renders none of them', roots: ['charts'] },
 	{
 		name: 'chart-table',
@@ -274,7 +276,12 @@ export const AREAS: readonly Area[] = [
 	},
 	{ name: 'file-tree', why: 'the flat (non-nested) file list and its row chrome', roots: ['file-tree'] },
 	{ name: 'filter-rail', why: 'the faceted filter rail', roots: ['filter-rail'] },
-	{ name: 'folder-tree', why: 'the nested folder tree', roots: ['folder-tree'] },
+	{
+		name: 'folder-tree',
+		why: 'the nested folder tree',
+		// The breadcrumb's menus and pivot are `import()`ed by `nav/BreadcrumbTrail.tsx` (lazyImportFault).
+		roots: ['folder-tree', 'nav/BreadcrumbMenus.tsx', 'nav/BreadcrumbPivot.tsx'],
+	},
 	{ name: 'keep-awake', why: 'the keep-awake toggle and its badge', roots: ['keep-awake'] },
 	{ name: 'layout-engine', why: 'the persisted pane/grid layout engine — apps with a fixed layout render none of it', roots: ['layoutEngine'] },
 	{ name: 'markdown', why: 'the rendered-markdown document', roots: ['markdown', 'markdown/MarkdownDoc.tsx'] },
@@ -292,12 +299,33 @@ export const AREAS: readonly Area[] = [
 		// two entries up: the gallery reaches it through `lazyWithReload(() => import(…))`, and the
 		// closure walk reads static specifiers only — so a lazily-imported dialog is an orphan
 		// unless it is its own root. The coverage gate is what says so, by name, at build time.
-		roots: ['media-gallery', 'media-gallery/MediaMetaEditor.tsx', 'components/Lightbox.tsx'],
+		// The viewers it opens are `import()`ed too, so they are named (lazyImportFault): a gallery
+		// app that does not import `media`, `pdf-viewer` or `workbook-viewer` still opens them styled.
+		roots: [
+			'media-gallery',
+			'media-gallery/MediaMetaEditor.tsx',
+			'components/Lightbox.tsx',
+			'markdown/MarkdownDoc.tsx',
+			'media/FrameGrabber.tsx',
+			'media/VideoChapterEditor.tsx',
+			'media/VideoCutEditor.tsx',
+			'media/VideoPlayer.tsx',
+			'pdf-viewer/PdfViewer.tsx',
+			'workbook-viewer/WorkbookViewer.tsx',
+		],
 	},
 	{
 		name: 'nav',
 		why: 'the AppShell chrome — the command palette, the nav rail, the place bar and the app menus',
-		roots: ['nav', 'nav/BreadcrumbMenus.tsx', 'nav/SideNavCustomize.tsx', 'components/AppShell.tsx'],
+		// `palette/CommandPalette.tsx` is named for media-gallery's reason above: AppShell reaches its
+		// ⌘K palette through `import()` since forge task 2533, and the walk follows static imports only.
+		roots: [
+			'nav',
+			'nav/BreadcrumbMenus.tsx',
+			'nav/SideNavCustomize.tsx',
+			'components/AppShell.tsx',
+			'palette/CommandPalette.tsx',
+		],
 	},
 	{ name: 'notifications', why: 'the notification centre and its feed', roots: ['notifications'] },
 	{
@@ -312,7 +340,7 @@ export const AREAS: readonly Area[] = [
 			'components/AddItemsMenu.tsx',
 		],
 	},
-	{ name: 'palette', why: 'the theme/colour palette editor', roots: ['palette'] },
+	{ name: 'palette', why: 'the ⌘K command palette and its hotkey/source hooks', roots: ['palette'] },
 	{ name: 'pdf-viewer', why: 'the lazy PDF viewer (an optional peer already)', roots: ['pdf-viewer'] },
 	{ name: 'problem-detail', why: 'the RFC-7807 problem renderer', roots: ['problem-detail'] },
 	{ name: 'rich-text', why: 'the TipTap editor and its toolbar', roots: ['rich-text'] },
@@ -412,8 +440,8 @@ export const nonModuleFiles = (): string[] => {
 };
 
 /**
- * Relative import specifiers in a module — `from '…'`, bare `import '…'` and
- * `import('…')` alike.
+ * Relative import specifiers in a module — `from '…'` and bare `import '…'`. NOT `import('…')`:
+ * a lazily-imported module is an orphan unless an area names it as a root (see `media-gallery`).
  *
  * A regex and not the TypeScript AST on purpose: this runs over 700 modules on
  * every build, the only thing it has to understand is a string literal after a
@@ -537,6 +565,60 @@ export const coverageFault = (closures: Map<string, Set<string>>, areas: readonl
 	);
 };
 
+/** `import('./x')` specifiers — the edges the static walk above deliberately does not follow. */
+const DYNAMIC_SPECIFIER = /\bimport\s*\(\s*['"](\.[^'"]*)['"]/g;
+
+/** Module → the modules it `import()`s lazily, inside `src/react`. */
+export const buildLazyGraph = async (): Promise<Map<string, string[]>> => {
+	const graph = new Map<string, string[]>();
+	await Promise.all(
+		allModules().map(async (file) => {
+			const out = new Set<string>();
+			for (const match of (await Bun.file(file).text()).matchAll(DYNAMIC_SPECIFIER)) {
+				const target = resolveRelative(file, match[1] as string);
+				if (target?.startsWith(`${REACT_DIR}/`) && !SPEC.test(target)) out.add(target);
+			}
+			if (out.size > 0) graph.set(file, [...out]);
+		}),
+	);
+	return graph;
+};
+
+/**
+ * 🔴 A module an area reaches LAZILY is styled by that area too (forge task 2533).
+ *
+ * The walk follows static imports only, so when a component moves a body behind `import()` —
+ * AppShell's ⌘K palette, to take it off every app's entry chunk — that body leaves the area's
+ * closure. `coverageFault` stays quiet as long as SOME area still reaches it, and the area that
+ * renders it regenerates without its utilities: an app that imports `nav` but not `palette`
+ * would open an unstyled palette. Every lazy target must be in the importing area's own closure,
+ * in `core`, or in an area it `needs` — usually by naming it as a root, as `media-gallery` does.
+ */
+export const lazyImportFault = (
+	closures: Map<string, Set<string>>,
+	lazyGraph: Map<string, string[]>,
+	areas: readonly Area[] = AREAS,
+): string | null => {
+	const faults: string[] = [];
+	const rel = (f: string) => f.replace(`${REACT_DIR}/`, '');
+	for (const area of areas) {
+		const own = closures.get(area.name) ?? new Set<string>();
+		const styled = new Set(own);
+		for (const name of [CORE, ...transitiveNeeds(area.name, areas)]) for (const f of closures.get(name) ?? []) styled.add(f);
+		for (const file of own) {
+			for (const target of lazyGraph.get(file) ?? []) {
+				if (!styled.has(target)) faults.push(`${area.name}: ${rel(file)} → import('${rel(target)}')`);
+			}
+		}
+	}
+	if (faults.length === 0) return null;
+	return (
+		`${faults.length} lazy import(s) leave their area, so the module they load is unstyled in an app that\n` +
+		"imports that area alone. Name each target in the area's `roots` in scripts/styleAreas.ts:\n  " +
+		faults.sort().join('\n  ')
+	);
+};
+
 /**
  * 🔴 `needs` names areas that exist, never itself, and never a cycle.
  *

package/src/bundlerOnlyEntries.spec.ts

@@ -38,12 +38,9 @@ const isDirectoryImport = (specifier: string): boolean => {
 
 const SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
 
-async function measure(): Promise<Record<Reason, string[]>> {
-  const entries = Object.entries(pkg.exports as Record<string, unknown>).flatMap(([subpath, target]) => {
-    const source = (target as { source?: string }).source;
-    return source && /\.tsx?$/.test(source) ? [[subpath, source.replace(/^\.\//, '')] as const] : [];
-  });
-  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-bundler-only-${process.pid}`;
+/** One `Bun.build` over `entries`: which of them import a stylesheet, and which reach a directory import. */
+async function bundle(entries: readonly (readonly [string, string])[], pass: number): Promise<Record<Reason, string[]>> {
+  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-bundler-only-${process.pid}-${pass}`;
   try {
     const result = await Bun.build({
       entrypoints: entries.map(([, source]) => `${REPO}${source}`),
@@ -62,14 +59,34 @@ async function measure(): Promise<Record<Reason, string[]>> {
       if (emitted.has(js.replace(/\.js$/, '.css')) || specifiers.some((s) => s.endsWith('.css'))) out.css.push(subpath);
       if (specifiers.some((s) => !s.startsWith('.') && isDirectoryImport(s))) out.directoryImport.push(subpath);
     }
-    out.css.sort();
-    out.directoryImport.sort();
     return out;
   } finally {
     rmSync(outdir, { recursive: true, force: true });
   }
 }
 
+async function measure(): Promise<Record<Reason, string[]>> {
+  const entries = Object.entries(pkg.exports as Record<string, unknown>).flatMap(([subpath, target]) => {
+    const source = (target as { source?: string }).source;
+    return source && /\.tsx?$/.test(source) ? [[subpath, source.replace(/^\.\//, '')] as const] : [];
+  });
+  const first = await bundle(entries, 0);
+  const css = new Set(first.css);
+  /*
+   * 🔴 One build emits a stylesheet that several entries import ONCE, beside the first of them
+   * (`canvas-hud` and `search-input` both import `searchInput.css`; only one got the sibling, so
+   * `search-input` read as stale — task 2401). So build again without the entries already
+   * counted, until a pass finds no new one: each pass hands a shared sheet to the next importer.
+   */
+  for (let pass = 1; ; pass++) {
+    const rest = entries.filter(([subpath]) => !css.has(subpath));
+    const found = (await bundle(rest, pass)).css;
+    if (found.length === 0) break;
+    for (const subpath of found) css.add(subpath);
+  }
+  return { css: [...css].sort(), directoryImport: [...first.directoryImport].sort() };
+}
+
 describe('bundlerOnly', () => {
   it('declares exactly the subpaths that import a stylesheet, and exactly those that reach a directory import', async () => {
     const measured = await measure();

package/src/react/canvas-hud/CanvasMinimap.tsx

@@ -0,0 +1,88 @@
+import type { MouseEvent, ReactNode } from 'react';
+import { cn } from '../lib/cn.js';
+import { type CanvasBounds, type CanvasSize, type CanvasView, visibleBounds } from './viewport.js';
+
+export interface CanvasMinimapProps {
+  /** The content's extent in WORLD units — what the thumbnail shows. */
+  bounds: CanvasBounds;
+  view: CanvasView;
+  /** The canvas viewport in screen pixels, for the visible window. */
+  viewport: CanvasSize;
+  /** A click on the thumbnail, in WORLD units — the canvas centres there. */
+  onJump?: (point: { x: number; y: number }) => void;
+  /** The thumbnail's longest side in pixels. Default 168. */
+  size?: number;
+  /** Drawn inside the SVG in WORLD units, under the window: dots, zones, edges. */
+  children?: ReactNode;
+  /** A one-line caption under the map. Default "Tap to jump" when `onJump` is set. */
+  hint?: ReactNode;
+  className?: string;
+}
+
+/**
+ * CNV-3's minimap — the whole content as a low-opacity thumbnail with the visible window drawn
+ * on it. What a canvas draws on it (a dot per node, a heat zone per cluster) is `children` in its
+ * own world coordinates; the frame, the scaling and the window are this component's.
+ *
+ * The SVG is `aria-hidden`: the jump is a pointer shortcut over content that is already
+ * reachable by keyboard on the canvas itself, and a parallel interface over unlabeled dots would
+ * be a second, worse way to do what Tab already does (family's reasoning, kept).
+ */
+export function CanvasMinimap({
+  bounds,
+  view,
+  viewport,
+  onJump,
+  size = 168,
+  children,
+  hint,
+  className,
+}: CanvasMinimapProps) {
+  if (bounds.width <= 0 || bounds.height <= 0 || viewport.width <= 0 || view.scale <= 0) return null;
+  const ratio = Math.min(size / bounds.width, (size * 0.62) / bounds.height);
+  const width = Math.max(1, bounds.width * ratio);
+  const height = Math.max(1, bounds.height * ratio);
+  const seen = visibleBounds(view, viewport);
+  const jump = (event: MouseEvent<SVGSVGElement>) => {
+    if (!onJump) return;
+    const rect = event.currentTarget.getBoundingClientRect();
+    onJump({
+      x: bounds.x + (event.clientX - rect.left) / ratio,
+      y: bounds.y + (event.clientY - rect.top) / ratio,
+    });
+  };
+  const caption = hint === undefined ? (onJump ? 'Tap to jump' : null) : hint;
+  return (
+    <div
+      data-testid='canvas-minimap'
+      className={cn(
+        'pointer-events-auto flex flex-col items-center gap-1 rounded-lg border border-border/60 bg-background/70 p-2 shadow-raised backdrop-blur-md',
+        className,
+      )}
+    >
+      <svg
+        width={width}
+        height={height}
+        viewBox={`${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}`}
+        onClick={jump}
+        aria-hidden='true'
+        className={cn('overflow-hidden', onJump && 'cursor-pointer')}
+      >
+        {children}
+        <rect
+          data-testid='canvas-minimap-window'
+          x={seen.x}
+          y={seen.y}
+          width={seen.width}
+          height={seen.height}
+          fill='var(--accent)'
+          fillOpacity={0.12}
+          stroke='var(--accent)'
+          strokeWidth={1.5 / ratio}
+          rx={3 / ratio}
+        />
+      </svg>
+      {caption ? <span className='text-caption text-muted-foreground'>{caption}</span> : null}
+    </div>
+  );
+}

package/src/react/canvas-hud/CanvasNodeMenu.tsx

@@ -0,0 +1,91 @@
+import type { PointerEvent, ReactNode } from 'react';
+import { Button } from '../components/Button.js';
+import { Popover } from '../components/Popover.js';
+import { cn } from '../lib/cn.js';
+
+export interface CanvasNodeMenuItem {
+  label: string;
+  onSelect: () => void;
+  /** Drawn disabled. The section's `note` is where the reason goes. */
+  disabled?: boolean;
+  destructive?: boolean;
+}
+
+export interface CanvasNodeMenuSection {
+  heading?: string;
+  items: CanvasNodeMenuItem[];
+  /** One quiet line under the rows: what they change, or why they cannot. */
+  note?: ReactNode;
+}
+
+export interface CanvasNodeMenuProps {
+  trigger: ReactNode;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  sections: CanvasNodeMenuSection[];
+  align?: 'start' | 'center' | 'end';
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  className?: string;
+}
+
+/**
+ * A node's menu on a canvas — a `Popover`, deliberately not a `DropdownMenu`.
+ *
+ * A menu takes the arrow keys for its own rows; on a canvas they belong to the CANVAS, which
+ * moves its cursor to the next node and closes this (family's branch menu, the owner's ask of
+ * 2026-09-24: *"I want it to disappear if I click off of it or use arrows to move to another
+ * person"*). So the rows are Tab-reachable buttons, the keys bubble, and an outside press or
+ * Escape closes it. Pointer-downs stop here so pressing a row never starts a pan.
+ */
+export function CanvasNodeMenu({
+  trigger,
+  open,
+  onOpenChange,
+  sections,
+  align = 'start',
+  side = 'bottom',
+  className,
+}: CanvasNodeMenuProps) {
+  const stop = (event: PointerEvent) => event.stopPropagation();
+  return (
+    <Popover
+      open={open}
+      onOpenChange={onOpenChange}
+      align={align}
+      side={side}
+      className={cn('w-64 p-1', className)}
+      trigger={trigger}
+    >
+      <div role='menu' onPointerDown={stop} className='flex flex-col'>
+        {sections.map((section, sectionIndex) => (
+          <div
+            // biome-ignore lint/suspicious/noArrayIndexKey: sections are a static list in the caller's order
+            key={sectionIndex}
+            className={cn('flex flex-col py-1', sectionIndex > 0 && 'border-t border-border')}
+          >
+            {section.heading ? <p className='cb-meta-label px-2 pt-1 pb-1.5'>{section.heading}</p> : null}
+            {section.items.map((item) => (
+              <Button
+                key={item.label}
+                role='menuitem'
+                variant={item.destructive ? 'destructive' : 'ghost'}
+                size='sm'
+                tooltip={item.label}
+                tooltipMobile='off'
+                disabled={item.disabled}
+                className='w-full justify-start'
+                onClick={(event) => {
+                  event.stopPropagation();
+                  item.onSelect();
+                }}
+              >
+                {item.label}
+              </Button>
+            ))}
+            {section.note ? <p className='px-2 pt-1 text-caption text-muted-foreground'>{section.note}</p> : null}
+          </div>
+        ))}
+      </div>
+    </Popover>
+  );
+}

package/src/react/canvas-hud/CanvasSearchField.tsx

@@ -0,0 +1,91 @@
+import type { KeyboardEvent } from 'react';
+import { HudPill } from '../components/HudPill.js';
+import { Input } from '../components/Input.js';
+import { IconSearch } from '../icons.js';
+import { cn } from '../lib/cn.js';
+import { HudButton } from './HudControls.js';
+
+export interface CanvasSearchFieldProps {
+  value: string;
+  onChange: (value: string) => void;
+  /** Step to the next (1) or previous (-1) match — Enter and Shift+Enter, and the ‹ › keys. */
+  onStep?: (delta: 1 | -1) => void;
+  /** How many matches the query has, and which one is current (0-based). */
+  matches?: number;
+  index?: number;
+  placeholder?: string;
+  'aria-label'?: string;
+  className?: string;
+}
+
+/**
+ * The find box that floats over a canvas, and the one that does not steal the canvas's keys.
+ *
+ * 🔴 A canvas binds the arrow keys on an ancestor of this field. Without stopping them here,
+ * typing a name and pressing ← to fix a typo walked the reader to a cousin instead of moving
+ * the caret (family, 2026-09). Every key stops at the field; Enter and Shift+Enter step through
+ * the matches, the convention of every find-in-page; Escape empties the box rather than blurring.
+ *
+ * It is the belt's `Input` drawn borderless, so the pill around it is the field — and NOT
+ * `SearchInput`: a find box over a canvas matches names, never wildcards or regexes, and the
+ * syntax parser and its badge were 5.6 kB gzip on family's first paint for nothing (task 2401).
+ * A ✕ empties it too, because a phone has no Escape key.
+ */
+export function CanvasSearchField({
+  value,
+  onChange,
+  onStep,
+  matches = 0,
+  index = 0,
+  placeholder = 'Find…',
+  'aria-label': ariaLabel,
+  className,
+}: CanvasSearchFieldProps) {
+  const searching = value.trim().length > 0;
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter' && onStep) {
+      event.preventDefault();
+      onStep(event.shiftKey ? -1 : 1);
+    }
+    if (event.key === 'Escape' && value !== '') {
+      event.preventDefault();
+      onChange('');
+    }
+    event.stopPropagation();
+  };
+  return (
+    <HudPill className={cn('gap-0.5 rounded-lg py-0.5 pr-1 pl-0', className)}>
+      <IconSearch size={16} className='ml-2 shrink-0 text-muted-foreground' />
+      <Input
+        type='search'
+        size='sm'
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+        placeholder={placeholder}
+        aria-label={ariaLabel ?? placeholder}
+        onKeyDown={onKeyDown}
+        className='w-40 border-transparent bg-transparent pl-1 shadow-none focus-visible:border-transparent focus-visible:ring-0 [&::-webkit-search-cancel-button]:hidden'
+      />
+      {searching ? (
+        <span className='min-w-10 text-center text-xs text-muted-foreground tabular-nums' aria-live='polite'>
+          {matches === 0 ? 'none' : `${index + 1}/${matches}`}
+        </span>
+      ) : null}
+      {onStep && matches > 1 ? (
+        <>
+          <HudButton label='Previous match — Shift+Enter' onClick={() => onStep(-1)}>
+            <span aria-hidden>‹</span>
+          </HudButton>
+          <HudButton label='Next match — Enter' onClick={() => onStep(1)}>
+            <span aria-hidden>›</span>
+          </HudButton>
+        </>
+      ) : null}
+      {searching ? (
+        <HudButton label='Clear the search — Escape' onClick={() => onChange('')}>
+          <span aria-hidden>×</span>
+        </HudButton>
+      ) : null}
+    </HudPill>
+  );
+}