@weasel-js/labkit 1.3.0-pre.0 → 1.4.0-pre.0

package/src/trial/Trial.tsx

@@ -1,7 +1,12 @@
-import { type ReactNode, useContext, useMemo, useRef, useState } from 'react';
+import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { useStore } from 'zustand/react';
+import { AnnotationsContext } from '../annotations/AnnotationsContext';
+import { AnnotationTargets } from '../annotations/AnnotationTargets';
+import { annotationsFromJSON } from '../annotations/store';
+import type { AnnotationTargetInfo } from '../annotations/types';
 import { CanvasStack } from '../canvas/CanvasStack';
 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';
@@ -9,13 +14,15 @@ import type { Instrument, LayerDescriptor, PaletteItem, RenderContext } from '..
 import { useJob } from '../job/useJob';
 import { useLabContext } from '../lab/LabContext';
 import { LayerList } from '../layers/LayerList';
-import { LabStoreContext } from '../state/context';
+import { TrialLoupe } from '../loupe/TrialLoupe';
+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 { createEventBus, type EventBus } from '../undo/eventBus';
 import { pushSnapshot, redo as undoRedo, undo as undoUndo } from '../undo/undoStack';
-import type { UndoBindings } from './TrialChrome';
+import type { LoupeBindings, UndoBindings } from './TrialChrome';
 import { TrialChrome } from './TrialChrome';
 
 /** Props for `<Trial>`. */
@@ -67,10 +74,12 @@ interface TrialRuntimeProps {
 
 function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: TrialRuntimeProps) {
   const canvasContainerRef = useRef<HTMLDivElement | null>(null);
+  const loupeHostRef = useRef<HTMLDivElement | null>(null);
   const updateTrialState = useStore(store, (s) => s.updateTrialState);
   const updateTrialConfig = useStore(store, (s) => s.updateTrialConfig);
   const updateTrialView = useStore(store, (s) => s.updateTrialView);
   const updateTrialUndoStack = useStore(store, (s) => s.updateTrialUndoStack);
+  const updateTrialAnnotations = useStore(store, (s) => s.updateTrialAnnotations);
   const labToolId = useStore(store, (s) => s.activeToolId);
   const setLabTool = useStore(store, (s) => s.setLabTool);
   const setTrialTool = useStore(store, (s) => s.setTrialTool);
@@ -81,6 +90,15 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
 
   const [layerVisibility, setLayerVisibility] = useState<Record<string, boolean>>({});
   const [layerOrder, setLayerOrder] = useState<string[] | null>(null);
+  const [loupeOn, setLoupeOn] = useState(false);
+
+  const visibleLayers = useMemo(
+    () =>
+      (instrument.canvas?.layers ?? [])
+        .filter((l) => layerVisibility[l.id] !== false)
+        .map((l) => l.id),
+    [instrument.canvas, layerVisibility],
+  );
 
   const undoCap = instrument.undo;
   const undoEvents = useMemo(() => new Set(undoCap?.snapshotOn ?? ['state.change']), [undoCap]);
@@ -96,11 +114,101 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
 
   const setView = (v: unknown): void => updateTrialView(record.id, v);
 
+  // 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 placeView = (size: ViewportSize): void => {
+    const declared = instrument.canvas?.initialView;
+    if (typeof declared !== 'function') return;
+    if (record.view != null) return;
+    setView(declared(size));
+  };
+
+  // The capability's own `targets` thunk, re-read on every call: a target
+  // resizing or gaining a dependency must not need the store rebuilt. Held in
+  // a ref because the store is built once and closes over it.
+  const annotationsCap = instrument.annotations;
+  const targetsRef = useRef<() => readonly AnnotationTargetInfo[]>(() => []);
+  targetsRef.current = () =>
+    annotationsCap ? annotationsCap.targets(record.state, record.config) : [];
+
+  // One store for the trial's lifetime. Marks do not survive a reload yet —
+  // the storage slot is 3d.
+  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;
+  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;
+    annotationsRef.current = annotationsFromJSON(kept, () => targetsRef.current(), {
+      meaning: annotationsCap?.meaning,
+      config: () => configRef.current,
+      onCapture: (result) => annotationsCap?.onCapture?.(result),
+    });
+  }
+  const annotations = annotationsRef.current;
+
+  // Written on a trailing debounce rather than per notification: a scene
+  // mutates every frame of a drag, and a zustand write per frame re-renders
+  // every trial in the lab. The unmount flush is not an optimization — the
+  // last mark before a trial closes is otherwise lost.
+  const saveCap = annotationsCap?.storage;
+  const saveRef = useRef<(doc: unknown) => void>(() => {});
+  saveRef.current = (doc) => {
+    if (saveCap) saveCap.save(doc as never);
+    else updateTrialAnnotations(record.id, doc);
+  };
+  // Only when the pair flips, which is rare: bumping React state on every
+  // scene notification would re-render the trial on every frame of a drag,
+  // which is the thing the debounce below exists to avoid.
+  const [markMoves, setMarkMoves] = useState({ undo: false, redo: false });
+  useEffect(() => {
+    if (!annotationsCap) return;
+    const read = (): void => {
+      const next = { undo: annotations.canUndo(), redo: annotations.canRedo() };
+      setMarkMoves((prev) => (prev.undo === next.undo && prev.redo === next.redo ? prev : next));
+    };
+    read();
+    return annotations.subscribe(read);
+  }, [annotations, annotationsCap]);
+
+  useEffect(() => {
+    if (!annotationsCap) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let dirty = false;
+    const flush = (): void => {
+      if (!dirty) return;
+      dirty = false;
+      saveRef.current(annotations.toJSON());
+    };
+    const off = annotations.subscribe(() => {
+      dirty = true;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        flush();
+      }, 250);
+    });
+    return () => {
+      off();
+      if (timer) clearTimeout(timer);
+      flush();
+    };
+  }, [annotations, annotationsCap]);
+
   // 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.
-  const declaresTools = instrument.tools != null;
+  // 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;
   const resolvedToolId = declaresTools
-    ? (record.activeToolId ?? instrument.tools?.initial ?? instrument.tools?.tools[0]?.id ?? null)
+    ? (record.activeToolId ??
+      instrument.tools?.initial ??
+      instrument.tools?.tools[0]?.id ??
+      (instrument.annotations ? 'select' : null))
     : labToolId;
   const setActiveTool = (id: string): void => {
     if (declaresTools) setTrialTool(record.id, id);
@@ -147,6 +255,7 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
         updateTrialView(record.id, { ...view2d, zoom: z });
       },
       activeToolId: resolvedToolId,
+      visibleLayers,
     },
     emit: (event) => {
       snapshotIfNeeded(event);
@@ -155,23 +264,46 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
     job: jobCap ? job : undefined,
   };
 
-  const undoBindings: UndoBindings | undefined = undoCap
-    ? {
-        canUndo: record.undoStack.past.length > 0,
-        canRedo: record.undoStack.future.length > 0,
-        undo: () => {
-          const result = undoUndo(record.undoStack, structuredClone(record.state));
-          if (!result) return;
-          updateTrialState(record.id, result.snapshot as never);
-          updateTrialUndoStack(record.id, result.stack);
-        },
-        redo: () => {
-          const result = undoRedo(record.undoStack, structuredClone(record.state));
-          if (!result) return;
-          updateTrialState(record.id, result.snapshot as never);
-          updateTrialUndoStack(record.id, result.stack);
-        },
-      }
+  // Marks are undone through weasel history, not through labkit's snapshot
+  // stack — the spec's rule, and the reason a mark scene is the truth. A trial
+  // declaring both takes the marks first: the most recent thing the user did
+  // is what undo is for, and only a mark change moves the mark history.
+  const undoState = () => {
+    const result = undoUndo(record.undoStack, structuredClone(record.state));
+    if (!result) return;
+    updateTrialState(record.id, result.snapshot as never);
+    updateTrialUndoStack(record.id, result.stack);
+  };
+  const redoState = () => {
+    const result = undoRedo(record.undoStack, structuredClone(record.state));
+    if (!result) return;
+    updateTrialState(record.id, result.snapshot as never);
+    updateTrialUndoStack(record.id, result.stack);
+  };
+
+  const undoBindings: UndoBindings | undefined =
+    undoCap || annotationsCap
+      ? {
+          canUndo: markMoves.undo || (undoCap ? record.undoStack.past.length > 0 : false),
+          canRedo: markMoves.redo || (undoCap ? record.undoStack.future.length > 0 : false),
+          undo: () => {
+            if (annotationsCap && annotations.undo()) return;
+            if (undoCap) undoState();
+          },
+          redo: () => {
+            if (annotationsCap && annotations.redo()) return;
+            if (undoCap) redoState();
+          },
+        }
+      : undefined;
+
+  const loupeCap = useMemo(() => {
+    const declared = instrument.loupe;
+    if (declared == null) return null;
+    return resolveLoupe(typeof declared === 'function' ? declared(record.config) : declared);
+  }, [instrument.loupe, record.config]);
+  const loupeBindings: LoupeBindings | undefined = loupeCap
+    ? { on: loupeOn, toggle: () => setLoupeOn((v) => !v) }
     : undefined;
 
   const canvasLayers: CanvasLayerDescriptor[] = useMemo(() => {
@@ -183,11 +315,10 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
     return ordered.map((layer) => ({
       id: layer.id,
       visible: layerVisibility[layer.id] !== false,
-      render: (ctx, view) => {
+      render: (ctx, view, frame) => {
         // Camera applied here, so a layer draws in world coordinates. `zoom`
         // stays in the args for line widths, which must not scale with it.
-        ctx.translate(view.pan.x, view.pan.y);
-        ctx.scale(view.zoom, view.zoom);
+        applyCamera(ctx, view, frame);
         layer.draw(ctx, { state: record.state, config: record.config, zoom: view.zoom });
       },
     }));
@@ -202,6 +333,7 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
     capability: instrument.dragDrop ?? { palette: [], onDrop: (_p, _i, s) => s },
     canvasContainerRef,
     view: view2d ?? DEFAULT_VIEW,
+    worldSpec: instrument.canvas?.worldSpec,
     state: record.state,
     config: record.config,
     setState: (next) => {
@@ -245,6 +377,20 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
     ];
   }, [canvasLayers, dragDropResult.drag]);
 
+  // The lens tracks the pointer over whatever box holds the content: the canvas
+  // stack's own element, which it takes from context, or the wrapper below.
+  const lens = loupeCap ? (
+    <TrialLoupe
+      capability={loupeCap}
+      enabled={loupeOn}
+      state={record.state}
+      config={record.config}
+      view={view2d ?? DEFAULT_VIEW}
+      worldSpec={instrument.canvas?.worldSpec}
+      hostRef={loupeHostRef}
+    />
+  ) : null;
+
   let body: ReactNode;
   if (instrument.canvas) {
     body = (
@@ -253,14 +399,24 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
           layers={layersWithFeedback}
           view={view2d ?? DEFAULT_VIEW}
           onViewChange={setView}
+          worldSpec={instrument.canvas.worldSpec}
+          onResize={placeView}
           minZoom={instrument.canvas.minZoom}
           maxZoom={instrument.canvas.maxZoom}
         >
           {instrument.render(renderCtx)}
+          {lens}
         </CanvasStack>
         <DragOverlay drag={dragDropResult.drag} />
       </div>
     );
+  } else if (lens) {
+    body = (
+      <div ref={loupeHostRef} className="lk-trial__loupe-host">
+        {instrument.render(renderCtx)}
+        {lens}
+      </div>
+    );
   } else {
     body = instrument.render(renderCtx);
   }
@@ -310,21 +466,40 @@ function TrialRuntime({ record, instrument, store, isLast, chrome, suppress }: T
     return out;
   }, [paletteNode, layerListNode]);
 
-  return (
-    <TrialChrome
-      job={jobCap ? job : undefined}
-      trialId={record.id}
-      record={record}
-      instrument={instrument}
-      isLastTrial={isLast}
-      undoBindings={undoBindings}
-      trialChrome={extraChrome}
-      chrome={chrome}
-      suppress={suppress}
+  // Rendered beside the body rather than inside it: an overlay portals itself
+  // into the surface container, so where it sits in this tree decides only
+  // when its effects run — after the instrument's refs have attached.
+  const annotationOverlays = annotationsCap ? (
+    <AnnotationTargets
+      capability={annotationsCap}
+      state={record.state}
+      config={record.config}
+      annotations={annotations}
       activeToolId={resolvedToolId}
-      setActiveTool={setActiveTool}
-    >
-      {body}
-    </TrialChrome>
+    />
+  ) : 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>
+      </AnnotationsContext.Provider>
+    </TrialIdProvider>
   );
 }

package/src/trial/TrialChrome.tsx

@@ -18,6 +18,13 @@ import { LabStoreContext } from '../state/context';
 import type { TrialRecord } from '../state/types';
 import { as2DView } from '../state/view';
 import { TrialTitleBar } from './TrialTitleBar';
+import { UndockedSections } from './UndockedSections';
+
+/** The trial's loupe as its chrome sees it: a switch and its position. */
+export interface LoupeBindings {
+  on: boolean;
+  toggle: () => void;
+}
 
 export interface UndoBindings {
   canUndo: boolean;
@@ -35,6 +42,9 @@ export interface TrialChromeProps {
   undoBindings?: UndoBindings;
   /** Supplied when the instrument declares a `job`. */
   job?: JobHandle;
+  /** Supplied when the instrument declares a `loupe`. The lens itself is the
+   *  trial's to mount; the chrome only offers the switch. */
+  loupe?: LoupeBindings;
   /** Contributions the trial runtime itself adds — the drag palette and the
    *  layer list, which depend on runtime state the instrument cannot reach. */
   trialChrome?: readonly TrialContribution[];
@@ -61,6 +71,7 @@ export function TrialChrome({
   isLastTrial,
   undoBindings,
   job,
+  loupe,
   trialChrome,
   chrome,
   suppress,
@@ -74,6 +85,16 @@ export function TrialChrome({
   const updateTrialView = useStore(storeCtx.store, (s) => s.updateTrialView);
   const updateTrialConfig = useStore(storeCtx.store, (s) => s.updateTrialConfig);
   const updateTrialState = useStore(storeCtx.store, (s) => s.updateTrialState);
+  const undockPanelAction = useStore(storeCtx.store, (s) => s.undockPanel);
+  const dockPanelAction = useStore(storeCtx.store, (s) => s.dockPanel);
+  const undockedPanels = useStore(storeCtx.store, (s) => s.undockedPanels);
+  const undockedIds = useMemo(
+    () =>
+      Object.values(undockedPanels)
+        .filter((p) => p.trialId === trialId)
+        .map((p) => p.sectionId),
+    [undockedPanels, trialId],
+  );
 
   // The trial view is opaque to labkit, so the zoom chrome asks for the 2D shape
   // and goes inert when the trial holds something else — an orbit, say.
@@ -96,6 +117,8 @@ export function TrialChrome({
       canRedo: undoBindings?.canRedo ?? false,
       undo: undoBindings?.undo ?? NO_OP,
       redo: undoBindings?.redo ?? NO_OP,
+      loupeOn: loupe?.on ?? false,
+      toggleLoupe: loupe?.toggle ?? NO_OP,
       configSchema,
       configFields: instrument.config ? [] : (instrument.configSchema?.() ?? []),
       config: record.config,
@@ -113,6 +136,9 @@ export function TrialChrome({
           updateTrialState(trialId, nextState as never);
         }
       },
+      undockedPanels: undockedIds,
+      undockPanel: (sectionId, as) => undockPanelAction(trialId, sectionId, as),
+      dockPanel: (sectionId) => dockPanelAction(trialId, sectionId),
       savedSnapshots: lab.savedSnapshots.filter((s) => s.trialId === trialId),
       saveSnapshot: (name) => lab.saveSnapshot(trialId, name),
       loadSnapshot: (snapshotId) => lab.loadSnapshot(trialId, snapshotId),
@@ -132,10 +158,14 @@ export function TrialChrome({
     updateTrialConfig,
     updateTrialState,
     undoBindings,
+    loupe,
     view2d,
     activeToolId,
     setActiveTool,
     configSchema,
+    undockedIds,
+    undockPanelAction,
+    dockPanelAction,
   ]);
 
   const contributions = useMemo(
@@ -185,6 +215,11 @@ export function TrialChrome({
         <PaletteRegion contributions={inRegion('palette')} ctx={ctx} />
         <div className="lk-trial__sidebar">
           <SidebarRegion contributions={inRegion('sidebar')} ctx={ctx} />
+          <UndockedSections
+            trialId={trialId}
+            sections={inRegion('sidebar').filter((c) => undockedIds.includes(c.id))}
+            onDock={ctx.dockPanel}
+          />
         </div>
         <div className={`lk-trial__content${instrument.canvas ? ' lk-trial__content--flush' : ''}`}>
           {children}

package/src/trial/UndockedSections.tsx

@@ -0,0 +1,65 @@
+import { useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
+import type { SidebarSection, TrialContribution } from '../chrome/types';
+import { usePanelHosts } from '../lab/panelHost';
+import { panelKey } from '../state/undock';
+
+/** Props for `<UndockedSections>`. */
+export interface UndockedSectionsProps {
+  trialId: string;
+  /** The trial's sidebar contributions that are currently torn out. */
+  sections: readonly TrialContribution[];
+  onDock: (sectionId: string) => void;
+}
+
+function Portalled({
+  trialId,
+  contribution,
+  onDock,
+}: {
+  trialId: string;
+  contribution: TrialContribution;
+  onDock: (sectionId: string) => void;
+}) {
+  const hosts = usePanelHosts();
+  const key = panelKey(trialId, contribution.id);
+  const host = useSyncExternalStore(
+    (fn) => hosts?.subscribe(fn) ?? (() => {}),
+    () => hosts?.get(key) ?? null,
+    () => null,
+  );
+  if (!host || !contribution.item) return null;
+  const item = contribution.item as SidebarSection;
+  return createPortal(
+    <>
+      <div className="lk-panel-tile__titlebar">
+        <span className="lk-panel-tile__title">{item.title}</span>
+        <button
+          type="button"
+          className="lk-panel-tile__dock"
+          aria-label={`Dock ${item.title}`}
+          title={`Dock ${item.title}`}
+          onClick={() => onDock(contribution.id)}
+        >
+          ⇤
+        </button>
+      </div>
+      {item.body}
+    </>,
+    host,
+  );
+}
+
+/** Renders a torn-out section's body into the workspace panel holding it. The
+ *  body stays mounted in the trial's React tree — only its DOM moves — so it
+ *  keeps the trial's context and its own state across an undock. */
+export function UndockedSections({ trialId, sections, onDock }: UndockedSectionsProps) {
+  if (sections.length === 0) return null;
+  return (
+    <>
+      {sections.map((c) => (
+        <Portalled key={c.id} trialId={trialId} contribution={c} onDock={onDock} />
+      ))}
+    </>
+  );
+}

package/src/trial/trialOps.test.ts

@@ -167,3 +167,24 @@ describe('reorderTrials', () => {
     expect(next.map((w) => w.id)).toEqual(['c', 'a', 'b']);
   });
 });
+
+describe('a size-aware initial view', () => {
+  const sized = {
+    name: 'Sized',
+    defaultConfig: () => ({}),
+    initialState: () => ({}),
+    render: () => null,
+    canvas: {
+      initialView: ({ width, height }: { width: number; height: number }) => ({
+        zoom: 1,
+        pan: { x: width / 2, y: height / 2 },
+      }),
+      layers: [],
+    },
+  } as unknown as Instrument;
+
+  it('leaves the view unplaced, because the canvas has no size yet', () => {
+    const [trial] = addTrial([], [sized], 'Sized');
+    expect(trial?.view).toBeNull();
+  });
+});

package/src/trial/trialOps.ts

@@ -12,9 +12,11 @@ function findInstrument(instruments: InstrumentList, name: string): Instrument {
 }
 
 function initialView(instrument: Instrument): TrialRecord['view'] {
-  return instrument.canvas?.initialView
-    ? structuredClone(instrument.canvas.initialView)
-    : { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
+  const declared = instrument.canvas?.initialView;
+  // A function needs the canvas size, which no trial has at creation. `null`
+  // is the unplaced marker; `Trial` resolves it on the first non-empty size.
+  if (typeof declared === 'function') return null;
+  return declared ? structuredClone(declared) : { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
 }
 
 /** Append a new trial running `instrumentName`, at that instrument's

package/src/ui/layers/index.ts

@@ -1 +1,5 @@
-export { LayerStack, type LayerStackItem, type LayerStackProps } from './LayerStack';
+// LayerStack lives in `@weasel-js/ui` now; labkit re-exports it so existing
+// `@weasel-js/labkit/ui/layers` imports keep resolving. Named, not `export *`
+// — a star re-export of an external package emits no binding in the bundle.
+export type { LayerStackItem, LayerStackProps } from '@weasel-js/ui';
+export { LayerStack } from '@weasel-js/ui';