@weasel-js/labkit 1.8.0 → 1.8.1

package/dist/loupe/index.js

@@ -1,27 +1,266 @@
 import { LoupeSwitchContext } from '../chunk-2ES4W47N.js';
 import { centerOn, zoomAt } from '../chunk-ROGJWDQA.js';
 import { screenToWorld } from '../chunk-FG3EXZDV.js';
+import { useSurfaceOptional } from '../chunk-6IIKLXBZ.js';
 import { CameraContext, CameraScope, fromCameraView } from '../chunk-VYVGVBGY.js';
 import { resolveFrame, DEFAULT_FRAME } from '../chunk-ULYYNWGP.js';
 import { CanvasStackContext } from '../chunk-ZQIHJXP4.js';
+import '../chunk-2YILQ7Y5.js';
 import { useLatest, useVisibleRaf, useActionsRegistry, useGestureDispatcher, normalizeZoom } from '@weasel-js/core';
 import { useRef, useEffect, useContext, useReducer, useCallback, useMemo, useState } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
+function loupeExtent(size) {
+  return typeof size === "number" ? { width: size, height: size } : size;
+}
+function loupeSourcePoint(p, rect, aim, factor) {
+  return {
+    x: aim.x + (p.x - (rect.x + rect.w / 2)) / factor,
+    y: aim.y + (p.y - (rect.y + rect.h / 2)) / factor
+  };
+}
+function placeBand({ band, factor, maxWidth, maxHeight }) {
+  let fit = factor;
+  if (band.w > 0) fit = Math.min(fit, maxWidth / band.w);
+  if (maxHeight !== void 0 && band.h > 0) fit = Math.min(fit, maxHeight / band.h);
+  const width = band.w * fit;
+  const height = band.h * fit;
+  const shows = { x: band.x + band.w / 2, y: band.y + band.h / 2 };
+  const within = (c, half, max) => Math.min(Math.max(c, half), Math.max(half, max - half));
+  return {
+    center: {
+      x: within(shows.x, width / 2, maxWidth),
+      y: maxHeight === void 0 ? shows.y : within(shows.y, height / 2, maxHeight)
+    },
+    shows,
+    width,
+    height,
+    factor: fit
+  };
+}
+function createLoupeModel(opts) {
+  const { surface } = opts;
+  let mode = opts.mode ?? "vector";
+  let factor = normalizeZoom(opts.factor ?? 8);
+  let aim = { x: 0, y: 0 };
+  let color = null;
+  let disposed = false;
+  let aimUnsampled = false;
+  const clamp = (n) => normalizeZoom(Math.min(
+    opts.maxFactor ?? Number.POSITIVE_INFINITY,
+    Math.max(opts.minFactor ?? Number.NEGATIVE_INFINITY, n)
+  ));
+  const sampleColor = () => {
+    const hex = surface.sample(aim);
+    if (hex === null || hex === color) return;
+    color = hex;
+    opts.onColorChange?.(hex);
+  };
+  const unsubscribeFrame = surface.subscribeFrame?.(() => {
+    if (!aimUnsampled) return;
+    aimUnsampled = false;
+    sampleColor();
+  });
+  const teardown = () => {
+    if (disposed) return;
+    disposed = true;
+    unsubscribeFrame?.();
+    opts.onDispose?.();
+  };
+  return {
+    get mode() {
+      return mode;
+    },
+    get factor() {
+      return factor;
+    },
+    get aim() {
+      return aim;
+    },
+    get color() {
+      return color;
+    },
+    setMode(next) {
+      if (disposed || next === mode) return;
+      mode = next;
+      surface.changed();
+    },
+    setFactor(next) {
+      if (disposed) return;
+      factor = clamp(next);
+      surface.changed();
+    },
+    aimAt(p) {
+      if (disposed) return;
+      if (surface.gone()) {
+        teardown();
+        return;
+      }
+      if (surface.hidden()) return;
+      if (surface.covers(p)) return;
+      aim = p;
+      if (unsubscribeFrame) aimUnsampled = true;
+      else sampleColor();
+      surface.changed();
+    },
+    pick(p) {
+      if (disposed) return null;
+      let at = aim;
+      if (p) {
+        const rect = surface.lens();
+        if (!rect) return null;
+        at = loupeSourcePoint(p, rect, rect.shows ?? aim, rect.factor ?? factor);
+        if (surface.covers(at)) return null;
+      }
+      const hex = surface.sample(at);
+      if (hex !== null) opts.onPick?.(hex);
+      return hex;
+    },
+    resample() {
+      if (disposed || surface.hidden()) return;
+      aimUnsampled = false;
+      sampleColor();
+    },
+    dispose: teardown
+  };
+}
+var MISSED_FRAMES_BEFORE_WARNING = 120;
+function isWebGL(ctx) {
+  return "drawArrays" in ctx;
+}
+function isContext(target) {
+  return "canvas" in target && !("getContext" in target);
+}
+function makeCanvas(width, height) {
+  if (typeof OffscreenCanvas !== "undefined") return new OffscreenCanvas(width, height);
+  const c = document.createElement("canvas");
+  c.width = width;
+  c.height = height;
+  return c;
+}
+function context2d(canvas, willReadFrequently = false) {
+  return canvas.getContext("2d", { willReadFrequently });
+}
+function createCanvasSource(target, options = {}) {
+  const canvas = isContext(target) ? target.canvas : target;
+  const mustCapture = isContext(target) && isWebGL(target) && !target.getContextAttributes()?.preserveDrawingBuffer;
+  let captured = mustCapture;
+  let readers = 0;
+  let snapshot = null;
+  let current = false;
+  let missed = 0;
+  let warned = false;
+  let probe = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const source = {
+    canvas,
+    get captured() {
+      return captured;
+    },
+    box: options.box,
+    capture() {
+      captured = true;
+      if (readers === 0) return;
+      const { width, height } = canvas;
+      if (width === 0 || height === 0) return;
+      if (!snapshot) snapshot = makeCanvas(width, height);
+      else if (snapshot.width !== width || snapshot.height !== height) {
+        snapshot.width = width;
+        snapshot.height = height;
+      }
+      const ctx = context2d(snapshot);
+      if (!ctx) return;
+      ctx.globalCompositeOperation = "copy";
+      ctx.drawImage(canvas, 0, 0);
+      current = true;
+      missed = 0;
+      for (const fn of listeners) fn();
+    },
+    frame() {
+      if (!captured) return canvas.width > 0 && canvas.height > 0 ? canvas : null;
+      if (current && snapshot) return snapshot;
+      if (!warned && ++missed >= MISSED_FRAMES_BEFORE_WARNING) {
+        warned = true;
+        console.warn(
+          "[weasel loupe] A WebGL canvas without preserveDrawingBuffer is being read, and nothing has called capture() on its source. Call source.capture() right after drawing each frame, or pass requestRedraw if the canvas draws on demand."
+        );
+      }
+      return null;
+    },
+    sample(p) {
+      const frame = source.frame();
+      if (!frame) return null;
+      const x = Math.floor(p.x);
+      const y = Math.floor(p.y);
+      if (x < 0 || y < 0 || x >= canvas.width || y >= canvas.height) return null;
+      if (!probe) {
+        const c = makeCanvas(1, 1);
+        probe = context2d(c, true);
+        if (!probe) return null;
+      }
+      probe.globalCompositeOperation = "copy";
+      probe.drawImage(frame, x, y, 1, 1, 0, 0, 1, 1);
+      const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;
+      if (a === 0) return null;
+      return `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+    },
+    retain() {
+      readers++;
+      if (readers === 1 && captured) {
+        current = false;
+        options.requestRedraw?.();
+      }
+      let held = true;
+      return () => {
+        if (!held) return;
+        held = false;
+        readers--;
+      };
+    },
+    subscribeFrame(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    }
+  };
+  return source;
+}
+function sourceRegion(aim, factor, size, box, backing) {
+  const { width, height } = loupeExtent(size);
+  const spanX = width / factor;
+  const spanY = height / factor;
+  const kx = box.width > 0 ? backing.width / box.width : 1;
+  const ky = box.height > 0 ? backing.height / box.height : 1;
+  return {
+    sx: (aim.x - spanX / 2 - box.x) * kx,
+    sy: (aim.y - spanY / 2 - box.y) * ky,
+    sw: spanX * kx,
+    sh: spanY * ky
+  };
+}
+function sourcePixel(p, box, backing) {
+  const kx = box.width > 0 ? backing.width / box.width : 1;
+  const ky = box.height > 0 ? backing.height / box.height : 1;
+  return { x: (p.x - box.x) * kx, y: (p.y - box.y) * ky };
+}
+
 // src/loupe/canvasLens.ts
-function lensCamera(aim, outer, outerFrame, factor, diameter, worldSpec) {
-  const size = { width: diameter, height: diameter };
-  const frame = resolveFrame(worldSpec, size);
+function lensCamera(aim, outer, outerFrame, factor, size, worldSpec) {
+  const extent = loupeExtent(size);
+  const frame = resolveFrame(worldSpec, extent);
   const world = screenToWorld(aim, outer, outerFrame);
-  return { view: centerOn(world, outer.zoom * factor, size, frame), frame };
+  return { view: centerOn(world, outer.zoom * factor, extent, frame), frame };
 }
-function lensSourceRect(aim, factor, diameter, dpr) {
-  const span = diameter / factor;
+function lensSourceRect(aim, factor, size, dpr) {
+  const { width, height } = loupeExtent(size);
+  const spanX = width / factor;
+  const spanY = height / factor;
   return {
-    sx: (aim.x - span / 2) * dpr,
-    sy: (aim.y - span / 2) * dpr,
-    sw: span * dpr,
-    sh: span * dpr
+    sx: (aim.x - spanX / 2) * dpr,
+    sy: (aim.y - spanY / 2) * dpr,
+    sw: spanX * dpr,
+    sh: spanY * dpr
   };
 }
 function sampleStack(layers, canvases, p, dpr) {
@@ -43,9 +282,10 @@ function sampleStack(layers, canvases, p, dpr) {
 }
 function drawCanvasLens(ctx, opts) {
   const { aim, factor, diameter, dpr, mode, outer, layers, canvases } = opts;
+  const { width, height } = loupeExtent(diameter);
   ctx.save();
   ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
-  ctx.clearRect(0, 0, diameter, diameter);
+  ctx.clearRect(0, 0, width, height);
   if (mode === "pixel") {
     const { sx, sy, sw, sh } = lensSourceRect(aim, factor, diameter, dpr);
     ctx.imageSmoothingEnabled = false;
@@ -53,7 +293,7 @@ function drawCanvasLens(ctx, opts) {
       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.drawImage(canvas, sx, sy, sw, sh, 0, 0, width, height);
     }
     ctx.restore();
     return;
@@ -120,8 +360,8 @@ function CanvasLoupe({
     {
       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))
     }
   );
 }
@@ -135,10 +375,11 @@ function DomLoupe({
   frame,
   render
 }) {
+  const { width, height } = loupeExtent(diameter);
   const style = {
     width: `${size.width}px`,
     height: `${size.height}px`,
-    transform: `translate(${diameter / 2 - aim.x}px, ${diameter / 2 - aim.y}px)`
+    transform: `translate(${width / 2 - aim.x}px, ${height / 2 - aim.y}px)`
   };
   return /* @__PURE__ */ jsx("div", { className: "lk-loupe__stage", style, children: render({
     view: zoomAt(view, factor, aim, { frame }),
@@ -147,13 +388,31 @@ function DomLoupe({
     size
   }) });
 }
-function LoupeBubble({ aim, diameter, hostRef, children }) {
+function LoupeBubble({
+  aim,
+  diameter,
+  shape = "circle",
+  hollow,
+  hostRef,
+  children
+}) {
+  const { width, height } = loupeExtent(diameter);
+  const square = shape === "square";
   const style = {
-    width: `${diameter}px`,
-    height: `${diameter}px`,
-    transform: `translate(${aim.x - diameter / 2}px, ${aim.y - diameter / 2}px)`
+    "--lk-loupe-width": `${width}px`,
+    "--lk-loupe-height": `${height}px`,
+    transform: `translate(${aim.x - width / 2}px, ${aim.y - height / 2}px)`
   };
-  return /* @__PURE__ */ jsx("div", { ref: hostRef, className: "lk-loupe", style, "aria-hidden": "true", children });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: hostRef,
+      className: ["lk-loupe", square && "lk-loupe--square", hollow && "lk-loupe--hollow"].filter(Boolean).join(" "),
+      style,
+      "aria-hidden": "true",
+      children
+    }
+  );
 }
 
 // src/loupe/loupeActions.ts
@@ -252,6 +511,95 @@ function LoupeGestures(props) {
   return /* @__PURE__ */ jsx(LoupeDispatch, { ...props, registry, ownDispatcher: camera === null });
 }
 
+// src/loupe/sourceLens.ts
+function isCanvasSource(t) {
+  return "capture" in t && "retain" in t;
+}
+var made = /* @__PURE__ */ new WeakMap();
+function resolveLoupeSource(source) {
+  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;
+}
+function sourceBoxIn(source, host) {
+  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 };
+}
+function sampleSource(source, p, box) {
+  return source.sample(sourcePixel(p, box, source.canvas));
+}
+function drawSourceLens(ctx, opts) {
+  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();
+}
+function SourceLoupe({ aim, factor, diameter, source, hostRef }) {
+  const canvasRef = useRef(null);
+  const dpr = typeof window === "undefined" ? 1 : window.devicePixelRatio || 1;
+  const argsRef = useLatest({ aim, factor, diameter, dpr, source });
+  const loop = useVisibleRaf(
+    () => {
+      loop.request();
+      const ctx = canvasRef.current?.getContext("2d");
+      const a = argsRef.current;
+      const src = resolveLoupeSource(a.source);
+      if (!ctx || !src) return;
+      drawSourceLens(ctx, {
+        aim: a.aim,
+        factor: a.factor,
+        diameter: a.diameter,
+        dpr: a.dpr,
+        source: src,
+        box: sourceBoxIn(src, hostRef.current)
+      });
+    },
+    { target: canvasRef }
+  );
+  useEffect(() => {
+    loop.request();
+    return () => loop.cancel();
+  }, [loop]);
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: canvasRef,
+      className: "lk-loupe__canvas",
+      width: Math.max(1, Math.round(loupeExtent(diameter).width * dpr)),
+      height: Math.max(1, Math.round(loupeExtent(diameter).height * dpr))
+    }
+  );
+}
+
 // src/loupe/types.ts
 var LOUPE_DEFAULTS = {
   factor: 6,
@@ -259,6 +607,8 @@ var LOUPE_DEFAULTS = {
   maxFactor: 32,
   mode: "vector",
   diameter: 200,
+  shape: "circle",
+  hollow: false,
   peekKey: "Alt"
 };
 function resolveLoupe(options = {}) {
@@ -266,14 +616,19 @@ function resolveLoupe(options = {}) {
   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 === void 0 ? 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
   };
 }
 var ZERO = { width: 0, height: 0 };
@@ -296,99 +651,19 @@ function useHostSize(ref) {
   }, [ref]);
   return size;
 }
-function loupeSourcePoint(p, rect, aim, factor) {
-  return {
-    x: aim.x + (p.x - (rect.x + rect.w / 2)) / factor,
-    y: aim.y + (p.y - (rect.y + rect.h / 2)) / factor
-  };
-}
-function createLoupeModel(opts) {
-  const { surface } = opts;
-  let mode = opts.mode ?? "vector";
-  let factor = normalizeZoom(opts.factor ?? 8);
-  let aim = { x: 0, y: 0 };
-  let color = null;
-  let disposed = false;
-  let aimUnsampled = false;
-  const clamp = (n) => normalizeZoom(Math.min(
-    opts.maxFactor ?? Number.POSITIVE_INFINITY,
-    Math.max(opts.minFactor ?? Number.NEGATIVE_INFINITY, n)
-  ));
-  const sampleColor = () => {
-    const hex = surface.sample(aim);
-    if (hex === null || hex === color) return;
-    color = hex;
-    opts.onColorChange?.(hex);
-  };
-  const unsubscribeFrame = surface.subscribeFrame?.(() => {
-    if (!aimUnsampled) return;
-    aimUnsampled = false;
-    sampleColor();
-  });
-  const teardown = () => {
-    if (disposed) return;
-    disposed = true;
-    unsubscribeFrame?.();
-    opts.onDispose?.();
-  };
-  return {
-    get mode() {
-      return mode;
-    },
-    get factor() {
-      return factor;
-    },
-    get aim() {
-      return aim;
-    },
-    get color() {
-      return color;
-    },
-    setMode(next) {
-      if (disposed || next === mode) return;
-      mode = next;
-      surface.changed();
-    },
-    setFactor(next) {
-      if (disposed) return;
-      factor = clamp(next);
-      surface.changed();
-    },
-    aimAt(p) {
-      if (disposed) return;
-      if (surface.gone()) {
-        teardown();
-        return;
-      }
-      if (surface.hidden()) return;
-      if (surface.covers(p)) return;
-      aim = p;
-      if (unsubscribeFrame) aimUnsampled = true;
-      else sampleColor();
-      surface.changed();
-    },
-    pick(p) {
-      if (disposed) return null;
-      let at = aim;
-      if (p) {
-        const rect = surface.lens();
-        if (!rect) return null;
-        at = loupeSourcePoint(p, rect, aim, factor);
-        if (surface.covers(at)) return null;
-      }
-      const hex = surface.sample(at);
-      if (hex !== null) opts.onPick?.(hex);
-      return hex;
-    },
-    dispose: teardown
-  };
-}
 function lensShown(over, enabled, peeking) {
   return over && (enabled || peeking);
 }
-function useLoupe({ options, hostRef, enabled, sample }) {
+function useLoupe({
+  options,
+  hostRef,
+  enabled,
+  sample,
+  subscribeResample
+}) {
   const [, bump] = useReducer((n) => n + 1, 0);
   const overRef = useRef(false);
+  const pointerRef = useRef(null);
   const peekingRef = useRef(false);
   const enabledRef = useLatest(enabled);
   const sampleRef = useLatest(sample);
@@ -407,9 +682,15 @@ function useLoupe({ options, hostRef, enabled, sample }) {
       onColorChange: (hex) => onColorChangeRef.current?.(hex),
       surface: {
         lens: () => {
-          const d = diameterRef.current;
-          const { x, y } = modelRef.current?.aim ?? { x: 0, y: 0 };
-          return { x: x - d / 2, y: y - d / 2, w: d, h: d };
+          const { center, shows, width, height, factor } = lensRef.current;
+          return {
+            x: center.x - width / 2,
+            y: center.y - height / 2,
+            w: width,
+            h: height,
+            shows,
+            factor
+          };
         },
         // The lens follows the pointer and is painted over the host rather than
         // into it, so it is never part of the picture being magnified.
@@ -422,7 +703,6 @@ function useLoupe({ options, hostRef, enabled, sample }) {
     });
   }
   const model = modelRef.current;
-  const diameterRef = useLatest(options.diameter);
   const goneRef = useRef(false);
   useEffect(() => {
     goneRef.current = false;
@@ -430,14 +710,24 @@ function useLoupe({ options, hostRef, enabled, sample }) {
       goneRef.current = true;
     };
   }, []);
+  const hostRefRef = useLatest(hostRef);
+  const aimAtPointer = useCallback(() => {
+    const host = hostRefRef.current.current;
+    const p = pointerRef.current;
+    if (!host || !p) return;
+    const rect = host.getBoundingClientRect();
+    modelRef.current?.aimAt({ x: p.clientX - rect.left, y: p.clientY - rect.top });
+  }, [hostRefRef]);
   useEffect(() => {
-    if (!enabled && !peekingRef.current) bump();
-  }, [enabled]);
+    if (enabled) aimAtPointer();
+    else if (!peekingRef.current) bump();
+  }, [enabled, aimAtPointer]);
   useEffect(() => {
     const host = hostRef.current;
     if (!host) return;
     const onPointerMove = (e) => {
       overRef.current = true;
+      pointerRef.current = { clientX: e.clientX, clientY: e.clientY };
       const rect = host.getBoundingClientRect();
       model.aimAt({ x: e.clientX - rect.left, y: e.clientY - rect.top });
       if (!shown()) return;
@@ -445,6 +735,7 @@ function useLoupe({ options, hostRef, enabled, sample }) {
     };
     const onPointerLeave = () => {
       overRef.current = false;
+      pointerRef.current = null;
       bump();
     };
     host.addEventListener("pointermove", onPointerMove);
@@ -454,6 +745,45 @@ function useLoupe({ options, hostRef, enabled, sample }) {
       host.removeEventListener("pointerleave", onPointerLeave);
     };
   }, [hostRef, model, shown]);
+  const visible = lensShown(overRef.current, enabled, peekingRef.current);
+  const placed = visible ? options.place?.({ aim: model.aim, factor: model.factor }) ?? null : null;
+  const lens = placed ? {
+    center: placed.center,
+    shows: placed.shows ?? placed.center,
+    width: placed.width,
+    height: placed.height,
+    factor: placed.factor ?? model.factor,
+    shape: options.shape
+  } : {
+    center: model.aim,
+    shows: model.aim,
+    width: options.diameter,
+    height: options.diameter,
+    factor: model.factor,
+    shape: options.shape
+  };
+  const lensRef = useLatest(lens);
+  const onLensRef = useLatest(options.onLens);
+  const reportedRef = useRef(JSON.stringify(null));
+  const report = useCallback(
+    (next) => {
+      const key = JSON.stringify(next);
+      if (key === reportedRef.current) return;
+      reportedRef.current = key;
+      onLensRef.current?.(next);
+    },
+    [onLensRef]
+  );
+  const shownLens = visible ? lens : null;
+  const shownKey = JSON.stringify(shownLens);
+  useEffect(() => {
+    report(JSON.parse(shownKey));
+  }, [shownKey, report]);
+  useEffect(() => () => report(null), [report]);
+  useEffect(() => {
+    if (!visible || !subscribeResample) return;
+    return subscribeResample(() => model.resample());
+  }, [visible, subscribeResample, model]);
   const inputRef = useRef(null);
   if (inputRef.current === null) {
     inputRef.current = {
@@ -461,6 +791,7 @@ function useLoupe({ options, hostRef, enabled, sample }) {
       setPeeking: (on) => {
         if (peekingRef.current === on) return;
         peekingRef.current = on;
+        if (on) aimAtPointer();
         bump();
       },
       magnifyBy: (deltaY) => {
@@ -470,14 +801,15 @@ function useLoupe({ options, hostRef, enabled, sample }) {
     };
   }
   return {
-    // This render's `enabled`: `enabledRef` holds the last committed one.
-    visible: lensShown(overRef.current, enabled, peekingRef.current),
+    visible,
     aim: model.aim,
     factor: model.factor,
+    lens,
     mode: model.mode,
     color: model.color,
     setMode: model.setMode,
     setFactor: model.setFactor,
+    resample: model.resample,
     pick: model.pick,
     input: inputRef.current
   };
@@ -489,31 +821,23 @@ function TrialLoupe({
   hostRef,
   children,
   render,
+  source,
   factor,
   minFactor,
   maxFactor,
   mode,
   diameter,
+  shape,
+  place,
+  hollow,
+  onLens,
   peekKey,
   onColorChange
 }) {
-  const options = useMemo(
-    () => resolveLoupe({
-      render,
-      factor,
-      minFactor,
-      maxFactor,
-      mode,
-      diameter,
-      peekKey,
-      onColorChange
-    }),
-    [render, factor, minFactor, maxFactor, mode, diameter, peekKey, onColorChange]
-  );
   const stack = useContext(CanvasStackContext);
   const camera = useContext(CameraContext);
   const loupeSwitch = useContext(LoupeSwitchContext);
-  const surface = options.render ? void 0 : stack?.surface;
+  const surface = render || source || hollow ? void 0 : stack?.surface;
   const ownHost = useRef(null);
   const cameraHost = useMemo(
     () => camera ? {
@@ -525,43 +849,125 @@ function TrialLoupe({
   );
   const host = surface?.element ?? hostRef ?? cameraHost ?? ownHost;
   const wraps = host === ownHost;
+  const hostLatest = useLatest(host);
+  const tiles = useSurfaceOptional();
+  const onLensLatest = useLatest(onLens);
+  const was = useRef(null);
+  const damage = hollow ? tiles : null;
+  const reportLens = useCallback(
+    (lens2) => {
+      onLensLatest.current?.(lens2);
+      if (!damage) return;
+      const at = hostLatest.current.current?.getBoundingClientRect();
+      const now = lens2 && at ? {
+        left: at.left + lens2.center.x - lens2.width / 2,
+        top: at.top + lens2.center.y - lens2.height / 2,
+        width: lens2.width,
+        height: lens2.height
+      } : null;
+      if (was.current) damage.invalidateBox(was.current);
+      if (now) damage.invalidateBox(now);
+      was.current = now;
+    },
+    [damage, onLensLatest, hostLatest]
+  );
+  const options = useMemo(
+    () => resolveLoupe({
+      render,
+      source,
+      factor,
+      minFactor,
+      maxFactor,
+      mode,
+      diameter,
+      shape,
+      place,
+      hollow,
+      onLens: onLens || damage ? reportLens : void 0,
+      peekKey,
+      onColorChange
+    }),
+    [
+      render,
+      source,
+      factor,
+      minFactor,
+      maxFactor,
+      mode,
+      diameter,
+      shape,
+      place,
+      hollow,
+      onLens,
+      damage,
+      reportLens,
+      peekKey,
+      onColorChange
+    ]
+  );
   const mount = enabled === void 0 ? loupeSwitch?.mount : void 0;
   useEffect(() => mount?.(), [mount]);
   const sample = useMemo(() => {
+    if (options.source) {
+      const input = options.source;
+      return (p) => {
+        const src = resolveLoupeSource(input);
+        return src ? sampleSource(src, p, sourceBoxIn(src, host.current)) : null;
+      };
+    }
     if (!surface) return void 0;
     return (p) => {
       const canvases = surface.canvases.current;
       return canvases ? sampleStack(surface.layers, canvases, p, surface.size.dpr) : null;
     };
-  }, [surface]);
+  }, [surface, options.source, host]);
+  const resolved = resolveLoupeSource(options.source);
+  const subscribeResample = useMemo(
+    () => resolved ? (fn) => resolved.subscribeFrame(fn) : void 0,
+    [resolved]
+  );
   const loupe = useLoupe({
     options,
     hostRef: host,
     enabled: enabled ?? loupeSwitch?.on ?? false,
-    sample
+    sample,
+    subscribeResample
   });
+  const reading = loupe.visible ? resolved : null;
+  useEffect(() => reading?.retain(), [reading]);
   const measured = useHostSize(host);
   const size = surface?.size ?? measured;
   const gestures = /* @__PURE__ */ jsx(CameraScope, { children: /* @__PURE__ */ jsx(LoupeGestures, { hostRef: host, input: loupe.input, peekKey: options.peekKey ?? null }) });
-  const lens = loupe.visible ? /* @__PURE__ */ jsx(LoupeBubble, { aim: loupe.aim, diameter: options.diameter, children: options.render ? /* @__PURE__ */ jsx(
+  const { center, shows, width, height, factor: shownFactor, shape: lensShape } = loupe.lens;
+  const box = { width, height };
+  const lens = loupe.visible ? /* @__PURE__ */ jsx(LoupeBubble, { aim: center, diameter: box, shape: lensShape, hollow: options.hollow, children: options.hollow ? null : options.render ? /* @__PURE__ */ jsx(
     DomLoupe,
     {
-      aim: loupe.aim,
-      factor: loupe.factor,
+      aim: shows,
+      factor: shownFactor,
       mode: loupe.mode,
-      diameter: options.diameter,
+      diameter: box,
       size,
       view: view ?? stack?.view ?? (camera ? fromCameraView(camera.view.get(), camera.frame) : IDENTITY),
       frame: stack?.frame ?? camera?.frame,
       render: options.render
     }
+  ) : options.source ? /* @__PURE__ */ jsx(
+    SourceLoupe,
+    {
+      aim: shows,
+      factor: shownFactor,
+      diameter: box,
+      source: options.source,
+      hostRef: host
+    }
   ) : surface && stack ? /* @__PURE__ */ jsx(
     CanvasLoupe,
     {
-      aim: loupe.aim,
-      factor: loupe.factor,
+      aim: shows,
+      factor: shownFactor,
       mode: loupe.mode,
-      diameter: options.diameter,
+      diameter: box,
       surface,
       view: stack.view,
       frame: stack.frame,
@@ -582,6 +988,6 @@ function TrialLoupe({
   ] });
 }
 
-export { CanvasLoupe, DomLoupe, LOUPE_DEFAULTS, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID, LoupeBubble, LoupeGestures, TrialLoupe, createLoupeActions, drawCanvasLens, lensCamera, lensSourceRect, resolveLoupe, sampleStack, useLoupe };
+export { CanvasLoupe, DomLoupe, LOUPE_DEFAULTS, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID, LoupeBubble, LoupeGestures, SourceLoupe, TrialLoupe, createCanvasSource, createLoupeActions, drawCanvasLens, drawSourceLens, lensCamera, lensSourceRect, loupeExtent, placeBand, resolveLoupe, resolveLoupeSource, sampleSource, sampleStack, sourceBoxIn, useLoupe };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map