@weasel-js/labkit 1.8.0 → 1.8.1

package/src/lightbox/Lightbox.test.tsx

@@ -0,0 +1,195 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { Lightbox } from './Lightbox';
+import { useLightboxControl } from './LightboxContext';
+
+function root(): HTMLElement {
+  return document.querySelector('.lk-lightbox') as HTMLElement;
+}
+
+const expanded = (): boolean => root().classList.contains('lk-lightbox--expanded');
+
+describe('Lightbox', () => {
+  it('does not open on a double-click unless asked to', () => {
+    render(
+      <Lightbox>
+        <div data-testid="out">output</div>
+      </Lightbox>,
+    );
+    fireEvent.doubleClick(screen.getByTestId('out'));
+    expect(expanded()).toBe(false);
+    expect(screen.getByRole('button', { name: 'Expand' })).toBeInTheDocument();
+  });
+
+  it('opens on a double-click on its content when asked to, and closes on another', () => {
+    render(
+      <Lightbox expandOnDoubleClick>
+        <div data-testid="out">output</div>
+      </Lightbox>,
+    );
+    fireEvent.doubleClick(screen.getByTestId('out'));
+    expect(expanded()).toBe(true);
+    expect(root().getAttribute('role')).toBe('dialog');
+    fireEvent.doubleClick(screen.getByTestId('out'));
+    expect(expanded()).toBe(false);
+  });
+
+  it('ignores a double-click on a control, on an opted-out region, or one already handled', () => {
+    render(
+      <Lightbox expandOnDoubleClick>
+        <button type="button">Run</button>
+        <input aria-label="n" />
+        <div data-lk-lightbox-ignore="">
+          <span data-testid="ignored">x</span>
+        </div>
+        {/* biome-ignore lint/a11y/noStaticElementInteractions: the subject is a handler that claims the gesture */}
+        <div data-testid="claimed" onDoubleClick={(e) => e.preventDefault()} />
+      </Lightbox>,
+    );
+    fireEvent.doubleClick(screen.getByRole('button', { name: 'Run' }));
+    fireEvent.doubleClick(screen.getByLabelText('n'));
+    fireEvent.doubleClick(screen.getByTestId('ignored'));
+    fireEvent.doubleClick(screen.getByTestId('claimed'));
+    expect(expanded()).toBe(false);
+  });
+
+  it('opens from the expand button and moves focus to the close button, then back', () => {
+    render(
+      <Lightbox>
+        <div>output</div>
+      </Lightbox>,
+    );
+    const open = screen.getByRole('button', { name: 'Expand' });
+    open.focus();
+    fireEvent.click(open);
+    const close = screen.getByRole('button', { name: 'Close expanded view' });
+    expect(document.activeElement).toBe(close);
+    fireEvent.click(close);
+    expect(expanded()).toBe(false);
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Expand' }));
+  });
+
+  it('closes on Escape unless something inside handled it', () => {
+    render(
+      <Lightbox>
+        {/* biome-ignore lint/a11y/noStaticElementInteractions: stands in for an overlay that consumes its own Escape */}
+        <div data-testid="menu" onKeyDown={(e) => e.preventDefault()} />
+      </Lightbox>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Expand' }));
+    fireEvent.keyDown(screen.getByTestId('menu'), { key: 'Escape' });
+    expect(expanded()).toBe(true);
+    fireEvent.keyDown(document.body, { key: 'Escape' });
+    expect(expanded()).toBe(false);
+  });
+
+  it('closes on a click in the margin, not on one in the content', () => {
+    render(
+      <Lightbox>
+        <div data-testid="out">output</div>
+      </Lightbox>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Expand' }));
+    fireEvent.click(screen.getByTestId('out'));
+    expect(expanded()).toBe(true);
+    fireEvent.click(root());
+    expect(expanded()).toBe(false);
+  });
+
+  it('makes everything outside it inert while open, and only what it marked', () => {
+    render(
+      <div>
+        <aside data-testid="already" inert />
+        <nav data-testid="sibling" />
+        <Lightbox>
+          <div>output</div>
+        </Lightbox>
+      </div>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Expand' }));
+    expect(screen.getByTestId('sibling').hasAttribute('inert')).toBe(true);
+    fireEvent.keyDown(document.body, { key: 'Escape' });
+    expect(screen.getByTestId('sibling').hasAttribute('inert')).toBe(false);
+    expect(screen.getByTestId('already').hasAttribute('inert')).toBe(true);
+  });
+
+  it('marks itself a portal host only while open, so overlays stack inside it', () => {
+    render(
+      <Lightbox>
+        <div>output</div>
+      </Lightbox>,
+    );
+    expect(root().hasAttribute('data-wzl-portal-host')).toBe(false);
+    fireEvent.click(screen.getByRole('button', { name: 'Expand' }));
+    expect(root().hasAttribute('data-wzl-portal-host')).toBe(true);
+  });
+
+  it('drops its corner button while a descendant draws the control', () => {
+    function OwnControl() {
+      const lb = useLightboxControl();
+      return (
+        <button type="button" onClick={lb?.toggle}>
+          Mine
+        </button>
+      );
+    }
+    render(
+      <Lightbox>
+        <OwnControl />
+      </Lightbox>,
+    );
+    expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'Mine' }));
+    expect(expanded()).toBe(true);
+  });
+
+  it('can be controlled', () => {
+    const onChange = vi.fn();
+    function Host() {
+      const [open, setOpen] = useState(true);
+      return (
+        <Lightbox
+          expanded={open}
+          onExpandedChange={(next) => {
+            onChange(next);
+            setOpen(next);
+          }}
+        >
+          <div>output</div>
+        </Lightbox>
+      );
+    }
+    render(<Host />);
+    expect(expanded()).toBe(true);
+    fireEvent.keyDown(document.body, { key: 'Escape' });
+    expect(onChange).toHaveBeenCalledWith(false);
+    expect(expanded()).toBe(false);
+  });
+
+  it('keeps its content mounted when it is turned off', () => {
+    let mounts = 0;
+    function Content() {
+      useState(() => {
+        mounts += 1;
+      });
+      return <div data-testid="out" />;
+    }
+    const { rerender } = render(
+      <Lightbox expandOnDoubleClick>
+        <Content />
+      </Lightbox>,
+    );
+    act(() => {
+      rerender(
+        <Lightbox disabled expandOnDoubleClick>
+          <Content />
+        </Lightbox>,
+      );
+    });
+    fireEvent.doubleClick(screen.getByTestId('out'));
+    expect(expanded()).toBe(false);
+    expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull();
+    expect(mounts).toBe(1);
+  });
+});

package/src/lightbox/Lightbox.tsx

@@ -0,0 +1,205 @@
+import { useLatest } from '@weasel-js/core';
+import { CloseIcon, FullscreenIcon } from '@weasel-js/ui';
+import {
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useSurfaceOptional } from '../surface/useSurfaceTile';
+import { LightboxContext, type LightboxContextValue } from './LightboxContext';
+import { useLightboxLayers } from './LightboxLayers';
+import { inertOutside, liftStack, opensLightbox } from './modal';
+
+/** Props for `<Lightbox>`. */
+export interface LightboxProps {
+  children: ReactNode;
+  /** Names the expanded view for assistive tech. */
+  label?: string;
+  /** Turns the lightbox off: no expand button, no double-click, and an open
+   *  one closes. The content stays mounted either way. */
+  disabled?: boolean;
+  /** Let a double-click on the content open it, and another close it. Off by
+   *  default — the expand button is always there; a double-click is for
+   *  content that has no other use for one, such as an image. */
+  expandOnDoubleClick?: boolean;
+  /** Controlled open state. Omit to let the lightbox keep its own. */
+  expanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  /** Extra class on the outer element. */
+  className?: string;
+}
+
+/** What the root becomes while open: a modal dialog, and the host overlays
+ *  opened inside it portal into, so they stack above it. */
+function dialogProps(label: string) {
+  return {
+    role: 'dialog',
+    'aria-modal': true,
+    'aria-label': label,
+    'data-wzl-portal-host': '',
+  } as const;
+}
+
+/**
+ * Shows its content large, over a dimmed page, from the expand button in its
+ * corner — or a double-click, where `expandOnDoubleClick` asks for one —
+ * without remounting it. The same element is lifted into the browser's top
+ * layer (`popover="manual"`), so a WebGL context or a scene inside keeps
+ * running and sees only a bigger box: anything sizing itself from a
+ * `ResizeObserver` follows on its own. The top layer also escapes an
+ * ancestor's transform, clipping, and stacking.
+ *
+ * Layers declared by a `<LightboxLayers>` above are lifted around it, and a
+ * labkit surface above is scoped to it while it is open, so pixels drawn for
+ * the content from outside it come along.
+ *
+ * Escape, a click on the dimmed margin, the close button, or another
+ * double-click where those open it closes it, and focus returns to wherever it
+ * was. A double-click on a control, inside `[data-lk-lightbox-ignore]`, or one
+ * a handler further in called `preventDefault()` on does not open it.
+ */
+export function Lightbox({
+  children,
+  label = 'Expanded view',
+  disabled = false,
+  expandOnDoubleClick = false,
+  expanded: expandedProp,
+  onExpandedChange,
+  className,
+}: LightboxProps) {
+  const [own, setOwn] = useState(false);
+  const expanded = !disabled && (expandedProp ?? own);
+  const onChangeRef = useLatest(onExpandedChange);
+  const expandedRef = useLatest(expanded);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const closeRef = useRef<HTMLButtonElement | null>(null);
+  const [claims, setClaims] = useState(0);
+  const layers = useLightboxLayers();
+  const surface = useSurfaceOptional();
+
+  const set = useCallback(
+    (next: boolean) => {
+      if (next === expandedRef.current) return;
+      setOwn(next);
+      onChangeRef.current?.(next);
+    },
+    [expandedRef, onChangeRef],
+  );
+
+  const ctx = useMemo<LightboxContextValue | null>(
+    () =>
+      disabled
+        ? null
+        : {
+            expanded,
+            open: () => set(true),
+            close: () => set(false),
+            toggle: () => set(!expandedRef.current),
+            claimControl: () => {
+              setClaims((n) => n + 1);
+              return () => setClaims((n) => n - 1);
+            },
+          },
+    [disabled, expanded, set, expandedRef],
+  );
+
+  // Lift, trap and focus before paint, so the first frame is already the
+  // expanded one. The popover attribute is set here rather than rendered: a
+  // closed popover is `display: none`, which would hide the tile.
+  useLayoutEffect(() => {
+    const el = rootRef.current;
+    if (!expanded || !el) return;
+    const returnTo = document.activeElement as HTMLElement | null;
+    const stack = [...layers.below, el, ...layers.above].filter(
+      (layer): layer is HTMLElement => layer !== null,
+    );
+    const unlift = liftStack(stack, el);
+    const release = inertOutside(stack);
+    // A shared buffer lifted with this one must stop painting every other tile
+    // over it.
+    surface?.scope(el);
+    closeRef.current?.focus({ preventScroll: true });
+    return () => {
+      surface?.scope(null);
+      release();
+      unlift();
+      if (returnTo?.isConnected) returnTo.focus({ preventScroll: true });
+    };
+  }, [expanded, layers, surface]);
+
+  useEffect(() => {
+    if (!expanded) return;
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key !== 'Escape' || e.defaultPrevented) return;
+      e.preventDefault();
+      set(false);
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [expanded, set]);
+
+  const onDoubleClick = (e: MouseEvent<HTMLDivElement>): void => {
+    if (disabled || !expandOnDoubleClick || !opensLightbox(e, e.currentTarget)) return;
+    e.preventDefault();
+    set(!expanded);
+  };
+
+  // Only the margin around the frame is the root's own surface.
+  const onClick = (e: MouseEvent<HTMLDivElement>): void => {
+    if (expanded && e.target === e.currentTarget) set(false);
+  };
+
+  const classes = ['lk-lightbox'];
+  if (expanded) classes.push('lk-lightbox--expanded');
+  if (className) classes.push(className);
+
+  let control: ReactNode = null;
+  if (expanded) {
+    control = (
+      <button
+        ref={closeRef}
+        type="button"
+        className="lk-lightbox__button lk-lightbox__close"
+        aria-label="Close expanded view"
+        title="Close (Esc)"
+        onClick={() => set(false)}
+      >
+        <CloseIcon size={16} />
+      </button>
+    );
+  } else if (!disabled && claims === 0) {
+    control = (
+      <button
+        type="button"
+        className="lk-lightbox__button lk-lightbox__open"
+        aria-label="Expand"
+        title="Expand"
+        onClick={() => set(true)}
+      >
+        <FullscreenIcon size={16} />
+      </button>
+    );
+  }
+
+  return (
+    <LightboxContext.Provider value={ctx}>
+      {/* biome-ignore lint/a11y/noStaticElementInteractions: the double-click is an opt-in shortcut; the expand and close buttons are the keyboard path */}
+      {/* biome-ignore lint/a11y/useKeyWithClickEvents: the margin click mirrors Escape, which is handled on the document */}
+      <div
+        ref={rootRef}
+        className={classes.join(' ')}
+        {...(expanded ? dialogProps(label) : null)}
+        onDoubleClick={onDoubleClick}
+        onClick={onClick}
+      >
+        <div className="lk-lightbox__frame">{children}</div>
+        {control}
+      </div>
+    </LightboxContext.Provider>
+  );
+}

package/src/lightbox/LightboxContext.ts

@@ -0,0 +1,38 @@
+import { createContext, useContext, useLayoutEffect } from 'react';
+
+/** What a `<Lightbox>` offers the content inside it. */
+export interface LightboxApi {
+  /** Whether the content is showing in the lightbox right now. */
+  expanded: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+}
+
+/** The context value: the public API plus the registration the
+ *  default affordance steps aside for. */
+export interface LightboxContextValue extends LightboxApi {
+  claimControl: () => () => void;
+}
+
+export const LightboxContext = createContext<LightboxContextValue | null>(null);
+
+/** The nearest `<Lightbox>`, or `null` outside one. Reading it changes
+ *  nothing; see `useLightboxControl` to replace the default expand button. */
+export function useLightbox(): LightboxApi | null {
+  return useContext(LightboxContext);
+}
+
+/**
+ * The nearest `<Lightbox>`, for a component that draws its own expand
+ * control: while a caller is mounted, the lightbox hides its default corner
+ * button so the tile does not offer two. `<Trial>` uses this to put the
+ * control in its title bar.
+ */
+export function useLightboxControl(): LightboxApi | null {
+  const ctx = useContext(LightboxContext);
+  const claim = ctx?.claimControl;
+  // Layout effect, so the corner button is gone before the first paint.
+  useLayoutEffect(() => claim?.(), [claim]);
+  return ctx;
+}

package/src/lightbox/LightboxLayers.tsx

@@ -0,0 +1,40 @@
+import { createContext, type ReactNode, useContext, useMemo } from 'react';
+
+/** Elements a lightbox lifts with it, in top-layer order around itself. A
+ *  null entry is skipped, so a ref that has not landed yet can be passed as
+ *  it is. */
+export interface LightboxLayerSet {
+  below: readonly (HTMLElement | null)[];
+  above: readonly (HTMLElement | null)[];
+}
+
+const NONE: LightboxLayerSet = { below: [], above: [] };
+
+const LightboxLayersContext = createContext<LightboxLayerSet>(NONE);
+
+/** Props for `<LightboxLayers>`. Keep the arrays stable across renders. */
+export interface LightboxLayersProps extends Partial<LightboxLayerSet> {
+  children: ReactNode;
+}
+
+/**
+ * Declares layers that belong to every lightbox below it: something drawn
+ * for the content from outside it, such as a shared buffer the tiles paint
+ * into. An open lightbox lifts each `below` layer, then itself, then each
+ * `above` layer into the top layer, each covering the window, so they keep
+ * stacking as they did. A layer is measured against the window while lifted,
+ * so whatever positions things inside it must re-measure — a labkit surface
+ * whose container is one of the layers does.
+ */
+export function LightboxLayers({ below, above, children }: LightboxLayersProps) {
+  const value = useMemo(
+    () => ({ below: below ?? NONE.below, above: above ?? NONE.above }),
+    [below, above],
+  );
+  return <LightboxLayersContext.Provider value={value}>{children}</LightboxLayersContext.Provider>;
+}
+
+/** The layers declared above, or none. */
+export function useLightboxLayers(): LightboxLayerSet {
+  return useContext(LightboxLayersContext);
+}

package/src/lightbox/index.ts

@@ -0,0 +1,8 @@
+export { Lightbox, type LightboxProps } from './Lightbox';
+export { type LightboxApi, useLightbox, useLightboxControl } from './LightboxContext';
+export {
+  type LightboxLayerSet,
+  LightboxLayers,
+  type LightboxLayersProps,
+  useLightboxLayers,
+} from './LightboxLayers';

package/src/lightbox/modal.ts

@@ -0,0 +1,94 @@
+/**
+ * Elements whose double-click already means something: a press there edits,
+ * selects text, or works a control. `data-lk-lightbox-ignore` is the opt-out
+ * for anything else.
+ */
+const OWN_DOUBLE_CLICK = [
+  'button',
+  'a[href]',
+  'input',
+  'select',
+  'textarea',
+  'label',
+  'summary',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[role="button"]',
+  '[role="checkbox"]',
+  '[role="combobox"]',
+  '[role="link"]',
+  '[role="menuitem"]',
+  '[role="option"]',
+  '[role="radio"]',
+  '[role="separator"]',
+  '[role="slider"]',
+  '[role="spinbutton"]',
+  '[role="switch"]',
+  '[role="tab"]',
+  '[role="textbox"]',
+  '[data-lk-lightbox-ignore]',
+].join(',');
+
+/** Whether a double-click that reached `root` should open its lightbox:
+ *  nothing handled it first, and it did not land on a control. */
+export function opensLightbox(
+  event: { target: EventTarget | null; defaultPrevented: boolean },
+  root: Element,
+): boolean {
+  if (event.defaultPrevented) return false;
+  const target = event.target;
+  if (!(target instanceof Element)) return true;
+  const owner = target.closest(OWN_DOUBLE_CLICK);
+  return owner === null || !root.contains(owner);
+}
+
+/**
+ * Marks everything outside `keep` inert — every sibling of each kept element
+ * and of each of their ancestors, up to the body — and returns the undo.
+ * Leaves alone what was already inert, so the undo cannot clear someone
+ * else's.
+ */
+export function inertOutside(keep: readonly Element[]): () => void {
+  const path = new Set<Element>();
+  for (const el of keep) {
+    for (let node: Element | null = el; node && node !== document.body; node = node.parentElement) {
+      path.add(node);
+    }
+  }
+  const marked: Element[] = [];
+  for (const node of path) {
+    const parent: Element | null = node.parentElement;
+    if (!parent) continue;
+    for (const sibling of Array.from(parent.children)) {
+      if (path.has(sibling) || sibling.hasAttribute('inert')) continue;
+      sibling.setAttribute('inert', '');
+      marked.push(sibling);
+    }
+  }
+  return () => {
+    for (const sibling of marked) sibling.removeAttribute('inert');
+  };
+}
+
+/**
+ * Lifts `stack` into the top layer in order, so the first ends up lowest, and
+ * returns the undo. The first carries the dimming. Every member but `self` is
+ * marked a layer, which the stylesheet stretches over the window. Does nothing
+ * where the browser has no popover support.
+ */
+export function liftStack(stack: readonly HTMLElement[], self: HTMLElement): () => void {
+  if (typeof self.showPopover !== 'function') return () => {};
+  stack.forEach((el, i) => {
+    el.setAttribute('popover', 'manual');
+    if (el !== self) el.setAttribute('data-lk-lightbox-layer', '');
+    if (i === 0) el.setAttribute('data-lk-lightbox-scrim', '');
+    el.showPopover();
+  });
+  return () => {
+    for (const el of [...stack].reverse()) {
+      if (el.matches(':popover-open')) el.hidePopover();
+      el.removeAttribute('popover');
+      el.removeAttribute('data-lk-lightbox-layer');
+      el.removeAttribute('data-lk-lightbox-scrim');
+    }
+  };
+}

package/src/loupe/AGENTS.md

@@ -18,10 +18,12 @@ This directory binds that model to a labkit trial and draws it.
 | `loupeActions.ts` | `loupe.peek` and `loupe.magnify`, as `Action` descriptors |
 | `LoupeGestures.tsx` | Registers those, and mounts a dispatcher on the host when no camera has one there |
 | `TrialLoupe.tsx` | Finds its host and the trial's switch, picks the painter, mounts the lens |
-| `LoupeBubble.tsx` | The circular clip, positioned on the aim |
+| `LoupeBubble.tsx` | The circle or square clip, positioned on the lens's center |
 | `CanvasLoupe.tsx` | Painter for a `<CanvasStack>` |
 | `canvasLens.ts` | That painter's geometry and drawing, with no React in it |
 | `DomLoupe.tsx` | Painter for DOM content |
+| `SourceLoupe.tsx` | Painter for any canvas named by `source` |
+| `sourceLens.ts` | That painter's source resolution, box measurement and drawing |
 | `useHostSize.ts` | The host's measured box, for the DOM stage |
 
 ## How it reads the trial
@@ -48,11 +50,42 @@ content again; a DOM loupe is always `vector`, since DOM has no framebuffer to
 enlarge. The canvas painter needs the stack's own pixels, which is why a
 drawing instrument mounts the lens in its `render`, inside `<CanvasStack>`.
 
+`source` names a canvas labkit need not own, and wins over the stack: the lens
+enlarges that canvas's pixels (`SourceLoupe`), or, beside `render`, only
+samples its color. The capture rule for WebGL lives with `createCanvasSource`
+in `@weasel-js/loupe`.
+
+## Where the lens goes
+
+By default a lens is a `diameter` box centered on the aim. `place` lets the
+host put it elsewhere per aim — a box of any size at `center`, showing what is
+around `shows` at its own `factor` — and `placeBand` (from `@weasel-js/loupe`)
+is the stock fit of a region shown whole. `useLoupe` resolves the result into
+`loupe.lens`; the bubble is drawn at `lens.center` and the painters are aimed at
+`lens.shows`, which are different points once a lens is moved to stay on the
+host. `onColorChange` still reports the aim.
+
+`hollow` runs no painter and leaves the bubble's inside clear, for a host that
+draws the magnified view itself; `onLens` tells it the box, on each change in
+value and with `null` once a lens that was up goes away.
+
 ## Traps
 
+**A placed lens must reach the model, not only the painters.** `pick` maps a
+point inside the lens back to the page through `LoupeSurface.lens()`; the rect
+it returns carries `shows` and `factor`, and a lens drawn somewhere the model
+does not know about picks colors from the wrong place with every test of the
+drawing still green.
+
 **jsdom cannot see magnification.** Everything assertable there is state — aim
 moved, factor clamped, mode switched, the lens raised and put away. That the
-lens shows the right region is a screenshot.
+lens shows the right region is a screenshot, or a pixel read in a browser test
+(`SourceLoupe.browser.test.tsx`).
+
+**Retain a source by its resolved identity, not the prop.** An inline
+`source={() => ref.current}` is a new function every render, and every aim
+re-renders. Keyed on the prop, the lens released and re-took the source on each
+aim, and each first reader marks a captured frame stale.
 
 **Do not dispose the model when React unmounts.** `dispose` is one-way, and
 StrictMode mounts / unmounts / mounts every effect — so disposing in the
@@ -70,6 +103,11 @@ reason and the dispatcher falls through to the zoom. Outside a camera — the DO
 `GESTURE_DESCRIPTORS` names no continuous-motion gesture, so `pointermove` /
 `pointerleave` stay hand-attached in `useLoupe`. Everything else routes.
 
+**The model ignores aims while the lens is down.** So a lens that comes up
+under a still pointer — the peek key, or the lens turned on — has had no aim
+since the last time it was up. `useLoupe` keeps the pointer's last spot over the
+host and aims there as the lens rises; without it the lens opens at 0,0.
+
 **`<LoupeGestures>` mounts outside the visibility gate.** Hold-to-peek is what
 raises a lens that is down; gate its registration on `loupe.visible` and the
 peek key stops working entirely.

package/src/loupe/CanvasLoupe.tsx

@@ -1,5 +1,5 @@
 import { useLatest, useVisibleRaf } from '@weasel-js/core';
-import type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
+import { type LoupeMode, type LoupePoint, type LoupeSize, loupeExtent } from '@weasel-js/loupe';
 import { useEffect, useRef } from 'react';
 import type { CanvasStackSurface } from '../canvas/CanvasStackContext';
 import type { WorldFrame, WorldSpec } from '../canvas/worldSpec';
@@ -11,7 +11,8 @@ export interface CanvasLoupeProps {
   aim: LoupePoint;
   factor: number;
   mode: LoupeMode;
-  diameter: number;
+  /** One number for a round or square lens, or a width and a height. */
+  diameter: LoupeSize;
   /** The stack being magnified: its layers, its pixels, and its measured box. */
   surface: CanvasStackSurface;
   view: ViewTransform;
@@ -75,8 +76,8 @@ export function CanvasLoupe({
     <canvas
       ref={canvasRef}
       className="lk-loupe__canvas"
-      width={Math.max(1, Math.round(diameter * dpr))}
-      height={Math.max(1, Math.round(diameter * dpr))}
+      width={Math.max(1, Math.round(loupeExtent(diameter).width * dpr))}
+      height={Math.max(1, Math.round(loupeExtent(diameter).height * dpr))}
     />
   );
 }