@weasel-js/labkit 1.4.4 → 1.5.0

package/src/lab/Lab.tsx

@@ -4,22 +4,37 @@ import {
   type ReactNode,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
 } from 'react';
 import { useStore } from 'zustand/react';
+import { AnnotationPreloadContext } from '../annotations/preload';
+import { ANNOTATION_TOOLS } from '../annotations/toolMap';
+import {
+  LabFooterRegion,
+  LabHeaderRegion,
+  LabSidebarRegion,
+  labContributions,
+} from '../chrome/LabChrome';
+import type { LabContribution } from '../chrome/labTypes';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigRule, ControlRenderer } from '../config/types';
-import { configDefaultsOf, serializersOf } from '../instrument/serializers';
 import type { InstrumentList } from '../instrument/types';
-import { noneAdapter } from '../state/adapters';
+import { Split } from '../primitives/Split';
+import { defaultStorage, noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
+import { type OpenedLabStore, openLabStore } from '../state/openLabStore';
+import { PersistenceContext } from '../state/Persistence';
+import { createRecordCache } from '../state/records';
 import { createLabStore, type LabStore } from '../state/store';
 import type { LabMode, StorageAdapter, TrialRecord } from '../state/types';
+import { useOpenOnce, useWarnIgnoredChange } from '../state/useOpenOnce';
+import { usePersistedState } from '../state/usePersistedState';
 import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
 import { useSurfaceCanvas, useSurfaceOptional } from '../surface/useSurfaceTile';
-import { useTiledSurface } from '../surface/useTiledSurface';
+import { type SurfaceFrame, useTiledSurface } from '../surface/useTiledSurface';
 import { interstellarTheme } from '../theme/interstellar';
 import type { TrialTool } from '../tools/types';
 import { Trial } from '../trial/Trial';
@@ -30,21 +45,25 @@ import {
   reorderTrials as reorderTrialsOp,
   resetTrial as resetTrialOp,
 } from '../trial/trialOps';
+import { useLabFitWarning } from './fitCheck';
 import { LabContext, type LabContextValue } from './LabContext';
 import { LabHeader } from './LabHeader';
 import { LabPalette } from './LabPalette';
 import { LabShell } from './LabShell';
+import type { LabPage } from './LabSwitcher';
 import { createPanelHostRegistry, PanelHostContext } from './panelHost';
 import { useResolvedMode } from './useSystemMode';
 import { type PanelDescriptor, type TrialLayout, Workspace } from './Workspace';
 
-/** Props for `<Lab>`. */
-export interface LabProps {
+interface LabBaseProps {
+  /** May change while mounted. An instrument that is a different object from
+   *  the last render counts as replaced and its open trials' configs are
+   *  refilled, so hoist or memoize the list. */
   instruments: InstrumentList;
   defaultInstrument: string;
-  storage?: StorageAdapter | null;
-  storageKey?: string;
   mode?: LabMode;
+  /** Rendered while a stored lab loads. Default: the lab's empty shell. */
+  fallback?: ReactNode;
   /**
    * Optional list of CSS colors used to compose the interstellar theme's
    * cosmic backdrop. Each color becomes one radial-gradient blob on the
@@ -53,12 +72,27 @@ export interface LabProps {
    */
   nebula?: readonly string[];
   title?: string;
+  /** The project's other labs. Given two or more, the title becomes the way to
+   *  reach them — the same switcher `<LabShell>` renders, so a lab reached from
+   *  one is not a dead end. */
+  pages?: readonly LabPage[];
+  /** The path the switcher marks as open. Defaults to the current location. */
+  path?: string;
   /** Rendered in the shell's footer, below the workspace. */
   footer?: ReactNode;
   /** Contributions added to every trial's chrome, after the instrument's own. */
   chrome?: readonly TrialContribution[];
+  /** Contributions to the lab's own chrome — its header bar, its sidebar, its
+   *  tool rail and its footer — rather than to every trial's. Rendered after
+   *  `children` and `footer`, which stay the way a lab drops arbitrary content
+   *  into those same two boxes. Going from no sidebar contributions to some
+   *  remounts the workspace and every trial, dropping unpersisted trial state. */
+  labChrome?: readonly LabContribution[];
   /** Built-in contribution ids to drop. Throws on an id that is not there. */
   suppress?: readonly string[];
+  /** Offer the header's add-trial control. Default `true`; a lab that opens
+   *  trials some other way passes `false`. */
+  addTrial?: boolean;
   /** Tools offered lab-wide. A trial whose instrument declares none of its own
    *  reflects and writes this slot. */
   tools?: readonly TrialTool[];
@@ -72,31 +106,89 @@ export interface LabProps {
   children?: ReactNode;
 }
 
-function buildStore(
+/** Props for `<Lab>`. With a `storageKey` the lab persists — to IndexedDB
+ *  unless `storage` names another substrate — and both are read once, at
+ *  mount. Without one, nothing persists. */
+export type LabProps = LabBaseProps &
+  (
+    | { storageKey?: undefined; storage?: undefined }
+    | { storageKey: string; storage?: StorageAdapter }
+  );
+
+interface OpenedLab extends OpenedLabStore {
+  marks: ReadonlyMap<string, unknown>;
+}
+
+function seedDefaultTrial(
+  store: LabStore,
   instruments: InstrumentList,
   defaultInstrument: string,
-  storage: StorageAdapter,
+): void {
+  if (store.getState().trials.length > 0) return;
+  const record = addTrialOp([], instruments, defaultInstrument)[0];
+  if (!record) return;
+  const { undoStack: _undoStack, ...rest } = record;
+  store.getState().addTrial(rest);
+}
+
+/** A lab with nothing to load renders at once. Its records hold
+ *  `usePersistedState` values for the session and write nothing. */
+function openUnstoredLab({ instruments, defaultInstrument, mode }: LabProps): OpenedLab {
+  const store = createLabStore({ initialMode: mode ?? 'auto', instruments });
+  seedDefaultTrial(store, instruments, defaultInstrument);
+  const records = createRecordCache({ storage: noneAdapter, prefix: '', writable: false });
+  return { store, records, close: () => records.close(), marks: new Map() };
+}
+
+async function openStoredLab(
+  { instruments, defaultInstrument, mode }: LabProps,
   storageKey: string,
-  initialMode: LabMode,
-): LabStore {
-  // Hydration reads the serializers, so they go in with the store rather than
-  // being registered onto it afterwards.
-  const store = createLabStore({
+  storage: StorageAdapter | undefined,
+): Promise<OpenedLab> {
+  // The store reads the instruments' serializers and defaults while it is being
+  // built, so they go in with it rather than being pushed onto it afterwards.
+  const opened = await openLabStore({
     storageKey,
-    storage,
-    initialMode,
-    serializers: serializersOf(instruments),
-    configDefaults: configDefaultsOf(instruments),
+    storage: storage ?? (await defaultStorage()),
+    initialMode: mode ?? 'auto',
+    instruments,
   });
-  if (store.getState().trials.length === 0) {
-    const seeded = addTrialOp([], instruments, defaultInstrument);
-    const record = seeded[0];
-    if (record) {
-      const { undoStack: _undoStack, ...rest } = record;
-      store.getState().addTrial(rest);
-    }
-  }
-  return store;
+  seedDefaultTrial(opened.store, instruments, defaultInstrument);
+  const marks = new Map<string, unknown>();
+  await Promise.all(
+    opened.store.getState().trials.map(async (trial) => {
+      const kept = instruments.find((i) => i.name === trial.instrumentName)?.annotations?.storage;
+      if (!kept) return;
+      try {
+        marks.set(trial.id, await kept.load());
+      } catch (error) {
+        console.warn(`[labkit] could not load the marks of trial "${trial.id}"`, error);
+        marks.set(trial.id, null);
+      }
+    }),
+  );
+  return { ...opened, marks };
+}
+
+function LabFallback({
+  title,
+  mode,
+  pages,
+  path,
+}: Pick<LabBaseProps, 'title' | 'mode' | 'pages' | 'path'>) {
+  const resolvedMode = useResolvedMode(mode ?? 'auto');
+  return (
+    <ThemeProvider theme={interstellarTheme} mode={resolvedMode} className="lk-lab">
+      <LabShell
+        title={title ?? 'Labkit'}
+        mode={mode}
+        {...(pages ? { pages } : {})}
+        {...(path !== undefined ? { path } : {})}
+      >
+        {null}
+      </LabShell>
+    </ThemeProvider>
+  );
 }
 
 // Fixed spread of nebula blob positions / sizes / fall-off stops. Colors
@@ -120,39 +212,87 @@ function buildNebula(colors: readonly string[]): string {
   return blobs.join(', ');
 }
 
-/** The lab runtime: creates the store, provides it, and renders one trial
+/** The strip holding the sidebar beside the tool rail and workspace. Its own component
+ *  because the width is a persisted value, and `LabRuntime` renders the
+ *  persistence provider it reads from. */
+function LabPanes({
+  contributions,
+  children,
+}: {
+  contributions: readonly LabContribution[];
+  children: ReactNode;
+}) {
+  const surface = useSurfaceOptional();
+  const [sidebarWidth, setSidebarWidth] = usePersistedState<number | undefined>(
+    'lk-lab-sidebar-width',
+    undefined,
+    { scope: 'lab' },
+  );
+  return (
+    <Split
+      className="lk-lab__panes"
+      sidebarClassName="lk-lab__sidebar"
+      contentClassName="lk-lab__main"
+      label="Lab sidebar"
+      defaultWidth={260}
+      width={sidebarWidth}
+      onWidthChange={(w) => {
+        setSidebarWidth(w);
+        surface?.invalidateRects();
+      }}
+      sidebar={<LabSidebarRegion contributions={contributions} />}
+    >
+      {children}
+    </Split>
+  );
+}
+
+/** The lab runtime: opens the store, provides it, and renders one trial
  *  per record in a grid. Each trial runs one of `instruments`. */
-export function Lab({
+export function Lab(props: LabProps) {
+  if (process.env.NODE_ENV !== 'production' && props.instruments.length === 0) {
+    throw new Error('[labkit] <Lab> requires a non-empty `instruments` array');
+  }
+  const { storageKey, storage } = props;
+  useWarnIgnoredChange('<Lab>', { storageKey, storage });
+  const opened = useOpenOnce<OpenedLab>(() =>
+    storageKey === undefined ? openUnstoredLab(props) : openStoredLab(props, storageKey, storage),
+  );
+  if (!opened) {
+    return props.fallback !== undefined ? (
+      <>{props.fallback}</>
+    ) : (
+      <LabFallback title={props.title} mode={props.mode} pages={props.pages} path={props.path} />
+    );
+  }
+  return <LabRuntime {...props} opened={opened} />;
+}
+
+function LabRuntime({
   instruments,
-  defaultInstrument,
-  storage,
-  storageKey,
   mode,
   nebula,
   title,
+  pages,
+  path,
   footer,
   chrome,
+  labChrome,
   suppress,
+  addTrial,
   tools,
   configRules,
   controls,
   children,
-}: LabProps) {
-  if (process.env.NODE_ENV !== 'production' && instruments.length === 0) {
-    throw new Error('[labkit] <Lab> requires a non-empty `instruments` array');
-  }
+  opened,
+}: LabProps & { opened: OpenedLab }) {
+  const { store } = opened;
 
-  const storeRef = useRef<LabStore | null>(null);
-  if (storeRef.current === null) {
-    storeRef.current = buildStore(
-      instruments,
-      defaultInstrument,
-      storage ?? noneAdapter,
-      storageKey ?? 'labkit',
-      mode ?? 'auto',
-    );
-  }
-  const store = storeRef.current;
+  // The store opened against the list <Lab> mounted with; a later list reaches
+  // it here, before paint.
+  useLayoutEffect(() => {
+    store.getState().setInstruments(instruments);
+  }, [instruments, store]);
 
   const trials = useStore(store, (s) => s.trials);
   const savedSnapshots = useStore(store, (s) => s.savedSnapshots);
@@ -167,38 +307,64 @@ export function Lab({
   if (panelHostsRef.current === null) panelHostsRef.current = createPanelHostRegistry();
 
   // One shared drawing surface for the whole lab, anchored to the body — tile
-  // rects compose against it, and every tile paints into the one buffer.
+  // rects compose against it, and both buffers compose against the same rects.
   // `Workspace` invalidates rects when the grid moves something a
   // ResizeObserver cannot see. A host that already owns a surface keeps it: a
   // lab embedded in a larger shared-surface app must not open a second GL
   // tenancy, and mounts no buffer of its own.
   const outerSurface = useSurfaceOptional();
-  const outerCanvas = useSurfaceCanvas();
-  const [ownCanvas, setOwnCanvas] = useState<HTMLCanvasElement | null>(null);
-  const ownCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  const outerOver = useSurfaceCanvas('over');
+  const outerUnder = useSurfaceCanvas('under');
+  const [ownOver, setOwnOver] = useState<HTMLCanvasElement | null>(null);
+  const [ownUnder, setOwnUnder] = useState<HTMLCanvasElement | null>(null);
+  const ownOverRef = useRef<HTMLCanvasElement | null>(null);
+  const ownUnderRef = useRef<HTMLCanvasElement | null>(null);
   const bufferRef = useRef({ w: 0, h: 0 });
   const surfaceRef = useRef<ReturnType<typeof useTiledSurface> | null>(null);
 
   // Sizing the buffer clears all of it, so every tile has to repaint — not
-  // only the one whose move triggered the measurement.
-  const onFrame = useCallback((frame: { size: { width: number; height: number }; dpr: number }) => {
-    const c = ownCanvasRef.current;
-    if (!c) return;
+  // only the one whose move triggered the measurement. Both buffers are sized
+  // together off one comparison: they are the same box, so a tenant of either
+  // is looking at the same rects, and one invalidateAll covers both.
+  const onFrame = useCallback((frame: SurfaceFrame) => {
+    const canvases = [ownUnderRef.current, ownOverRef.current].filter((c) => c !== null);
+    if (canvases.length === 0) return;
     const w = Math.round(frame.size.width * frame.dpr);
     const h = Math.round(frame.size.height * frame.dpr);
-    if (bufferRef.current.w === w && bufferRef.current.h === h) return;
-    bufferRef.current = { w, h };
-    c.width = w;
-    c.height = h;
-    c.style.width = `${frame.size.width}px`;
-    c.style.height = `${frame.size.height}px`;
-    surfaceRef.current?.invalidateAll();
+    if (bufferRef.current.w !== w || bufferRef.current.h !== h) {
+      bufferRef.current = { w, h };
+      for (const c of canvases) {
+        c.width = w;
+        c.height = h;
+        c.style.width = `${frame.size.width}px`;
+        c.style.height = `${frame.size.height}px`;
+      }
+      surfaceRef.current?.invalidateAll();
+      return;
+    }
+    // A same-size re-tile does not go through here: assigning `width` its own
+    // value resizes nothing, so it clears nothing. The tenants clear, through
+    // `registerClear`.
   }, []);
 
   const ownSurface = useTiledSurface({ onFrame });
   surfaceRef.current = ownSurface;
+  const [labBody, setLabBody] = useState<HTMLDivElement | null>(null);
+  const attachOwnSurface = ownSurface.containerRef;
+  const labBodyRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      setLabBody(el);
+      if (!outerSurface) attachOwnSurface(el);
+    },
+    [outerSurface, attachOwnSurface],
+  );
+  useLabFitWarning(labBody);
   const surface = outerSurface ?? ownSurface;
-  const surfaceCanvas = outerSurface ? outerCanvas : ownCanvas;
+  const surfaceCanvases = useMemo(
+    () =>
+      outerSurface ? { over: outerOver, under: outerUnder } : { over: ownOver, under: ownUnder },
+    [outerSurface, outerOver, outerUnder, ownOver, ownUnder],
+  );
 
   const workspacePanels = useMemo<PanelDescriptor[]>(
     () =>
@@ -211,6 +377,19 @@ export function Lab({
   );
   const resolvedMode = useResolvedMode(modeValue);
 
+  // Tools and lab contributions share one id namespace, so they merge once
+  // here — before any region renders — and a collision throws rather than one
+  // of them silently losing.
+  // Declaring `annotations` on any instrument puts the drawing tools here, in
+  // the lab's rail: one tool is armed across every trial.
+  const annotates = instruments.some((i) => i.annotations != null);
+  const labChromeAll = useMemo(
+    () => labContributions([...(annotates ? ANNOTATION_TOOLS : []), ...(tools ?? [])], labChrome),
+    [annotates, tools, labChrome],
+  );
+  const hasFooterChrome = labChromeAll.some((c) => c.region === 'footer');
+  const hasSidebarChrome = labChromeAll.some((c) => c.region === 'sidebar');
+
   useEffect(() => {
     if (mode && mode !== store.getState().mode) {
       store.getState().setMode(mode);
@@ -222,8 +401,6 @@ export function Lab({
       const currentById = new Map(store.getState().trials.map((w) => [w.id, w]));
       const merged = next.map((w) => currentById.get(w.id) ?? w);
       store.setState({ trials: merged });
-      // Trigger persistence flush via a tracked action.
-      store.getState().setMode(store.getState().mode);
     };
 
     return {
@@ -255,7 +432,6 @@ export function Lab({
               : w,
           ),
         }));
-        store.getState().updateTrialView(id, record.view);
       },
       savedSnapshots,
       saveSnapshot: (trialId, name) => {
@@ -284,66 +460,103 @@ export function Lab({
       ? ({ ['--wzl-backdrop' as string]: buildNebula(nebula) } as CSSProperties)
       : undefined;
 
+  const workspace = (
+    <Workspace
+      panels={workspacePanels}
+      ids={trials.map((w) => w.id)}
+      resizable
+      reorderable
+      onReorder={(ids) => contextValue.reorderTrials(ids)}
+      layout={layout as TrialLayout}
+      onLayoutChange={(next) => store.getState().setLayout(next)}
+    >
+      {trials.map((w) => (
+        <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
+      ))}
+    </Workspace>
+  );
+
   return (
     <LabStoreContext.Provider value={{ store }}>
-      <LabContext.Provider value={contextValue}>
-        <ThemeProvider
-          theme={interstellarTheme}
-          mode={resolvedMode}
-          className="lk-lab"
-          style={backdropStyle}
-        >
-          <LabShell
-            title={title ?? 'Labkit'}
-            mode={modeValue}
-            footer={footer}
-            header={
-              <>
-                <LabHeader />
-                {children}
-              </>
-            }
-          >
-            <PanelHostContext.Provider value={panelHostsRef.current}>
-              <SurfaceContext.Provider value={surface}>
-                <SurfaceCanvasContext.Provider value={surfaceCanvas}>
-                  <div
-                    className="lk-lab__body"
-                    ref={outerSurface ? undefined : ownSurface.containerRef}
-                  >
-                    {outerSurface ? null : (
-                      // Above the trials and inert: the marks a tile paints have
-                      // to sit over the instrument's own DOM, and nothing on this
-                      // buffer takes input — each tile has its own input box.
-                      <canvas
-                        className="lk-lab__surface"
-                        ref={(el) => {
-                          ownCanvasRef.current = el;
-                          setOwnCanvas(el);
-                        }}
-                      />
-                    )}
-                    {tools ? <LabPalette tools={tools} /> : null}
-                    <Workspace
-                      panels={workspacePanels}
-                      ids={trials.map((w) => w.id)}
-                      resizable
-                      reorderable
-                      onReorder={(ids) => contextValue.reorderTrials(ids)}
-                      layout={layout as TrialLayout}
-                      onLayoutChange={(next) => store.getState().setLayout(next)}
-                    >
-                      {trials.map((w) => (
-                        <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
-                      ))}
-                    </Workspace>
-                  </div>
-                </SurfaceCanvasContext.Provider>
-              </SurfaceContext.Provider>
-            </PanelHostContext.Provider>
-          </LabShell>
-        </ThemeProvider>
-      </LabContext.Provider>
+      <PersistenceContext.Provider value={opened.records}>
+        <AnnotationPreloadContext.Provider value={opened.marks}>
+          <LabContext.Provider value={contextValue}>
+            <ThemeProvider
+              theme={interstellarTheme}
+              mode={resolvedMode}
+              className="lk-lab"
+              style={backdropStyle}
+            >
+              <LabShell
+                title={title ?? 'Labkit'}
+                mode={modeValue}
+                {...(pages ? { pages } : {})}
+                {...(path !== undefined ? { path } : {})}
+                footer={
+                  hasFooterChrome ? (
+                    <>
+                      {footer}
+                      <LabFooterRegion contributions={labChromeAll} />
+                    </>
+                  ) : (
+                    footer
+                  )
+                }
+                header={
+                  <>
+                    <LabHeader {...(addTrial !== undefined ? { addTrial } : {})} />
+                    {children}
+                    <LabHeaderRegion contributions={labChromeAll} />
+                  </>
+                }
+              >
+                <PanelHostContext.Provider value={panelHostsRef.current}>
+                  <SurfaceContext.Provider value={surface}>
+                    <SurfaceCanvasContext.Provider value={surfaceCanvases}>
+                      <div className="lk-lab__body" ref={labBodyRef}>
+                        {outerSurface ? null : (
+                          // Two buffers stacked around the trials, both inert —
+                          // each tile takes input from its own box. A tile's marks
+                          // annotate the instrument's DOM from over it; an opaque
+                          // renderer sits under it, so the pane can still hold a
+                          // label. The under one is first so it paints first.
+                          <>
+                            <canvas
+                              className="lk-lab__surface lk-lab__surface--under"
+                              ref={(el) => {
+                                ownUnderRef.current = el;
+                                setOwnUnder(el);
+                              }}
+                            />
+                            <canvas
+                              className="lk-lab__surface lk-lab__surface--over"
+                              ref={(el) => {
+                                ownOverRef.current = el;
+                                setOwnOver(el);
+                              }}
+                            />
+                          </>
+                        )}
+                        {hasSidebarChrome ? (
+                          <LabPanes contributions={labChromeAll}>
+                            <LabPalette contributions={labChromeAll} />
+                            {workspace}
+                          </LabPanes>
+                        ) : (
+                          <>
+                            <LabPalette contributions={labChromeAll} />
+                            {workspace}
+                          </>
+                        )}
+                      </div>
+                    </SurfaceCanvasContext.Provider>
+                  </SurfaceContext.Provider>
+                </PanelHostContext.Provider>
+              </LabShell>
+            </ThemeProvider>
+          </LabContext.Provider>
+        </AnnotationPreloadContext.Provider>
+      </PersistenceContext.Provider>
     </LabStoreContext.Provider>
   );
 }

package/src/lab/LabFit.stories.less

@@ -0,0 +1,18 @@
+// Host pages for LabFit.stories. Each is scoped by its own class, so a story
+// that mounts no fixture leaves the page untouched.
+
+// The mount every example documents: `html, body, #root { margin: 0; height: 100% }`.
+html:has(> body > .lk-fit-host--reset),
+body:has(> .lk-fit-host--reset),
+.lk-fit-host--reset {
+  margin: 0;
+  height: 100%;
+}
+
+.lk-fit-heading {
+  height: 40px;
+}
+
+.lk-fit-frame {
+  height: 560px;
+}