@weasel-js/labkit 1.7.3 → 1.8.1

package/src/instrument/types.ts

@@ -3,6 +3,7 @@ import type { ReactNode } from 'react';
 import type { AnnotationsCapability } from '../annotations/types';
 import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
+import type { ClockCapability, TrialClock } from '../clock/trialClock';
 import type { ConfigPath, ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
@@ -41,6 +42,8 @@ export interface RenderContext<TS = unknown, TC = unknown> {
      * reading it works over either view.
      */
     pointer: PointerContextValue;
+    /** The trial's clock, present when the instrument declares `clock`. */
+    clock?: TrialClock;
   };
   emit: (event: string) => void;
   /** Present only when the instrument declares a `job`. */
@@ -54,7 +57,21 @@ export interface RenderContext<TS = unknown, TC = unknown> {
  *  set `ctx.lineWidth = 1 / zoom` to keep a hairline hairline. */
 export interface CanvasLayer<TS = unknown, TC = unknown> {
   id: string;
-  draw: (ctx: CanvasRenderingContext2D, args: { state: TS; config: TC; zoom: number }) => void;
+  /** Redraw every frame the trial's clock moves, not only when state, config
+   *  or the view change. For a layer that reads `elapsed`, `pass` or `phase`. */
+  timed?: boolean;
+  draw: (
+    ctx: CanvasRenderingContext2D,
+    args: {
+      state: TS;
+      config: TC;
+      zoom: number;
+      /** The trial clock's, as `TrialClock` has them; 0 with no clock. */
+      elapsed: number;
+      pass: number;
+      phase: number;
+    },
+  ) => void;
 }
 
 /** Declares that an instrument draws to a canvas: its layers, and where the
@@ -183,6 +200,9 @@ export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
   annotations?: AnnotationsCapability<TS, TC>;
   /** Chrome this instrument contributes beyond what its capabilities imply. */
   chrome?: TrialContribution[];
+  /** Gives the trial a clock: playback time that layers, renderers and chrome
+   *  read and drive. */
+  clock?: ClockCapability;
   /** Work too slow to do during a render. The runtime starts it, aborts it on
    *  unmount and on a `key` change, and renders progress into the trial. */
   job?: JobCapability<TS, TC, TItem>;

package/src/lab/Lab.chrome.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, it, vi } from 'vitest';
 import type { TrialContribution } from '../chrome/types';
@@ -32,6 +32,13 @@ describe('<Lab> chrome', () => {
     expect(screen.getByRole('button', { name: 'Export' })).toBeInTheDocument();
   });
 
+  it('puts the expand toggle in the trial title bar instead of the tile corner', async () => {
+    await renderSettled(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" />);
+    expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'Expand trial' }));
+    expect(document.querySelector('.lk-lightbox--expanded .lk-trial')).not.toBeNull();
+  });
+
   it('suppresses a built-in by id', async () => {
     await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['snapshot']} />,

package/src/lab/Lab.presentation.test.tsx

@@ -0,0 +1,113 @@
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { createMemoryAdapter } from '../state/adapters';
+import { labPrefix } from '../state/labRecords';
+import { Lab, type LabProps } from './Lab';
+import { LabContext, type LabContextValue } from './LabContext';
+import { type Presentation, usePresentation } from './presentation';
+
+const stub: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({ count: 0 }),
+  initialState: (config) => ({ value: (config as { count: number }).count }),
+  render: ({ state }) => <div data-testid="stub-content">{(state as { value: number }).value}</div>,
+};
+
+let presentation: Presentation | null = null;
+let lab: LabContextValue | null = null;
+function Capture() {
+  presentation = usePresentation();
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        lab = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+function mountLab(props: Partial<LabProps> = {}) {
+  return renderSettled(
+    <Lab {...({ instruments: [stub], defaultInstrument: 'Stub', ...props } as LabProps)}>
+      <Capture />
+    </Lab>,
+  );
+}
+
+const root = (container: HTMLElement) => container.querySelector('.lk-lab') as HTMLElement;
+const presented = (container: HTMLElement) =>
+  container.querySelectorAll<HTMLElement>('.lk-trial[data-lk-presented]');
+
+afterEach(() => {
+  presentation = null;
+  lab = null;
+  history.replaceState(null, '', '/');
+  vi.restoreAllMocks();
+});
+
+describe('<Lab present>', () => {
+  it('presents one trial opened on the seed', async () => {
+    const { container, getByTestId } = await mountLab({
+      present: true,
+      seed: { config: { count: 4 } },
+    });
+    expect(root(container).classList.contains('lk-lab--present')).toBe(true);
+    expect(presented(container)).toHaveLength(1);
+    expect(presented(container)[0]?.querySelector('.lk-trial__stage')).not.toBeNull();
+    expect(getByTestId('stub-content').textContent).toBe('4');
+    expect(presentation?.active).toBe(true);
+  });
+
+  it('presents from `?present` in the URL', async () => {
+    history.replaceState(null, '', '/?present');
+    const { container } = await mountLab();
+    expect(presented(container)).toHaveLength(1);
+  });
+
+  it('keeps a stored lab presenting under its own key', async () => {
+    const storage = createMemoryAdapter();
+    const { unmount } = await mountLab({ present: true, storageKey: 'lab', storage });
+    await waitFor(async () =>
+      expect((await storage.list(labPrefix('lab:present'))).length).toBeGreaterThan(0),
+    );
+    unmount();
+    expect(await storage.list(labPrefix('lab'))).toEqual([]);
+  });
+
+  it('does not leave on Escape, having nowhere to go back to', async () => {
+    const { container } = await mountLab({ present: true });
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(presented(container)).toHaveLength(1);
+  });
+
+  it('warns that a seed is ignored when the lab does not start presenting', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await mountLab({ seed: { config: { count: 4 } } });
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('`seed`'));
+  });
+});
+
+describe('usePresentation', () => {
+  it('presents the focused trial and returns on Escape', async () => {
+    const { container } = await mountLab();
+    await act(async () => lab?.addTrial('Stub', { config: { count: 2 } }));
+    await act(async () => lab?.focusTrial(lab.trials[1]?.id as string));
+    expect(presented(container)).toHaveLength(0);
+
+    await act(async () => presentation?.enter());
+    expect(presented(container)).toHaveLength(1);
+    expect(presented(container)[0]?.dataset.trialId).toBe(lab?.trials[1]?.id);
+
+    await act(async () => fireEvent.keyDown(document, { key: 'Escape' }));
+    expect(presented(container)).toHaveLength(0);
+    expect(root(container).classList.contains('lk-lab--present')).toBe(false);
+  });
+
+  it('throws outside <Lab>', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<Capture />)).toThrow(/inside <Lab>/);
+  });
+});

package/src/lab/Lab.surface.test.tsx

@@ -3,9 +3,10 @@
  * `SurfaceContext` in production — so `useSurfaceOptional()` always answered
  * null and a tile registered from inside a trial reached nothing.
  *
- * The surface is anchored to `.lk-lab__body` rather than wrapped around the
- * workspace: `.lk-lab__body > .lk-workspace { min-width: 0 }` is a direct-child
- * selector, so an extra element between them silently drops that rule.
+ * The surface's layers sit in `.lk-lab__body` beside the workspace rather than
+ * wrapped around it: `.lk-lab__body > .lk-workspace { min-width: 0 }` is a
+ * direct-child selector, so an extra element between them silently drops that
+ * rule.
  */
 import { act } from '@testing-library/react';
 import { renderSettled } from '@weasel-js/react/testing/renderSettled';
@@ -84,19 +85,29 @@ describe('<Lab> surface provider', () => {
     expect(typeof (seen as unknown as SurfaceHandle).registerTile).toBe('function');
   });
 
-  it('stacks an under and an over buffer inside the lab body', async () => {
+  it('stacks an under and an over buffer, each in its own layer of the lab body', async () => {
     const { container } = await renderSettled(
       <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />,
     );
-    const canvases = container.querySelectorAll('.lk-lab__body > canvas.lk-lab__surface');
-    expect(canvases).toHaveLength(2);
+    const layers = container.querySelectorAll('.lk-lab__body > .lk-lab__layer');
     // Source order, because the z-index that separates them is in a stylesheet
     // jsdom does not resolve — this is a proxy for the stacking, not proof of
     // it. The real check is a browser.
-    expect([...canvases].map((c) => c.className)).toEqual([
-      'lk-lab__surface lk-lab__surface--under',
-      'lk-lab__surface lk-lab__surface--over',
+    expect([...layers].map((l) => l.className)).toEqual([
+      'lk-lab__layer lk-lab__layer--under',
+      'lk-lab__layer lk-lab__layer--over',
     ]);
+    for (const layer of layers)
+      expect(layer.querySelector('canvas.lk-lab__surface')).not.toBeNull();
+  });
+
+  it('measures tile rects against the over layer', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />,
+    );
+    expect((seen as SurfaceHandle).getContainer()).toBe(
+      container.querySelector('.lk-lab__layer--over'),
+    );
   });
 
   it('hands a tenant whichever of the two it asks for', async () => {