@weasel-js/labkit 1.8.0 → 1.8.1

package/src/loupe/DomLoupe.tsx

@@ -1,4 +1,4 @@
-import type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
+import { type LoupeMode, type LoupePoint, type LoupeSize, loupeExtent } from '@weasel-js/loupe';
 import type { CSSProperties } from 'react';
 import { zoomAt } from '../canvas/camera';
 import type { ViewportSize, WorldFrame } from '../canvas/worldSpec';
@@ -10,7 +10,8 @@ export 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. */
@@ -25,8 +26,8 @@ export 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.
  */
 export function DomLoupe({
   aim,
@@ -38,10 +39,11 @@ export function DomLoupe({
   frame,
   render,
 }: DomLoupeProps) {
+  const { width, height } = loupeExtent(diameter);
   const style: CSSProperties = {
     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 (
     <div className="lk-loupe__stage" style={style}>

package/src/loupe/Loupe.less

@@ -2,6 +2,12 @@
   position: absolute;
   top: 0;
   left: 0;
+  // The ring sits outside the box the painters fill, centered on the aim;
+  // border-box here too, so `.lk-root`'s resets cannot squeeze that box.
+  box-sizing: border-box;
+  width: calc(var(--lk-loupe-width) + 2 * var(--wzl-border-w));
+  height: calc(var(--lk-loupe-height) + 2 * var(--wzl-border-w));
+  margin: calc(-1 * var(--wzl-border-w));
   border-radius: 50%;
   overflow: hidden;
   // Nothing under the lens stops working while it is up: the pan, the wheel and
@@ -15,6 +21,15 @@
   background: var(--wzl-surface-raised);
 }
 
+.lk-loupe--square {
+  border-radius: var(--wzl-radius-sm);
+}
+
+// The host draws the magnified view into this box itself.
+.lk-loupe--hollow {
+  background: transparent;
+}
+
 // `.lk-canvas-stack__overlay > *` turns pointer events back on for an
 // instrument's own overlay; the lens is the one child that must stay inert.
 .lk-canvas-stack__overlay > .lk-loupe {

package/src/loupe/LoupeBubble.tsx

@@ -1,31 +1,53 @@
-import type { LoupePoint } from '@weasel-js/loupe';
+import { type LoupePoint, type LoupeSize, loupeExtent } from '@weasel-js/loupe';
 import type { CSSProperties, ReactNode, RefObject } from 'react';
+import type { LoupeShape } from './types';
 
 /** Props for `<LoupeBubble>`. */
 export 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.
  */
-export function LoupeBubble({ aim, diameter, hostRef, children }: LoupeBubbleProps) {
-  const style: CSSProperties = {
-    width: `${diameter}px`,
-    height: `${diameter}px`,
-    transform: `translate(${aim.x - diameter / 2}px, ${aim.y - diameter / 2}px)`,
-  };
+export function LoupeBubble({
+  aim,
+  diameter,
+  shape = 'circle',
+  hollow,
+  hostRef,
+  children,
+}: LoupeBubbleProps) {
+  const { width, height } = loupeExtent(diameter);
+  const square = shape === 'square';
+  const style = {
+    '--lk-loupe-width': `${width}px`,
+    '--lk-loupe-height': `${height}px`,
+    transform: `translate(${aim.x - width / 2}px, ${aim.y - height / 2}px)`,
+  } as CSSProperties;
   return (
-    <div ref={hostRef} className="lk-loupe" style={style} aria-hidden="true">
+    <div
+      ref={hostRef}
+      className={['lk-loupe', square && 'lk-loupe--square', hollow && 'lk-loupe--hollow']
+        .filter(Boolean)
+        .join(' ')}
+      style={style}
+      aria-hidden="true"
+    >
       {children}
     </div>
   );

package/src/loupe/SourceLoupe.browser.test.tsx

@@ -0,0 +1,204 @@
+import '@weasel-js/theme/tokens.css';
+import '../styles.less';
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
+import { type CanvasSource, createCanvasSource } from '@weasel-js/loupe';
+import { useEffect, useRef, useState } from 'react';
+import { afterEach, expect, test } from 'vitest';
+import { TrialLoupe } from './TrialLoupe';
+
+// A foreign WebGL canvas — one labkit neither created nor draws — read by the
+// lens. Its pixels only exist in the task that drew them, which is what a
+// real browser shows and jsdom cannot.
+
+afterEach(cleanup);
+
+const CSS_W = 100;
+const CSS_H = 50;
+/** The backing store is twice the CSS box, as on a 2x display. */
+const SCALE = 2;
+/** Four vertical bands, each a quarter of the canvas wide. */
+const BANDS: Array<[number, number, number]> = [
+  [255, 0, 0],
+  [0, 255, 0],
+  [0, 0, 255],
+  [255, 255, 255],
+];
+
+function drawBands(gl: WebGLRenderingContext): void {
+  const w = gl.drawingBufferWidth / BANDS.length;
+  gl.enable(gl.SCISSOR_TEST);
+  BANDS.forEach(([r, g, b], i) => {
+    gl.scissor(i * w, 0, w, gl.drawingBufferHeight);
+    gl.clearColor(r / 255, g / 255, b / 255, 1);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+  });
+  gl.disable(gl.SCISSOR_TEST);
+}
+
+interface SceneProps {
+  /** Whether the drawing code calls `capture()` after it draws. */
+  captures: boolean;
+  onColorChange?: (hex: string) => void;
+  /** Handed the context, and a way to redraw the whole canvas one color — a
+   *  frame that changes what is under a lens that has not moved. */
+  onReady?: (gl: WebGLRenderingContext, fill: (rgb: [number, number, number]) => void) => void;
+}
+
+/** Stands in for an app's own WebGL view: it owns the context, draws on
+ *  demand, and hands the lens a source. */
+function Scene({ captures, onColorChange, onReady }: SceneProps) {
+  const ref = useRef<HTMLCanvasElement | null>(null);
+  const [source, setSource] = useState<CanvasSource | null>(null);
+  const onReadyRef = useRef(onReady);
+
+  useEffect(() => {
+    const canvas = ref.current;
+    const gl = canvas?.getContext('webgl', { preserveDrawingBuffer: false, antialias: false });
+    if (!gl) throw new Error('no WebGL');
+    let solid: [number, number, number] | null = null;
+    const draw = (): void => {
+      if (solid) {
+        gl.clearColor(solid[0] / 255, solid[1] / 255, solid[2] / 255, 1);
+        gl.clear(gl.COLOR_BUFFER_BIT);
+      } else drawBands(gl);
+      if (captures) s.capture();
+    };
+    const s = createCanvasSource(gl, { requestRedraw: draw });
+    draw();
+    setSource(s);
+    onReadyRef.current?.(gl, (rgb) => {
+      solid = rgb;
+      draw();
+    });
+  }, [captures]);
+
+  return (
+    <div style={{ width: CSS_W, height: CSS_H }}>
+      <TrialLoupe
+        enabled
+        source={source ?? undefined}
+        factor={4}
+        diameter={40}
+        peekKey={null}
+        onColorChange={onColorChange}
+      >
+        <canvas
+          ref={ref}
+          width={CSS_W * SCALE}
+          height={CSS_H * SCALE}
+          style={{ display: 'block', width: CSS_W, height: CSS_H }}
+        />
+      </TrialLoupe>
+    </div>
+  );
+}
+
+const frames = (n: number): Promise<void> =>
+  new Promise((resolve) => {
+    const step = (k: number): void => {
+      if (k === 0) resolve();
+      else requestAnimationFrame(() => step(k - 1));
+    };
+    step(n);
+  });
+
+function aim(container: HTMLElement, x: number, y: number): void {
+  const host = container.querySelector('.lk-loupe-host');
+  if (!host) throw new Error('no host');
+  const r = host.getBoundingClientRect();
+  fireEvent.pointerMove(host, { clientX: r.left + x, clientY: r.top + y });
+}
+
+/** The lens pixel at a CSS point inside the lens. */
+function lensPixel(container: HTMLElement, x: number, y: number): number[] {
+  const lens = container.querySelector<HTMLCanvasElement>('.lk-loupe__canvas');
+  if (!lens) throw new Error('no lens');
+  const k = lens.width / 40;
+  const ctx = lens.getContext('2d');
+  if (!ctx) throw new Error('no 2d');
+  return [...ctx.getImageData(Math.floor(x * k), Math.floor(y * k), 1, 1).data];
+}
+
+test('a WebGL canvas without preserveDrawingBuffer reads blank after its frame', async () => {
+  // The premise the capture exists for. If this ever reads the bands, the
+  // browser has started keeping the buffer and the lens would pass for free.
+  let gl: WebGLRenderingContext | null = null;
+  render(<Scene captures={false} onReady={(g) => (gl = g)} />);
+  await frames(3);
+  const canvas = (gl as WebGLRenderingContext | null)?.canvas as HTMLCanvasElement;
+  const probe = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+  probe?.drawImage(canvas, 10, 10, 1, 1, 0, 0, 1, 1);
+  expect([...(probe?.getImageData(0, 0, 1, 1).data ?? [])]).toEqual([0, 0, 0, 0]);
+});
+
+test('the lens magnifies the frame a foreign WebGL canvas captured', async () => {
+  const { container } = render(<Scene captures />);
+  await frames(3);
+  // On the boundary between the green and blue bands, at 4x: the lens spans
+  // 10 CSS px of the canvas, half of each.
+  aim(container, 50, 25);
+  await waitFor(() => expect(lensPixel(container, 10, 20)).toEqual([0, 255, 0, 255]));
+  expect(lensPixel(container, 30, 20)).toEqual([0, 0, 255, 255]);
+
+  aim(container, 12, 25);
+  await waitFor(() => expect(lensPixel(container, 20, 20)).toEqual([255, 0, 0, 255]));
+});
+
+test('without capture the lens has nothing to show', async () => {
+  const { container } = render(<Scene captures={false} />);
+  await frames(3);
+  aim(container, 50, 25);
+  await frames(3);
+  expect(lensPixel(container, 10, 20)).toEqual([0, 0, 0, 0]);
+});
+
+test('reports the captured color on the first aim', async () => {
+  const colors: string[] = [];
+  const { container } = render(<Scene captures onColorChange={(c) => colors.push(c)} />);
+  await frames(3);
+  aim(container, 80, 25);
+  await waitFor(() => expect(colors.at(-1)).toBe('#ffffff'));
+  aim(container, 30, 25);
+  await waitFor(() => expect(colors.at(-1)).toBe('#00ff00'));
+});
+
+test('a still aim follows the canvas as it redraws', async () => {
+  const colors: string[] = [];
+  let fill: ((rgb: [number, number, number]) => void) | undefined;
+  const { container } = render(
+    <Scene captures onColorChange={(c) => colors.push(c)} onReady={(_, f) => (fill = f)} />,
+  );
+  await frames(3);
+  aim(container, 80, 25);
+  await waitFor(() => expect(colors.at(-1)).toBe('#ffffff'));
+  fill?.([255, 0, 255]);
+  await waitFor(() => expect(colors.at(-1)).toBe('#ff00ff'));
+});
+
+test('reads a plain 2D canvas directly, with no capture', async () => {
+  function Flat() {
+    const ref = useRef<HTMLCanvasElement | null>(null);
+    useEffect(() => {
+      const ctx = ref.current?.getContext('2d');
+      if (!ctx) return;
+      ctx.fillStyle = '#ff00ff';
+      ctx.fillRect(0, 0, CSS_W * SCALE, CSS_H * SCALE);
+    }, []);
+    return (
+      <div style={{ width: CSS_W, height: CSS_H }}>
+        <TrialLoupe enabled source={() => ref.current} factor={4} diameter={40} peekKey={null}>
+          <canvas
+            ref={ref}
+            width={CSS_W * SCALE}
+            height={CSS_H * SCALE}
+            style={{ display: 'block', width: CSS_W, height: CSS_H }}
+          />
+        </TrialLoupe>
+      </div>
+    );
+  }
+  const { container } = render(<Flat />);
+  await frames(2);
+  aim(container, 50, 25);
+  await waitFor(() => expect(lensPixel(container, 20, 20)).toEqual([255, 0, 255, 255]));
+});

package/src/loupe/SourceLoupe.tsx

@@ -0,0 +1,60 @@
+import { useLatest, useVisibleRaf } from '@weasel-js/core';
+import { type LoupePoint, type LoupeSize, loupeExtent } from '@weasel-js/loupe';
+import { type RefObject, useEffect, useRef } from 'react';
+import { drawSourceLens, type LoupeSource, resolveLoupeSource, sourceBoxIn } from './sourceLens';
+
+/** Props for `<SourceLoupe>`. */
+export 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.
+ */
+export function SourceLoupe({ aim, factor, diameter, source, hostRef }: SourceLoupeProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(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 (
+    <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))}
+    />
+  );
+}