@weasel-js/labkit 1.4.3 → 1.5.0

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

@@ -4,12 +4,13 @@
  * follow. The overlay's own geometry is covered in
  * `annotations/Annotations.overlay.test.tsx`.
  */
-import { act, fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen, within } from '@testing-library/react';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { useAnnotations, useAnnotationsOptional } from '../annotations/AnnotationsContext';
 import type { AnnotationsApi } from '../annotations/types';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
+import { LabContext, type LabContextValue } from '../lab/LabContext';
 
 beforeAll(() => {
   HTMLCanvasElement.prototype.getContext = vi.fn(
@@ -19,9 +20,9 @@ beforeAll(() => {
 
 let api: AnnotationsApi | null = null;
 
-function Pane() {
+function Pane({ tool }: { tool: string | null }) {
   api = useAnnotations();
-  return <div data-testid="pane" data-marks={api.query().length} />;
+  return <div data-testid="pane" data-marks={api.query().length} data-tool={tool ?? ''} />;
 }
 
 function marks(): AnnotationsApi {
@@ -33,7 +34,7 @@ const annotating = defineInstrument<Record<string, never>, Record<string, never>
   name: 'Annotating',
   defaultConfig: () => ({}),
   initialState: () => ({}),
-  render: () => <Pane />,
+  render: (ctx) => <Pane tool={ctx.trial.activeToolId} />,
   annotations: {
     targets: () => [{ id: 'pane', ref: { current: null }, content: { w: 200, h: 100 } }],
   },
@@ -72,6 +73,48 @@ describe('an instrument that declares annotations', () => {
   });
 });
 
+let labRef: LabContextValue | null = null;
+
+function CaptureLab() {
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        if (value) labRef = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+describe('the annotation tool', () => {
+  it("is offered in the lab's rail, not in a trial's", () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    expect(screen.getAllByRole('button', { name: 'Rectangle' })).toHaveLength(1);
+    const trial = screen.getByRole('region', { name: /trial/i });
+    expect(within(trial).queryByRole('button', { name: 'Rectangle' })).toBeNull();
+  });
+
+  it('is one tool across every trial', () => {
+    // A tool is what the hand is holding, not a property of a picture: picking
+    // Rectangle once has to arm it wherever the next mark is drawn.
+    labRef = null;
+    render(
+      <Lab instruments={[annotating]} defaultInstrument="Annotating">
+        <CaptureLab />
+      </Lab>,
+    );
+    act(() => labRef?.addTrial('Annotating'));
+    const panes = screen.getAllByTestId('pane');
+    expect(panes).toHaveLength(2);
+    for (const p of panes) expect(p.dataset.tool).toBe('select');
+
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Rectangle' }));
+    });
+    for (const p of screen.getAllByTestId('pane')) expect(p.dataset.tool).toBe('rect');
+  });
+});
+
 describe('the trial undo chrome over marks', () => {
   it('gets undo and redo without the instrument declaring `undo`', () => {
     // Weasel history is the authority for marks, so the capability that

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

@@ -36,7 +36,7 @@ function makeInstrument(name: string, n: number, delay: 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} />);
+    render(<Lab instruments={[fast]} defaultInstrument="fast" />);
     const bar = await waitFor(() => screen.getByRole('progressbar', { name: /job progress/i }));
     await waitFor(() => {
       // A job that reported a total drives a determinate bar, so the count and
@@ -49,7 +49,7 @@ describe('a trial whose instrument declares a job', () => {
 
   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} />);
+    render(<Lab instruments={[slow]} defaultInstrument="slow" />);
     const cancel = await waitFor(() => screen.getByRole('button', { name: /cancel/i }));
     await userEvent.click(cancel);
     await waitFor(() => {
@@ -64,7 +64,7 @@ describe('a trial whose instrument declares a job', () => {
       initialState: () => ({ items: [] }),
       render: () => null,
     });
-    render(<Lab instruments={[plain]} defaultInstrument="plain" storage={null} />);
+    render(<Lab instruments={[plain]} defaultInstrument="plain" />);
     await waitFor(() => {
       expect(document.querySelector('.lk-trial')).toBeInTheDocument();
     });

package/src/trial/Trial.less

@@ -9,7 +9,7 @@
   // from its own workspace by nothing but a hairline. Raised reads as a panel,
   // and in dark it is translucent, so the backdrop still shows through.
   background: var(--wzl-surface-raised);
-  border: var(--wzl-border-w) solid var(--wzl-border-raised);
+  border: var(--wzl-border-w) solid var(--wzl-border-strong);
   border-radius: var(--wzl-radius-md);
   box-shadow: 0 1px 3px var(--wzl-shadow);
   overflow: hidden;
@@ -96,21 +96,6 @@
     flex-shrink: 0;
   }
 
-  // The strip's own seam. windease positions and sizes it; this is only what
-  // it looks like.
-  &__panes [data-affordance-kind='resize-x'] {
-    background: var(--wzl-border);
-  }
-
-  &__panes .windease-affordance-hit:hover [data-affordance-kind='resize-x'],
-  &__panes .windease-affordance-hit:focus-visible [data-affordance-kind='resize-x'] {
-    background: var(--wzl-accent);
-  }
-
-  &__panes .windease-affordance-hit:focus-visible {
-    outline: none;
-  }
-
   &--unknown {
     display: flex;
     align-items: center;
@@ -126,16 +111,6 @@
   padding: 0 var(--wzl-space-sm);
 }
 
-.lk-toolbar__load-select {
-  font-size: var(--wzl-font-size-sm);
-}
-
-// Same `width: 100%` default as the header's Select — pinned so it cannot
-// absorb the toolbar's slack. Placeholder-only, so it need only fit "Load…".
-.lk-root .lk-toolbar__load-select {
-  width: 88px;
-}
-
 .lk-sidebar__placeholder {
   padding: var(--wzl-space-sm);
   color: var(--wzl-fg-muted);

package/src/trial/Trial.stories.tsx

@@ -1,7 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import type { Instrument } from '../instrument/types';
 import { LabContext, type LabContextValue } from '../lab/LabContext';
-import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
 import { createLabStore } from '../state/store';
 import type { TrialRecord } from '../state/types';
@@ -27,7 +26,7 @@ const record: TrialRecord = {
 };
 
 function Harness() {
-  const store = createLabStore({ storageKey: 'sb', storage: noneAdapter });
+  const store = createLabStore();
   const lab: LabContextValue = {
     instruments: [stub],
     trials: [record],

package/src/trial/Trial.test.tsx

@@ -35,10 +35,7 @@ type ChromeProps = Parameters<typeof TrialChrome>[0];
  *  and section folds live on the record, so a test that outlives one mount
  *  keeps its own store and hands it to both. */
 function makeChromeStore() {
-  const store = createLabStore({
-    storageKey: 'test',
-    storage: { read: () => null, write: () => {} },
-  });
+  const store = createLabStore();
   const { undoStack: _undo, ...seed } = stubRecord;
   store.getState().addTrial(seed);
   return store;
@@ -205,6 +202,33 @@ describe('<TrialChrome>', () => {
     expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
   });
 
+  it("reads the instrument's title over its name, and returns to it on setTitle(null)", () => {
+    const titled: Instrument = { ...stubInstrument, title: 'Stub / Default' };
+    render(
+      <ChromeHarness
+        instrument={titled}
+        chrome={[
+          {
+            id: 'rename',
+            region: 'titlebar',
+            item: { icon: Glyph, label: 'Rename', onActivate: (ctx) => ctx.setTitle('Sprocket 7') },
+          },
+          {
+            id: 'untitle',
+            region: 'titlebar',
+            item: { icon: Glyph, label: 'Untitle', onActivate: (ctx) => ctx.setTitle(null) },
+          },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('region', { name: 'Trial Stub / Default' })).toBeInTheDocument();
+    expect(screen.getByText('Stub / Default')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Rename' }));
+    expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Untitle' }));
+    expect(screen.getByRole('region', { name: 'Trial Stub / Default' })).toBeInTheDocument();
+  });
+
   it('Cmd+S triggers saveSnapshot', () => {
     const saveSnapshot = vi.fn();
     render(<ChromeHarness labOverrides={{ saveSnapshot }} />);

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

@@ -4,10 +4,11 @@
  * `SingletonExperiment` — so `useTrialState()` threw everywhere else, which
  * made the documented hook pattern unreachable from an instrument's `render`.
  */
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
+import { LabContext, type LabContextValue } from '../lab/LabContext';
 import { useTrialState } from '../state/useTrialState';
 
 beforeAll(() => {
@@ -34,3 +35,24 @@ describe('<Trial> trial-scoped hooks', () => {
     expect(screen.getByTestId('probe')).toHaveTextContent('hits:7');
   });
 });
+
+describe('<Trial> root element', () => {
+  it('carries its trial id, so a lab can find a trial from outside', () => {
+    let labRef: LabContextValue | null = null;
+    const { container } = render(
+      <Lab instruments={[reader]} defaultInstrument="Reader">
+        <LabContext.Consumer>
+          {(value) => {
+            if (value) labRef = value;
+            return null;
+          }}
+        </LabContext.Consumer>
+      </Lab>,
+    );
+    act(() => (labRef as LabContextValue | null)?.addTrial('Reader'));
+    const ids = (labRef as LabContextValue | null)?.trials.map((t) => t.id) ?? [];
+    expect(ids).toHaveLength(2);
+    const roots = container.querySelectorAll<HTMLElement>('.lk-trial[data-trial-id]');
+    expect([...roots].map((el) => el.dataset.trialId)).toEqual(ids);
+  });
+});

package/src/trial/Trial.tsx

@@ -2,15 +2,24 @@ import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from
 import { useStore } from 'zustand/react';
 import { AnnotationsContext } from '../annotations/AnnotationsContext';
 import { AnnotationTargets } from '../annotations/AnnotationTargets';
+import { AnnotationPreloadContext } from '../annotations/preload';
 import { annotationsFromJSON } from '../annotations/store';
-import type { AnnotationTargetInfo } from '../annotations/types';
+import type { AnnotationStorage, AnnotationTargetInfo } from '../annotations/types';
+import { CameraWheelContext, type CameraWheelSlot } from '../canvas/CameraWheelContext';
 import { CanvasStack } from '../canvas/CanvasStack';
+import { fitStage, Stage } from '../canvas/Stage';
 import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
 import { applyCamera, type ViewportSize } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
 import { DragOverlay, useDragDrop } from '../dragdrop/DragDropRuntime';
 import { Palette } from '../dragdrop/Palette';
-import type { Instrument, LayerDescriptor, PaletteItem, RenderContext } from '../instrument/types';
+import type {
+  Instrument,
+  InstrumentList,
+  LayerDescriptor,
+  PaletteItem,
+  RenderContext,
+} from '../instrument/types';
 import { useJob } from '../job/useJob';
 import { useLabContext } from '../lab/LabContext';
 import { LayerList } from '../layers/LayerList';
@@ -19,7 +28,8 @@ import { resolveLoupe } from '../loupe/types';
 import { LabStoreContext, TrialIdProvider } from '../state/context';
 import type { LabStore } from '../state/store';
 import type { TrialRecord } from '../state/types';
-import { as2DView, DEFAULT_VIEW } from '../state/view';
+import { as2DView, DEFAULT_VIEW, withZoom } from '../state/view';
+import { resolveLabTool } from '../tools/labTool';
 import { createEventBus, type EventBus } from '../undo/eventBus';
 import { pushSnapshot, redo as undoRedo, undo as undoUndo } from '../undo/undoStack';
 import type { LoupeBindings, UndoBindings } from './TrialChrome';
@@ -41,20 +51,25 @@ export function Trial({ id, chrome, suppress }: TrialProps) {
   const lab = useLabContext();
   const storeCtx = useContext(LabStoreContext);
   if (!storeCtx) throw new Error('[labkit] <Trial> requires <LabStoreProvider>');
+  const instruments = useStore(storeCtx.store, (s) => s.instruments) ?? lab.instruments;
   const record = useStore(storeCtx.store, (s) => s.trials.find((w) => w.id === id));
+  const instrument = record ? instruments.find((i) => i.name === record.instrumentName) : undefined;
+  const kept = useKeptMarks(instrument?.annotations?.storage, id);
   if (!record) {
     return <div className="lk-trial lk-trial--unknown">Trial not found: {id}</div>;
   }
-  const instrument = lab.instruments.find((i) => i.name === record.instrumentName);
   if (!instrument) {
     return (
       <div className="lk-trial lk-trial--unknown">Unknown instrument: {record.instrumentName}</div>
     );
   }
+  if (!kept.ready) return <div className="lk-trial lk-trial--loading" />;
   return (
     <TrialRuntime
+      keptMarks={kept.value}
       record={record}
       instrument={instrument}
+      instruments={instruments}
       store={storeCtx.store}
       isLast={lab.trials.length <= 1}
       chrome={chrome}
@@ -63,16 +78,60 @@ export function Trial({ id, chrome, suppress }: TrialProps) {
   );
 }
 
+/** The marks an instrument keeps in its own storage: preloaded by the lab for
+ *  the trials it opened with, loaded here for any added since. */
+function useKeptMarks(
+  storage: AnnotationStorage | undefined,
+  trialId: string,
+): { ready: boolean; value: unknown } {
+  const preload = useContext(AnnotationPreloadContext);
+  const [loaded, setLoaded] = useState<{ value: unknown } | null>(() =>
+    storage && preload?.has(trialId) ? { value: preload.get(trialId) } : null,
+  );
+  useEffect(() => {
+    if (!storage || loaded) return;
+    let live = true;
+    storage.load().then(
+      (value) => {
+        if (live) setLoaded({ value });
+      },
+      (error) => {
+        console.warn(`[labkit] could not load the marks of trial "${trialId}"`, error);
+        if (live) setLoaded({ value: null });
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [storage, loaded, trialId]);
+  if (!storage) return { ready: true, value: undefined };
+  return loaded ? { ready: true, value: loaded.value } : { ready: false, value: undefined };
+}
+
 interface TrialRuntimeProps {
+  /** The marks an instrument's own `AnnotationStorage` loaded. */
+  keptMarks: unknown;
   record: TrialRecord;
   instrument: Instrument;
+  /** The lab's instruments as the store holds them now. */
+  instruments: InstrumentList;
   store: LabStore;
   isLast: boolean;
   chrome?: readonly TrialContribution[];
   suppress?: readonly string[];
 }
 
-function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: TrialRuntimeProps) {
+function TrialRuntime({
+  keptMarks,
+  record,
+  instrument,
+  instruments,
+  store,
+  isLast,
+  chrome,
+  suppress,
+}: TrialRuntimeProps) {
+  const wheelSlot = useRef<CameraWheelSlot['current']>(null);
   const canvasContainerRef = useRef<HTMLDivElement | null>(null);
   const loupeHostRef = useRef<HTMLDivElement | null>(null);
   const updateTrialState = useStore(store, (s) => s.updateTrialState);
@@ -117,8 +176,11 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
   // A function `initialView` needs the canvas size, so `trialOps` leaves the
   // view null and the first measurement resolves it. Reset nulls it again,
   // which re-frames — so the guard is the null itself, not a "have I run" flag.
+  const stage = instrument.canvas ? undefined : instrument.stage;
   const placeView = (size: ViewportSize): void => {
-    const declared = instrument.canvas?.initialView;
+    const declared =
+      instrument.canvas?.initialView ??
+      (stage ? (stage.initialView ?? ((vp: ViewportSize) => fitStage(stage.size, vp))) : undefined);
     if (typeof declared !== 'function') return;
     if (record.view != null) return;
     setView(declared(size));
@@ -134,21 +196,23 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
       ? annotationsCap.targets(record.state, record.config, { id: record.id, view: record.view })
       : [];
 
-  // One store for the trial's lifetime. Marks do not survive a reload yet —
-  // the storage slot is 3d.
+  // One store for the trial's lifetime.
   const annotationsRef = useRef<ReturnType<typeof annotationsFromJSON> | null>(null);
   // Read through refs for the same reason `targets` is: the store is built
   // once, and an export must draw against the config the trial holds now.
   const configRef = useRef<unknown>(record.config);
   configRef.current = record.config;
+  // The instrument can be swapped under a live trial, so the capability is read at use too.
+  const capRef = useRef(annotationsCap);
+  capRef.current = annotationsCap;
   if (annotationsRef.current === null) {
     // Seeded from wherever the marks were kept: the instrument's own store if
     // it declared one, else this trial's slot.
-    const kept = annotationsCap?.storage ? annotationsCap.storage.load() : record.annotations;
+    const kept = annotationsCap?.storage ? keptMarks : record.annotations;
     annotationsRef.current = annotationsFromJSON(kept, () => targetsRef.current(), {
-      meaning: annotationsCap?.meaning,
+      meaning: () => capRef.current?.meaning,
       config: () => configRef.current,
-      onCapture: (result) => annotationsCap?.onCapture?.(result),
+      onCapture: (result) => capRef.current?.onCapture?.(result),
     });
   }
   const annotations = annotationsRef.current;
@@ -203,15 +267,14 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
 
   // A trial gets its own slot when its instrument declares tools; otherwise it
   // reads the lab's. Which slot a change writes follows from the same thing.
-  // Annotation tools are a trial's own for the same reason: two trials
-  // annotating different pictures must not share one active tool.
-  const declaresTools = instrument.tools != null || instrument.annotations != null;
+  // Annotation tools always read the lab's: a tool is what the hand holds, so
+  // picking one arms it in every trial, the way artboards share a tool. They
+  // were once per trial, back when one trial compared several pictures.
+  const declaresTools = instrument.tools != null;
+  const labTool = resolveLabTool(labToolId, instruments);
   const resolvedToolId = declaresTools
-    ? (record.activeToolId ??
-      instrument.tools?.initial ??
-      instrument.tools?.tools[0]?.id ??
-      (instrument.annotations ? 'select' : null))
-    : labToolId;
+    ? (record.activeToolId ?? instrument.tools?.initial ?? instrument.tools?.tools[0]?.id ?? null)
+    : labTool;
   const setActiveTool = (id: string): void => {
     if (declaresTools) setTrialTool(record.id, id);
     else setLabTool(id);
@@ -254,7 +317,7 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
       zoom: view2d?.zoom ?? 1,
       setZoom: (z) => {
         if (!view2d) return;
-        updateTrialView(record.id, { ...view2d, zoom: z });
+        updateTrialView(record.id, withZoom(view2d, z));
       },
       activeToolId: resolvedToolId,
       visibleLayers,
@@ -412,6 +475,21 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
         <DragOverlay drag={dragDropResult.drag} />
       </div>
     );
+  } else if (stage) {
+    body = (
+      <Stage
+        size={stage.size}
+        view={view2d ?? DEFAULT_VIEW}
+        onViewChange={setView}
+        onResize={placeView}
+        minZoom={stage.minZoom}
+        maxZoom={stage.maxZoom}
+        hostRef={loupeHostRef}
+        overlay={lens}
+      >
+        {instrument.render(renderCtx)}
+      </Stage>
+    );
   } else if (lens) {
     body = (
       <div ref={loupeHostRef} className="lk-trial__loupe-host">
@@ -478,30 +556,32 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
       config={record.config}
       trial={{ id: record.id, view: record.view }}
       annotations={annotations}
-      activeToolId={resolvedToolId}
+      activeToolId={labTool}
     />
   ) : null;
 
   return (
     <TrialIdProvider trialId={record.id}>
       <AnnotationsContext.Provider value={annotationsCap ? annotations : null}>
-        <TrialChrome
-          job={jobCap ? job : undefined}
-          loupe={loupeBindings}
-          trialId={record.id}
-          record={record}
-          instrument={instrument}
-          isLastTrial={isLast}
-          undoBindings={undoBindings}
-          trialChrome={extraChrome}
-          chrome={chrome}
-          suppress={suppress}
-          activeToolId={resolvedToolId}
-          setActiveTool={setActiveTool}
-        >
-          {body}
-          {annotationOverlays}
-        </TrialChrome>
+        <CameraWheelContext.Provider value={wheelSlot}>
+          <TrialChrome
+            job={jobCap ? job : undefined}
+            loupe={loupeBindings}
+            trialId={record.id}
+            record={record}
+            instrument={instrument}
+            isLastTrial={isLast}
+            undoBindings={undoBindings}
+            trialChrome={extraChrome}
+            chrome={chrome}
+            suppress={suppress}
+            activeToolId={resolvedToolId}
+            setActiveTool={setActiveTool}
+          >
+            {body}
+            {annotationOverlays}
+          </TrialChrome>
+        </CameraWheelContext.Provider>
       </AnnotationsContext.Provider>
     </TrialIdProvider>
   );