@weasel-js/labkit 1.6.1 → 1.7.1

package/src/trial/Trial.tsx

@@ -1,14 +1,29 @@
-import { createPointerStore, PointerContextProvider, WeaselProvider } from '@weasel-js/core';
-import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  createPointerStore,
+  PointerContextProvider,
+  useLatest,
+  WeaselProvider,
+} from '@weasel-js/core';
+import {
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 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 { AnnotationStorage, AnnotationTargetInfo } from '../annotations/types';
-import { CameraScopeContext } from '../canvas/CameraInput';
+import type { AnnotationStorage, AnnotationsApi, AnnotationTargetInfo } from '../annotations/types';
+import type { CameraView } from '../canvas/CameraInput';
 import { CameraWheelContext, type CameraWheelSlot } from '../canvas/CameraWheelContext';
 import { CanvasStack } from '../canvas/CanvasStack';
+import { CameraPublishContext, CameraRegistryContext } from '../canvas/cameraRegistry';
 import { fitStage, Stage } from '../canvas/Stage';
 import type { CanvasLayerDescriptor } from '../canvas/useLayerScheduler';
 import { applyCamera, type ViewportSize } from '../canvas/worldSpec';
@@ -26,8 +41,6 @@ import type {
 } from '../instrument/types';
 import { useJob } from '../job/useJob';
 import { useLabContext } from '../lab/LabContext';
-import { TrialLoupe } from '../loupe/TrialLoupe';
-import { resolveLoupe } from '../loupe/types';
 import { LayerList, type LayerListItem, moveLayers } from '../passthrough/weasel-ui';
 import { LabStoreContext, TrialIdProvider } from '../state/context';
 import type { LabStore } from '../state/store';
@@ -36,6 +49,7 @@ 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 { LoupeSwitchContext } from './loupeSwitch';
 import type { LoupeBindings, UndoBindings } from './TrialChrome';
 import { TrialChrome } from './TrialChrome';
 
@@ -136,9 +150,14 @@ function TrialRuntime({
   suppress,
 }: TrialRuntimeProps) {
   const wheelSlot = useRef<CameraWheelSlot['current']>(null);
+  const cameras = useContext(CameraRegistryContext);
+  const trialId = record.id;
+  const publishCamera = useMemo(
+    () => (cameras ? (camera: CameraView) => cameras.register(trialId, camera) : null),
+    [cameras, trialId],
+  );
   const [pointer] = useState(createPointerStore);
   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);
@@ -160,6 +179,12 @@ function TrialRuntime({
   const [layerVisibility, setLayerVisibility] = useState<Record<string, boolean>>({});
   const [layerOrder, setLayerOrder] = useState<string[] | null>(null);
   const [loupeOn, setLoupeOn] = useState(false);
+  const [lenses, setLenses] = useState(0);
+  const mountLens = useCallback(() => {
+    setLenses((n) => n + 1);
+    return () => setLenses((n) => n - 1);
+  }, []);
+  const loupeSwitch = useMemo(() => ({ on: loupeOn, mount: mountLens }), [loupeOn, mountLens]);
 
   const visibleLayers = useMemo(
     () =>
@@ -200,43 +225,69 @@ function TrialRuntime({
   // 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 = () =>
+  const targetsRef = useLatest((): readonly AnnotationTargetInfo[] =>
     annotationsCap
       ? annotationsCap.targets(record.state, config, { id: record.id, view: record.view })
-      : [];
+      : [],
+  );
 
   // 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>(config);
-  configRef.current = config;
+  const configRef = useLatest(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;
+  const capRef = useLatest(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 ? keptMarks : record.annotations;
-    annotationsRef.current = annotationsFromJSON(kept, () => targetsRef.current(), {
-      meaning: () => capRef.current?.meaning,
-      config: () => configRef.current,
-      onCapture: (result) => capRef.current?.onCapture?.(result),
-    });
+    annotationsRef.current = annotationsFromJSON(
+      annotationsCap?.storage ? keptMarks : record.annotations,
+      () => targetsRef.current(),
+      {
+        meaning: () => capRef.current?.meaning,
+        config: () => configRef.current,
+        onCapture: (result) => capRef.current?.onCapture?.(result),
+        selection: () => capRef.current?.selection,
+      },
+    );
   }
   const annotations = annotationsRef.current;
 
+  // Chrome reads the store while it renders — a mark list, the export menu,
+  // the overview — and the store reads the refs above, which hold the last
+  // commit. So once a change to them commits, those readers are told to read
+  // again. Through the context's `subscribe` alone: the store's own would have
+  // the debounce below save marks that did not change.
+  const inputsCommitted = useRef(new Set<() => void>());
+  // biome-ignore lint/correctness/useExhaustiveDependencies: these are what `targets` and `config` answer from — the signal, not values this reads
+  useLayoutEffect(() => {
+    for (const fn of inputsCommitted.current) fn();
+  }, [record.state, record.view, config, annotationsCap]);
+  const provided = useMemo<AnnotationsApi>(
+    () => ({
+      ...annotations,
+      subscribe: (fn) => {
+        const off = annotations.subscribe(fn);
+        inputsCommitted.current.add(fn);
+        return () => {
+          off();
+          inputsCommitted.current.delete(fn);
+        };
+      },
+    }),
+    [annotations],
+  );
+
   // 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) => {
+  const saveRef = useLatest((doc: unknown): void => {
     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.
@@ -273,7 +324,7 @@ function TrialRuntime({
       if (timer) clearTimeout(timer);
       flush();
     };
-  }, [annotations, annotationsCap]);
+  }, [annotations, annotationsCap, saveRef]);
 
   // 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.
@@ -373,14 +424,8 @@ function TrialRuntime({
         }
       : undefined;
 
-  const loupeCap = useMemo(() => {
-    const declared = instrument.loupe;
-    if (declared == null) return null;
-    return resolveLoupe(typeof declared === 'function' ? declared(config) : declared);
-  }, [instrument.loupe, config]);
-  const loupeBindings: LoupeBindings | undefined = loupeCap
-    ? { on: loupeOn, toggle: () => setLoupeOn((v) => !v) }
-    : undefined;
+  const loupeBindings: LoupeBindings | undefined =
+    lenses > 0 ? { on: loupeOn, toggle: () => setLoupeOn((v) => !v) } : undefined;
 
   const canvasLayers: CanvasLayerDescriptor[] = useMemo(() => {
     if (!instrument.canvas) return [];
@@ -471,20 +516,6 @@ function TrialRuntime({
     ];
   }, [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={config}
-      view={view2d ?? DEFAULT_VIEW}
-      worldSpec={instrument.canvas?.worldSpec}
-      hostRef={loupeHostRef}
-    />
-  ) : null;
-
   let body: ReactNode;
   if (instrument.canvas) {
     body = (
@@ -499,7 +530,6 @@ function TrialRuntime({
           maxZoom={instrument.canvas.maxZoom}
         >
           {instrument.render(renderCtx)}
-          {lens}
         </CanvasStack>
         <DragOverlay drag={dragDropResult.drag} />
       </div>
@@ -513,24 +543,11 @@ function TrialRuntime({
         onResize={placeView}
         minZoom={stage.minZoom}
         maxZoom={stage.maxZoom}
-        hostRef={loupeHostRef}
-        overlay={
-          <>
-            {stage.overlay?.(renderCtx)}
-            {lens}
-          </>
-        }
+        overlay={stage.overlay?.(renderCtx)}
       >
         {instrument.render(renderCtx)}
       </Stage>
     );
-  } else if (lens) {
-    body = (
-      <div ref={loupeHostRef} className="lk-trial__loupe-host">
-        {instrument.render(renderCtx)}
-        {lens}
-      </div>
-    );
   } else {
     body = instrument.render(renderCtx);
   }
@@ -593,21 +610,22 @@ function TrialRuntime({
     />
   ) : null;
 
-  // One input scope for the trial's body: the camera, the loupe and an
-  // overview share its actions, its deps and its pointer. Isolated, because an
-  // actions registry holds one dispatcher and the trial beside this one has
-  // its own.
+  // The trial's root registries, isolated from the trial beside it. Each
+  // camera inside mounts an input scope under them; chrome here reaches the
+  // one last used. The pointer store is the trial's, shared by all of them.
   const scopedBody = (
     <WeaselProvider isolate>
       <PointerContextProvider store={pointer}>
-        <CameraScopeContext.Provider value={true}>{body}</CameraScopeContext.Provider>
+        <CameraPublishContext.Provider value={publishCamera}>
+          <LoupeSwitchContext.Provider value={loupeSwitch}>{body}</LoupeSwitchContext.Provider>
+        </CameraPublishContext.Provider>
       </PointerContextProvider>
     </WeaselProvider>
   );
 
   return (
     <TrialIdProvider trialId={record.id}>
-      <AnnotationsContext.Provider value={annotationsCap ? annotations : null}>
+      <AnnotationsContext.Provider value={annotationsCap ? provided : null}>
         <CameraWheelContext.Provider value={wheelSlot}>
           <TrialChrome
             job={jobCap ? job : undefined}

package/src/trial/TrialChrome.tsx

@@ -1,6 +1,14 @@
-import { type KeyboardEvent, type ReactNode, useContext, useMemo } from 'react';
+import {
+  type KeyboardEvent,
+  type ReactNode,
+  useContext,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
 import { useStore } from 'zustand/react';
-import { builtinContributions } from '../chrome/builtins';
+import { CameraRegistryContext } from '../canvas/cameraRegistry';
+import { zoomCameraTo } from '../canvas/cameraZoom';
+import { builtinContributions, TRANSIENT_BUILTINS } from '../chrome/builtins';
 import { mergeContributions, suppressContributions } from '../chrome/merge';
 import { PaletteRegion } from '../chrome/regions/PaletteRegion';
 import { SidebarRegion } from '../chrome/regions/SidebarRegion';
@@ -30,6 +38,7 @@ export interface LoupeBindings {
   toggle: () => void;
 }
 
+/** The trial's undo history as its chrome sees it. */
 export interface UndoBindings {
   canUndo: boolean;
   canRedo: boolean;
@@ -46,8 +55,8 @@ 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. */
+  /** Supplied while a lens is mounted in the trial. The lens itself is the
+   *  instrument'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. */
@@ -68,6 +77,7 @@ const NO_OP = (): void => {};
 /** One frozen empty map, so a trial that has folded nothing keeps a stable
  *  context identity across renders. */
 const NO_SECTIONS: Readonly<Record<string, boolean>> = Object.freeze({});
+const noSubscribe = (): (() => void) => NO_OP;
 
 /** The frame around a running instrument. Builds one chrome context, assembles
  *  the contributions the instrument, the runtime and the lab declare, and hands
@@ -123,10 +133,18 @@ export function TrialChrome({
   const title = record.title ?? instrument.title ?? instrument.name;
   const collapsedSections = record.collapsedSections ?? NO_SECTIONS;
 
+  // The trial's own camera, where it has one: zoom goes through it, about the
+  // middle of the view and inside the instrument's range, as the lab's does.
+  const cameras = useContext(CameraRegistryContext);
+  const camera = useSyncExternalStore(
+    cameras?.subscribe ?? noSubscribe,
+    () => cameras?.get(trialId) ?? null,
+  );
+
   const ctx = useMemo<TrialChromeContext>(() => {
     const setZoom = (z: number): void => {
-      if (!view2d) return;
-      updateTrialView(trialId, withZoom(view2d, z));
+      if (camera) zoomCameraTo(camera, z);
+      else if (view2d) updateTrialView(trialId, withZoom(view2d, z));
     };
     return {
       trialId,
@@ -140,6 +158,7 @@ export function TrialChrome({
       canRedo: undoBindings?.canRedo ?? false,
       undo: undoBindings?.undo ?? NO_OP,
       redo: undoBindings?.redo ?? NO_OP,
+      hasLoupe: loupe != null,
       loupeOn: loupe?.on ?? false,
       toggleLoupe: loupe?.toggle ?? NO_OP,
       configSchema,
@@ -203,6 +222,7 @@ export function TrialChrome({
     setTrialTitle,
     setTrialSectionCollapsed,
     collapsedSections,
+    camera,
   ]);
 
   const contributions = useMemo(
@@ -215,6 +235,7 @@ export function TrialChrome({
           [...(chrome ?? [])],
         ),
         suppress ?? [],
+        TRANSIENT_BUILTINS,
       ),
     [instrument, ctx, trialChrome, chrome, suppress, lab.controls],
   );

package/src/trial/index.ts

@@ -1,3 +1,5 @@
+export type { LoupeSwitch } from './loupeSwitch';
+export { LoupeSwitchContext } from './loupeSwitch';
 export type { TrialProps } from './Trial';
 export { Trial } from './Trial';
 export type { TrialBodyProps } from './TrialBody';

package/src/trial/loupeSwitch.ts

@@ -0,0 +1,15 @@
+import { createContext } from 'react';
+
+/**
+ * A trial's loupe switch, as a lens mounted inside the trial finds it. The
+ * trial offers its toolbar toggle while at least one lens has called `mount`,
+ * and every lens reads `on` as whether it is turned on.
+ */
+export interface LoupeSwitch {
+  on: boolean;
+  /** Reports a lens mounted; the returned function reports it gone. */
+  mount: () => () => void;
+}
+
+/** The loupe switch of the trial around the caller, or `null` outside one. */
+export const LoupeSwitchContext = createContext<LoupeSwitch | null>(null);

package/dist/_dts/LayerList.d-BoELAMsM.d.ts

@@ -1,83 +0,0 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
-
-/** One layer. With a body (see `renderBody`) it draws as a card that folds its
- *  body away; without one, as a one-line row. Either can hold child layers. */
-interface LayerListItem {
-    id: string;
-    /** The layer's name. Also what its controls are labeled by. */
-    label: string;
-    /** Shown in the header in place of `label` — a select that switches the
-     *  layer's kind, say. */
-    title?: ReactNode;
-    /** Fixed-size content before the label: a color swatch, a kind icon. */
-    leading?: ReactNode;
-    /** Drawn in the drag handle in place of the grip — an ordinal. */
-    badge?: ReactNode;
-    /** Which of its list this layer is: an index into the theme's tone list, or
-     *  a color. A card draws its edge and handle in it and recolors its controls. */
-    tone?: StanceProps['tone'];
-    /** Cannot be dragged, hidden or removed, walls off drops on either side, and
-     *  selects alone rather than joining a multi-selection. */
-    locked?: boolean;
-    /** Shown or not, when the list has `onVisibilityChange`. Default true. */
-    visible?: boolean;
-    children?: LayerListItem[];
-    /** Folds the body and children away until the user opens them.
-     *  `collapsedIds` overrides it. */
-    defaultCollapsed?: boolean;
-}
-/**
- * A reorder: `ids`, siblings under `parentId` (`null` at the top level), now
- * sit as one block in list order starting at `index` of the parent's children.
- * A drag never moves a layer to another parent.
- */
-interface LayerMove {
-    ids: string[];
-    parentId: string | null;
-    index: number;
-}
-/** Props for `<LayerList>`. */
-interface LayerListProps {
-    items: LayerListItem[];
-    /** Omit for a list the user cannot reorder. */
-    onReorder?: (move: LayerMove) => void;
-    /** Giving both makes rows selectable: a click selects one, shift-click adds
-     *  or removes one, and dragging a selected row drags its selected siblings. */
-    selectedIds?: readonly string[];
-    onSelect?: (ids: string[]) => void;
-    /** Adds a visibility checkbox to every unlocked layer. */
-    onVisibilityChange?: (id: string, visible: boolean) => void;
-    /** Adds a ✕ to every unlocked layer. */
-    onRemove?: (id: string) => void;
-    /** A layer's controls. Returning `null` leaves that layer a one-line row. */
-    renderBody?: (item: LayerListItem) => ReactNode;
-    /** Ids whose body and children are folded away. Giving it makes folding
-     *  controlled; `onCollapsedChange` fires either way. */
-    collapsedIds?: readonly string[];
-    onCollapsedChange?: (ids: string[]) => void;
-    /** Heading above the list. */
-    title?: string;
-    /** Names the list for assistive tech when it has no `title`. */
-    label?: string;
-    /** Kinds the user can add, as buttons beside the title. Shown only with `onAdd`. */
-    addKinds?: string[];
-    onAdd?: (kind: string) => void;
-    /** Shown in place of the list when `items` is empty. */
-    empty?: ReactNode;
-    /** Appended to the root's class list — the module's own names are hashed. */
-    className?: string;
-}
-/** Returns `items` with `move` applied, for a consumer that holds the tree as state. */
-declare function moveLayers(items: LayerListItem[], move: LayerMove): LayerListItem[];
-/**
- * An ordered, drag-reorderable list of layers — a document's objects, a lab's
- * canvases, a fill's effects. Each layer is a one-line row or, with a body, a
- * card whose controls fold away; either can nest child layers. Selection,
- * visibility, removal and an add palette are each on when their handler is given.
- */
-declare function LayerList(props: LayerListProps): react.JSX.Element;
-
-export { LayerList as L, moveLayers as m };
-export type { LayerListItem as a, LayerListProps as b, LayerMove as c };

package/dist/_dts/PrefsRow.d-DFpPIeIC.d.ts

@@ -1,39 +0,0 @@
-import { Stance } from '@weasel-js/theme';
-import { ReactNode } from 'react';
-import { ToolPrefLeaf } from '@weasel-js/core';
-
-/**
- * What a surface holds, and which of its peers it is. Every surface that takes
- * these takes both, and the theme decides how each looks.
- */
-interface StanceProps {
-    /** The class of content the surface holds. Omitted, it draws as it always has. */
-    stance?: Stance;
-    /**
-     * Which of its peers this is: an index into the theme's tone list, wrapping,
-     * or a color given directly. Independent of `stance`, and allowed without one.
-     */
-    tone?: number | string;
-}
-
-/** What a {@link PrefRenderer} is given for the leaf it is rendering. */
-interface PrefRenderContext {
-    /** Dotted path of the leaf within the schema root. */
-    path: string;
-    /** The schema node. App renderers narrow this to their own kind shape. */
-    pref: ToolPrefLeaf;
-    /** Current value — `values` at `path`, falling back to `pref.default`. */
-    value: unknown;
-    setValue: (value: unknown) => void;
-    /** Whether this leaf is currently auto — not pinned, computed by the owner. */
-    auto: boolean;
-    /** Toggle this leaf's auto state. */
-    setAuto: (next: boolean) => void;
-}
-/**
- * Renders the control cell for one preference leaf. Returning `null`
- * collapses the row.
- */
-type PrefRenderer = (ctx: PrefRenderContext) => ReactNode;
-
-export type { PrefRenderer as P, StanceProps as S, PrefRenderContext as a };