cursedbelt 1.0.0 → 2.5.0

package/src/game/react/index.ts

@@ -1,10 +0,0 @@
-// cursedbelt/game/react — the browser-only React host hook. Reads `document`/`window`;
-// never import this subpath from a Bun server file. The engine-agnostic core (no React,
-// Bun-safe) lives in `cursedbelt/game`.
-
-export type {
-  GameFactory,
-  GameHandle,
-  UseGameEngineResult,
-} from './useGameEngine';
-export { useGameEngine } from './useGameEngine';

package/src/game/react/useGameEngine.ts

@@ -1,125 +0,0 @@
-import { type DependencyList, type RefObject, useEffect, useRef, useState } from 'react';
-import { DisposeRegistry } from '../core/DisposeRegistry';
-
-/**
- * The handle a {@link GameFactory} returns. The host hook owns its lifecycle:
- * `dispose` runs on true unmount; `pause`/`resume` run on tab hide/show.
- */
-export interface GameHandle {
-  /** Tear down the engine. Called exactly once, on true unmount. */
-  dispose(): void;
-  /** Optional: called when the tab is hidden (Page Visibility). Cancel your rAF here. */
-  pause?(): void;
-  /** Optional: called when the tab becomes visible again. Restart your rAF here. */
-  resume?(): void;
-}
-
-/**
- * Creates the engine for a freshly-mounted canvas. Receives a {@link DisposeRegistry}
- * for RAII cleanup — register every listener / rAF id / resource you allocate.
- *
- * MUST be referentially stable: define it at module level or wrap it in `useCallback`.
- * (It's read through a ref, so an unstable identity won't restart the engine — but a
- * stale closure could capture old props. Prefer reading live values through refs.)
- *
- * @returns the handle, or a promise of it (async setup — e.g. loading WASM — is fine).
- */
-export type GameFactory<THandle extends GameHandle> = (
-  canvas: HTMLCanvasElement,
-  registry: DisposeRegistry,
-) => THandle | Promise<THandle>;
-
-export interface UseGameEngineResult<THandle extends GameHandle> {
-  /** Attach to your `<canvas ref={canvasRef} />`. */
-  canvasRef: RefObject<HTMLCanvasElement | null>;
-  /**
-   * The live handle, available after mount (`null` during SSR/init). This is a ref
-   * value, NOT reactive — gate UI that needs it on {@link UseGameEngineResult.isReady}.
-   */
-  handle: THandle | null;
-  /** `true` once the factory has resolved and the engine is running. */
-  isReady: boolean;
-}
-
-/**
- * Stable game-engine host hook — the architectural fix for the "game froze, can't
- * click out" bug.
- *
- * The bug: a game's lifecycle `useEffect` listed a context-derived value (typically
- * `authRequest` / `saveNow` from `AuthContext`) in its dep array. When that value's
- * identity churned on an unrelated re-render, React tore down and re-ran the effect —
- * disposing the *live* engine mid-session. A guarded setup (`if (engine) return`) then
- * refused to recreate it, leaving a dead canvas with no way out.
- *
- * The fix, by construction: the `factory` is held in a ref and is **never** an effect
- * dependency. The engine starts once on mount and is disposed once on true unmount.
- * AuthContext can re-render as much as it likes — the engine lifecycle is fully
- * decoupled from React's render cycle. Only the explicit `deps` (true restart triggers
- * like a room id or game mode) re-create the engine.
- *
- * Notes:
- * - **Canvas sizing / DPR is game-specific** and intentionally NOT handled here. Call
- *   `resizeCanvasToDisplaySize(canvas)` (from `cursedbelt/game`) in your render loop.
- * - **Page Visibility**: the hook calls `handle.pause?()` on hide and `handle.resume?()`
- *   on show. Cancel your rAF in `pause` and restart it in `resume`; pair with
- *   `createFixedTimestep`'s `maxCatchup` guard so the post-resume delta can't spiral.
- *
- * @param factory Stable engine constructor (module-level or `useCallback`).
- * @param deps    True restart triggers (keep small + stable). Default `[]` = mount-once.
- */
-export function useGameEngine<THandle extends GameHandle>(
-  factory: GameFactory<THandle>,
-  deps: DependencyList = [],
-): UseGameEngineResult<THandle> {
-  const canvasRef = useRef<HTMLCanvasElement | null>(null);
-  const factoryRef = useRef(factory); // ← intentionally never an effect dependency
-  const handleRef = useRef<THandle | null>(null);
-  const [isReady, setIsReady] = useState(false);
-
-  // Keep the factory ref fresh on every render WITHOUT re-running the engine effect.
-  // (Same pattern as a `useEvent` / event-handler ref.)
-  useEffect(() => {
-    factoryRef.current = factory;
-  });
-
-  // NOTE (the freeze fix): `factory` is intentionally NOT a dependency of this effect —
-  // it is read through the stable `factoryRef`, so AuthContext churn (or any re-render)
-  // can never tear down and restart the live engine. Only `deps` (true restart triggers
-  // like a room id) re-create it. The exhaustive-deps lint has nothing to flag precisely
-  // because `factory` is never referenced directly here.
-  useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas) return;
-
-    const registry = new DisposeRegistry();
-    let active = true;
-
-    Promise.resolve(factoryRef.current(canvas, registry)).then((handle) => {
-      if (!active) {
-        // Unmounted before the (possibly async) factory resolved — dispose immediately.
-        handle.dispose();
-        return;
-      }
-      handleRef.current = handle;
-      setIsReady(true);
-
-      const onVisibility = () => {
-        if (document.hidden) handle.pause?.();
-        else handle.resume?.();
-      };
-      document.addEventListener('visibilitychange', onVisibility);
-      registry.add(() => document.removeEventListener('visibilitychange', onVisibility));
-    });
-
-    return () => {
-      active = false;
-      registry.disposeAll();
-      handleRef.current?.dispose();
-      handleRef.current = null;
-      setIsReady(false);
-    };
-    // biome-ignore lint/correctness/useExhaustiveDependencies: `deps` is this hook's own pass-through dependency-list parameter (same shape as useEffect's own deps arg), inherently caller-supplied rather than an inline literal; `factory` is intentionally excluded per the freeze-fix note above.
-  }, deps);
-
-  return { canvasRef, handle: handleRef.current, isReady };
-}

package/src/react/canvas/CanvasNavHUD.spec.tsx

@@ -1,62 +0,0 @@
-import { afterEach, describe, expect, test } from 'bun:test';
-import { cleanup, fireEvent, render } from '@testing-library/react';
-import { CanvasNavHUD } from './CanvasNavHUD';
-
-afterEach(cleanup);
-
-const WORLD = { x: 0, y: 0, width: 1000, height: 500 };
-
-describe('CanvasNavHUD — DESIGN.md §7 names three controls', () => {
-  test('fit, centre-on-focus and the radar are all present', () => {
-    const { getByLabelText } = render(
-      <CanvasNavHUD
-        onFit={() => {}}
-        onCenterFocus={() => {}}
-        focusLabel='Ada Lovelace'
-        world={WORLD}
-        viewport={{ x: 100, y: 50, width: 200, height: 100 }}
-      />,
-    );
-    expect(getByLabelText('Fit to canvas')).toBeTruthy();
-    // The hint names WHAT it centres on, not "centre".
-    expect(getByLabelText('Centre on Ada Lovelace')).toBeTruthy();
-    expect(getByLabelText('Radar')).toBeTruthy();
-  });
-
-  test('the radar draws the viewport rectangle in world coordinates', () => {
-    const { container } = render(
-      <CanvasNavHUD
-        onFit={() => {}}
-        world={WORLD}
-        viewport={{ x: 500, y: 250, width: 250, height: 125 }}
-      />,
-    );
-    const rect = container.querySelector('[data-cb-hud-viewport]');
-    // 132×88 radar; half-way across the world is half-way across the radar.
-    expect(rect?.getAttribute('x')).toBe('66');
-    expect(rect?.getAttribute('y')).toBe('44');
-    expect(rect?.getAttribute('width')).toBe('33');
-  });
-
-  test('a canvas with no focus node simply omits that control', () => {
-    const { queryByLabelText } = render(<CanvasNavHUD onFit={() => {}} world={WORLD} />);
-    expect(queryByLabelText(/Centre on/)).toBeNull();
-  });
-
-  test('the zoom cluster clamps to its range and reports a percentage', () => {
-    const seen: number[] = [];
-    const { getByLabelText, getByText } = render(
-      <CanvasNavHUD onFit={() => {}} zoom={0.1} zoomRange={[0.1, 4]} onZoomChange={(z) => seen.push(z)} />,
-    );
-    expect(getByText('10%')).toBeTruthy();
-    // At the floor, zooming out further is not offered rather than silently ignored.
-    expect(getByLabelText('Zoom out').hasAttribute('disabled')).toBe(true);
-    fireEvent.click(getByLabelText('Zoom in'));
-    expect(seen).toEqual([0.125]);
-  });
-
-  test('without world bounds there is no radar to draw', () => {
-    const { queryByLabelText } = render(<CanvasNavHUD onFit={() => {}} />);
-    expect(queryByLabelText('Radar')).toBeNull();
-  });
-});

package/src/react/canvas/CanvasNavHUD.tsx

@@ -1,210 +0,0 @@
-import { Crosshair, Maximize2, Minus, Plus } from 'lucide-react';
-import { type PointerEvent as ReactPointerEvent, useCallback, useRef } from 'react';
-import { IconButton } from '../components/IconButton';
-import { Surface } from '../components/Surface';
-import { cn } from '../lib/cn';
-
-export interface CanvasRect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-export interface CanvasMinimapPoint {
-  x: number;
-  y: number;
-  /** A `--tone-*`/`--chart-*` CSS value. Defaults to the muted foreground. */
-  color?: string;
-  /** The focus node is drawn larger and on top. */
-  focus?: boolean;
-}
-
-export interface CanvasNavHUDProps {
-  /** "Fit to canvas size" — frame the whole graph. Required: it is the escape
-   *  hatch from being lost, and a canvas without one is the reported defect. */
-  onFit: () => void;
-  /** "Centre on the active focus node". Omit only if the canvas has no focus. */
-  onCenterFocus?: () => void;
-  /** Named in the centre control's hint, so it says WHAT it will centre on. */
-  focusLabel?: string;
-  /** Current zoom (1 = 100%). Renders the zoom cluster when `onZoomChange` is set. */
-  zoom?: number;
-  onZoomChange?: (zoom: number) => void;
-  /** Zoom bounds for the +/- controls. Default 0.1 – 4. */
-  zoomRange?: [number, number];
-  /** The whole graph's bounds, in world units. */
-  world?: CanvasRect;
-  /** What the user can currently see, in the same units. */
-  viewport?: CanvasRect;
-  /** Optional node dots for the radar. Keep it cheap — sample, don't map 10k nodes. */
-  points?: CanvasMinimapPoint[];
-  /** Click/drag the radar to jump. Receives world coordinates. */
-  onMinimapJump?: (point: { x: number; y: number }) => void;
-  /** Which corner the HUD floats in. Default `bottom-right`. */
-  corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-  className?: string;
-}
-
-const CORNER_CLASS: Record<NonNullable<CanvasNavHUDProps['corner']>, string> = {
-  'top-left': 'top-3 left-3',
-  'top-right': 'top-3 right-3',
-  'bottom-left': 'bottom-3 left-3',
-  'bottom-right': 'bottom-3 right-3',
-};
-
-const MINIMAP_W = 132;
-const MINIMAP_H = 88;
-
-/**
- * The floating navigation HUD every infinite canvas must have.
- *
- * `DESIGN.md` §7: *"Every infinite panning or zooming canvas must include an
- * explicit floating Navigation HUD. The HUD must pack three essential controls: a
- * 'Fit to Canvas Size' trigger, a 'Center Canvas on Active Focus Node' tracking
- * action, and a low-opacity Radar Mini-Map positioned in a viewport corner
- * indicating active coordinate bounds."*
- *
- * Nothing shared implemented any of the three — `HudPill` is a pill, not a HUD —
- * so the family tree, the atlas, the orch lanes and fractals each had a different
- * partial answer or none. This is the one implementation.
- *
- * It is deliberately presentational: it owns no camera. The canvas keeps its own
- * transform and passes `world`/`viewport` in the SAME units, which is the only
- * contract the radar needs and the reason this works for an SVG tree and a WebGL
- * field alike. The controls sit in a `Surface` at `--z-sticky`, above the canvas
- * and below every overlay (`DESIGN.md` §5's containment rule), and every one of
- * them is a real 44×44 target on a coarse pointer via `IconButton`.
- */
-export function CanvasNavHUD({
-  onFit,
-  onCenterFocus,
-  focusLabel,
-  zoom,
-  onZoomChange,
-  zoomRange = [0.1, 4],
-  world,
-  viewport,
-  points,
-  onMinimapJump,
-  corner = 'bottom-right',
-  className,
-}: CanvasNavHUDProps) {
-  const svgRef = useRef<SVGSVGElement | null>(null);
-  const [minZoom, maxZoom] = zoomRange;
-
-  const jump = useCallback(
-    (e: ReactPointerEvent<SVGSVGElement>) => {
-      if (!onMinimapJump || !world) return;
-      const box = svgRef.current?.getBoundingClientRect();
-      if (!box || box.width === 0 || box.height === 0) return;
-      const fx = (e.clientX - box.left) / box.width;
-      const fy = (e.clientY - box.top) / box.height;
-      onMinimapJump({ x: world.x + fx * world.width, y: world.y + fy * world.height });
-    },
-    [onMinimapJump, world],
-  );
-
-  const showRadar = Boolean(world && world.width > 0 && world.height > 0);
-  const scaleX = showRadar ? MINIMAP_W / (world as CanvasRect).width : 0;
-  const scaleY = showRadar ? MINIMAP_H / (world as CanvasRect).height : 0;
-  const toX = (x: number) => (x - (world as CanvasRect).x) * scaleX;
-  const toY = (y: number) => (y - (world as CanvasRect).y) * scaleY;
-
-  return (
-    <Surface
-      level='overlay'
-      pad='none'
-      className={cn(
-        'pointer-events-auto absolute z-[var(--z-sticky)] flex flex-col gap-2 rounded-lg p-2',
-        // Low-opacity by default so it never competes with the graph, full presence
-        // the moment the pointer or the keyboard is anywhere near it.
-        'opacity-70 transition-opacity duration-[var(--duration-fast)] hover:opacity-100 focus-within:opacity-100',
-        CORNER_CLASS[corner],
-        className,
-      )}
-      data-cb-canvas-hud=''
-    >
-      <div className='flex items-center gap-1'>
-        <IconButton size='sm' label='Fit to canvas' onClick={onFit}>
-          <Maximize2 />
-        </IconButton>
-        {onCenterFocus ? (
-          <IconButton
-            size='sm'
-            label={focusLabel ? `Centre on ${focusLabel}` : 'Centre on the focused item'}
-            onClick={onCenterFocus}
-          >
-            <Crosshair />
-          </IconButton>
-        ) : null}
-        {onZoomChange ? (
-          <>
-            <IconButton
-              size='sm'
-              label='Zoom out'
-              disabled={zoom !== undefined && zoom <= minZoom}
-              onClick={() => onZoomChange(Math.max(minZoom, (zoom ?? 1) / 1.25))}
-            >
-              <Minus />
-            </IconButton>
-            <span className='min-w-10 text-center text-caption tabular-nums text-muted-foreground'>
-              {Math.round((zoom ?? 1) * 100)}%
-            </span>
-            <IconButton
-              size='sm'
-              label='Zoom in'
-              disabled={zoom !== undefined && zoom >= maxZoom}
-              onClick={() => onZoomChange(Math.min(maxZoom, (zoom ?? 1) * 1.25))}
-            >
-              <Plus />
-            </IconButton>
-          </>
-        ) : null}
-      </div>
-
-      {showRadar ? (
-        <svg
-          ref={svgRef}
-          role={onMinimapJump ? 'button' : 'img'}
-          aria-label={onMinimapJump ? 'Radar — click to jump' : 'Radar'}
-          tabIndex={onMinimapJump ? 0 : undefined}
-          width={MINIMAP_W}
-          height={MINIMAP_H}
-          viewBox={`0 0 ${MINIMAP_W} ${MINIMAP_H}`}
-          onPointerDown={jump}
-          className={cn(
-            'rounded border border-border bg-surface-sunken',
-            onMinimapJump && 'cursor-pointer',
-          )}
-        >
-          <title>Radar</title>
-          {(points ?? []).map((p, i) => (
-            <circle
-              // biome-ignore lint/suspicious/noArrayIndexKey: sampled dots have no stable identity
-              key={i}
-              cx={toX(p.x)}
-              cy={toY(p.y)}
-              r={p.focus ? 2.5 : 1.4}
-              fill={p.color ?? 'var(--muted-foreground)'}
-              opacity={p.focus ? 1 : 0.55}
-            />
-          ))}
-          {viewport ? (
-            <rect
-              x={toX(viewport.x)}
-              y={toY(viewport.y)}
-              width={Math.max(2, viewport.width * scaleX)}
-              height={Math.max(2, viewport.height * scaleY)}
-              fill='var(--accent)'
-              fillOpacity={0.12}
-              stroke='var(--accent)'
-              strokeWidth={1}
-              data-cb-hud-viewport=''
-            />
-          ) : null}
-        </svg>
-      ) : null}
-    </Surface>
-  );
-}

package/src/react/canvas/fitLabel.spec.ts

@@ -1,82 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { fitLabel } from './fitLabel';
-import { lodForNode, lodForZoom, lodShowsDetail, lodShowsText } from './lod';
-
-// A deterministic measurer: 6px per character at fontSize 12, scaling linearly.
-const measure = (t: string, size: number) => t.length * size * 0.5;
-
-describe('fitLabel — DESIGN.md §5, in the order the clause states', () => {
-  test('a name that fits is left alone', () => {
-    const fit = fitLabel('Ada Lovelace', { width: 200, fontSize: 12, measure });
-    expect(fit.lines).toEqual(['Ada Lovelace']);
-    expect(fit.strategy).toBe('as-is');
-    expect(fit.overflow).toBe(false);
-  });
-
-  test('middle names go before anything else does', () => {
-    // "Mary Anne Beth Sullivan" is 23 chars = 138px; "Mary Sullivan" is 13 = 78px.
-    const fit = fitLabel('Mary Anne Beth Sullivan', { width: 90, fontSize: 12, measure });
-    expect(fit.lines).toEqual(['Mary Sullivan']);
-    expect(fit.strategy).toBe('stripped');
-  });
-
-  test('then a clean second line, never a mid-word cut', () => {
-    const fit = fitLabel('Bartholomew Wickersham', { width: 80, fontSize: 12, measure });
-    expect(fit.lines.length).toBe(2);
-    expect(fit.lines.join(' ')).toBe('Bartholomew Wickersham');
-    // The load-bearing property: nothing is chopped.
-    for (const line of fit.lines) expect(line.endsWith('…')).toBe(false);
-  });
-
-  test('then the type scales down, in whole pixels', () => {
-    // 11 chars: 66px at 12, 55px at 10 — so it lands on 10 and stops there.
-    const fit = fitLabel('Bartholomew', { width: 58, fontSize: 12, measure });
-    expect(fit.strategy).toBe('scaled');
-    expect(Number.isInteger(fit.fontSize)).toBe(true);
-    expect(fit.fontSize).toBeLessThan(12);
-    expect(measure(fit.lines[0] as string, fit.fontSize)).toBeLessThanOrEqual(58);
-  });
-
-  test('the last rung is a first name and a last initial', () => {
-    // "Alexander Wickersham" is 20 chars and will not scale into 62px at the 10px
-    // floor; "Alexander W." is 12 chars = 60px, which does.
-    const fit = fitLabel('Alexander Wickersham', { width: 62, fontSize: 12, measure, maxLines: 1 });
-    expect(fit.lines).toEqual(['Alexander W.']);
-    expect(fit.strategy).toBe('initials');
-  });
-
-  test('a box too small for even that reports overflow, so the caller draws a glyph', () => {
-    const fit = fitLabel('Bartholomew Wickersham', { width: 4, fontSize: 12, measure });
-    expect(fit.overflow).toBe(true);
-    expect(fit.strategy).toBe('overflow');
-  });
-
-  test('empty and zero-width inputs do not throw', () => {
-    expect(fitLabel('', { width: 100, fontSize: 12 }).lines).toEqual(['']);
-    expect(fitLabel('x', { width: 0, fontSize: 12 }).overflow).toBe(true);
-  });
-});
-
-describe('lodForZoom — DESIGN.md §7 draws the line at 50%', () => {
-  test('full detail at 100%, names only in between, glyphs below half', () => {
-    expect(lodForZoom(1)).toBe('full');
-    expect(lodForZoom(0.6)).toBe('compact');
-    expect(lodForZoom(0.49)).toBe('glyph');
-  });
-
-  test('the 50% boundary itself still shows the name', () => {
-    expect(lodForZoom(0.5)).toBe('compact');
-    expect(lodShowsText(lodForZoom(0.5))).toBe(true);
-    expect(lodShowsDetail(lodForZoom(0.5))).toBe(false);
-  });
-
-  test('a hovered or focused node keeps its label at any zoom', () => {
-    // "until zoomed in OR HOVERED over" — the half that keeps a glyph field usable.
-    expect(lodForNode(0.1, false)).toBe('glyph');
-    expect(lodForNode(0.1, true)).toBe('full');
-  });
-
-  test('a nonsense zoom degrades to full detail rather than to nothing', () => {
-    expect(lodForZoom(Number.NaN)).toBe('full');
-  });
-});

package/src/react/canvas/fitLabel.ts

@@ -1,150 +0,0 @@
-/**
- * Fitting a human name into a node box without a harsh cut.
- *
- * `DESIGN.md` §5: *"Node diagrams, map elements, or tree visualizations displaying
- * user identities must never truncate names with harsh, broken text string cuts.
- * Use responsive font scaling, wrap long strings onto a clean second line, or
- * optimize middle-initial stripping to keep names human-readable."*
- *
- * That is three strategies in a stated order, and every canvas in the fleet was
- * improvising one of them (family's `TreeCanvas` does its own; the atlas does
- * none). This is the shared ladder, as a pure function with no DOM, so a `<text>`
- * in SVG, a 2D canvas and an absolutely-positioned `<div>` all fit labels the same
- * way and it can be tested without a browser.
- *
- * @see lodForZoom — below ~50% zoom the answer is not a smaller label, it is a glyph.
- */
-
-export type FitStrategy = 'as-is' | 'stripped' | 'wrapped' | 'scaled' | 'initials' | 'overflow';
-
-export interface FitLabelOptions {
-  /** Usable width of the node box, in px. */
-  width: number;
-  /** The size the label would like to be, in px. */
-  fontSize: number;
-  /** How many lines the box can hold. Default 2 — the "clean second line". */
-  maxLines?: number;
-  /** Never scale below this. Default 10px, which is `DESIGN.md` §4's floor minus
-   *  the two px a canvas label is allowed as a non-body-text glyph label. */
-  minFontSize?: number;
-  /**
-   * Width of `text` at `fontSize`. The default is a linear approximation
-   * (0.52em average advance, which is close for a UI sans at these sizes); a
-   * caller holding a real `CanvasRenderingContext2D` should pass `measureText`
-   * so the fit is exact.
-   */
-  measure?: (text: string, fontSize: number) => number;
-}
-
-export interface FittedLabel {
-  /** One entry per rendered line. Never empty. */
-  lines: string[];
-  /** The size to actually draw at. */
-  fontSize: number;
-  /** What the ladder had to do — surfaced so a caller can offer the full name in a
-   *  hint exactly when something was dropped, rather than always or never. */
-  strategy: FitStrategy;
-  /** True when even the last rung does not fit. Draw a glyph, not an ellipsis. */
-  overflow: boolean;
-}
-
-const defaultMeasure = (text: string, fontSize: number) => text.length * fontSize * 0.52;
-
-/** `Mary Anne Beth Sullivan` → `Mary Sullivan`; drops middles, keeps first + last. */
-function stripMiddles(parts: string[]): string[] {
-  if (parts.length <= 2) return parts;
-  return [parts[0] as string, parts[parts.length - 1] as string];
-}
-
-/** `Mary Sullivan` → `Mary S.` — the last rung before giving up on text entirely. */
-function toInitialForm(parts: string[]): string {
-  if (parts.length === 0) return '';
-  if (parts.length === 1) return parts[0] as string;
-  const first = parts[0] as string;
-  const last = parts[parts.length - 1] as string;
-  return `${first} ${last.charAt(0).toUpperCase()}.`;
-}
-
-/** Greedy word wrap into at most `maxLines`; returns null if it does not fit. */
-function wrap(
-  words: string[],
-  width: number,
-  fontSize: number,
-  maxLines: number,
-  measure: (t: string, s: number) => number,
-): string[] | null {
-  const lines: string[] = [];
-  let current = '';
-  for (const word of words) {
-    const candidate = current ? `${current} ${word}` : word;
-    if (measure(candidate, fontSize) <= width || !current) {
-      current = candidate;
-    } else {
-      lines.push(current);
-      current = word;
-      if (lines.length >= maxLines) return null;
-    }
-  }
-  if (current) lines.push(current);
-  if (lines.length === 0 || lines.length > maxLines) return null;
-  return lines.every((l) => measure(l, fontSize) <= width) ? lines : null;
-}
-
-/**
- * Fit `text` into `width`, in `DESIGN.md` §5's stated order: as-is → drop middle
- * names → wrap onto a second line → scale the type down → first name + last
- * initial → give up and tell the caller to draw a glyph.
- */
-export function fitLabel(text: string, options: FitLabelOptions): FittedLabel {
-  const {
-    width,
-    fontSize,
-    maxLines = 2,
-    minFontSize = 10,
-    measure = defaultMeasure,
-  } = options;
-  const clean = String(text ?? '').trim().replace(/\s+/g, ' ');
-  if (!clean) return { lines: [''], fontSize, strategy: 'as-is', overflow: false };
-  if (width <= 0) return { lines: [clean], fontSize, strategy: 'overflow', overflow: true };
-
-  if (measure(clean, fontSize) <= width) {
-    return { lines: [clean], fontSize, strategy: 'as-is', overflow: false };
-  }
-
-  const parts = clean.split(' ');
-  const stripped = stripMiddles(parts).join(' ');
-  if (stripped !== clean && measure(stripped, fontSize) <= width) {
-    return { lines: [stripped], fontSize, strategy: 'stripped', overflow: false };
-  }
-
-  if (maxLines > 1) {
-    const wrapped = wrap(stripped.split(' '), width, fontSize, maxLines, measure);
-    if (wrapped) {
-      return {
-        lines: wrapped,
-        fontSize,
-        strategy: stripped === clean ? 'wrapped' : 'stripped',
-        overflow: false,
-      };
-    }
-  }
-
-  // Scale down in whole pixels — a fractional ladder produces sizes that differ
-  // between two adjacent nodes by less than the eye can see, for no extra fit.
-  for (let size = fontSize - 1; size >= minFontSize; size--) {
-    const wrapped =
-      maxLines > 1
-        ? wrap(stripped.split(' '), width, size, maxLines, measure)
-        : measure(stripped, size) <= width
-          ? [stripped]
-          : null;
-    if (wrapped) return { lines: wrapped, fontSize: size, strategy: 'scaled', overflow: false };
-  }
-
-  const initials = toInitialForm(parts);
-  if (measure(initials, minFontSize) <= width) {
-    return { lines: [initials], fontSize: minFontSize, strategy: 'initials', overflow: false };
-  }
-
-  return { lines: [initials], fontSize: minFontSize, strategy: 'overflow', overflow: true };
-}

package/src/react/canvas/index.ts

@@ -1,15 +0,0 @@
-export {
-  CanvasNavHUD,
-  type CanvasMinimapPoint,
-  type CanvasNavHUDProps,
-  type CanvasRect,
-} from './CanvasNavHUD';
-export { fitLabel, type FitLabelOptions, type FittedLabel, type FitStrategy } from './fitLabel';
-export {
-  type CanvasLod,
-  lodForNode,
-  lodForZoom,
-  lodShowsDetail,
-  lodShowsText,
-  type LodThresholds,
-} from './lod';