@weasel-js/labkit 1.8.0 → 1.8.1

package/src/loupe/index.ts

@@ -1,4 +1,16 @@
-export type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
+export type {
+  BandPlacement,
+  CanvasSource,
+  CanvasSourceOptions,
+  LoupeMode,
+  LoupePoint,
+  LoupeSize,
+  PlaceBandArgs,
+  SourceBox,
+  SourceCanvas,
+  SourceContext,
+} from '@weasel-js/loupe';
+export { createCanvasSource, loupeExtent, placeBand } from '@weasel-js/loupe';
 export type { CanvasLoupeProps } from './CanvasLoupe';
 export { CanvasLoupe } from './CanvasLoupe';
 export type { LensCamera, SourceRect } from './canvasLens';
@@ -11,9 +23,21 @@ export type { LoupeGesturesProps } from './LoupeGestures';
 export { LoupeGestures } from './LoupeGestures';
 export type { LoupeInputApi } from './loupeActions';
 export { createLoupeActions, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID } from './loupeActions';
+export type { SourceLoupeProps } from './SourceLoupe';
+export { SourceLoupe } from './SourceLoupe';
+export type { LoupeSource, LoupeSourceTarget } from './sourceLens';
+export { drawSourceLens, resolveLoupeSource, sampleSource, sourceBoxIn } from './sourceLens';
 export type { TrialLoupeProps } from './TrialLoupe';
 export { TrialLoupe } from './TrialLoupe';
-export type { LoupeOptions, LoupeRenderArgs, ResolvedLoupe } from './types';
+export type {
+  LoupeLens,
+  LoupeOptions,
+  LoupePlaceArgs,
+  LoupePlacement,
+  LoupeRenderArgs,
+  LoupeShape,
+  ResolvedLoupe,
+} from './types';
 export { LOUPE_DEFAULTS, resolveLoupe } from './types';
 export type { LoupeState, UseLoupeOptions } from './useLoupe';
 export { useLoupe } from './useLoupe';

package/src/loupe/sourceLens.test.ts

@@ -0,0 +1,65 @@
+import { createCanvasSource } from '@weasel-js/loupe';
+import { describe, expect, it } from 'vitest';
+import { resolveLoupeSource, sourceBoxIn } from './sourceLens';
+
+function canvas(width = 200, height = 100): HTMLCanvasElement {
+  const c = document.createElement('canvas');
+  c.width = width;
+  c.height = height;
+  return c;
+}
+
+describe('resolveLoupeSource', () => {
+  it('passes a CanvasSource through', () => {
+    const s = createCanvasSource(canvas());
+    expect(resolveLoupeSource(s)).toBe(s);
+  });
+
+  it('makes one source per canvas, however often a getter returns it', () => {
+    const c = canvas();
+    const get = () => c;
+    const a = resolveLoupeSource(get);
+    expect(a?.canvas).toBe(c);
+    expect(resolveLoupeSource(get)).toBe(a);
+    expect(resolveLoupeSource(c)).toBe(a);
+  });
+
+  it('is null while a getter has nothing yet', () => {
+    expect(resolveLoupeSource(() => null)).toBeNull();
+    expect(resolveLoupeSource(undefined)).toBeNull();
+  });
+});
+
+describe('sourceBoxIn', () => {
+  it('prefers the box the source declares', () => {
+    const box = { x: 4, y: 5, width: 6, height: 7 };
+    expect(sourceBoxIn(createCanvasSource(canvas(), { box: () => box }), null)).toBe(box);
+  });
+
+  it('falls back to the whole host for a canvas that is not on the page', () => {
+    const host = document.createElement('div');
+    host.getBoundingClientRect = () => ({ left: 0, top: 0, width: 300, height: 150 }) as DOMRect;
+    expect(sourceBoxIn(createCanvasSource(canvas()), host)).toEqual({
+      x: 0,
+      y: 0,
+      width: 300,
+      height: 150,
+    });
+  });
+
+  it('measures a laid-out canvas against the host', () => {
+    const host = document.createElement('div');
+    const c = canvas();
+    host.append(c);
+    document.body.append(host);
+    host.getBoundingClientRect = () => ({ left: 100, top: 50, width: 300, height: 150 }) as DOMRect;
+    c.getBoundingClientRect = () => ({ left: 120, top: 60, width: 100, height: 50 }) as DOMRect;
+    expect(sourceBoxIn(createCanvasSource(c), host)).toEqual({
+      x: 20,
+      y: 10,
+      width: 100,
+      height: 50,
+    });
+    host.remove();
+  });
+});

package/src/loupe/sourceLens.ts

@@ -0,0 +1,97 @@
+import {
+  type CanvasSource,
+  createCanvasSource,
+  type LoupePoint,
+  type LoupeSize,
+  loupeExtent,
+  type SourceBox,
+  type SourceCanvas,
+  type SourceContext,
+  sourcePixel,
+  sourceRegion,
+} from '@weasel-js/loupe';
+
+/** Anything a lens can be pointed at for its pixels: a `CanvasSource`, a
+ *  canvas, a context on one, or a function returning any of those once it
+ *  exists. */
+export type LoupeSourceTarget = CanvasSource | SourceCanvas | SourceContext;
+export type LoupeSource = LoupeSourceTarget | (() => LoupeSourceTarget | null | undefined);
+
+function isCanvasSource(t: LoupeSourceTarget): t is CanvasSource {
+  return 'capture' in t && 'retain' in t;
+}
+
+// One source per canvas or context, so a getter returning the same canvas
+// every frame keeps one snapshot rather than minting a new one per call.
+const made = new WeakMap<object, CanvasSource>();
+
+/** `source` as a `CanvasSource`, or `null` while a getter has nothing yet. */
+export function resolveLoupeSource(source: LoupeSource | undefined): CanvasSource | null {
+  if (!source) return null;
+  const target = typeof source === 'function' ? source() : source;
+  if (!target) return null;
+  if (isCanvasSource(target)) return target;
+  let s = made.get(target);
+  if (!s) {
+    s = createCanvasSource(target);
+    made.set(target, s);
+  }
+  return s;
+}
+
+/**
+ * Where a source canvas sits over the lens's host, in the host's CSS px: its
+ * own `box` if it has one, else the canvas's laid-out box measured against the
+ * host, else — for an offscreen canvas, or one not on the page — the whole
+ * host.
+ */
+export function sourceBoxIn(source: CanvasSource, host: HTMLElement | null): SourceBox {
+  const own = source.box?.();
+  if (own) return own;
+  const hostRect = host?.getBoundingClientRect();
+  const c = source.canvas;
+  if (typeof HTMLCanvasElement !== 'undefined' && c instanceof HTMLCanvasElement && c.isConnected) {
+    const r = c.getBoundingClientRect();
+    if (r.width > 0 && r.height > 0) {
+      return {
+        x: r.left - (hostRect?.left ?? 0),
+        y: r.top - (hostRect?.top ?? 0),
+        width: r.width,
+        height: r.height,
+      };
+    }
+  }
+  return { x: 0, y: 0, width: hostRect?.width ?? c.width, height: hostRect?.height ?? c.height };
+}
+
+/** The color a source shows at a host point, or `null` where it shows none. */
+export function sampleSource(source: CanvasSource, p: LoupePoint, box: SourceBox): string | null {
+  return source.sample(sourcePixel(p, box, source.canvas));
+}
+
+/** Enlarge the pixels of `source` around `aim` into a lens' own canvas, with
+ *  smoothing off. Leaves the lens clear while the source has no frame. */
+export function drawSourceLens(
+  ctx: CanvasRenderingContext2D,
+  opts: {
+    aim: LoupePoint;
+    factor: number;
+    diameter: LoupeSize;
+    dpr: number;
+    source: CanvasSource;
+    box: SourceBox;
+  },
+): void {
+  const { aim, factor, diameter, dpr, source, box } = opts;
+  const { width, height } = loupeExtent(diameter);
+  ctx.save();
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.clearRect(0, 0, width, height);
+  const frame = source.frame();
+  if (frame) {
+    const { sx, sy, sw, sh } = sourceRegion(aim, factor, diameter, box, source.canvas);
+    ctx.imageSmoothingEnabled = false;
+    ctx.drawImage(frame, sx, sy, sw, sh, 0, 0, width, height);
+  }
+  ctx.restore();
+}

package/src/loupe/types.test.ts

@@ -21,6 +21,12 @@ describe('resolveLoupe', () => {
     expect(resolveLoupe({ mode: 'pixel' }).mode).toBe('pixel');
   });
 
+  it('forces pixel on a source loupe, unless render draws it', () => {
+    const source = () => null;
+    expect(resolveLoupe({ source, mode: 'vector' }).mode).toBe('pixel');
+    expect(resolveLoupe({ source, render: () => null }).mode).toBe('vector');
+  });
+
   it('distinguishes an unset peek key from one turned off', () => {
     expect(resolveLoupe({}).peekKey).toBe('Alt');
     expect(resolveLoupe({ peekKey: null }).peekKey).toBeNull();

package/src/loupe/types.ts

@@ -1,7 +1,8 @@
-import type { LoupeMode } from '@weasel-js/loupe';
+import type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
 import type { ReactNode } from 'react';
 import type { ViewportSize } from '../canvas/worldSpec';
 import type { ViewTransform } from '../instrument/types';
+import type { LoupeSource } from './sourceLens';
 
 /** What a DOM loupe's `render` is handed: the camera to draw the content
  *  through again. */
@@ -18,15 +19,66 @@ export interface LoupeRenderArgs {
   size: ViewportSize;
 }
 
+/** The outline of a lens. On a box that is not square, `'circle'` is an ellipse. */
+export type LoupeShape = 'circle' | 'square';
+
+/** Where a host puts the lens for one aim, in the host's own CSS px. */
+export interface LoupePlacement {
+  /** Where the lens is drawn: the middle of its box. */
+  center: LoupePoint;
+  /** The host point the lens shows at its middle. Omitted, `center`; it
+   *  differs when a lens is moved to stay on the host but keeps showing what
+   *  it was placed over. */
+  shows?: LoupePoint;
+  width: number;
+  height: number;
+  /** The magnification for this placement. Omitted, the wheel's. */
+  factor?: number;
+}
+
+/** Where a lens is drawn and what it shows, once `place` has had its say. */
+export interface LoupeLens {
+  /** Where the lens is drawn: the middle of its box. */
+  center: LoupePoint;
+  /** The host point the lens shows at its middle. */
+  shows: LoupePoint;
+  width: number;
+  height: number;
+  /** What it magnifies by: the wheel's, unless `place` chose another. */
+  factor: number;
+  shape: LoupeShape;
+}
+
+/** What `place` is asked with. */
+export interface LoupePlaceArgs {
+  aim: LoupePoint;
+  factor: number;
+}
+
 /**
  * How a lens magnifies.
  *
  * With no `render`, the lens re-draws the canvas stack's layers through a
  * zoomed camera, so it stays sharp at any factor. Over DOM content, `render`
- * draws it instead: given a camera, draw me again.
+ * draws it instead: given a camera, draw me again. With a `source`, it
+ * enlarges the pixels of that canvas — any canvas, labkit's or not.
  */
 export interface LoupeOptions {
   render?: (args: LoupeRenderArgs) => ReactNode;
+  /**
+   * A canvas to read pixels from instead of the canvas stack: a
+   * `CanvasSource` from `createCanvasSource`, a canvas, a context on one, or
+   * a function returning one once it exists. 2D, WebGL and WebGL2 all work.
+   * Without `render` the lens enlarges its pixels, so the mode is `'pixel'`;
+   * with `render`, `render` draws the lens and the source answers
+   * `onColorChange`.
+   *
+   * A WebGL canvas made without `preserveDrawingBuffer` is blank to anyone
+   * reading it after the frame that drew it. Make its source with
+   * `createCanvasSource(gl)` and call `source.capture()` right after each
+   * draw; a canvas that draws on demand also passes `requestRedraw`.
+   */
+  source?: LoupeSource;
   /** Opening magnification, clamped to the bounds below. Default 6. */
   factor?: number;
   /** What the wheel clamps to. Defaults 2 and 32. */
@@ -34,27 +86,62 @@ export interface LoupeOptions {
   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. */
+   *  DOM has no framebuffer to enlarge — and a `source` loupe always pixel. */
   mode?: LoupeMode;
   /** Lens diameter in CSS px. Default 200. */
   diameter?: number;
+  /** Default `'circle'`. */
+  shape?: LoupeShape;
+  /**
+   * Puts the lens somewhere other than a `diameter` box on the aim: the lens is
+   * drawn with the returned box centered on `center`, and shows what is around
+   * `shows` (or `center`) magnified by the returned `factor`, or by the wheel's when it
+   * returns none. `factor` in the argument is always the wheel's, so a host
+   * lowering it to fit something in keeps the wheel as the ceiling. Returning
+   * `null` keeps the default. It is
+   * called while the lens renders, so a host whose content moves under a still
+   * pointer re-renders the lens to re-place it. The color under the aim is
+   * still the one `onColorChange` reports.
+   */
+  place?: (at: LoupePlaceArgs) => LoupePlacement | null;
+  /**
+   * Draw only the lens's outline — ring, shadow, shape — and leave its inside
+   * empty, so whatever is under it shows through: for a host that draws the
+   * magnified view itself, into the box `onLens` reports. No painter runs; a
+   * `source`, if given, still answers `onColorChange`. Under a tiled surface,
+   * each move invalidates the tiles under the box it left and the box it now
+   * covers, so the host redraws those and no others.
+   */
+  hollow?: boolean;
+  /**
+   * Called with where the lens is drawn and what it shows, in host CSS px,
+   * whenever that changes — an aim, the wheel, `place`, `shape` — and with
+   * `null` when a lens that was up goes away.
+   */
+  onLens?: (lens: LoupeLens | null) => void;
   /** 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 color under the aim, wherever the surface can say. The
-   *  canvas painter reads it back; a DOM loupe has no pixels to sample. */
+   *  canvas painter and a `source` read it back; a DOM loupe with no `source`
+   *  has no pixels to sample. */
   onColorChange?: (hex: string) => void;
 }
 
 /** {@link LoupeOptions} with every default filled in. */
 export interface ResolvedLoupe {
   render?: (args: LoupeRenderArgs) => ReactNode;
+  source?: LoupeSource;
   onColorChange?: (hex: string) => void;
   factor: number;
   minFactor: number;
   maxFactor: number;
   mode: LoupeMode;
   diameter: number;
+  shape: LoupeShape;
+  place?: (at: LoupePlaceArgs) => LoupePlacement | null;
+  hollow: boolean;
+  onLens?: (lens: LoupeLens | null) => void;
   peekKey: string | null;
 }
 
@@ -65,23 +152,38 @@ export const LOUPE_DEFAULTS = {
   maxFactor: 32,
   mode: 'vector',
   diameter: 200,
+  shape: 'circle',
+  hollow: false,
   peekKey: 'Alt',
-} as const satisfies Omit<ResolvedLoupe, 'render' | 'onColorChange'>;
+} as const satisfies Omit<
+  ResolvedLoupe,
+  'render' | 'source' | 'onColorChange' | 'place' | 'onLens'
+>;
 
 /** `options` with every default filled in and `factor` clamped to
- *  `[minFactor, maxFactor]`. A loupe with its own `render` is always `'vector'`. */
+ *  `[minFactor, maxFactor]`. A loupe with its own `render` is always `'vector'`,
+ *  and one with only a `source` always `'pixel'`. */
 export function resolveLoupe(options: LoupeOptions = {}): ResolvedLoupe {
   const minFactor = options.minFactor ?? LOUPE_DEFAULTS.minFactor;
   const maxFactor = options.maxFactor ?? LOUPE_DEFAULTS.maxFactor;
   return {
     render: options.render,
+    source: options.source,
     onColorChange: options.onColorChange,
     minFactor,
     maxFactor,
     factor: Math.min(maxFactor, Math.max(minFactor, options.factor ?? LOUPE_DEFAULTS.factor)),
     diameter: options.diameter ?? LOUPE_DEFAULTS.diameter,
+    shape: options.shape ?? LOUPE_DEFAULTS.shape,
+    place: options.place,
+    hollow: options.hollow ?? LOUPE_DEFAULTS.hollow,
+    onLens: options.onLens,
     peekKey: options.peekKey === undefined ? LOUPE_DEFAULTS.peekKey : options.peekKey,
     // A DOM loupe has no framebuffer, so `pixel` would have nothing to enlarge.
-    mode: options.render ? 'vector' : (options.mode ?? LOUPE_DEFAULTS.mode),
+    mode: options.render
+      ? 'vector'
+      : options.source
+        ? 'pixel'
+        : (options.mode ?? LOUPE_DEFAULTS.mode),
   };
 }

package/src/loupe/useLoupe.test.tsx

@@ -4,7 +4,7 @@ import { renderThenAbandon } from '@weasel-js/react/testing/abandonRender';
 import { type RefObject, StrictMode, useRef } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import { LoupeGestures } from './LoupeGestures';
-import { resolveLoupe } from './types';
+import { type LoupeOptions, type LoupeShape, resolveLoupe } from './types';
 import { type LoupeState, useLoupe } from './useLoupe';
 
 interface HarnessProps {
@@ -14,7 +14,13 @@ interface HarnessProps {
   minFactor?: number;
   maxFactor?: number;
   onColorChange?: (hex: string) => void;
+  shape?: LoupeShape;
+  place?: LoupeOptions['place'];
+  onLens?: LoupeOptions['onLens'];
   seen?: (loupe: LoupeState) => void;
+  /** A wheel listener of the host's own, attached before the loupe's, as a
+   *  camera's controls on the same canvas would be. */
+  hostWheel?: (e: WheelEvent) => void;
 }
 
 /** Reports the loupe's state as text, which is every assertion jsdom can make
@@ -22,7 +28,7 @@ interface HarnessProps {
  *
  *  Mounts `<LoupeGestures>` the way `<TrialLoupe>` does, so the key and wheel
  *  cases below exercise the real dispatcher route rather than a stand-in. */
-function Harness({ enabled = true, seen, sample, ...rest }: HarnessProps) {
+function Harness({ enabled = true, seen, sample, hostWheel, ...rest }: HarnessProps) {
   const hostRef = useRef<HTMLDivElement | null>(null);
   const options = resolveLoupe(rest);
   const loupe = useLoupe({
@@ -33,7 +39,13 @@ function Harness({ enabled = true, seen, sample, ...rest }: HarnessProps) {
   });
   seen?.(loupe);
   return (
-    <div ref={hostRef} data-testid="host">
+    <div
+      ref={(el) => {
+        if (el && hostWheel && hostRef.current !== el) el.addEventListener('wheel', hostWheel);
+        hostRef.current = el;
+      }}
+      data-testid="host"
+    >
       <WeaselProvider isolate>
         <LoupeGestures
           hostRef={hostRef as RefObject<HTMLElement | null>}
@@ -93,6 +105,25 @@ describe('useLoupe', () => {
     expect(read('visible')).toBe('false');
   });
 
+  it('opens a peek where the pointer already is', () => {
+    // The model ignores aims while the lens is down, so a peek over a pointer
+    // that has not moved since must aim from what the listener saw.
+    render(<Harness enabled={false} />);
+    move(40, 25);
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Alt' });
+    });
+    expect(read('aim')).toBe('40,25');
+  });
+
+  it('opens where the pointer already is when turned on', () => {
+    const { rerender } = render(<Harness enabled={false} />);
+    move(40, 25);
+    rerender(<Harness enabled />);
+    expect(read('visible')).toBe('true');
+    expect(read('aim')).toBe('40,25');
+  });
+
   it('does not peek when its options turned the key off', () => {
     render(<Harness enabled={false} peekKey={null} />);
     move(40, 25);
@@ -125,6 +156,20 @@ describe('useLoupe', () => {
     expect(Number(read('factor'))).toBeGreaterThan(6);
   });
 
+  it('keeps the wheel from the host’s own listeners while the lens is up', () => {
+    const hostWheel = vi.fn();
+    render(<Harness hostWheel={hostWheel} />);
+    move(40, 25);
+    act(() => {
+      fireEvent.wheel(screen.getByTestId('host'), { deltaY: -100 });
+    });
+    expect(Number(read('factor'))).toBeGreaterThan(6);
+    expect(hostWheel).not.toHaveBeenCalled();
+    fireEvent.pointerLeave(screen.getByTestId('host'));
+    fireEvent.wheel(screen.getByTestId('host'), { deltaY: -100 });
+    expect(hostWheel).toHaveBeenCalledTimes(1);
+  });
+
   it('clamps the wheel to the declared bounds', () => {
     render(<Harness minFactor={4} maxFactor={8} />);
     move(40, 25);
@@ -276,4 +321,144 @@ describe('useLoupe', () => {
     expect(seen[0]?.pick()).toBe('#111111');
     expect(abandoned).not.toHaveBeenCalled();
   });
+
+  describe('placed by the host', () => {
+    const last = (seen: LoupeState[]): LoupeState => seen[seen.length - 1] as LoupeState;
+
+    it('is a diameter box on the aim, at the wheel factor, when nothing places it', () => {
+      const seen: LoupeState[] = [];
+      render(<Harness seen={(l) => seen.push(l)} />);
+      move(40, 30);
+      expect(last(seen).lens).toEqual({
+        center: { x: 40, y: 30 },
+        shows: { x: 40, y: 30 },
+        width: 200,
+        height: 200,
+        factor: 6,
+        shape: 'circle',
+      });
+    });
+
+    it('asks place with the aim and the wheel factor, and draws the box it returns', () => {
+      const seen: LoupeState[] = [];
+      const place = vi.fn(({ aim }: { aim: { x: number; y: number } }) => ({
+        center: { x: 150, y: Math.floor(aim.y / 20) * 20 + 10 },
+        width: 300,
+        height: 60,
+      }));
+      render(<Harness shape="square" place={place} seen={(l) => seen.push(l)} />);
+      move(40, 33);
+      expect(place).toHaveBeenLastCalledWith({ aim: { x: 40, y: 33 }, factor: 6 });
+      expect(last(seen).lens).toEqual({
+        center: { x: 150, y: 30 },
+        shows: { x: 150, y: 30 },
+        width: 300,
+        height: 60,
+        factor: 6,
+        shape: 'square',
+      });
+    });
+
+    it('draws a placement at its center while showing the point it names', () => {
+      const seen: LoupeState[] = [];
+      render(
+        <Harness
+          place={() => ({
+            center: { x: 50, y: 20 },
+            shows: { x: 10, y: 20 },
+            width: 100,
+            height: 40,
+          })}
+          seen={(l) => seen.push(l)}
+        />,
+      );
+      move(10, 20);
+      expect(last(seen).lens).toMatchObject({ center: { x: 50, y: 20 }, shows: { x: 10, y: 20 } });
+    });
+
+    it('shows at the factor place returns, leaving the wheel factor as what place is asked with', () => {
+      const seen: LoupeState[] = [];
+      const place = vi.fn(({ factor }: { factor: number }) => ({
+        center: { x: 0, y: 0 },
+        width: 100,
+        height: 20,
+        factor: Math.min(factor, 2.5),
+      }));
+      render(<Harness place={place} seen={(l) => seen.push(l)} />);
+      move(10, 10);
+      expect(last(seen).lens.factor).toBe(2.5);
+      expect(last(seen).factor).toBe(6);
+    });
+
+    it('falls back to the diameter box when place returns null', () => {
+      const seen: LoupeState[] = [];
+      render(<Harness place={() => null} seen={(l) => seen.push(l)} />);
+      move(40, 30);
+      expect(last(seen).lens).toMatchObject({ center: { x: 40, y: 30 }, width: 200, height: 200 });
+    });
+
+    it('does not ask place while the lens is down', () => {
+      const place = vi.fn(() => null);
+      render(<Harness enabled={false} place={place} />);
+      move(40, 30);
+      expect(place).not.toHaveBeenCalled();
+    });
+
+    it('tells onLens where the lens is drawn as it moves, and null once it is put away', () => {
+      const onLens = vi.fn();
+      render(<Harness shape="square" onLens={onLens} />);
+      expect(onLens).not.toHaveBeenCalled();
+      move(40, 30);
+      expect(onLens).toHaveBeenLastCalledWith({
+        center: { x: 40, y: 30 },
+        shows: { x: 40, y: 30 },
+        width: 200,
+        height: 200,
+        factor: 6,
+        shape: 'square',
+      });
+      move(50, 30);
+      expect(onLens).toHaveBeenLastCalledWith(
+        expect.objectContaining({ center: { x: 50, y: 30 } }),
+      );
+      const calls = onLens.mock.calls.length;
+      fireEvent.pointerLeave(screen.getByTestId('host'));
+      expect(onLens).toHaveBeenLastCalledWith(null);
+      expect(onLens).toHaveBeenCalledTimes(calls + 1);
+    });
+
+    it('does not tell onLens again when a render changes nothing about the lens', () => {
+      const onLens = vi.fn();
+      const { rerender } = render(<Harness onLens={onLens} />);
+      move(40, 30);
+      const calls = onLens.mock.calls.length;
+      rerender(<Harness onLens={onLens} />);
+      expect(onLens).toHaveBeenCalledTimes(calls);
+    });
+
+    it('tells onLens null when a lens that is up unmounts', () => {
+      const onLens = vi.fn();
+      const { unmount } = render(<Harness onLens={onLens} />);
+      move(40, 30);
+      unmount();
+      expect(onLens).toHaveBeenLastCalledWith(null);
+    });
+
+    it('picks what a placed lens shows, about its own center and factor', () => {
+      const seen: LoupeState[] = [];
+      render(
+        <Harness
+          sample={(p) => `#${Math.round(p.x)}`}
+          place={() => ({ center: { x: 300, y: 50 }, width: 400, height: 40, factor: 2 })}
+          seen={(l) => seen.push(l)}
+        />,
+      );
+      move(100, 50);
+      // 100px right of the lens's middle, at 2x, is 50 page px right of the
+      // center it shows — not of the aim.
+      expect(last(seen).pick({ x: 300 + 100, y: 50 })).toBe('#350');
+      // The color under the aim is still the aim's.
+      expect(read('color')).toBe('#100');
+    });
+  });
 });