@weasel-js/labkit 1.4.4 → 1.5.0

package/src/instrument/serializers.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { configMigrationsOf } from './serializers';
+import type { InstrumentList } from './types';
+
+const instrument = (name: string, extra: Record<string, unknown> = {}) => ({
+  name,
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+  ...extra,
+});
+
+describe('configMigrationsOf', () => {
+  it('keys each declared migration by instrument name, and skips the rest', () => {
+    const migrations = configMigrationsOf([
+      instrument('moves', { migrateConfig: (c: unknown) => ({ moved: c }) }),
+      instrument('stays'),
+    ] as InstrumentList);
+    expect(Object.keys(migrations)).toEqual(['moves']);
+    expect(migrations.moves?.({ a: 1 })).toEqual({ moved: { a: 1 } });
+  });
+});

package/src/instrument/serializers.ts

@@ -12,6 +12,17 @@ export function configDefaultsOf(instruments: InstrumentList): Record<string, ()
   return out;
 }
 
+/** Each instrument's `migrateConfig`, keyed by name, for those that declare one. */
+export function configMigrationsOf(
+  instruments: InstrumentList,
+): Record<string, (stored: unknown) => unknown> {
+  const out: Record<string, (stored: unknown) => unknown> = {};
+  for (const { name, migrateConfig } of instruments) {
+    if (migrateConfig) out[name] = (stored) => migrateConfig(stored);
+  }
+  return out;
+}
+
 /**
  * The `serialize` / `deserialize` an instrument list declares, keyed by
  * instrument name — what `createLabStore` needs to rebuild a trial's state

package/src/instrument/types.ts

@@ -67,6 +67,19 @@ export interface CanvasCapability<TS = unknown, TC = unknown> {
   maxZoom?: number;
 }
 
+/** Declares that an instrument's DOM is content of a fixed size, which the
+ *  trial pans and zooms the way it does a canvas's layers. Not combined with
+ *  `canvas`: there the DOM is an unzoomed overlay, and `canvas` wins. */
+export interface StageCapability {
+  /** The content's own size in CSS pixels, at zoom 1. */
+  size: ViewportSize;
+  /** Where the view starts. Omitted, the content opens centered and shrunk to
+   *  fit (`fitStage`). A function is called once the stage knows its size. */
+  initialView?: ViewTransform | ((viewport: ViewportSize) => ViewTransform);
+  minZoom?: number;
+  maxZoom?: number;
+}
+
 /** Declares which of an instrument's layers the trial should offer
  *  show/hide controls for. */
 export interface LayerCapability {
@@ -99,7 +112,8 @@ export type SystemEvent = string;
 export type Point = { x: number; y: number };
 /** What a hit-test found, and where. */
 export type HitResult = { hit: boolean; layerId?: string; pointId?: string };
-/** A trial's camera. */
+/** A trial's camera. `zoom` is always positive and finite once labkit holds
+ *  it — see `normalize2DView`. */
 export type ViewTransform = { zoom: number; pan: Point };
 /** A layer as the layer list shows it. `alwaysOn` layers cannot be hidden. */
 export type LayerDescriptor = { id: string; label: string; alwaysOn?: boolean };
@@ -119,7 +133,10 @@ export type DragFeedback = { ok: boolean; reason?: string };
  * is what makes the trial provide the corresponding chrome.
  */
 export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
+  /** The id a trial record names its instrument by. */
   name: string;
+  /** What a trial of this instrument and the add-trial menu read. Default: `name`. */
+  title?: string;
   defaultConfig: () => TC;
   initialState: (config: TC) => TS;
   /** The instrument's config, declared once: values, types and controls.
@@ -133,9 +150,16 @@ export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
    *  layers rather than instead of them; return `null` for canvas only. */
   render: (ctx: RenderContext<TS, TC>) => ReactNode;
   onConfigChange?: (config: TC, prev: TC, state: TS) => TS;
+  /** Moves a stored config's values to where the current schema keeps them —
+   *  `gridSize` to `grid.size` — before the defaults fill its gaps, so it
+   *  returns only what it moved and leaves the rest to them. It runs on every
+   *  read of a stored config, including one already moved, so it must hand
+   *  back a current config unchanged. */
+  migrateConfig?: (stored: unknown) => unknown;
   serialize?: (state: TS) => unknown;
   deserialize?: (data: unknown, config: TC) => TS;
   canvas?: CanvasCapability<TS, TC>;
+  stage?: StageCapability;
   layers?: LayerCapability;
   dragDrop?: DragDropCapability<TS, TC>;
   undo?: UndoCapability;

package/src/lab/Lab.less

@@ -1,17 +1,8 @@
-// `height: 100%` resolves against the containing block, so the lab needs an
-// unbroken chain of sized ancestors — and a host that supplies the height but
-// not the margin reset gets a page 16px taller than the viewport, which reads
-// as a stuck canvas rather than as overflow. Scoped with `:has` so a page that
-// mounts no lab is untouched, and stopping at the lab's own parent so an
-// embedded lab cannot resize its host's layout.
-html:has(.lk-lab),
-body:has(.lk-lab) {
+// A fullscreen lab's page is the viewport, and body's default margin would
+// scroll it. `<LabShell>` alone fills the viewport too. `:has` leaves a page
+// that mounts neither untouched.
+body:has(.lk-lab, .lk-shell) {
   margin: 0;
-  height: 100%;
-}
-
-body:has(.lk-lab) > :has(> .lk-lab) {
-  height: 100%;
 }
 
 .lk-lab {

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

@@ -0,0 +1,147 @@
+import 'fake-indexeddb/auto';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { StrictMode } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { createMemoryAdapter, indexedDbAdapter, resetDefaultStorage } from '../state/adapters';
+import { labPrefix } from '../state/labRecords';
+import type { StorageAdapter } from '../state/types';
+import { Lab } from './Lab';
+import { LabContext, type LabContextValue } from './LabContext';
+
+const stub: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div data-testid="stub-content">stub</div>,
+};
+
+let labRef: LabContextValue | null = null;
+function CaptureLab() {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        labRef = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+/** A memory adapter whose first `list` waits until released. */
+function gated() {
+  const memory = createMemoryAdapter();
+  let release = (): void => {};
+  const opened = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const storage: StorageAdapter = {
+    ...memory,
+    list: async (prefix) => {
+      await opened;
+      return memory.list(prefix);
+    },
+  };
+  return { storage, release };
+}
+
+afterEach(() => {
+  resetDefaultStorage();
+  vi.restoreAllMocks();
+});
+
+describe('<Lab> with a storageKey', () => {
+  it('renders its fallback until the lab has loaded', async () => {
+    const { storage, release } = gated();
+    render(
+      <Lab
+        instruments={[stub]}
+        defaultInstrument="Stub"
+        storageKey="gate"
+        storage={storage}
+        fallback={<p>loading</p>}
+      />,
+    );
+    expect(screen.getByText('loading')).toBeInTheDocument();
+    expect(screen.queryByTestId('stub-content')).toBeNull();
+    await act(async () => release());
+    expect(await screen.findByTestId('stub-content')).toBeInTheDocument();
+    expect(screen.queryByText('loading')).toBeNull();
+  });
+
+  it("falls back to the lab's empty shell by default", () => {
+    const { storage } = gated();
+    const { container } = render(
+      <Lab
+        instruments={[stub]}
+        defaultInstrument="Stub"
+        storageKey="gate"
+        storage={storage}
+        title="Waiting"
+      />,
+    );
+    expect(container.querySelector('.lk-lab .lk-shell')).not.toBeNull();
+    expect(screen.getByText('Waiting')).toBeInTheDocument();
+    expect(screen.queryByRole('region', { name: /trial/i })).toBeNull();
+  });
+
+  it('opens the lab once under StrictMode', async () => {
+    const storage = createMemoryAdapter();
+    const list = vi.spyOn(storage, 'list');
+    render(
+      <StrictMode>
+        <Lab instruments={[stub]} defaultInstrument="Stub" storageKey="strict" storage={storage} />
+      </StrictMode>,
+    );
+    await screen.findByTestId('stub-content');
+    expect(list).toHaveBeenCalledTimes(1);
+  });
+
+  it('persists to IndexedDB when given no storage', async () => {
+    const view = render(
+      <Lab instruments={[stub]} defaultInstrument="Stub" storageKey="idb-lab">
+        <CaptureLab />
+      </Lab>,
+    );
+    await screen.findByTestId('stub-content');
+    act(() => labRef?.setMode('light'));
+    view.unmount();
+    await waitFor(async () => {
+      const records = new Map(await indexedDbAdapter.list(labPrefix('idb-lab')));
+      expect(records.get(`${labPrefix('idb-lab')}meta`)).toMatchObject({ mode: 'light' });
+    });
+  });
+
+  it('warns when its storageKey changes after mount, and keeps the first', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const storage = createMemoryAdapter();
+    const view = render(
+      <Lab instruments={[stub]} defaultInstrument="Stub" storageKey="one" storage={storage} />,
+    );
+    await screen.findByTestId('stub-content');
+    view.rerender(
+      <Lab instruments={[stub]} defaultInstrument="Stub" storageKey="two" storage={storage} />,
+    );
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('`storageKey`'));
+  });
+
+  it('closes the lab on unmount, sending what was queued', async () => {
+    const backing = new Map<string, unknown>();
+    const view = render(
+      <Lab
+        instruments={[stub]}
+        defaultInstrument="Stub"
+        storageKey="close"
+        storage={createMemoryAdapter(backing)}
+      >
+        <CaptureLab />
+      </Lab>,
+    );
+    await screen.findByTestId('stub-content');
+    act(() => labRef?.setMode('dark'));
+    view.unmount();
+    await waitFor(() =>
+      expect(backing.get(`${labPrefix('close')}meta`)).toMatchObject({ mode: 'dark' }),
+    );
+  });
+});

package/src/lab/Lab.stories.tsx

@@ -27,7 +27,6 @@ export const Default: Story = {
     instruments: [StubInstrument],
     defaultInstrument: 'Stub',
     title: 'Default Lab',
-    storage: null,
   },
 };
 
@@ -44,7 +43,6 @@ export const TwoTrials: Story = {
     instruments: [StubInstrument],
     defaultInstrument: 'Stub',
     title: 'Two Trials',
-    storage: null,
     children: <AddSecondTrial />,
   },
 };

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

@@ -12,7 +12,7 @@ import type { ReactNode } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { SurfaceContext } from '../surface/SurfaceContext';
-import { useSurfaceOptional, useSurfaceTile, useTileId } from '../surface/useSurfaceTile';
+import { useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId } from '../surface/useSurfaceTile';
 import type { SurfaceFrame, SurfaceHandle } from '../surface/useTiledSurface';
 import { useTiledSurface } from '../surface/useTiledSurface';
 import { Lab } from './Lab';
@@ -43,9 +43,21 @@ let seen: SurfaceHandle | null | 'not-rendered' = 'not-rendered';
  *  trial is scoped by it, and the trial's id is minted by the store. */
 let paneTileId = 'pane';
 
+interface SeenCanvases {
+  over: HTMLCanvasElement | null;
+  under: HTMLCanvasElement | null;
+  byDefault: HTMLCanvasElement | null;
+}
+let seenCanvases: SeenCanvases = { over: null, under: null, byDefault: null };
+
 function Probe() {
   seen = useSurfaceOptional();
   paneTileId = useTileId('pane');
+  seenCanvases = {
+    over: useSurfaceCanvas('over'),
+    under: useSurfaceCanvas('under'),
+    byDefault: useSurfaceCanvas(),
+  };
   const tile = useSurfaceTile('pane');
   return <div data-testid="pane" ref={tile} />;
 }
@@ -66,10 +78,34 @@ describe('<Lab> surface provider', () => {
     expect(typeof (seen as unknown as SurfaceHandle).registerTile).toBe('function');
   });
 
-  it('mounts one inert buffer inside the lab body', () => {
+  it('stacks an under and an over buffer inside the lab body', () => {
     const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
     const canvases = container.querySelectorAll('.lk-lab__body > canvas.lk-lab__surface');
-    expect(canvases).toHaveLength(1);
+    expect(canvases).toHaveLength(2);
+    // 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',
+    ]);
+  });
+
+  it('hands a tenant whichever of the two it asks for', () => {
+    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const [underEl, overEl] = [...container.querySelectorAll('canvas.lk-lab__surface')];
+    expect(seenCanvases.over).toBe(overEl);
+    expect(seenCanvases.under).toBe(underEl);
+    expect(overEl).not.toBe(underEl);
+  });
+
+  it('defaults a tenant to the buffer over the trials', () => {
+    // Every tenant predating the split wants the over one: the surface was
+    // built for marks that annotate an instrument.
+    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const [underEl, overEl] = [...container.querySelectorAll('canvas.lk-lab__surface')];
+    expect(seenCanvases.byDefault).toBe(overEl);
+    expect(seenCanvases.byDefault).not.toBe(underEl);
   });
 
   it('mounts no buffer of its own when a host already owns the surface', () => {
@@ -165,3 +201,30 @@ describe('<Lab> tile round trip', () => {
     expect(rect).toEqual({ x: 240, y: 100, w: 320, h: 200 });
   });
 });
+
+describe('<Lab> pages', () => {
+  it('gives the title a way back to the project\'s other labs', () => {
+    const { getByRole } = render(
+      <Lab
+        instruments={[probeInstrument]}
+        defaultInstrument="Probe"
+        title="kliegsminister"
+        path="/kliegsminister"
+        pages={[
+          { href: '/kliegsminister', label: 'kliegsminister' },
+          { href: '/stats', label: 'corpus stats' },
+        ]}
+      />,
+    );
+    // A switcher, not a bare heading: the lab it came from has to be reachable.
+    expect(getByRole('button', { name: /kliegsminister/ })).toBeTruthy();
+  });
+
+  it('leaves the title a plain heading when there are no other labs', () => {
+    const { getByRole, queryByRole } = render(
+      <Lab instruments={[probeInstrument]} defaultInstrument="Probe" title="solo" />,
+    );
+    expect(getByRole('heading', { name: 'solo' })).toBeTruthy();
+    expect(queryByRole('button', { name: /solo/ })).toBeNull();
+  });
+});

package/src/lab/Lab.test.tsx

@@ -1,10 +1,9 @@
-import { act, render, screen } from '@testing-library/react';
-import type { ReactNode } from 'react';
-import { describe, expect, it, vi } from 'vitest';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { type ReactNode, useEffect } from 'react';
+import { describe, expect, it } from 'vitest';
 import type { Instrument } from '../instrument/types';
 import { createMemoryAdapter } from '../state/adapters';
-import { labDocumentKey } from '../state/document';
-import { Lab } from './Lab';
+import { Lab, type LabProps } from './Lab';
 import { LabContext, type LabContextValue } from './LabContext';
 
 const stub: Instrument = {
@@ -33,10 +32,10 @@ function CaptureLab({ children }: { children?: ReactNode }) {
   );
 }
 
-function mountLab(props: Partial<Parameters<typeof Lab>[0]> = {}) {
+function mountLab(props: Partial<Record<keyof LabProps, unknown>> = {}) {
   labRef = null;
   return render(
-    <Lab instruments={[stub, stubB]} defaultInstrument="Stub" {...props}>
+    <Lab {...({ instruments: [stub, stubB], defaultInstrument: 'Stub', ...props } as LabProps)}>
       <CaptureLab />
     </Lab>,
   );
@@ -142,9 +141,8 @@ describe('<Lab>', () => {
   // the only thing positioned to collect them off the instruments. They went
   // uncollected for months, and an instrument holding anything JSON drops
   // lost it with no error.
-  it('gives the store the serializers its instruments declare', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
+  it('gives the store the serializers its instruments declare', async () => {
+    const backing = new Map<string, unknown>();
     const mapped: Instrument = {
       ...stub,
       name: 'Mapped',
@@ -152,15 +150,91 @@ describe('<Lab>', () => {
       serialize: (state) => ({ seen: [...(state as { seen: Set<string> }).seen] }),
       deserialize: (data) => ({ seen: new Set((data as { seen: string[] }).seen) }),
     };
+    const storage = () => createMemoryAdapter(backing);
 
-    render(
-      <Lab instruments={[mapped]} defaultInstrument="Mapped" storage={storage} storageKey="s" />,
+    const first = render(
+      <Lab instruments={[mapped]} defaultInstrument="Mapped" storage={storage()} storageKey="s" />,
     );
-    act(() => vi.advanceTimersByTime(500));
-    expect(storage.read(labDocumentKey('s')) ?? '').toContain('"seen":["a"]');
-    vi.useRealTimers();
-
-    mountLab({ instruments: [mapped], defaultInstrument: 'Mapped', storage, storageKey: 's' });
+    await waitFor(() => expect(JSON.stringify([...backing.values()])).toContain('"seen":["a"]'));
+    first.unmount();
+
+    mountLab({
+      instruments: [mapped],
+      defaultInstrument: 'Mapped',
+      storage: storage(),
+      storageKey: 's',
+    });
+    await waitFor(() => expect(labRef?.trials[0]).toBeDefined());
     expect((labRef?.trials[0]?.state as { seen: Set<string> }).seen).toEqual(new Set(['a']));
   });
 });
+
+describe('instruments that change while mounted', () => {
+  it('fills an open trial’s config before its replaced instrument renders', () => {
+    const v1: Instrument = {
+      name: 'Grow',
+      defaultConfig: () => ({ size: 1 }),
+      initialState: () => ({}),
+      render: () => null,
+    };
+    const seenByV2: Array<{ color?: string }> = [];
+    const v2: Instrument = {
+      ...v1,
+      defaultConfig: () => ({ size: 1, color: 'red' }),
+      render: ({ config }) => {
+        seenByV2.push(config as { color?: string });
+        return null;
+      },
+    };
+    const view = render(
+      <Lab instruments={[v1]} defaultInstrument="Grow">
+        <CaptureLab />
+      </Lab>,
+    );
+    view.rerender(
+      <Lab instruments={[v2]} defaultInstrument="Grow">
+        <CaptureLab />
+      </Lab>,
+    );
+    expect(labRef?.trials[0]?.config).toEqual({ size: 1, color: 'red' });
+    expect(seenByV2.length).toBeGreaterThan(0);
+    expect(seenByV2.every((c) => c.color === 'red')).toBe(true);
+  });
+
+  it('opens a trial of an instrument added after mount', () => {
+    const later: Instrument = { ...stub, name: 'Later' };
+    const view = render(
+      <Lab instruments={[stub]} defaultInstrument="Stub">
+        <CaptureLab />
+      </Lab>,
+    );
+    view.rerender(
+      <Lab instruments={[stub, later]} defaultInstrument="Stub">
+        <CaptureLab />
+      </Lab>,
+    );
+    act(() => labRef?.addTrial('Later'));
+    expect(labRef?.trials.map((t) => t.instrumentName)).toEqual(['Stub', 'Later']);
+    expect(screen.queryByText(/Unknown instrument/)).toBeNull();
+  });
+
+  it('keeps a trial’s content mounted across an instrument swap', () => {
+    let mounts = 0;
+    function Probe() {
+      useEffect(() => {
+        mounts += 1;
+      }, []);
+      return <p>probe</p>;
+    }
+    const v1: Instrument = {
+      name: 'Keep',
+      defaultConfig: () => ({}),
+      initialState: () => ({}),
+      render: () => <Probe />,
+    };
+    const v2: Instrument = { ...v1, defaultConfig: () => ({ extra: 1 }) };
+    const view = render(<Lab instruments={[v1]} defaultInstrument="Keep" />);
+    view.rerender(<Lab instruments={[v2]} defaultInstrument="Keep" />);
+    expect(mounts).toBe(1);
+  });
+});