cursedbelt 5.45.0 → 5.46.0

package/src/react/canvas-hud/HudControls.spec.tsx

@@ -0,0 +1,160 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { CanvasMinimap } from './CanvasMinimap.js';
+import { CanvasSearchField } from './CanvasSearchField.js';
+import { HudButton, HudZoomControls } from './HudControls.js';
+import { readWheel } from './useCanvasWheel.js';
+
+afterEach(cleanup);
+
+describe('HudZoomControls (CNV-3)', () => {
+  test('draws the zoom as a percentage and wires −, +, Fit and Center', () => {
+    const calls: string[] = [];
+    const { getByRole, getByTestId } = render(
+      <HudZoomControls
+        scale={0.734}
+        onZoomIn={() => calls.push('in')}
+        onZoomOut={() => calls.push('out')}
+        onFit={() => calls.push('fit')}
+        onCenter={() => calls.push('center')}
+      />,
+    );
+    expect(getByTestId('hud-zoom').textContent).toBe('73%');
+    for (const name of ['Zoom out', 'Zoom in', 'Fit to screen', 'Center on the selection']) {
+      fireEvent.click(getByRole('button', { name }));
+    }
+    expect(calls).toEqual(['out', 'in', 'fit', 'center']);
+  });
+
+  test('no Center key when the canvas has nothing to centre on', () => {
+    const { queryByRole } = render(
+      <HudZoomControls scale={1} onZoomIn={() => {}} onZoomOut={() => {}} onFit={() => {}} />,
+    );
+    expect(queryByRole('button', { name: 'Center on the selection' })).toBeNull();
+  });
+});
+
+describe('HudButton', () => {
+  test('a toggle announces its pressed state; a refused one stays focusable and does not fire', () => {
+    const onClick = mock(() => {});
+    const { getByRole } = render(
+      <>
+        <HudButton label='Map' pressed onClick={() => {}}>
+          ▦
+        </HudButton>
+        <HudButton label='Arrange' unavailableReason='Not in this view' onClick={onClick}>
+          ⇹
+        </HudButton>
+      </>,
+    );
+    expect(getByRole('button', { name: 'Map' }).getAttribute('aria-pressed')).toBe('true');
+    const refused = getByRole('button', { name: 'Arrange' });
+    expect(refused.getAttribute('aria-disabled')).toBe('true');
+    fireEvent.click(refused);
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});
+
+describe('CanvasSearchField', () => {
+  test('keys stop at the field, so a canvas binding the arrows on an ancestor never sees them', () => {
+    const canvasKeys = mock(() => {});
+    const { getByRole } = render(
+      // biome-ignore lint/a11y/noStaticElementInteractions: a stand-in for the canvas's own key binding
+      <div onKeyDown={canvasKeys}>
+        <CanvasSearchField value='ann' onChange={() => {}} aria-label='Find' />
+      </div>,
+    );
+    fireEvent.keyDown(getByRole('searchbox'), { key: 'ArrowLeft' });
+    expect(canvasKeys).not.toHaveBeenCalled();
+  });
+
+  test('Enter steps forward, Shift+Enter back, Escape empties', () => {
+    const steps: number[] = [];
+    const onChange = mock((_: string) => {});
+    const { getByRole, getByText } = render(
+      <CanvasSearchField
+        value='ann'
+        onChange={onChange}
+        onStep={(d) => steps.push(d)}
+        matches={3}
+        index={1}
+        aria-label='Find'
+      />,
+    );
+    const box = getByRole('searchbox');
+    fireEvent.keyDown(box, { key: 'Enter' });
+    fireEvent.keyDown(box, { key: 'Enter', shiftKey: true });
+    fireEvent.keyDown(box, { key: 'Escape' });
+    expect(steps).toEqual([1, -1]);
+    expect(onChange).toHaveBeenCalledWith('');
+    getByText('2/3');
+  });
+
+  test('a ✕ empties it too — a phone has no Escape key', () => {
+    const onChange = mock((_: string) => {});
+    const { getByRole, rerender, queryByRole } = render(
+      <CanvasSearchField value='ann' onChange={onChange} aria-label='Find' />,
+    );
+    fireEvent.click(getByRole('button', { name: 'Clear the search — Escape' }));
+    expect(onChange).toHaveBeenCalledWith('');
+    rerender(<CanvasSearchField value='' onChange={onChange} aria-label='Find' />);
+    expect(queryByRole('button', { name: 'Clear the search — Escape' })).toBeNull();
+  });
+});
+
+describe('CanvasMinimap', () => {
+  test('draws the visible window in world units, and a click jumps in world units', () => {
+    const jumps: { x: number; y: number }[] = [];
+    const { getByTestId, container } = render(
+      <CanvasMinimap
+        bounds={{ x: 0, y: 0, width: 1000, height: 500 }}
+        view={{ x: -500, y: 0, scale: 0.5 }}
+        viewport={{ width: 400, height: 200 }}
+        onJump={(p) => jumps.push(p)}
+        size={100}
+      />,
+    );
+    const win = getByTestId('canvas-minimap-window');
+    expect(win.getAttribute('x')).toBe('1000');
+    expect(win.getAttribute('width')).toBe('800');
+    const svg = container.querySelector('svg') as SVGSVGElement;
+    svg.getBoundingClientRect = () => ({ left: 10, top: 20 }) as DOMRect;
+    fireEvent.click(svg, { clientX: 60, clientY: 30 });
+    // 100px across 1000 units: one pixel is ten units.
+    expect(jumps).toEqual([{ x: 500, y: 100 }]);
+  });
+
+  test('draws nothing before there is anything to map', () => {
+    const { container } = render(
+      <CanvasMinimap
+        bounds={{ x: 0, y: 0, width: 0, height: 0 }}
+        view={{ x: 0, y: 0, scale: 1 }}
+        viewport={{ width: 400, height: 200 }}
+      />,
+    );
+    expect(container.innerHTML).toBe('');
+  });
+});
+
+describe('readWheel (CNV-1: one gesture, one meaning)', () => {
+  const wheel = (over: Partial<WheelEvent> = {}) => ({
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    deltaX: 0,
+    deltaY: 10,
+    ...over,
+  });
+  test('a pinch (ctrl+wheel) and ⌘+wheel zoom in every mode', () => {
+    for (const mode of ['full', 'full-zoom', 'embedded'] as const) {
+      expect(readWheel(mode, wheel({ ctrlKey: true }))).toBe('zoom');
+      expect(readWheel(mode, wheel({ metaKey: true }))).toBe('zoom');
+    }
+  });
+  test('a plain wheel pans a full canvas, zooms a map-style one, and scrolls the page past an embedded one', () => {
+    expect(readWheel('full', wheel())).toBe('pan');
+    expect(readWheel('full-zoom', wheel())).toBe('zoom');
+    expect(readWheel('full-zoom', wheel({ shiftKey: true }))).toBe('pan');
+    expect(readWheel('embedded', wheel())).toBe('page');
+  });
+});

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

@@ -0,0 +1,128 @@
+import type { ReactNode } from 'react';
+import { HudPill } from '../components/HudPill.js';
+import { IconButton } from '../components/IconButton.js';
+import { IconCenter, IconFit, IconZoomIn, IconZoomOut } from '../icons.js';
+import { cn } from '../lib/cn.js';
+
+/*
+ * The canvas HUD (CNV-3, CNV-4) — the floating chrome every pan-and-zoom canvas carries, built
+ * from the four the fleet had each drawn for itself (task 2401): family's tree (`TreeCanvas.tsx`,
+ * its zoom cluster, locator and find pill), patterns' and fractals' studios, and desk's boards.
+ *
+ * Every control is a belt `IconButton` / `Button` in a `HudPill`, so a canvas never hand-rolls a
+ * button again. Positioning is the canvas's: each piece takes `className` and is placed with
+ * `absolute bottom-4 right-4` and the like inside the canvas's own relative box (HudPill's rule).
+ *
+ * 🔴 One module per piece, never one file for all of them: a bundler splits by MODULE, so a
+ * canvas that draws the zoom keys on first paint and opens its node menu lazily would otherwise
+ * carry the menu's Popover in its entry chunk (family measured +27.8 kB gzip, task 2401).
+ */
+
+export interface HudButtonProps {
+  /** What it does — the accessible name and the hover hint. */
+  label: string;
+  onClick: () => void;
+  children: ReactNode;
+  /** Present only on a control that TOGGLES, so the others announce no pressed state. */
+  pressed?: boolean;
+  /** Why it cannot act right now: drawn disabled, still focusable, the reason on hover. */
+  unavailableReason?: string | null;
+  className?: string;
+}
+
+/** One HUD control — an icon-sized belt `IconButton`, with a pressed state for a toggle. */
+export function HudButton({ label, onClick, children, pressed, unavailableReason, className }: HudButtonProps) {
+  return (
+    <IconButton
+      label={label}
+      size='sm'
+      aria-pressed={pressed}
+      unavailableReason={unavailableReason ?? undefined}
+      tooltipMobile='off'
+      onClick={onClick}
+      className={cn('text-muted-foreground aria-pressed:bg-muted aria-pressed:text-foreground', className)}
+    >
+      {children}
+    </IconButton>
+  );
+}
+
+export interface HudZoomControlsProps {
+  /** The live scale; drawn as a percentage. */
+  scale: number;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  /** Fit the content to the screen. */
+  onFit: () => void;
+  /** Center on the focused node. Omit it when the canvas has no focus to centre on. */
+  onCenter?: () => void;
+  fitLabel?: string;
+  centerLabel?: string;
+  /** The canvas's own utilities, drawn before the zoom keys in the same pill (CNV-4 — utilities
+   *  only; preferences and primary actions belong in the page's panel). */
+  children?: ReactNode;
+  className?: string;
+}
+
+/** CNV-3's essentials as one pill: −, the zoom %, +, Fit and Center. */
+export function HudZoomControls({
+  scale,
+  onZoomIn,
+  onZoomOut,
+  onFit,
+  onCenter,
+  fitLabel = 'Fit to screen',
+  centerLabel = 'Center on the selection',
+  children,
+  className,
+}: HudZoomControlsProps) {
+  return (
+    <HudPill role='group' aria-label='View' className={cn('gap-0.5 rounded-lg px-1 py-1', className)}>
+      {children}
+      <HudButton label='Zoom out' onClick={onZoomOut}>
+        <IconZoomOut />
+      </HudButton>
+      <span className='min-w-11 text-center text-xs text-muted-foreground tabular-nums' data-testid='hud-zoom'>
+        {Math.round(scale * 100)}%
+      </span>
+      <HudButton label='Zoom in' onClick={onZoomIn}>
+        <IconZoomIn />
+      </HudButton>
+      <HudButton label={fitLabel} onClick={onFit}>
+        <IconFit />
+      </HudButton>
+      {onCenter ? (
+        <HudButton label={centerLabel} onClick={onCenter}>
+          <IconCenter />
+        </HudButton>
+      ) : null}
+    </HudPill>
+  );
+}
+
+export interface CanvasZoomHintProps {
+  /** `useCanvasWheel(…).hint` — up while the reader wheels over an embedded canvas. */
+  show: boolean;
+  className?: string;
+}
+
+/**
+ * CNV-1's "Hold ⌘ to zoom" — what an embedded canvas says when a plain wheel scrolled the page
+ * instead of zooming it, the way an embedded Google Map does. Says Ctrl off a Mac.
+ */
+export function CanvasZoomHint({ show, className }: CanvasZoomHintProps) {
+  const mac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+  return (
+    <div
+      aria-hidden={!show}
+      data-testid='canvas-zoom-hint'
+      className={cn(
+        'pointer-events-none absolute inset-0 grid place-items-center bg-background/40 transition-opacity duration-200',
+        show ? 'opacity-100' : 'opacity-0',
+        className,
+      )}
+    >
+      <HudPill className='px-3 py-1.5 text-sm'>Hold {mac ? '⌘' : 'Ctrl'} to zoom</HudPill>
+    </div>
+  );
+}

package/src/react/canvas-hud/index.ts

@@ -0,0 +1,33 @@
+// cursedbelt/react/canvas-hud — the viewport arithmetic and the floating chrome every pan-and-zoom
+// canvas carries (docs/design/canvas.md, CNV-1…CNV-5; forge task 2401). Its own subpath, so a
+// page with no canvas never pulls it in.
+export type { CanvasMinimapProps } from './CanvasMinimap.js';
+export { CanvasMinimap } from './CanvasMinimap.js';
+export type { CanvasNodeMenuItem, CanvasNodeMenuProps, CanvasNodeMenuSection } from './CanvasNodeMenu.js';
+export { CanvasNodeMenu } from './CanvasNodeMenu.js';
+export type { CanvasSearchFieldProps } from './CanvasSearchField.js';
+export { CanvasSearchField } from './CanvasSearchField.js';
+export type { CanvasZoomHintProps, HudButtonProps, HudZoomControlsProps } from './HudControls.js';
+export { CanvasZoomHint, HudButton, HudZoomControls } from './HudControls.js';
+export type { CanvasWheelMode, CanvasWheelOptions } from './useCanvasWheel.js';
+export { readWheel, useCanvasWheel, useLevelOfDetail } from './useCanvasWheel.js';
+export type {
+  CanvasBounds,
+  CanvasPoint,
+  CanvasSize,
+  CanvasView,
+  FitOptions,
+  LevelOfDetail,
+  LevelOfDetailThresholds,
+} from './viewport.js';
+export {
+  centerView,
+  clampScale,
+  fitScale,
+  fitView,
+  LEVEL_OF_DETAIL,
+  levelOfDetail,
+  visibleBounds,
+  wheelZoomFactor,
+  zoomAt,
+} from './viewport.js';

package/src/react/canvas-hud/useCanvasWheel.ts

@@ -0,0 +1,99 @@
+import { type RefObject, useEffect, useRef, useState } from 'react';
+import {
+  type CanvasPoint,
+  LEVEL_OF_DETAIL,
+  type LevelOfDetail,
+  type LevelOfDetailThresholds,
+  levelOfDetail,
+  wheelZoomFactor,
+} from './viewport.js';
+
+/**
+ * How a canvas reads the wheel (CNV-1 — one gesture, one meaning, on every surface):
+ *
+ * - `'full'` — the canvas owns the viewport and the page does not scroll. Pinch and ⌘/Ctrl+wheel
+ *   zoom; a plain wheel or a two-finger swipe PANS (Figma, Miro).
+ * - `'full-zoom'` — the same, except a plain wheel ZOOMS, the way a full-page map does. For a
+ *   canvas whose readers already zoom with a mouse wheel (family's tree): a shift+wheel pans.
+ * - `'embedded'` — the page scrolls past the canvas. A plain wheel is the PAGE's and is left
+ *   alone; pinch and ⌘/Ctrl+wheel zoom; the hook raises `hint` so the canvas can say
+ *   "Hold ⌘ to zoom", the way an embedded Google Map does.
+ */
+export type CanvasWheelMode = 'full' | 'full-zoom' | 'embedded';
+
+export interface CanvasWheelOptions {
+  mode: CanvasWheelMode;
+  /** Zoom by `factor` about `anchor` (viewport pixels). The canvas clamps. */
+  onZoom: (factor: number, anchor: CanvasPoint) => void;
+  /** Pan by screen pixels. Unused in `'embedded'` mode. */
+  onPan?: (dx: number, dy: number) => void;
+  /** How long the embedded hint stays up after the last plain wheel. Default 1200 ms. */
+  hintMs?: number;
+}
+
+/** The decision, separated from the DOM so it is testable: what one wheel event means. */
+export function readWheel(
+  mode: CanvasWheelMode,
+  event: Pick<WheelEvent, 'ctrlKey' | 'metaKey' | 'shiftKey' | 'deltaX' | 'deltaY'>,
+): 'zoom' | 'pan' | 'page' {
+  // A trackpad pinch arrives as a wheel event with ctrlKey set, on every browser.
+  if (event.ctrlKey || event.metaKey) return 'zoom';
+  if (mode === 'embedded') return 'page';
+  if (mode === 'full-zoom') return event.shiftKey ? 'pan' : 'zoom';
+  return 'pan';
+}
+
+/**
+ * Binds the wheel on `ref` per {@link CanvasWheelMode}.
+ *
+ * 🔴 A NON-passive native listener, never a JSX `onWheel`: React registers `wheel` at the root as
+ * passive, so `preventDefault()` there is ignored and the page scrolls (or zooms the whole
+ * browser on a pinch) under the canvas.
+ */
+export function useCanvasWheel(ref: RefObject<HTMLElement | null>, options: CanvasWheelOptions): { hint: boolean } {
+  const latest = useRef(options);
+  latest.current = options;
+  const [hint, setHint] = useState(false);
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onWheel = (event: WheelEvent): void => {
+      const { mode, onZoom, onPan, hintMs = 1200 } = latest.current;
+      const meaning = readWheel(mode, event);
+      if (meaning === 'page') {
+        setHint(true);
+        clearTimeout(timer);
+        timer = setTimeout(() => setHint(false), hintMs);
+        return;
+      }
+      event.preventDefault();
+      if (meaning === 'zoom') {
+        const rect = element.getBoundingClientRect();
+        onZoom(wheelZoomFactor(event.deltaY), { x: event.clientX - rect.left, y: event.clientY - rect.top });
+        return;
+      }
+      // A shift+wheel from a mouse reports its motion on Y; a sideways trackpad swipe on X.
+      const dx = event.shiftKey && event.deltaX === 0 ? event.deltaY : event.deltaX;
+      const dy = event.shiftKey && event.deltaX === 0 ? 0 : event.deltaY;
+      onPan?.(-dx, -dy);
+    };
+    element.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+      clearTimeout(timer);
+      element.removeEventListener('wheel', onWheel);
+    };
+  }, [ref]);
+  return { hint };
+}
+
+/**
+ * CNV-5 — the density to draw at this scale. A string that changes only at a threshold, so an
+ * effect or memo keyed on it re-runs three times across the whole zoom range, not every frame.
+ */
+export function useLevelOfDetail(
+  scale: number,
+  thresholds: LevelOfDetailThresholds = LEVEL_OF_DETAIL,
+): LevelOfDetail {
+  return levelOfDetail(scale, thresholds);
+}

package/src/react/canvas-hud/viewport.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  centerView,
+  clampScale,
+  fitScale,
+  fitView,
+  levelOfDetail,
+  visibleBounds,
+  wheelZoomFactor,
+  zoomAt,
+} from './viewport.js';
+
+/** Where a world point lands on screen under a view. */
+const toScreen = (view: { x: number; y: number; scale: number }, p: { x: number; y: number }) => ({
+  x: p.x * view.scale + view.x,
+  y: p.y * view.scale + view.y,
+});
+const toWorld = (view: { x: number; y: number; scale: number }, p: { x: number; y: number }) => ({
+  x: (p.x - view.x) / view.scale,
+  y: (p.y - view.y) / view.scale,
+});
+
+describe('zoomAt (CNV-2: zoom anchors on the pointer)', () => {
+  test('the world point under the anchor stays under the anchor', () => {
+    const view = { x: -120, y: 40, scale: 0.8 };
+    const anchor = { x: 311, y: 207 };
+    const under = toWorld(view, anchor);
+    for (const scale of [0.1, 0.5, 1.7, 4]) {
+      const next = zoomAt(view, scale, anchor);
+      expect(next.scale).toBe(scale);
+      const landed = toScreen(next, under);
+      expect(landed.x).toBeCloseTo(anchor.x, 9);
+      expect(landed.y).toBeCloseTo(anchor.y, 9);
+    }
+  });
+
+  test('a non-finite or non-positive scale leaves the view alone', () => {
+    const view = { x: 3, y: 4, scale: 1 };
+    expect(zoomAt(view, Number.NaN, { x: 0, y: 0 })).toBe(view);
+    expect(zoomAt(view, 0, { x: 0, y: 0 })).toBe(view);
+    expect(zoomAt(view, Number.POSITIVE_INFINITY, { x: 0, y: 0 })).toBe(view);
+  });
+
+  test('a wheel notch in and the same notch out return to the same scale', () => {
+    expect(wheelZoomFactor(100) * wheelZoomFactor(-100)).toBeCloseTo(1, 12);
+    expect(wheelZoomFactor(-100)).toBeGreaterThan(1);
+  });
+});
+
+describe('fit and center (CNV-3)', () => {
+  test('fit shrinks a large extent and centres it', () => {
+    const bounds = { x: 100, y: 50, width: 4000, height: 1000 };
+    const viewport = { width: 1000, height: 600 };
+    const view = fitView(bounds, viewport, { padding: 50 });
+    expect(view).not.toBeNull();
+    if (!view) return;
+    expect(view.scale).toBeCloseTo(900 / 4000, 12);
+    const middle = toScreen(view, { x: 2100, y: 550 });
+    expect(middle.x).toBeCloseTo(500, 9);
+    expect(middle.y).toBeCloseTo(300, 9);
+  });
+
+  test('fit never magnifies past maxScale (default 1)', () => {
+    expect(fitScale({ width: 10, height: 10 }, { width: 1000, height: 1000 })).toBe(1);
+    expect(fitScale({ width: 10, height: 10 }, { width: 1000, height: 1000 }, { maxScale: 2 })).toBe(2);
+  });
+
+  test('fit has nothing to do before the viewport is measured or with an empty extent', () => {
+    expect(fitScale({ width: 0, height: 10 }, { width: 100, height: 100 })).toBeNull();
+    expect(fitView({ x: 0, y: 0, width: 10, height: 10 }, { width: 0, height: 0 })).toBeNull();
+  });
+
+  test('fit is floored at minScale, so a huge extent is still drawable', () => {
+    expect(fitScale({ width: 1e9, height: 1 }, { width: 400, height: 400 })).toBe(0.02);
+  });
+
+  test('center puts the point in the middle at the asked scale', () => {
+    const view = centerView({ x: 40, y: -20 }, { width: 800, height: 400 }, 2);
+    expect(toScreen(view, { x: 40, y: -20 })).toEqual({ x: 400, y: 200 });
+  });
+
+  test('visibleBounds is the inverse of the view', () => {
+    const view = { x: -200, y: -100, scale: 0.5 };
+    expect(visibleBounds(view, { width: 800, height: 600 })).toEqual({ x: 400, y: 200, width: 1600, height: 1200 });
+  });
+
+  test('clampScale', () => {
+    expect(clampScale(5, 0.1, 2)).toBe(2);
+    expect(clampScale(0.01, 0.1, 2)).toBe(0.1);
+  });
+});
+
+describe('levelOfDetail (CNV-5)', () => {
+  test('far under 30%, mid to 50%, close from 50%', () => {
+    expect(levelOfDetail(0.29)).toBe('far');
+    expect(levelOfDetail(0.3)).toBe('mid');
+    expect(levelOfDetail(0.49)).toBe('mid');
+    expect(levelOfDetail(0.5)).toBe('close');
+    expect(levelOfDetail(2)).toBe('close');
+  });
+
+  test('a canvas may move the thresholds', () => {
+    expect(levelOfDetail(0.4, { mid: 0.2, close: 0.4 })).toBe('close');
+  });
+});

package/src/react/canvas-hud/viewport.ts

@@ -0,0 +1,124 @@
+/**
+ * The camera arithmetic every pan-and-zoom canvas needs (CNV-2, CNV-3, CNV-5).
+ *
+ * Pure — no React, no DOM — so each rule is pinned by a spec rather than by opening an app.
+ * A view maps a WORLD point to the screen as `screen = world × scale + (x, y)`: `x`/`y` are the
+ * screen position of the world origin, which is what a CSS `translate(x, y) scale(scale)` on the
+ * stage means. Every canvas in the fleet already used that convention (family's `Camera`,
+ * patterns' `viewportGestures.ts`, desk's xyflow viewport), which is why it is the one here.
+ */
+
+export interface CanvasView {
+  x: number;
+  y: number;
+  scale: number;
+}
+
+export interface CanvasPoint {
+  x: number;
+  y: number;
+}
+
+export interface CanvasSize {
+  width: number;
+  height: number;
+}
+
+/** A rectangle in WORLD units — the content's extent, or the visible window. */
+export interface CanvasBounds extends CanvasPoint, CanvasSize {}
+
+export function clampScale(scale: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, scale));
+}
+
+/**
+ * CNV-2 — zoom to `scale` keeping the screen point `anchor` still: the pointer for a wheel or a
+ * pinch, the middle of the viewport for the ± buttons. The caller clamps `scale` first, because
+ * the floor is the canvas's own business (family floors it at the whole tree).
+ */
+export function zoomAt(view: CanvasView, scale: number, anchor: CanvasPoint): CanvasView {
+  if (!Number.isFinite(scale) || scale <= 0 || view.scale <= 0) return view;
+  const applied = scale / view.scale;
+  return {
+    scale,
+    x: anchor.x - (anchor.x - view.x) * applied,
+    y: anchor.y - (anchor.y - view.y) * applied,
+  };
+}
+
+/** The zoom factor for one wheel event — exponential, so a trackpad pinch (which arrives as a
+ *  ctrl+wheel stream of small deltas) and a mouse notch feel equally linear. */
+export function wheelZoomFactor(deltaY: number): number {
+  return Math.exp(-deltaY * 0.0015);
+}
+
+export interface FitOptions {
+  /** Screen pixels of breathing room on every side. Default 48. */
+  padding?: number;
+  /**
+   * The largest scale a fit may land on. Default 1: fit SHRINKS to fit and never magnifies a
+   * small graph past its natural size — a two-node graph "fitted" to 400% reads as a zoom
+   * nobody asked for (Figma's and Miro's zoom-to-fit behave the same way).
+   */
+  maxScale?: number;
+  /** The smallest. Default 0.02 — a degenerate extent must still be a drawable number. */
+  minScale?: number;
+}
+
+/** The scale at which `bounds` fits the viewport, or `null` while there is nothing to fit
+ *  (an empty extent, or a viewport not measured yet). */
+export function fitScale(bounds: CanvasSize, viewport: CanvasSize, options: FitOptions = {}): number | null {
+  const { padding = 48, maxScale = 1, minScale = 0.02 } = options;
+  if (bounds.width <= 0 || bounds.height <= 0 || viewport.width <= 0 || viewport.height <= 0) return null;
+  const scale = Math.min(
+    (viewport.width - padding * 2) / bounds.width,
+    (viewport.height - padding * 2) / bounds.height,
+  );
+  if (!Number.isFinite(scale)) return null;
+  return clampScale(scale, minScale, maxScale);
+}
+
+/** CNV-3 "Fit" — the view that centres `bounds` in the viewport at {@link fitScale}. */
+export function fitView(bounds: CanvasBounds, viewport: CanvasSize, options: FitOptions = {}): CanvasView | null {
+  const scale = fitScale(bounds, viewport, options);
+  if (scale === null) return null;
+  return centerView({ x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 }, viewport, scale);
+}
+
+/** CNV-3 "Center" — the view that puts the world point `point` in the middle of the viewport. */
+export function centerView(point: CanvasPoint, viewport: CanvasSize, scale: number): CanvasView {
+  return {
+    scale,
+    x: viewport.width / 2 - point.x * scale,
+    y: viewport.height / 2 - point.y * scale,
+  };
+}
+
+/** The part of the world the viewport shows — what a minimap draws as its window. */
+export function visibleBounds(view: CanvasView, viewport: CanvasSize): CanvasBounds {
+  return {
+    x: -view.x / view.scale,
+    y: -view.y / view.scale,
+    width: viewport.width / view.scale,
+    height: viewport.height / view.scale,
+  };
+}
+
+/** CNV-5's three densities. */
+export type LevelOfDetail = 'far' | 'mid' | 'close';
+
+export interface LevelOfDetailThresholds {
+  /** At and above this scale, primary labels may appear. Default 0.3. */
+  mid: number;
+  /** At and above this scale, full labels and metadata. Default 0.5. */
+  close: number;
+}
+
+export const LEVEL_OF_DETAIL: LevelOfDetailThresholds = { mid: 0.3, close: 0.5 };
+
+/** CNV-5 — which density a canvas draws at this scale. */
+export function levelOfDetail(scale: number, thresholds: LevelOfDetailThresholds = LEVEL_OF_DETAIL): LevelOfDetail {
+  if (scale >= thresholds.close) return 'close';
+  if (scale >= thresholds.mid) return 'mid';
+  return 'far';
+}

package/src/react/charts/capacityFormat.spec.ts

@@ -1,6 +1,18 @@
 import { describe, expect, test } from 'bun:test';
 import { formatBytes, formatCount, formatDays, formatDelta, formatNumber, formatRate } from './format.js';
 
+describe('formatNumber', () => {
+  test('never rounds two axis ticks to one label', () => {
+    // A phone chart of small counts (max 1) ticks 0, 0.25, 0.5, 0.75, 1 — rounded, three read "1".
+    const ticks = [0, 0.25, 0.5, 0.75, 1].map(formatNumber);
+    expect(new Set(ticks).size).toBe(ticks.length);
+    expect(formatNumber(0.5)).toBe('0.5');
+    expect(formatNumber(12.5)).toBe('12.5');
+    expect(formatNumber(7)).toBe('7');
+    expect(formatNumber(1_500)).toBe('1.5k');
+  });
+});
+
 describe('formatDelta', () => {
   test('signs the magnitude with the caller’s formatter', () => {
     expect(formatDelta(1_048_576, formatBytes)).toStartWith('+');

package/src/react/charts/format.ts

@@ -11,7 +11,8 @@ export const formatNumber = (n: number): string => {
   if (abs >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
   if (abs >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
   if (abs >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
-  return Math.round(n).toString();
+  // A fraction keeps its digits: rounded, a count axis peaking at 1 ticks 0.5 as a second "1".
+  return Number(n.toFixed(abs < 10 ? 2 : abs < 100 ? 1 : 0)).toString();
 };
 
 export const formatMs = (n: number): string => {