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

package/src/loupe/canvasLens.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it, vi } from 'vitest';
+import { worldToScreen } from '../canvas/canvasCoords';
+import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
+import { DEFAULT_FRAME, resolveFrame } from '../canvas/worldSpec';
+import { drawCanvasLens, lensCamera, lensSourceRect, sampleStack } from './canvasLens';
+
+const outer = { zoom: 2, pan: { x: 30, y: -10 } };
+
+describe('lensCamera', () => {
+  it('multiplies the stack zoom by the factor', () => {
+    expect(lensCamera({ x: 50, y: 50 }, outer, DEFAULT_FRAME, 6, 200).view.zoom).toBe(12);
+  });
+
+  it('puts the aimed world point at the middle of the lens', () => {
+    const aim = { x: 137, y: 61 };
+    const lens = lensCamera(aim, outer, DEFAULT_FRAME, 6, 200);
+    // The world point the stack shows at `aim`, projected through the lens.
+    const world = {
+      x: (aim.x - outer.pan.x) / outer.zoom,
+      y: (aim.y - outer.pan.y) / outer.zoom,
+    };
+    const p = worldToScreen(world, lens.view, lens.frame);
+    expect(p.x).toBeCloseTo(100, 8);
+    expect(p.y).toBeCloseTo(100, 8);
+  });
+
+  it('resolves the world spec against the lens, not the stack', () => {
+    const spec = { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' as const };
+    const stackFrame = resolveFrame(spec, { width: 800, height: 600 });
+    const lens = lensCamera({ x: 137, y: 61 }, outer, stackFrame, 6, 200, spec);
+    expect(lens.frame.originPx).toEqual({ x: 100, y: 100 });
+    expect(lens.frame.yDir).toBe(-1);
+  });
+
+  it('centres the same world point on a flipped, re-origined frame', () => {
+    const spec = { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' as const };
+    const stackFrame = resolveFrame(spec, { width: 800, height: 600 });
+    const aim = { x: 137, y: 61 };
+    const lens = lensCamera(aim, outer, stackFrame, 6, 200, spec);
+    const world = {
+      x: (aim.x - stackFrame.originPx.x - outer.pan.x) / outer.zoom,
+      y: (aim.y - stackFrame.originPx.y - outer.pan.y) / (outer.zoom * stackFrame.yDir),
+    };
+    const p = worldToScreen(world, lens.view, lens.frame);
+    expect(p.x).toBeCloseTo(100, 8);
+    expect(p.y).toBeCloseTo(100, 8);
+  });
+});
+
+describe('lensSourceRect', () => {
+  it('copies the diameter-over-factor CSS px around the aim', () => {
+    expect(lensSourceRect({ x: 100, y: 50 }, 4, 200, 1)).toEqual({
+      sx: 75,
+      sy: 25,
+      sw: 50,
+      sh: 50,
+    });
+  });
+
+  it('is measured in backing-store pixels', () => {
+    expect(lensSourceRect({ x: 100, y: 50 }, 4, 200, 2)).toEqual({
+      sx: 150,
+      sy: 50,
+      sw: 100,
+      sh: 100,
+    });
+  });
+});
+
+function fakeCanvas(pixel: [number, number, number, number] | null): HTMLCanvasElement {
+  return {
+    width: 100,
+    height: 100,
+    getContext: () =>
+      pixel === null ? null : { getImageData: () => ({ data: Uint8ClampedArray.from(pixel) }) },
+  } as unknown as HTMLCanvasElement;
+}
+
+describe('sampleStack', () => {
+  const layers = (ids: string[]): CanvasLayerDescriptor[] =>
+    ids.map((id) => ({ id, visible: true, render: vi.fn() }));
+
+  it('reports the topmost layer with something opaque there', () => {
+    const canvases = new Map([
+      ['under', fakeCanvas([0, 0, 255, 255])],
+      ['over', fakeCanvas([255, 0, 0, 255])],
+    ]);
+    expect(sampleStack(layers(['under', 'over']), canvases, { x: 5, y: 5 }, 1)).toBe('#ff0000');
+  });
+
+  it('falls through a transparent pixel to the layer below', () => {
+    const canvases = new Map([
+      ['under', fakeCanvas([0, 0, 255, 255])],
+      ['over', fakeCanvas([255, 0, 0, 0])],
+    ]);
+    expect(sampleStack(layers(['under', 'over']), canvases, { x: 5, y: 5 }, 1)).toBe('#0000ff');
+  });
+
+  it('skips a hidden layer even when it has pixels', () => {
+    const stack = layers(['under', 'over']);
+    stack[1].visible = false;
+    const canvases = new Map([
+      ['under', fakeCanvas([0, 0, 255, 255])],
+      ['over', fakeCanvas([255, 0, 0, 255])],
+    ]);
+    expect(sampleStack(stack, canvases, { x: 5, y: 5 }, 1)).toBe('#0000ff');
+  });
+
+  it('says nothing rather than black when every layer is transparent', () => {
+    const canvases = new Map([['only', fakeCanvas([0, 0, 0, 0])]]);
+    expect(sampleStack(layers(['only']), canvases, { x: 5, y: 5 }, 1)).toBeNull();
+  });
+
+  it('says nothing for a point off the backing store', () => {
+    const canvases = new Map([['only', fakeCanvas([255, 0, 0, 255])]]);
+    expect(sampleStack(layers(['only']), canvases, { x: 400, y: 5 }, 1)).toBeNull();
+  });
+
+  it('pads a single-digit channel, so #0a0a0a is not #aaa', () => {
+    const canvases = new Map([['only', fakeCanvas([10, 10, 10, 255])]]);
+    expect(sampleStack(layers(['only']), canvases, { x: 5, y: 5 }, 1)).toBe('#0a0a0a');
+  });
+});
+
+function recordingContext(): CanvasRenderingContext2D & { calls: unknown[][] } {
+  const calls: unknown[][] = [];
+  const ctx = {
+    calls,
+    imageSmoothingEnabled: true,
+    save: () => calls.push(['save']),
+    restore: () => calls.push(['restore']),
+    setTransform: (...a: unknown[]) => calls.push(['setTransform', ...a]),
+    clearRect: (...a: unknown[]) => calls.push(['clearRect', ...a]),
+    drawImage: (...a: unknown[]) => calls.push(['drawImage', ...a]),
+  };
+  return ctx as unknown as CanvasRenderingContext2D & { calls: unknown[][] };
+}
+
+describe('drawCanvasLens', () => {
+  const base = {
+    aim: { x: 100, y: 50 },
+    factor: 4,
+    diameter: 200,
+    dpr: 1,
+    outer,
+    layers: [] as CanvasLayerDescriptor[],
+    canvases: new Map<string, HTMLCanvasElement>(),
+  };
+
+  it('re-runs each visible layer at the lens camera in vector mode', () => {
+    const under = vi.fn();
+    const over = vi.fn();
+    const hidden = vi.fn();
+    const layers: CanvasLayerDescriptor[] = [
+      { id: 'under', visible: true, render: under },
+      { id: 'hidden', visible: false, render: hidden },
+      { id: 'over', visible: true, render: over },
+    ];
+    const ctx = recordingContext();
+    drawCanvasLens(ctx, { ...base, mode: 'vector', layers });
+
+    expect(hidden).not.toHaveBeenCalled();
+    const expected = lensCamera(base.aim, outer, DEFAULT_FRAME, 4, 200);
+    for (const fn of [under, over]) {
+      expect(fn).toHaveBeenCalledWith(ctx, expected.view, expected.frame);
+    }
+    // Bottom layer first, so the stack composites the way the trial shows it.
+    expect(under.mock.invocationCallOrder[0]).toBeLessThan(over.mock.invocationCallOrder[0]);
+  });
+
+  it('enlarges the presented pixels with smoothing off in pixel mode', () => {
+    const canvases = new Map([['only', fakeCanvas([0, 0, 0, 255])]]);
+    const layers: CanvasLayerDescriptor[] = [{ id: 'only', visible: true, render: vi.fn() }];
+    const ctx = recordingContext();
+    drawCanvasLens(ctx, { ...base, mode: 'pixel', layers, canvases });
+
+    expect(ctx.imageSmoothingEnabled).toBe(false);
+    const draw = ctx.calls.find((c) => c[0] === 'drawImage');
+    expect(draw?.slice(2)).toEqual([75, 25, 50, 50, 0, 0, 200, 200]);
+  });
+
+  it('does not re-run a layer draw in pixel mode', () => {
+    const render = vi.fn();
+    const canvases = new Map([['only', fakeCanvas([0, 0, 0, 255])]]);
+    drawCanvasLens(recordingContext(), {
+      ...base,
+      mode: 'pixel',
+      layers: [{ id: 'only', visible: true, render }],
+      canvases,
+    });
+    expect(render).not.toHaveBeenCalled();
+  });
+
+  it('skips a backing store with no pixels rather than throwing', () => {
+    const empty = { width: 0, height: 0, getContext: () => null } as unknown as HTMLCanvasElement;
+    const ctx = recordingContext();
+    drawCanvasLens(ctx, {
+      ...base,
+      mode: 'pixel',
+      layers: [{ id: 'only', visible: true, render: vi.fn() }],
+      canvases: new Map([['only', empty]]),
+    });
+    expect(ctx.calls.some((c) => c[0] === 'drawImage')).toBe(false);
+  });
+});

package/src/loupe/canvasLens.ts

@@ -0,0 +1,141 @@
+import type { LoupePoint } from '@weasel-js/loupe';
+import { centerOn } from '../canvas/camera';
+import { screenToWorld } from '../canvas/canvasCoords';
+import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
+import { DEFAULT_FRAME, resolveFrame, type WorldFrame, type WorldSpec } from '../canvas/worldSpec';
+import type { ViewTransform } from '../instrument/types';
+
+/** The camera a round lens of `diameter` shows a magnified region through, and
+ *  the coordinate system it is read in — the instrument's own `WorldSpec`,
+ *  resolved against the lens rather than the stack. */
+export interface LensCamera {
+  view: ViewTransform;
+  frame: WorldFrame;
+}
+
+/**
+ * What a lens aimed at `aim` renders the stack's layers through.
+ *
+ * The lens is its own viewport, so the world spec resolves against its box: an
+ * instrument centred on its viewport is centred in the lens too.
+ */
+export function lensCamera(
+  aim: LoupePoint,
+  outer: ViewTransform,
+  outerFrame: WorldFrame,
+  factor: number,
+  diameter: number,
+  worldSpec?: WorldSpec,
+): LensCamera {
+  const size = { width: diameter, height: diameter };
+  const frame = resolveFrame(worldSpec, size);
+  const world = screenToWorld(aim, outer, outerFrame);
+  return { view: centerOn(world, outer.zoom * factor, size, frame), frame };
+}
+
+/** A rectangle in a backing store's own device pixels. */
+export interface SourceRect {
+  sx: number;
+  sy: number;
+  sw: number;
+  sh: number;
+}
+
+/**
+ * The region a pixel-mode lens copies out of a presented canvas: the `diameter
+ * / factor` CSS px around `aim`, in that canvas' backing-store pixels.
+ */
+export function lensSourceRect(
+  aim: LoupePoint,
+  factor: number,
+  diameter: number,
+  dpr: number,
+): SourceRect {
+  const span = diameter / factor;
+  return {
+    sx: (aim.x - span / 2) * dpr,
+    sy: (aim.y - span / 2) * dpr,
+    sw: span * dpr,
+    sh: span * dpr,
+  };
+}
+
+/**
+ * The colour a stack presents at a point: the topmost visible layer with
+ * anything opaque there, or `null` when every layer is transparent — which is
+ * the honest answer for a point showing nothing but the workspace behind.
+ */
+export function sampleStack(
+  layers: readonly CanvasLayerDescriptor[],
+  canvases: Map<string, HTMLCanvasElement>,
+  p: LoupePoint,
+  dpr: number,
+): string | null {
+  for (let i = layers.length - 1; i >= 0; i--) {
+    const layer = layers[i];
+    if (!layer.visible) continue;
+    const canvas = canvases.get(layer.id);
+    if (!canvas) continue;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    if (!ctx) continue;
+    const x = Math.floor(p.x * dpr);
+    const y = Math.floor(p.y * dpr);
+    if (x < 0 || y < 0 || x >= canvas.width || y >= canvas.height) continue;
+    const [r, g, b, a] = ctx.getImageData(x, y, 1, 1).data;
+    if (a === 0) continue;
+    return `#${[r, g, b].map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+  }
+  return null;
+}
+
+/** Redraw the stack into a lens' own canvas. `mode` decides whether the layers
+ *  are re-run at the lens camera or their presented pixels are enlarged. */
+export function drawCanvasLens(
+  ctx: CanvasRenderingContext2D,
+  opts: {
+    aim: LoupePoint;
+    factor: number;
+    diameter: number;
+    dpr: number;
+    mode: 'vector' | 'pixel';
+    outer: ViewTransform;
+    outerFrame?: WorldFrame;
+    worldSpec?: WorldSpec;
+    layers: readonly CanvasLayerDescriptor[];
+    canvases: Map<string, HTMLCanvasElement>;
+  },
+): void {
+  const { aim, factor, diameter, dpr, mode, outer, layers, canvases } = opts;
+  ctx.save();
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.clearRect(0, 0, diameter, diameter);
+
+  if (mode === 'pixel') {
+    const { sx, sy, sw, sh } = lensSourceRect(aim, factor, diameter, dpr);
+    ctx.imageSmoothingEnabled = false;
+    for (const layer of layers) {
+      if (!layer.visible) continue;
+      const canvas = canvases.get(layer.id);
+      if (!canvas || canvas.width === 0 || canvas.height === 0) continue;
+      ctx.drawImage(canvas, sx, sy, sw, sh, 0, 0, diameter, diameter);
+    }
+    ctx.restore();
+    return;
+  }
+
+  const lens = lensCamera(
+    aim,
+    outer,
+    opts.outerFrame ?? DEFAULT_FRAME,
+    factor,
+    diameter,
+    opts.worldSpec,
+  );
+  for (const layer of layers) {
+    if (!layer.visible) continue;
+    ctx.save();
+    layer.render(ctx, lens.view, lens.frame);
+    ctx.restore();
+  }
+  ctx.restore();
+}

package/src/loupe/index.ts

@@ -0,0 +1,19 @@
+export type { CanvasLoupeProps } from './CanvasLoupe';
+export { CanvasLoupe } from './CanvasLoupe';
+export type { LensCamera, SourceRect } from './canvasLens';
+export { drawCanvasLens, lensCamera, lensSourceRect, sampleStack } from './canvasLens';
+export type { DomLoupeProps } from './DomLoupe';
+export { DomLoupe } from './DomLoupe';
+export type { LoupeBubbleProps } from './LoupeBubble';
+export { LoupeBubble } from './LoupeBubble';
+export type { TrialLoupeProps } from './TrialLoupe';
+export { TrialLoupe } from './TrialLoupe';
+export type {
+  LoupeCapability,
+  LoupeDeclaration,
+  LoupeRenderArgs,
+  ResolvedLoupe,
+} from './types';
+export { LOUPE_DEFAULTS, resolveLoupe } from './types';
+export type { LoupeState, UseLoupeOptions } from './useLoupe';
+export { useLoupe } from './useLoupe';

package/src/loupe/types.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { LOUPE_DEFAULTS, resolveLoupe } from './types';
+
+describe('resolveLoupe', () => {
+  it('takes every default from a bare `true`', () => {
+    expect(resolveLoupe(true)).toMatchObject(LOUPE_DEFAULTS);
+  });
+
+  it('keeps what the instrument declared', () => {
+    const cap = resolveLoupe({ factor: 12, diameter: 320, minFactor: 1, maxFactor: 40 });
+    expect(cap).toMatchObject({ factor: 12, diameter: 320, minFactor: 1, maxFactor: 40 });
+  });
+
+  it('clamps an opening factor outside the bounds it also declared', () => {
+    expect(resolveLoupe({ factor: 100, maxFactor: 16 }).factor).toBe(16);
+    expect(resolveLoupe({ factor: 1, minFactor: 4 }).factor).toBe(4);
+  });
+
+  it('forces vector on a DOM loupe, which has no framebuffer to enlarge', () => {
+    expect(resolveLoupe({ render: () => null, mode: 'pixel' }).mode).toBe('vector');
+    expect(resolveLoupe({ mode: 'pixel' }).mode).toBe('pixel');
+  });
+
+  it('distinguishes an unset peek key from one turned off', () => {
+    expect(resolveLoupe({}).peekKey).toBe('Alt');
+    expect(resolveLoupe({ peekKey: null }).peekKey).toBeNull();
+    expect(resolveLoupe({ peekKey: 'Shift' }).peekKey).toBe('Shift');
+  });
+});

package/src/loupe/types.ts

@@ -0,0 +1,90 @@
+import type { LoupeMode } from '@weasel-js/loupe';
+import type { ReactNode } from 'react';
+import type { ViewportSize } from '../canvas/worldSpec';
+import type { ViewTransform } from '../instrument/types';
+
+/** What a DOM instrument's loupe `render` is handed: the same data its own
+ *  `render` gets, and the camera to draw it through. */
+export interface LoupeRenderArgs<TS = unknown, TC = unknown> {
+  state: TS;
+  config: TC;
+  /** The trial's own camera composed with the magnification, about the aimed
+   *  point — so drawing the same content through it magnifies in place. */
+  view: ViewTransform;
+  /** The magnification on its own, for whatever must not scale with the
+   *  camera. */
+  factor: number;
+  mode: LoupeMode;
+  /** The size of the viewport `view` is written for: the trial's content well,
+   *  not the lens. The lens shows a circle cut out of it. */
+  size: ViewportSize;
+}
+
+/**
+ * Declares that an instrument can be magnified.
+ *
+ * With no `render`, the loupe re-draws the instrument's canvas layers through a
+ * zoomed camera, so it stays sharp at any factor. An instrument whose content is
+ * DOM supplies `render` instead: given a camera, draw me again.
+ */
+export interface LoupeCapability<TS = unknown, TC = unknown> {
+  render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
+  /** Opening magnification, clamped to the bounds below. Default 6. */
+  factor?: number;
+  /** What the wheel clamps to. Defaults 2 and 32. */
+  minFactor?: number;
+  maxFactor?: number;
+  /** `'vector'` (default) re-renders the content magnified; `'pixel'` blows up
+   *  the pixels the instrument presented. A `render` loupe is always vector —
+   *  DOM has no framebuffer to enlarge. */
+  mode?: LoupeMode;
+  /** Lens diameter in CSS px. Default 200. */
+  diameter?: number;
+  /** Held for a momentary peek while the loupe is off. Default `'Alt'`; `null`
+   *  turns hold-to-peek off. Matched against `KeyboardEvent.key`. */
+  peekKey?: string | null;
+  /** Called with the colour under the aim, wherever the surface can say. The
+   *  canvas painter reads it back; a DOM loupe has no pixels to sample. */
+  onColorChange?: (hex: string) => void;
+}
+
+/** An instrument's loupe declaration. `true` takes every default. */
+export type LoupeDeclaration<TS = unknown, TC = unknown> = true | LoupeCapability<TS, TC>;
+
+/** A {@link LoupeCapability} with every default filled in. */
+export interface ResolvedLoupe<TS = unknown, TC = unknown> {
+  render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
+  onColorChange?: (hex: string) => void;
+  factor: number;
+  minFactor: number;
+  maxFactor: number;
+  mode: LoupeMode;
+  diameter: number;
+  peekKey: string | null;
+}
+
+export const LOUPE_DEFAULTS = {
+  factor: 6,
+  minFactor: 2,
+  maxFactor: 32,
+  mode: 'vector',
+  diameter: 200,
+  peekKey: 'Alt',
+} as const satisfies Omit<ResolvedLoupe, 'render' | 'onColorChange'>;
+
+export function resolveLoupe<TS, TC>(declared: LoupeDeclaration<TS, TC>): ResolvedLoupe<TS, TC> {
+  const cap = declared === true ? {} : declared;
+  const minFactor = cap.minFactor ?? LOUPE_DEFAULTS.minFactor;
+  const maxFactor = cap.maxFactor ?? LOUPE_DEFAULTS.maxFactor;
+  return {
+    render: cap.render,
+    onColorChange: cap.onColorChange,
+    minFactor,
+    maxFactor,
+    factor: Math.min(maxFactor, Math.max(minFactor, cap.factor ?? LOUPE_DEFAULTS.factor)),
+    diameter: cap.diameter ?? LOUPE_DEFAULTS.diameter,
+    peekKey: cap.peekKey === undefined ? LOUPE_DEFAULTS.peekKey : cap.peekKey,
+    // A DOM loupe has no framebuffer, so `pixel` would have nothing to enlarge.
+    mode: cap.render ? 'vector' : (cap.mode ?? LOUPE_DEFAULTS.mode),
+  };
+}

package/src/loupe/useHostSize.ts

@@ -0,0 +1,30 @@
+import { type RefObject, useEffect, useState } from 'react';
+import type { ViewportSize } from '../canvas/worldSpec';
+
+const ZERO: ViewportSize = { width: 0, height: 0 };
+
+/** An element's CSS-pixel box, kept current. `{0, 0}` until it is measured, and
+ *  wherever `ResizeObserver` is absent. */
+export function useHostSize(ref: RefObject<HTMLElement | null>): ViewportSize {
+  const [size, setSize] = useState<ViewportSize>(ZERO);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const update = (): void => {
+      const rect = el.getBoundingClientRect();
+      setSize((prev) =>
+        prev.width === rect.width && prev.height === rect.height
+          ? prev
+          : { width: rect.width, height: rect.height },
+      );
+    };
+    update();
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [ref]);
+
+  return size;
+}