@weasel-js/labkit 1.0.4 → 1.2.0

package/src/surface/useTiledSurface.test.tsx

@@ -0,0 +1,231 @@
+import { act, render } from '@testing-library/react';
+import { useEffect } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SurfaceFrame, SurfaceHandle } from './useTiledSurface';
+import { useTiledSurface } from './useTiledSurface';
+
+/** jsdom measures everything as zero, so each element is given a box by hand. */
+function stubBox(el: HTMLElement, left: number, top: number, width: number, height: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+interface HarnessProps {
+  frames: SurfaceFrame[];
+  onHandle: (h: SurfaceHandle) => void;
+}
+
+function Harness({ frames, onHandle }: HarnessProps) {
+  const surface = useTiledSurface({
+    onFrame: (f) => {
+      frames.push(f);
+    },
+  });
+  useEffect(() => {
+    onHandle(surface);
+  }, [surface, onHandle]);
+  return (
+    <div
+      data-testid="stage"
+      ref={(el) => {
+        if (!el) return;
+        stubBox(el, 0, 0, 800, 600);
+        surface.containerRef(el);
+      }}
+    >
+      <div
+        data-testid="a"
+        ref={(el) => {
+          if (!el) return;
+          stubBox(el, 0, 0, 400, 600);
+          surface.registerTile('a', el);
+        }}
+      />
+      <div
+        data-testid="b"
+        ref={(el) => {
+          if (!el) return;
+          stubBox(el, 400, 0, 400, 600);
+          surface.registerTile('b', el);
+        }}
+      />
+    </div>
+  );
+}
+
+/** Runs every pending rAF callback. */
+function flushFrames(): void {
+  act(() => {
+    vi.advanceTimersByTime(64);
+  });
+}
+
+describe('useTiledSurface', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) =>
+      setTimeout(() => cb(0), 16),
+    );
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('coalesces three invalidations in one tick into a single frame', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => {
+      handle?.invalidate('a');
+      handle?.invalidate('b');
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    expect(frames).toHaveLength(1);
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+  });
+
+  it('fires nothing on a clean tick', () => {
+    const frames: SurfaceFrame[] = [];
+    render(<Harness frames={frames} onHandle={() => {}} />);
+    flushFrames();
+    frames.length = 0;
+    flushFrames();
+    expect(frames).toHaveLength(0);
+  });
+
+  it('carries every tile rect, not only the dirty ones', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => handle?.invalidate('a'));
+    flushFrames();
+
+    expect([...(frames[0]?.dirty ?? [])]).toEqual(['a']);
+    expect(frames[0]?.rects.get('b')).toEqual({ x: 400, y: 0, w: 400, h: 600 });
+  });
+
+  it('reports the surface size and dpr', () => {
+    vi.stubGlobal('devicePixelRatio', 3);
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => handle?.invalidateAll());
+    flushFrames();
+
+    expect(frames[0]?.dpr).toBe(3);
+    expect(frames[0]?.size).toEqual({ width: 800, height: 600 });
+  });
+
+  it('marks every tile dirty when the dpr changes', () => {
+    vi.stubGlobal('devicePixelRatio', 1);
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    vi.stubGlobal('devicePixelRatio', 2);
+    act(() => handle?.invalidateRects());
+    flushFrames();
+
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+    expect(frames[0]?.dpr).toBe(2);
+  });
+
+  it('re-measures on invalidateRects, which is how a moved tile is caught', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    const { getByTestId } = render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    // A sibling reflow slides tile b left. ResizeObserver sees no size change.
+    stubBox(getByTestId('b'), 320, 0, 400, 600);
+
+    act(() => handle?.invalidateRects());
+    flushFrames();
+
+    expect(frames[0]?.rects.get('b')).toEqual({ x: 320, y: 0, w: 400, h: 600 });
+  });
+
+  it('drops a tile that unregisters', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => {
+      handle?.registerTile('b', null);
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    expect(frames[0]?.rects.has('b')).toBe(false);
+  });
+});

package/src/surface/useTiledSurface.ts

@@ -0,0 +1,157 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { composeRects, rectsEqual } from './composeRects';
+import type { Box, Rect } from './rect';
+
+/** What a surface owner is handed once per animation frame. `rects` carries every
+ *  tile, not only the dirty ones: a scissored draw has to know where it is drawing
+ *  relative to a surface that may have resized under it. */
+export interface SurfaceFrame {
+  dirty: ReadonlySet<string>;
+  rects: ReadonlyMap<string, Rect>;
+  dpr: number;
+  size: { width: number; height: number };
+}
+
+/** The invalidators and the two ref callbacks that publish geometry. */
+export interface SurfaceHandle {
+  /** Mark one tile for redraw. */
+  invalidate: (id: string) => void;
+  /** Mark every tile — what a resize or a tile-set change means. */
+  invalidateAll: () => void;
+  /** Re-measure before the next frame. The escape hatch for a host that knows it
+   *  moved something a ResizeObserver cannot see. */
+  invalidateRects: () => void;
+  registerTile: (id: string, el: HTMLElement | null) => void;
+  containerRef: (el: HTMLElement | null) => void;
+}
+
+export interface UseTiledSurfaceOptions {
+  onFrame: (frame: SurfaceFrame) => void;
+}
+
+export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHandle {
+  const container = useRef<HTMLElement | null>(null);
+  const tiles = useRef(new Map<string, HTMLElement>());
+  const rects = useRef(new Map<string, Rect>());
+  const dirty = useRef(new Set<string>());
+  const needsMeasure = useRef(true);
+  const raf = useRef(0);
+  const observer = useRef<ResizeObserver | null>(null);
+  const lastDpr = useRef(0);
+
+  // Held in a ref so a caller passing an inline closure does not re-create every
+  // callback below on each render.
+  const onFrameRef = useRef(onFrame);
+  onFrameRef.current = onFrame;
+
+  const measure = useCallback((): boolean => {
+    const el = container.current;
+    if (!el) return false;
+    const boxes = new Map<string, Box>();
+    for (const [id, tile] of tiles.current) boxes.set(id, tile.getBoundingClientRect());
+    const next = composeRects(el.getBoundingClientRect(), boxes);
+    let changed = next.size !== rects.current.size;
+    for (const [id, rect] of next) {
+      if (!rectsEqual(rects.current.get(id), rect)) changed = true;
+    }
+    rects.current = next;
+    return changed;
+  }, []);
+
+  const schedule = useCallback(() => {
+    if (raf.current) return;
+    raf.current = requestAnimationFrame(() => {
+      raf.current = 0;
+      const el = container.current;
+      if (!el) {
+        dirty.current.clear();
+        return;
+      }
+      if (needsMeasure.current) {
+        needsMeasure.current = false;
+        if (measure()) for (const id of rects.current.keys()) dirty.current.add(id);
+      }
+      const dpr = globalThis.devicePixelRatio ?? 1;
+      if (dpr !== lastDpr.current) {
+        lastDpr.current = dpr;
+        for (const id of rects.current.keys()) dirty.current.add(id);
+      }
+      if (dirty.current.size === 0) return;
+      const box = el.getBoundingClientRect();
+      onFrameRef.current({
+        dirty: new Set(dirty.current),
+        rects: new Map(rects.current),
+        dpr,
+        size: { width: box.width, height: box.height },
+      });
+      dirty.current.clear();
+    });
+  }, [measure]);
+
+  const invalidate = useCallback(
+    (id: string) => {
+      dirty.current.add(id);
+      schedule();
+    },
+    [schedule],
+  );
+
+  const invalidateAll = useCallback(() => {
+    for (const id of tiles.current.keys()) dirty.current.add(id);
+    schedule();
+  }, [schedule]);
+
+  const invalidateRects = useCallback(() => {
+    needsMeasure.current = true;
+    schedule();
+  }, [schedule]);
+
+  const registerTile = useCallback(
+    (id: string, el: HTMLElement | null) => {
+      const known = tiles.current.get(id);
+      if (known === el) return;
+      if (known) observer.current?.unobserve(known);
+      if (el) {
+        tiles.current.set(id, el);
+        observer.current?.observe(el);
+      } else {
+        tiles.current.delete(id);
+        rects.current.delete(id);
+        dirty.current.delete(id);
+      }
+      needsMeasure.current = true;
+      schedule();
+    },
+    [schedule],
+  );
+
+  const containerRef = useCallback(
+    (el: HTMLElement | null) => {
+      if (container.current === el) return;
+      if (container.current) observer.current?.unobserve(container.current);
+      container.current = el;
+      if (el) observer.current?.observe(el);
+      needsMeasure.current = true;
+      schedule();
+    },
+    [schedule],
+  );
+
+  useEffect(() => {
+    const ro = new ResizeObserver(() => {
+      needsMeasure.current = true;
+      schedule();
+    });
+    observer.current = ro;
+    if (container.current) ro.observe(container.current);
+    for (const el of tiles.current.values()) ro.observe(el);
+    return () => {
+      ro.disconnect();
+      observer.current = null;
+      if (raf.current) cancelAnimationFrame(raf.current);
+      raf.current = 0;
+    };
+  }, [schedule]);
+
+  return { invalidate, invalidateAll, invalidateRects, registerTile, containerRef };
+}

package/src/theme/base.less

@@ -61,7 +61,7 @@
 }
 
 // Cosmic background applied to the Lab root. The starscape sits as a fixed
-// pseudo-element so panning the workspace doesn't shift the field of stars.
+// pseudo-element so panning the trial doesn't shift the field of stars.
 .lk-lab {
   position: relative;
   isolation: isolate;

package/src/{workspace → trial}/DefaultSidebar.tsx

@@ -1,13 +1,13 @@
 import { ControlPanel } from '../controls/ControlPanel';
 import { Sidebar } from '../primitives/Sidebar';
-import type { WorkspaceSidebarContext } from './slotTypes';
+import type { TrialSidebarContext } from './slotTypes';
 
 /** Props for `<DefaultSidebar>`. */
 export interface DefaultSidebarProps {
-  ctx: WorkspaceSidebarContext;
+  ctx: TrialSidebarContext;
 }
 
-/** The sidebar a workspace renders when no `sidebar` slot is supplied: a
+/** The sidebar a trial renders when no `sidebar` slot is supplied: a
  *  control panel over the instrument's config schema. */
 export function DefaultSidebar({ ctx }: DefaultSidebarProps) {
   if (ctx.configFields.length === 0) {

package/src/trial/DefaultStatusBar.tsx

@@ -0,0 +1,19 @@
+import { StatusBar } from '../primitives/StatusBar';
+import { formatZoom } from '../ui/format';
+import type { TrialStatusBarContext } from './slotTypes';
+
+/** Props for `<DefaultStatusBar>`. */
+export interface DefaultStatusBarProps {
+  ctx: TrialStatusBarContext;
+}
+
+/** The status bar a trial renders when no `statusBar` slot is supplied:
+ *  the instrument's name, and the zoom when the trial's view has one. */
+export function DefaultStatusBar({ ctx }: DefaultStatusBarProps) {
+  return (
+    <StatusBar>
+      <StatusBar.Section>{ctx.instrumentName}</StatusBar.Section>
+      {ctx.zoom === null ? null : <StatusBar.Section>{formatZoom(ctx.zoom)}</StatusBar.Section>}
+    </StatusBar>
+  );
+}

package/src/{workspace → trial}/DefaultToolbar.tsx

@@ -1,12 +1,13 @@
 import { Toolbar } from '../primitives/Toolbar';
-import type { WorkspaceToolbarContext } from './slotTypes';
+import { formatZoom } from '../ui/format';
+import type { TrialToolbarContext } from './slotTypes';
 
 /** Props for `<DefaultToolbar>`. */
 export interface DefaultToolbarProps {
-  ctx: WorkspaceToolbarContext;
+  ctx: TrialToolbarContext;
 }
 
-/** The toolbar a workspace renders when no `toolbar` slot is supplied. Only
+/** The toolbar a trial renders when no `toolbar` slot is supplied. Only
  *  shows the controls the instrument's declared capabilities support. */
 export function DefaultToolbar({ ctx }: DefaultToolbarProps) {
   return (
@@ -32,7 +33,7 @@ export function DefaultToolbar({ ctx }: DefaultToolbarProps) {
           <Toolbar.Button onClick={ctx.zoomOut} title="Zoom out">
             −
           </Toolbar.Button>
-          <span className="lk-toolbar__zoom-label">{Math.round(ctx.zoom * 100)}%</span>
+          <span className="lk-toolbar__zoom-label">{formatZoom(ctx.zoom)}</span>
           <Toolbar.Button onClick={ctx.zoomIn} title="Zoom in">
             +
           </Toolbar.Button>
@@ -73,16 +74,16 @@ export function DefaultToolbar({ ctx }: DefaultToolbarProps) {
 
       <Toolbar.Spacer />
 
-      <Toolbar.Button onClick={ctx.clone} title="Clone workspace">
+      <Toolbar.Button onClick={ctx.clone} title="Clone trial">
         Clone
       </Toolbar.Button>
-      <Toolbar.Button onClick={ctx.reset} title="Reset workspace">
+      <Toolbar.Button onClick={ctx.reset} title="Reset trial">
         Reset
       </Toolbar.Button>
       <Toolbar.Button
         onClick={ctx.close}
-        disabled={ctx.isLastWorkspace}
-        title={ctx.isLastWorkspace ? 'Cannot close the last workspace' : 'Close workspace'}
+        disabled={ctx.isLastTrial}
+        title={ctx.isLastTrial ? 'Cannot close the last trial' : 'Close trial'}
       >
         Close
       </Toolbar.Button>

package/src/trial/Trial.canvas.test.tsx

@@ -0,0 +1,80 @@
+import { render, screen } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+
+interface St {
+  n: number;
+}
+
+const ctxSpies = {
+  save: vi.fn(),
+  restore: vi.fn(),
+  setTransform: vi.fn(),
+  clearRect: vi.fn(),
+  translate: vi.fn(),
+  scale: vi.fn(),
+};
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => ctxSpies,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+function makeInstrument(draw: (ctx: CanvasRenderingContext2D, args: unknown) => void) {
+  return defineInstrument<St, Record<string, never>>({
+    name: 'Probe',
+    defaultConfig: () => ({}),
+    initialState: () => ({ n: 7 }),
+    render: ({ state }) => <output data-testid="readout">n = {state.n}</output>,
+    canvas: {
+      initialView: { zoom: 2, pan: { x: 30, y: 40 } },
+      layers: [{ id: 'main', draw }],
+    },
+  });
+}
+
+describe('an instrument that draws', () => {
+  it('still renders its own DOM, as an overlay over the canvas', () => {
+    const { container } = render(
+      <Lab instruments={[makeInstrument(() => undefined)]} defaultInstrument="Probe" />,
+    );
+    expect(screen.getByTestId('readout')).toHaveTextContent('n = 7');
+    expect(container.querySelector('.lk-canvas-stack__overlay')).toContainElement(
+      screen.getByTestId('readout'),
+    );
+    expect(container.querySelectorAll('canvas').length).toBeGreaterThan(0);
+  });
+
+  it('draws with the camera applied, so world geometry lands where the view says', async () => {
+    const draw = vi.fn();
+    render(<Lab instruments={[makeInstrument(draw)]} defaultInstrument="Probe" />);
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+
+    expect(draw).toHaveBeenCalled();
+    expect(ctxSpies.translate).toHaveBeenCalledWith(30, 40);
+    expect(ctxSpies.scale).toHaveBeenCalledWith(2, 2);
+  });
+
+  it('passes zoom in the args so a layer can keep line widths unscaled', async () => {
+    const draw = vi.fn();
+    render(<Lab instruments={[makeInstrument(draw)]} defaultInstrument="Probe" />);
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+
+    expect(draw).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ zoom: 2, state: { n: 7 } }),
+    );
+  });
+});
+
+describe('LabProps.instruments', () => {
+  it('accepts a typed instrument with no cast', () => {
+    // The assignment is the assertion: this file fails to compile if
+    // `defineInstrument<St, ...>`'s result stops being assignable.
+    const typed = makeInstrument(() => undefined);
+    render(<Lab instruments={[typed]} defaultInstrument="Probe" />);
+    expect(screen.getByTestId('readout')).toBeInTheDocument();
+  });
+});

package/src/trial/Trial.job.test.tsx

@@ -0,0 +1,75 @@
+import { render, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { JobEvent } from '../job/types';
+import { Lab } from '../lab/Lab';
+
+interface S {
+  items: number[];
+}
+interface C {
+  n: number;
+}
+
+function makeInstrument(name: string, n: number, delay: number) {
+  return defineInstrument<S, C>({
+    name,
+    defaultConfig: () => ({ n }),
+    initialState: () => ({ items: [] }),
+    render: () => null,
+    job: {
+      auto: true,
+      run: async function* ({ config, signal }): AsyncGenerator<JobEvent<never>> {
+        yield { kind: 'total', total: config.n };
+        for (let i = 0; i < config.n; i++) {
+          await new Promise((r) => setTimeout(r, delay));
+          if (signal.aborted) return;
+          yield { kind: 'item', item: i as never };
+        }
+      },
+      onItem: (item, state) => ({ items: [...state.items, item as number] }),
+    },
+  });
+}
+
+describe('a trial whose instrument declares a job', () => {
+  it('shows progress in the trial chrome', async () => {
+    const fast = makeInstrument('fast', 3, 1);
+    render(<Lab instruments={[fast]} defaultInstrument="fast" storage={null} />);
+    await waitFor(() => {
+      expect(document.querySelector('.lk-trial__job')).toBeInTheDocument();
+    });
+    await waitFor(() => {
+      expect(document.querySelector('.lk-trial__job-count')?.textContent).toMatch(/3\s*\/\s*3/);
+    });
+  });
+
+  it('offers a cancel control while running, and drops it once cancelled', async () => {
+    const slow = makeInstrument('slow', 40, 20);
+    render(<Lab instruments={[slow]} defaultInstrument="slow" storage={null} />);
+    const cancel = await waitFor(() => {
+      const el = document.querySelector('.lk-trial__job-cancel');
+      expect(el).toBeInTheDocument();
+      return el as HTMLElement;
+    });
+    await userEvent.click(cancel);
+    await waitFor(() => {
+      expect(document.querySelector('.lk-trial__job-cancel')).not.toBeInTheDocument();
+    });
+  });
+
+  it('renders no job chrome for an instrument that declares none', async () => {
+    const plain = defineInstrument<S, C>({
+      name: 'plain',
+      defaultConfig: () => ({ n: 0 }),
+      initialState: () => ({ items: [] }),
+      render: () => null,
+    });
+    render(<Lab instruments={[plain]} defaultInstrument="plain" storage={null} />);
+    await waitFor(() => {
+      expect(document.querySelector('.lk-trial')).toBeInTheDocument();
+    });
+    expect(document.querySelector('.lk-trial__job')).not.toBeInTheDocument();
+  });
+});

package/src/{workspace/Workspace.less → trial/Trial.less}

@@ -1,4 +1,4 @@
-.lk-workspace {
+.lk-trial {
   display: flex;
   flex-direction: column;
   height: 100%;
@@ -56,3 +56,15 @@
   color: var(--wzl-fg-muted);
   font-size: var(--wzl-font-size-sm);
 }
+
+.lk-trial__job {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 0.75rem;
+}
+
+.lk-trial__job-failures,
+.lk-trial__job-error {
+  color: var(--wsl-color-danger, #c0392b);
+}