@weasel-js/labkit 1.8.0 → 1.8.1

package/dist/layers/index.d.ts

@@ -1,5 +1,5 @@
 export { LayerList, LayerListItem, LayerListProps, LayerMove, moveLayers } from '@weasel-js/ui';
-export { ad as LayerCapability, ae as LayerDescriptor } from '../_dts/index-DRaswz91.js';
+export { ae as LayerCapability, af as LayerDescriptor } from '../_dts/index-8geQNQet.js';
 import '@weasel-js/core';
 import 'react';
 import '@weasel-js/theme';

package/dist/layers/index.js

@@ -1,6 +1,6 @@
 import '../chunk-2RVCB2PT.js';
-export { D2 as LayerList, S as moveLayers } from '../chunk-WURZTJGQ.js';
-import '../chunk-E23Q6A3Y.js';
-import '../chunk-XVUKDSYV.js';
+export { A2 as LayerList, T as moveLayers } from '../chunk-V4SMGEYY.js';
+import '../chunk-VCK5T6EP.js';
+import '../chunk-AVOILDN2.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/loupe/index.d.ts

@@ -1,5 +1,5 @@
-import { LoupePoint, LoupeMode } from '@weasel-js/loupe';
-export { LoupeMode, LoupePoint } from '@weasel-js/loupe';
+import { LoupePoint, LoupeMode, LoupeSize, CanvasSource, SourceCanvas, SourceContext, SourceBox } from '@weasel-js/loupe';
+export { BandPlacement, CanvasSource, CanvasSourceOptions, LoupeMode, LoupePoint, LoupeSize, PlaceBandArgs, SourceBox, SourceCanvas, SourceContext, createCanvasSource, loupeExtent, placeBand } from '@weasel-js/loupe';
 import * as react from 'react';
 import { ReactNode, RefObject } from 'react';
 import { CanvasStackSurface, CanvasLayerDescriptor } from '../canvas/index.js';
@@ -18,7 +18,8 @@ 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;
@@ -32,7 +33,7 @@ interface CanvasLoupeProps {
  */
 declare function CanvasLoupe({ aim, factor, mode, diameter, surface, view, frame, worldSpec, }: CanvasLoupeProps): react.JSX.Element;
 
-/** The camera a round lens of `diameter` shows a magnified region through, and
+/** The camera a lens of `size` 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. */
 interface LensCamera {
@@ -45,7 +46,7 @@ interface LensCamera {
  * 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.
  */
-declare function lensCamera(aim: LoupePoint, outer: ViewTransform, outerFrame: WorldFrame, factor: number, diameter: number, worldSpec?: WorldSpec): LensCamera;
+declare function lensCamera(aim: LoupePoint, outer: ViewTransform, outerFrame: WorldFrame, factor: number, size: LoupeSize, worldSpec?: WorldSpec): LensCamera;
 /** A rectangle in a backing store's own device pixels. */
 interface SourceRect {
     sx: number;
@@ -54,10 +55,10 @@ interface SourceRect {
     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.
+ * The region a pixel-mode lens copies out of a presented canvas: `size /
+ * factor` CSS px around `aim`, in that canvas' backing-store pixels.
  */
-declare function lensSourceRect(aim: LoupePoint, factor: number, diameter: number, dpr: number): SourceRect;
+declare function lensSourceRect(aim: LoupePoint, factor: number, size: LoupeSize, dpr: number): SourceRect;
 /**
  * The color a stack presents at a point: the topmost visible layer with
  * anything opaque there, or `null` when every layer is transparent — which is
@@ -69,7 +70,7 @@ declare function sampleStack(layers: readonly CanvasLayerDescriptor[], canvases:
 declare function drawCanvasLens(ctx: CanvasRenderingContext2D, opts: {
     aim: LoupePoint;
     factor: number;
-    diameter: number;
+    diameter: LoupeSize;
     dpr: number;
     mode: 'vector' | 'pixel';
     outer: ViewTransform;
@@ -79,6 +80,33 @@ declare function drawCanvasLens(ctx: CanvasRenderingContext2D, opts: {
     canvases: Map<string, HTMLCanvasElement>;
 }): void;
 
+/** 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. */
+type LoupeSourceTarget = CanvasSource | SourceCanvas | SourceContext;
+type LoupeSource = LoupeSourceTarget | (() => LoupeSourceTarget | null | undefined);
+/** `source` as a `CanvasSource`, or `null` while a getter has nothing yet. */
+declare function resolveLoupeSource(source: LoupeSource | undefined): CanvasSource | null;
+/**
+ * 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.
+ */
+declare function sourceBoxIn(source: CanvasSource, host: HTMLElement | null): SourceBox;
+/** The color a source shows at a host point, or `null` where it shows none. */
+declare function sampleSource(source: CanvasSource, p: LoupePoint, box: SourceBox): string | null;
+/** 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. */
+declare function drawSourceLens(ctx: CanvasRenderingContext2D, opts: {
+    aim: LoupePoint;
+    factor: number;
+    diameter: LoupeSize;
+    dpr: number;
+    source: CanvasSource;
+    box: SourceBox;
+}): void;
+
 /** What a DOM loupe's `render` is handed: the camera to draw the content
  *  through again. */
 interface LoupeRenderArgs {
@@ -93,15 +121,62 @@ interface LoupeRenderArgs {
      *  not the lens. The lens shows a circle cut out of it. */
     size: ViewportSize;
 }
+/** The outline of a lens. On a box that is not square, `'circle'` is an ellipse. */
+type LoupeShape = 'circle' | 'square';
+/** Where a host puts the lens for one aim, in the host's own CSS px. */
+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. */
+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. */
+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.
  */
 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. */
@@ -109,26 +184,61 @@ 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. */
 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;
 }
 /** What `resolveLoupe` fills in for anything a declaration leaves unset. */
@@ -138,10 +248,13 @@ declare const LOUPE_DEFAULTS: {
     readonly maxFactor: 32;
     readonly mode: "vector";
     readonly diameter: 200;
+    readonly shape: "circle";
+    readonly hollow: false;
     readonly peekKey: "Alt";
 };
 /** `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'`. */
 declare function resolveLoupe(options?: LoupeOptions): ResolvedLoupe;
 
 /** Props for `<DomLoupe>`. */
@@ -149,7 +262,8 @@ interface DomLoupeProps {
     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 host the instrument draws into, which the stage reproduces. */
     size: ViewportSize;
     /** The trial's own camera. */
@@ -163,28 +277,33 @@ interface DomLoupeProps {
  *
  * The stage is a full copy of the host, so the instrument's own layout still
  * holds; the camera is composed about the aimed point, which keeps that point
- * where it already was, and the stage is then slid by `diameter / 2 - aim` to
- * bring it to the middle of the lens.
+ * where it already was, and the stage is then slid by half the lens less `aim`
+ * to bring it to the middle of the lens.
  */
 declare function DomLoupe({ aim, factor, mode, diameter, size, view, frame, render, }: DomLoupeProps): react.JSX.Element;
 
 /** Props for `<LoupeBubble>`. */
 interface LoupeBubbleProps {
-    /** Where the lens is aimed, in its container's own pixels. */
+    /** Where the lens is centered, in its container's own pixels. */
     aim: LoupePoint;
-    diameter: number;
+    /** One number for a round or square lens, or a width and a height. */
+    diameter: LoupeSize;
+    /** Default `'circle'`; on a box that is not square, `'circle'` is an ellipse. */
+    shape?: LoupeShape;
+    /** Only the ring and shadow: the inside is left clear for what is under it. */
+    hollow?: boolean;
     hostRef?: RefObject<HTMLDivElement | null>;
-    children: ReactNode;
+    children?: ReactNode;
 }
 /**
- * The lens itself: a circle centred on the aimed point, clipping whatever a
- * painter draws into it.
+ * The lens itself: a circle or a rectangle centered on `aim`, clipping whatever
+ * a painter draws into it.
  *
  * It takes no pointer events, so the pan, the wheel and anything underneath
  * keep working while it is up — and it is `aria-hidden`, since it magnifies
  * content already on the page rather than adding any.
  */
-declare function LoupeBubble({ aim, diameter, hostRef, children }: LoupeBubbleProps): react.JSX.Element;
+declare function LoupeBubble({ aim, diameter, shape, hollow, hostRef, children, }: LoupeBubbleProps): react.JSX.Element;
 
 /**
  * The loupe's two bindable interactions, as `Action` descriptors the gesture
@@ -234,6 +353,24 @@ interface LoupeGesturesProps {
  */
 declare function LoupeGestures(props: LoupeGesturesProps): react.JSX.Element | null;
 
+/** Props for `<SourceLoupe>`. */
+interface SourceLoupeProps {
+    aim: LoupePoint;
+    factor: number;
+    /** One number for a round or square lens, or a width and a height. */
+    diameter: LoupeSize;
+    /** The canvas whose pixels the lens enlarges. */
+    source: LoupeSource;
+    /** The element `aim` is measured in, which the source's box is found against. */
+    hostRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Paints a pixel lens from any canvas — one labkit drew or one it has never
+ * seen, 2D or WebGL. It redraws every frame, since the canvas it reads moves
+ * on its own schedule.
+ */
+declare function SourceLoupe({ aim, factor, diameter, source, hostRef }: SourceLoupeProps): react.JSX.Element;
+
 /** Props for `<TrialLoupe>`. */
 interface TrialLoupeProps extends LoupeOptions {
     /** Whether the lens is turned on. Omitted, it follows the trial's toolbar
@@ -256,9 +393,9 @@ interface TrialLoupeProps extends LoupeOptions {
  *
  * With no `render` inside a `<CanvasStack>`, it re-draws the stack's own
  * layers through a zoomed camera. With `render`, it asks for the content again
- * at a magnified camera.
+ * at a magnified camera. With `source`, it enlarges the pixels of any canvas.
  */
-declare function TrialLoupe({ enabled, view, hostRef, children, render, factor, minFactor, maxFactor, mode, diameter, peekKey, onColorChange, }: TrialLoupeProps): react.JSX.Element;
+declare function TrialLoupe({ enabled, view, hostRef, children, render, source, factor, minFactor, maxFactor, mode, diameter, shape, place, hollow, onLens, peekKey, onColorChange, }: TrialLoupeProps): react.JSX.Element;
 
 /** Options for {@link useLoupe}. */
 interface UseLoupeOptions {
@@ -270,6 +407,12 @@ interface UseLoupeOptions {
     /** Hex color at a host point. Omitted, the loupe reports no color — which
      *  is the honest answer for a surface with no pixels to read. */
     sample?: (p: LoupePoint) => string | null;
+    /** Run `fn` whenever what `sample` reads changes without the aim moving — a
+     *  canvas that animates, or a frame that arrives after the aim did; returns
+     *  an unsubscribe. While the lens is up, each call samples the aim again, on
+     *  top of the sample every aim takes at once. Omitted, color changes only on
+     *  an aim. */
+    subscribeResample?: (fn: () => void) => () => void;
 }
 /** A loupe as a React view reads it. */
 interface LoupeState {
@@ -277,11 +420,16 @@ interface LoupeState {
     visible: boolean;
     /** Where it is aimed, in the host's own pixels. */
     aim: LoupePoint;
+    /** The wheel's magnification. What the lens shows at is `lens.factor`. */
     factor: number;
+    /** The box the lens is drawn in, and what it shows. */
+    lens: LoupeLens;
     mode: LoupeMode;
     color: string | null;
     setMode: (mode: LoupeMode) => void;
     setFactor: (factor: number) => void;
+    /** Sample the aim again, for pixels that changed under a still aim. */
+    resample: () => void;
     /** Sample what the lens shows at a point inside it. */
     pick: (p?: LoupePoint) => string | null;
     /** What `<LoupeGestures>` drives the lens through. Stable for the life of
@@ -299,7 +447,7 @@ interface LoupeState {
  * has no continuous-motion entry, and inventing one to carry the lens' aim
  * would be an input taxonomy change, not a loupe change.
  */
-declare function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions): LoupeState;
+declare function useLoupe({ options, hostRef, enabled, sample, subscribeResample, }: UseLoupeOptions): LoupeState;
 
-export { CanvasLoupe, DomLoupe, LOUPE_DEFAULTS, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID, LoupeBubble, LoupeGestures, TrialLoupe, createLoupeActions, drawCanvasLens, lensCamera, lensSourceRect, resolveLoupe, sampleStack, useLoupe };
-export type { CanvasLoupeProps, DomLoupeProps, LensCamera, LoupeBubbleProps, LoupeGesturesProps, LoupeInputApi, LoupeOptions, LoupeRenderArgs, LoupeState, ResolvedLoupe, SourceRect, TrialLoupeProps, UseLoupeOptions };
+export { CanvasLoupe, DomLoupe, LOUPE_DEFAULTS, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID, LoupeBubble, LoupeGestures, SourceLoupe, TrialLoupe, createLoupeActions, drawCanvasLens, drawSourceLens, lensCamera, lensSourceRect, resolveLoupe, resolveLoupeSource, sampleSource, sampleStack, sourceBoxIn, useLoupe };
+export type { CanvasLoupeProps, DomLoupeProps, LensCamera, LoupeBubbleProps, LoupeGesturesProps, LoupeInputApi, LoupeLens, LoupeOptions, LoupePlaceArgs, LoupePlacement, LoupeRenderArgs, LoupeShape, LoupeSource, LoupeSourceTarget, LoupeState, ResolvedLoupe, SourceLoupeProps, SourceRect, TrialLoupeProps, UseLoupeOptions };