@weasel-js/labkit 1.3.0 → 1.4.0-pre.1

package/src/annotations/types.ts

@@ -0,0 +1,229 @@
+import type { RefObject } from 'react';
+import type { ViewTransform } from '../instrument/types';
+import type { MarkScene } from './store';
+
+/** A point in fractions of a target's content box. */
+export interface FracPoint {
+  x: number;
+  y: number;
+}
+
+/** A rectangle in fractions of a target's content box.
+ *
+ *  Fractions rather than pixels because a mark must survive a change of render
+ *  resolution: the picture gets bigger, the mark stays on the same feature. */
+export interface FracRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** What shape a mark is. The kinds map onto weasel's own tools; an arrow is a
+ *  line carrying an end marker, not a separate geometry. */
+export type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text';
+
+/** One selectable status in an instrument's meaning tier. */
+export interface AnnotationStatus {
+  id: string;
+  label: string;
+  /** What a mark in this status is drawn in. Omitted, it takes the default
+   *  mark colour — a status is allowed to be a label and nothing more. */
+  color?: string;
+}
+
+/** The optional meaning tier: what a mark means, as opposed to where it is.
+ *  An instrument declaring it gets labkit's own chrome for the vocabulary;
+ *  one that omits it keeps `meta` and owns meaning entirely. */
+export interface AnnotationMeaning {
+  statuses?: readonly AnnotationStatus[];
+}
+
+/** What labkit keeps in a mark's scene-node data. */
+export interface AnnotationData {
+  target: string;
+  kind: AnnotationKind;
+  /** Vertices for the kinds a bounding box cannot describe — a line's two
+   *  ends, a stroke's path. In fractions, like the bounds. */
+  points?: readonly FracPoint[];
+  title?: string;
+  status?: string;
+  tags?: readonly string[];
+  meta?: unknown;
+  /** The target's `positionDependsOn` values when the mark was made. Compared
+   *  against the live config to answer whether the mark still describes the
+   *  same picture. */
+  seen?: Readonly<Record<string, unknown>>;
+}
+
+/** A mark, as the store reports it. `id` is `<target>/<node>`: one scene per
+ *  target means a node id is only unique within one. */
+export interface Annotation extends AnnotationData {
+  id: string;
+  /** Bounds in fractions of the target's content box. */
+  frac: FracRect;
+}
+
+/** A new mark, before the store gives it an id and dates it. */
+export interface AnnotationInit {
+  target: string;
+  kind: AnnotationKind;
+  frac: FracRect;
+  points?: readonly FracPoint[];
+  title?: string;
+  status?: string;
+  tags?: readonly string[];
+  meta?: unknown;
+}
+
+/** Filters, ANDed. A mark matches `tags` when it carries every tag listed. */
+export interface AnnotationQuery {
+  target?: string;
+  kind?: AnnotationKind;
+  status?: string;
+  tags?: readonly string[];
+  where?: (a: Annotation) => boolean;
+}
+
+/** What a mark's meaning can be patched to. Geometry moves through `frac` /
+ *  `points`; everything else is the meaning tier. */
+export type AnnotationPatch = Partial<
+  Pick<Annotation, 'frac' | 'points' | 'title' | 'status' | 'tags' | 'meta'>
+>;
+
+/** A target's own picture, handed over for an export to draw marks on top of.
+ *  labkit cannot rasterize it: it is the consumer's DOM. `svg` is the one that
+ *  keeps the export vector all the way through. */
+export type CaptureSource =
+  | { kind: 'svg'; markup: string }
+  | { kind: 'image'; src: string }
+  | { kind: 'canvas'; canvas: HTMLCanvasElement };
+
+/** What an export produces, and at what resolution. */
+export interface CaptureOptions {
+  /** `png` rasterizes; `svg` stays vector, which needs the base to be one too
+   *  — a raster base embeds as an `<image>`. Default `png`. */
+  format?: 'png' | 'svg';
+  /** Output pixels per unit of the target's content box. Default 2. */
+  scale?: number;
+}
+
+/** A finished export. `width`/`height` are the output's, not the content
+ *  box's — `content × scale`. */
+export interface CaptureResult {
+  target: string;
+  blob: Blob;
+  format: 'png' | 'svg';
+  width: number;
+  height: number;
+}
+
+/** What the store needs to know about a target: enough to convert a position
+ *  and to date a mark. `AnnotationTarget` adds what only the overlay reads. */
+export interface AnnotationTargetInfo {
+  id: string;
+  /** Intrinsic content size in CSS pixels at zoom 1 — the box fractions are
+   *  fractions *of*, and the target's world. */
+  content: { w: number; h: number };
+  /** Config keys whose change means a stored position no longer refers to the
+   *  same picture. labkit snapshots and compares them without knowing what any
+   *  of them mean. */
+  positionDependsOn?: readonly string[];
+  /** The target's own picture, for an export to draw marks over. A target
+   *  declaring none exports its marks on transparency, which fails visibly
+   *  rather than producing a blank brick.
+   *
+   *  Here rather than on `AnnotationTarget` because the store is what calls
+   *  it: `ref` and `view` are the React-shaped half only the overlay reads. */
+  base?: () => CaptureSource | Promise<CaptureSource>;
+}
+
+/** One region of an instrument that accepts marks. */
+export interface AnnotationTarget extends AnnotationTargetInfo {
+  /** The element the overlay tracks and takes input from. */
+  ref: RefObject<HTMLElement | null>;
+  /** The pane's camera, mirrored so marks pan and zoom with what they mark. */
+  view?: ViewTransform;
+}
+
+/** Where an instrument keeps its own marks. Declaring this means labkit never
+ *  writes its trial slot — for an instrument whose marks belong in a format it
+ *  already owns. Both halves are called outside React; `save` is already
+ *  debounced by the time it arrives. */
+export interface AnnotationStorage {
+  load: () => SerializedAnnotations | null | undefined;
+  save: (doc: SerializedAnnotations) => void;
+}
+
+/** Declares that an instrument accepts marks: which regions take them,
+ *  optionally what a mark is allowed to mean, and optionally where they live. */
+export interface AnnotationsCapability<TS = unknown, TC = unknown> {
+  targets: (state: TS, config: TC) => readonly AnnotationTarget[];
+  meaning?: AnnotationMeaning;
+  storage?: AnnotationStorage;
+  /** Fires after every finished export, labkit's own chrome included. A
+   *  notification, not an interception: a host wanting its own flow calls
+   *  `capture()` from its own UI, which is the surface the chrome uses. */
+  onCapture?: (result: CaptureResult) => void;
+}
+
+/** A persisted mark set. Versioned by this arc rather than by labkit's
+ *  document migrations, which only ever reach top-level document sections and
+ *  never into a trial's state. */
+export interface SerializedAnnotations {
+  version: 1;
+  /** One serialized scene per target that has ever held a mark. */
+  scenes: Record<string, unknown>;
+}
+
+/** Everything a host can ask or tell labkit about the marks on its targets. */
+export interface AnnotationsApi {
+  /** The scene a target's marks live in, created on first ask. One per target
+   *  because a pane's hit-test, marquee and paint walk the whole scene they
+   *  are given: a shared one would put a neighbour's marks under the pointer. */
+  sceneFor(target: string): MarkScene;
+  /** The targets the instrument declares, in declaration order. Chrome needs
+   *  the list and cannot get it from the capability, which wants instrument
+   *  state the chrome context does not carry. */
+  targets(): readonly AnnotationTargetInfo[];
+  get(id: string): Annotation | undefined;
+  /** Every mark matching the filters, in scene order. Omit `q` for all. */
+  query(q?: AnnotationQuery): Annotation[];
+  /** Marks whose bounds contain `pt`, topmost first. `tol` widens the hit in
+   *  fractions, so a hairline mark stays reachable. */
+  hitTest(target: string, pt: FracPoint, tol?: number): Annotation[];
+  /** Marks wholly inside `box` — a marquee, not a brush. */
+  within(target: string, box: FracRect): Annotation[];
+  /** Whether `a`'s position still describes the picture `config` produces. */
+  isStale(a: Annotation, config: unknown): boolean;
+  /** The marks the user currently has selected, across every target, as
+   *  annotation ids. Every one resolves through `get`. */
+  selection(): readonly string[];
+  /** Replace the selection. An id naming a target or a mark that is not
+   *  there is dropped, the way `update` and `remove` ignore one. */
+  setSelection(ids: readonly string[]): void;
+  /** Fires after every mutation *and* after a selection change — weasel keeps
+   *  a canvas's selection on the scene, so both already arrive on this one
+   *  channel. No delta: re-query, and re-read `selection()`. */
+  subscribe(fn: () => void): () => void;
+
+  /** Whether the last mark change on any target can be taken back. Weasel
+   *  history is the authority; this only decides *which* target's. */
+  canUndo(): boolean;
+  canRedo(): boolean;
+  /** Take back the most recent mark change, wherever it was made. */
+  undo(): boolean;
+  redo(): boolean;
+
+  /** Export a target's picture with its marks on it. Rejects on an id the
+   *  instrument does not declare. */
+  capture(target: string, opts?: CaptureOptions): Promise<CaptureResult>;
+
+  add(init: AnnotationInit, config?: unknown): string;
+  update(id: string, patch: AnnotationPatch): void;
+  setMeta(id: string, meta: unknown): void;
+  remove(id: string): void;
+
+  /** A JSON-safe snapshot for `record.state`. */
+  toJSON(): SerializedAnnotations;
+}

package/src/annotations/view.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { fitView, fromWeaselView, toWeaselView } from './view';
+
+describe('fitView', () => {
+  it("scales a target's content box to the box it is drawn in", () => {
+    expect(fitView({ w: 256, h: 170 }, { w: 512, h: 340 })).toEqual({
+      zoom: 2,
+      pan: { x: 0, y: 0 },
+    });
+  });
+
+  it('takes the smaller axis, so nothing is drawn past the pane', () => {
+    expect(fitView({ w: 256, h: 170 }, { w: 512, h: 170 })).toEqual({
+      zoom: 1,
+      pan: { x: 0, y: 0 },
+    });
+  });
+
+  it('reads zoom 1 from a degenerate content box rather than Infinity', () => {
+    expect(fitView({ w: 0, h: 0 }, { w: 512, h: 340 })).toEqual({ zoom: 1, pan: { x: 0, y: 0 } });
+  });
+});
+
+describe('view conversion', () => {
+  it("round-trips a target's camera through weasel's shape", () => {
+    const v = { zoom: 1.5, pan: { x: -12, y: 40 } };
+    expect(fromWeaselView(toWeaselView(v))).toEqual(v);
+  });
+
+  it("puts the pan in weasel's translation and the zoom in both scale axes", () => {
+    expect(toWeaselView({ zoom: 2, pan: { x: 10, y: -5 } })).toEqual({
+      x: 10,
+      y: -5,
+      scale: { x: 2, y: 2 },
+    });
+  });
+});

package/src/annotations/view.ts

@@ -0,0 +1,40 @@
+import type { View } from '@weasel-js/core';
+import type { ViewTransform } from '../instrument/types';
+
+/** A target's world in CSS pixels: the box its fractions are fractions of. */
+export interface ContentSize {
+  w: number;
+  h: number;
+}
+
+/** A target's drawn box on the surface, in CSS pixels. */
+export interface PaneSize {
+  w: number;
+  h: number;
+}
+
+/** labkit's camera in weasel's shape. Zoom is uniform, so it lands on both
+ *  scale axes; pan is weasel's translation unchanged. */
+export function toWeaselView(v: ViewTransform): View {
+  return { x: v.pan.x, y: v.pan.y, scale: { x: v.zoom, y: v.zoom } };
+}
+
+/** The inverse. A weasel view with unequal axis scales collapses to its x —
+ *  labkit's camera has one zoom and cannot hold the other. */
+export function fromWeaselView(v: View): ViewTransform {
+  return { zoom: v.scale.x, pan: { x: v.x, y: v.y } };
+}
+
+/**
+ * The camera a target with none of its own draws through: its content box
+ * scaled to fit the box it is drawn in, anchored at the origin.
+ *
+ * The spec calls the camera "a plain scale" at zoom 1; zoom 1 is only right
+ * when the pane happens to be the content's size, and a mark drawn on a
+ * scaled-down pane otherwise lands outside it.
+ */
+export function fitView(content: ContentSize, pane: PaneSize): ViewTransform {
+  const zoom =
+    content.w > 0 && content.h > 0 ? Math.min(pane.w / content.w, pane.h / content.h) : 1;
+  return { zoom: Number.isFinite(zoom) && zoom > 0 ? zoom : 1, pan: { x: 0, y: 0 } };
+}

package/src/canvas/AGENTS.md

@@ -18,7 +18,9 @@ into a camera is the host's job.
 | `CanvasStackContext.ts` | React context exposing the current `view` to descendants |
 | `useLayerScheduler.ts` | DPR-aware rAF scheduler; redraws dirty layers on view/state changes |
 | `usePanZoom.ts` | Pointer + wheel handlers that mutate `view` via `onViewChange` |
+| `camera.ts` | `zoomAt` (fixed-point zoom) and `centerOn` (put a world point at a viewport's middle) |
 | `canvasCoords.ts` | Pure `screenToWorld` / `worldToScreen` helpers |
+| `worldSpec.ts` | The instrument's declared coordinate system, and the camera derived from it |
 | `CanvasStack.less` | Container + canvas + overlay positioning |
 
 ## Props (`<CanvasStack>`)
@@ -28,6 +30,8 @@ interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];      // { id, visible, render(ctx, view) }
   view: ViewTransform;                  // { zoom, pan: { x, y } }
   onViewChange: (v: ViewTransform) => void;
+  worldSpec?: WorldSpec;                // origin + y direction; default top-left, y down
+  onResize?: (size: ViewportSize) => void;
   minZoom?: number;                     // default 0.1, forwarded to usePanZoom
   maxZoom?: number;                     // default 32, forwarded to usePanZoom
   width?: number | string;              // default '100%'
@@ -51,6 +55,7 @@ A layer is defined by the instrument's `canvas.layers[]` (type `CanvasLayer`), t
 
 ```ts
 canvas: {
+  worldSpec: { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' },   // optional
   layers: [
     {
       id: 'grid',
@@ -60,9 +65,9 @@ canvas: {
 }
 ```
 
-`draw` receives the context with the camera already applied, so its coordinates are world coordinates — `Trial.tsx` translates by `view.pan` and scales by `view.zoom` before calling it. `zoom` is still passed so a layer can keep line widths and handle sizes from growing: divide by it (`ctx.lineWidth = 1 / zoom`).
+`draw` receives the context with the camera already applied, so its coordinates are world coordinates — `Trial.tsx` calls `applyCamera(ctx, view, frame)` before calling it. `zoom` is still passed so a layer can keep line widths and handle sizes from growing: divide by it (`ctx.lineWidth = 1 / zoom`).
 
-That is the difference between the two layer types. The lower-level `CanvasLayerDescriptor.render(ctx, view)` gets the raw view and an untransformed context, which is what screen-space chrome wants.
+That is the difference between the two layer types. The lower-level `CanvasLayerDescriptor.render(ctx, view, frame)` gets the raw view, the resolved frame and an untransformed context, which is what screen-space chrome wants.
 
 Layer order in the array = paint order (first drawn = bottom).
 
@@ -70,17 +75,62 @@ Layer order in the array = paint order (first drawn = bottom).
 
 The `children` prop renders in `.lk-canvas-stack__overlay`, which is `position: absolute; inset: 0; pointer-events: none`. Direct children re-enable pointer events. Use this for HUDs, scale indicators, or interactive overlays that don't belong in a canvas layer.
 
+## The world spec
+
+An instrument's world does not have to be labkit's. `CanvasCapability.worldSpec`
+declares two things, and everything that maps between world and screen reads
+them:
+
+```ts
+worldSpec: { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' }   // centred, y upward
+```
+
+`origin` is a **fraction of the viewport** — where world (0,0) sits at `pan`
+zero — so "centre" is `0.5` and needs no knowledge of the canvas size. `yAxis`
+is `'down'` (default) or `'up'`. Omitting the spec entirely gives the original
+convention: origin at the element's top-left, y downward.
+
+`resolveFrame(spec, size)` turns a spec plus a measured viewport into a
+`WorldFrame` — `{ originPx, yDir }` — which is what the rest of the directory
+actually consumes. `CanvasStack` owns the measurement, so it owns the frame and
+hands it to `usePanZoom`, to the scheduler, and to every `render`.
+
+**Every world↔screen path must go through the frame.** There are four, and each
+one is a silent wrong answer if it is missed: `worldToScreen` / `screenToWorld`,
+the camera (`applyCamera`), the wheel anchor in `usePanZoom`, and
+`DragDropRuntime`'s drop position. A miss produces geometry that is off by a
+constant, or a wheel that drifts — never an error.
+
 ## Coordinate conversions
 
-- `screenToWorld({x, y}, view)` → world coords given a CSS-pixel offset relative to the container's top-left
-- `worldToScreen({x, y}, view)` → inverse
+- `screenToWorld({x, y}, view, frame?)` → world coords given a CSS-pixel offset relative to the container's top-left
+- `worldToScreen({x, y}, view, frame?)` → inverse
+- `applyCamera(ctx, view, frame?)` → puts a 2D context into world coordinates; the exact inverse of `screenToWorld`
 
-Both are pure. Pan is applied in screen space; zoom multiplies world coordinates.
+All pure, and all default to `DEFAULT_FRAME` (top-left, y down).
 
 ## Pan/zoom behavior
 
 Implemented in `usePanZoom`. Mouse-wheel zoom is anchored at the cursor; primary-button drag pans. `isDragging()` is exposed so consumers can suppress click handlers during a pan.
 
+The anchor is taken **in frame space** (`cursor - frame.originPx`), because
+`pan` is measured from the frame's origin. Anchoring at the raw cursor instead
+drifts by `(1 - ratio) * originPx` on every wheel step for any frame that moves
+the origin — around 180x110 px per step on a centred 1430x870 canvas, with no
+error raised. The anchoring itself is `zoomAt` in `camera.ts`, which the loupe's wheel also
+uses — one fixed-point zoom rather than a copy per caller. Do not reach for
+`zoomAt` from `@weasel-js/core` instead: that one clamps
+`min(max, max(min, scale * factor))` per axis with positive defaults, so a y-up
+view (`scale.y` negative) comes back at `+0.1` — flipped and collapsed. labkit's
+holds one scalar zoom and keeps the y direction in the frame, so it has no such
+axis to invert.
+
+`CanvasCapability.initialView` may be a function of the viewport size instead of
+a literal. labkit then leaves the trial's view `null` until the canvas is first
+measured and places it from `onResize` — so an instrument framing content it can
+only size against the viewport does not need a "have I centred yet" sentinel of
+its own. Reset nulls the view again, which re-frames.
+
 Zoom is clamped to `[minZoom, maxZoom]` (defaults 0.1 / 32), settable via `CanvasStack`'s props and, for an instrument's own canvas, `CanvasCapability.minZoom` / `maxZoom`. The clamp always widens to admit whatever zoom the canvas opened at — an instrument declaring `initialView.zoom: 1600` with the default range is not clamped down to 32 on the first wheel event.
 
 ## Testing notes

package/src/canvas/CanvasStack.test.tsx

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react';
+import { fireEvent, render } from '@testing-library/react';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { CanvasStack } from './CanvasStack';
 import type { CanvasLayerDescriptor } from './useLayerScheduler';
@@ -79,4 +79,30 @@ describe('<CanvasStack>', () => {
     );
     expect(getByText('overlay-content')).toBeInTheDocument();
   });
+
+  it('hit-tests through the declared world spec', () => {
+    const rect = { left: 0, top: 0, width: 800, height: 600, right: 800, bottom: 600 };
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue(
+      rect as unknown as DOMRect,
+    );
+    const onHitTest = vi.fn();
+    const { container } = render(
+      <CanvasStack
+        layers={makeLayers(1)}
+        view={{ zoom: 2, pan: { x: 0, y: 0 } }}
+        onViewChange={vi.fn()}
+        worldSpec={{ origin: { x: 0.5, y: 0.5 }, yAxis: 'up' }}
+        onHitTest={onHitTest}
+      />,
+    );
+    const host = container.querySelector('.lk-canvas-stack');
+    if (!host) throw new Error('no stack host');
+    fireEvent.pointerDown(host, { button: 0, pointerId: 1, clientX: 500, clientY: 200 });
+    fireEvent.pointerUp(host, { pointerId: 1, clientX: 500, clientY: 200 });
+
+    // Origin is (400,300); the cursor is 100px right of it and 100px above it,
+    // at zoom 2 with y running up.
+    expect(onHitTest).toHaveBeenCalledWith({ x: 50, y: 50 });
+    vi.restoreAllMocks();
+  });
 });

package/src/canvas/CanvasStack.tsx

@@ -4,17 +4,24 @@ import { CanvasStackContext } from './CanvasStackContext';
 import { screenToWorld } from './canvasCoords';
 import { type CanvasLayerDescriptor, useLayerScheduler } from './useLayerScheduler';
 import { usePanZoom } from './usePanZoom';
+import { resolveFrame, type ViewportSize, type WorldSpec } from './worldSpec';
 
 /** Props for `<CanvasStack>`. */
 export interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];
   view: ViewTransform;
   onViewChange: (v: ViewTransform) => void;
+  /** The instrument's coordinate system. Omitted, world (0,0) sits at the
+   *  element's top-left with y running down. */
+  worldSpec?: WorldSpec;
   minZoom?: number;
   maxZoom?: number;
   width?: number | string;
   height?: number | string;
   className?: string;
+  /** Fired whenever the stack is measured, so a consumer can place a view that
+   *  only makes sense in terms of the viewport. */
+  onResize?: (size: ViewportSize) => void;
   onHitTest?: (worldPos: Point) => void;
   children?: ReactNode;
 }
@@ -26,11 +33,13 @@ export function CanvasStack({
   layers,
   view,
   onViewChange,
+  worldSpec,
   minZoom,
   maxZoom,
   width = '100%',
   height = '100%',
   className,
+  onResize,
   onHitTest,
   children,
 }: CanvasStackProps) {
@@ -63,10 +72,26 @@ export function CanvasStack({
     return () => ro.disconnect();
   }, []);
 
-  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom });
-  useLayerScheduler({ layers, view, canvasRefs: canvasMap, size, host: containerRef });
+  const onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+  useEffect(() => {
+    if (size.width === 0 && size.height === 0) return;
+    onResizeRef.current?.({ width: size.width, height: size.height });
+  }, [size.width, size.height]);
+
+  const frame = useMemo(() => resolveFrame(worldSpec, size), [worldSpec, size]);
 
-  const ctxValue = useMemo(() => ({ view }), [view]);
+  const handlers = usePanZoom({ view, onViewChange, minZoom, maxZoom, frame });
+  useLayerScheduler({ layers, view, frame, canvasRefs: canvasMap, size, host: containerRef });
+
+  const ctxValue = useMemo(
+    () => ({
+      view,
+      frame,
+      surface: { element: containerRef, size, canvases: canvasMap, layers },
+    }),
+    [view, frame, size, layers],
+  );
 
   const containerStyle: CSSProperties = { width, height };
   const canvasPx = {
@@ -84,7 +109,7 @@ export function CanvasStack({
     if (!wasDragging && onHitTest && containerRef.current) {
       const rect = containerRef.current.getBoundingClientRect();
       const screen = { x: e.clientX - rect.left, y: e.clientY - rect.top };
-      onHitTest(screenToWorld(screen, view));
+      onHitTest(screenToWorld(screen, view, frame));
     }
   };
 

package/src/canvas/CanvasStackContext.ts

@@ -1,11 +1,30 @@
-import { createContext } from 'react';
+import { createContext, type RefObject } from 'react';
 import type { ViewTransform } from '../instrument/types';
+import type { CanvasLayerDescriptor } from './useLayerScheduler';
+import type { WorldFrame } from './worldSpec';
 
-/** What a canvas stack publishes to its children — currently the view, so
- *  DOM overlays can position themselves in the same coordinates. */
+/** The stack's own drawing surface, for an overlay that has to re-draw it at
+ *  another camera or read back what it presented — a loupe. */
+export interface CanvasStackSurface {
+  /** The element the layers are stacked in, and the one pan/zoom listens on. */
+  element: RefObject<HTMLElement | null>;
+  /** Its measured CSS size, and the ratio the backing stores are scaled by. */
+  size: { width: number; height: number; dpr: number };
+  /** The presented `<canvas>` per layer id. */
+  canvases: RefObject<Map<string, HTMLCanvasElement>>;
+  /** The layers as the stack is drawing them, bottom first. */
+  layers: readonly CanvasLayerDescriptor[];
+}
+
+/** What a canvas stack publishes to its children: the view, and the resolved
+ *  coordinate system it is read in, so DOM overlays can place themselves in the
+ *  same coordinates the layers draw in. */
 export interface CanvasStackContextValue {
   view: ViewTransform;
+  frame: WorldFrame;
+  /** Absent from a context assembled by hand, which has no stack behind it. */
+  surface?: CanvasStackSurface;
 }
 
-/** Context carrying the surrounding canvas stack's view. */
+/** Context carrying the surrounding canvas stack's view and world frame. */
 export const CanvasStackContext = createContext<CanvasStackContextValue | null>(null);

package/src/canvas/camera.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { centerOn, zoomAt } from './camera';
+import { screenToWorld, worldToScreen } from './canvasCoords';
+import { DEFAULT_FRAME, resolveFrame } from './worldSpec';
+
+const view = { zoom: 2, pan: { x: 30, y: -10 } };
+
+describe('zoomAt', () => {
+  it('multiplies the zoom by the factor', () => {
+    expect(zoomAt(view, 3, { x: 0, y: 0 }).zoom).toBe(6);
+  });
+
+  it('keeps the world point under the anchor fixed', () => {
+    const at = { x: 120, y: 80 };
+    const before = screenToWorld(at, view);
+    const next = zoomAt(view, 3, at);
+    expect(screenToWorld(at, next).x).toBeCloseTo(before.x, 10);
+    expect(screenToWorld(at, next).y).toBeCloseTo(before.y, 10);
+  });
+
+  it('keeps it fixed on a frame whose origin is not the top-left', () => {
+    const frame = resolveFrame(
+      { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' },
+      {
+        width: 400,
+        height: 300,
+      },
+    );
+    const at = { x: 120, y: 80 };
+    const before = screenToWorld(at, view, frame);
+    const next = zoomAt(view, 3, at, { frame });
+    expect(screenToWorld(at, next, frame).x).toBeCloseTo(before.x, 10);
+    expect(screenToWorld(at, next, frame).y).toBeCloseTo(before.y, 10);
+  });
+
+  it('clamps to the bounds, and anchors on the zoom it actually reached', () => {
+    const at = { x: 120, y: 80 };
+    const next = zoomAt(view, 100, at, { max: 8 });
+    expect(next.zoom).toBe(8);
+    const before = screenToWorld(at, view);
+    expect(screenToWorld(at, next).x).toBeCloseTo(before.x, 10);
+  });
+
+  it('treats a non-finite zoom as 1 rather than propagating NaN', () => {
+    const next = zoomAt({ zoom: Number.NaN, pan: { x: 0, y: 0 } }, 2, { x: 10, y: 10 });
+    expect(next.zoom).toBe(2);
+    expect(Number.isFinite(next.pan.x)).toBe(true);
+  });
+});
+
+describe('centerOn', () => {
+  it('puts the world point at the middle of the viewport', () => {
+    const world = { x: 12, y: -4 };
+    const v = centerOn(world, 6, { width: 200, height: 120 });
+    const p = worldToScreen(world, v);
+    expect(p.x).toBeCloseTo(100, 10);
+    expect(p.y).toBeCloseTo(60, 10);
+  });
+
+  it('respects the frame it is given', () => {
+    const frame = resolveFrame(
+      { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' },
+      {
+        width: 200,
+        height: 120,
+      },
+    );
+    const world = { x: 12, y: -4 };
+    const v = centerOn(world, 6, { width: 200, height: 120 }, frame);
+    const p = worldToScreen(world, v, frame);
+    expect(p.x).toBeCloseTo(100, 10);
+    expect(p.y).toBeCloseTo(60, 10);
+  });
+
+  it('carries the zoom it was given', () => {
+    expect(centerOn({ x: 0, y: 0 }, 6, { width: 10, height: 10 }, DEFAULT_FRAME).zoom).toBe(6);
+  });
+});