@weasel-js/labkit 1.0.2 → 1.0.4

package/src/lab/WorkspaceGrid.tsx

@@ -1,20 +1,196 @@
-import { Children, type CSSProperties, type ReactNode } from 'react';
-import { gridDims } from './gridDims';
+import {
+  Children,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
+import { asNodeId, createNode, gridStrategy, type NodeId, Store } from 'windease';
+import {
+  type ChromeMap,
+  Container,
+  DragHandle,
+  DragProvider,
+  Provider,
+  StrategyRegistryProvider,
+} from 'windease/react';
+
+const ZONE_ID = asNodeId('lk-workspaces');
+const STRATEGIES = { grid: gridStrategy as never };
+const KIND = 'workspace';
+
+/** A tile's persisted extent, keyed by the id its caller gave it. Grid resizes
+ *  write `span`; `size` is here because a strategy swap would write that. */
+export type WorkspaceLayout = Record<
+  string,
+  { size?: { w?: number; h?: number }; span?: { cols?: number; rows?: number } }
+>;
 
 export interface WorkspaceGridProps {
   children: ReactNode;
+  /**
+   * Stable id per child, positionally matched. Supply these whenever a tile
+   * can be closed from the middle: without them a tile is identified by its
+   * position, so closing one shifts every id after it and the panes inherit
+   * each other's dragged extents. `layout` and `reorderable` both key off
+   * these, so neither means much without them.
+   */
+  ids?: readonly string[];
+  /** Draggable seams between tiles. Off by default — an even tiling is the
+   *  behavior every existing caller has. */
+  resizable?: boolean;
+  /** Let a tile be dragged to a new position. Off by default. The grid never
+   *  reorders `children` itself: it reports the order a drop would produce and
+   *  the caller commits it. */
+  reorderable?: boolean;
+  /** The full id list a drop would produce, in its new order. */
+  onReorder?: (ids: string[]) => void;
+  /** Extents from a previous session, applied to tiles as they register. */
+  layout?: WorkspaceLayout;
+  /** Fires when a tile's extent changes. Persist it and hand it back as
+   *  `layout` to make a resize survive a reload. */
+  onLayoutChange?: (layout: WorkspaceLayout) => void;
+  gap?: number;
+  padding?: number;
+  /**
+   * Fixed tiling extent. Omit in an app — the grid measures its own box. Supply
+   * it where nothing measures, notably jsdom: at a zero measurement the grid
+   * renders no tiles at all.
+   */
+  viewport?: { w: number; h: number };
+}
+
+function extentOf(store: Store, id: NodeId): WorkspaceLayout[string] | null {
+  const p = store.getNode(id)?.membership?.placement as WorkspaceLayout[string] | undefined;
+  if (!p) return null;
+  const out: WorkspaceLayout[string] = {};
+  if (p.size) out.size = p.size;
+  if (p.span) out.span = p.span;
+  return Object.keys(out).length > 0 ? out : null;
 }
 
-export function WorkspaceGrid({ children }: WorkspaceGridProps) {
-  const count = Children.count(children);
-  const { cols, rows } = gridDims(count);
-  const style = {
-    '--lk-grid-cols': String(cols),
-    '--lk-grid-rows': String(rows),
-  } as CSSProperties;
+/**
+ * Auto-balanced tiling of workspaces, `ceil(sqrt(n))` columns wide.
+ *
+ * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
+ * laid out by CSS — `windease/styles.css` (folded into
+ * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
+ */
+export function WorkspaceGrid({
+  children,
+  ids,
+  resizable = false,
+  reorderable = false,
+  onReorder,
+  layout,
+  onLayoutChange,
+  gap = 12,
+  padding = 0,
+  viewport,
+}: WorkspaceGridProps) {
+  const items = Children.toArray(children);
+  const idKey = ids ? ids.join(',') : `#${items.length}`;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: idKey is the stable projection of items/ids; depending on those directly rebuilds every render and re-runs the sync effect forever
+  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]);
+
+  // Held in refs rather than depended on: a fresh object each render would
+  // re-run the sync effect, and only a newly registered tile reads `layout`.
+  const layoutRef = useRef(layout);
+  layoutRef.current = layout;
+  const onLayoutChangeRef = useRef(onLayoutChange);
+  onLayoutChangeRef.current = onLayoutChange;
+
+  // One store for the component's lifetime: a tile's dragged extent lives in
+  // its node, so rebuilding the store on every add or close would silently
+  // reset every pane.
+  const storeRef = useRef<Store | null>(null);
+  if (storeRef.current === null) {
+    const store = new Store();
+    store.registerNode(
+      createNode({
+        kind: 'zone',
+        id: ZONE_ID,
+        container: { strategyId: 'grid', config: { resizable, gap, padding } },
+      }),
+    );
+    storeRef.current = store;
+  }
+  const store = storeRef.current;
+
+  useLayoutEffect(() => {
+    store.updateContainerConfig(ZONE_ID, { resizable, gap, padding });
+  }, [store, resizable, gap, padding]);
+
+  useLayoutEffect(() => {
+    const present = new Set(store.getContainerView(ZONE_ID)?.childOrder ?? []);
+    const wanted = new Set(nodeIds);
+    for (const id of present) {
+      if (!wanted.has(id)) store.unregisterNode(id);
+    }
+    for (const id of nodeIds) {
+      if (present.has(id)) continue;
+      store.registerNode(createNode({ kind: KIND, id, parentId: ZONE_ID, focus: true }));
+      store.showNode(id);
+      const saved = layoutRef.current?.[id];
+      if (saved) store.patchPlacement(id, saved);
+    }
+    store.setChildOrder(ZONE_ID, [...nodeIds]);
+  }, [store, nodeIds]);
+
+  useEffect(() => {
+    if (!onLayoutChange) return;
+    return store.events.on('node.placementChanged', () => {
+      const next: WorkspaceLayout = {};
+      for (const child of store.getChildren(ZONE_ID)) {
+        const extent = extentOf(store, child.id);
+        if (extent) next[child.id] = extent;
+      }
+      onLayoutChangeRef.current?.(next);
+    });
+  }, [store, onLayoutChange]);
+
+  const commitOrder = useCallback(
+    (nextIds: NodeId[]) => onReorder?.(nextIds.map(String)),
+    [onReorder],
+  );
+
+  const chrome = useMemo<ChromeMap>(() => {
+    const byId = new Map<string, ReactNode>(nodeIds.map((id, i) => [id, items[i]]));
+    return {
+      [KIND]: ({ node }) => {
+        const content = byId.get(node.id) ?? null;
+        if (!reorderable) return content;
+        // A tile is full of controls, so the whole thing can't be the handle.
+        return (
+          <div className="lk-workspace-tile">
+            <DragHandle nodeId={node.id} className="lk-workspace-tile__grip">
+              <span className="lk-workspace-tile__grip-dots" aria-hidden="true" />
+            </DragHandle>
+            <div className="lk-workspace-tile__body">{content}</div>
+          </div>
+        );
+      },
+    };
+  }, [nodeIds, items, reorderable]);
+
+  const grid = (
+    <Container
+      parentId={ZONE_ID}
+      chrome={chrome}
+      className="lk-workspace-grid windease-zone"
+      affordances={resizable}
+      viewport={viewport}
+      onChildOrderChange={reorderable ? commitOrder : undefined}
+    />
+  );
+
   return (
-    <div className="lk-workspace-grid" style={style}>
-      {children}
-    </div>
+    <Provider store={store}>
+      <StrategyRegistryProvider strategies={STRATEGIES}>
+        {reorderable ? <DragProvider>{grid}</DragProvider> : grid}
+      </StrategyRegistryProvider>
+    </Provider>
   );
 }

package/src/lab/index.ts

@@ -1,5 +1,3 @@
-export type { GridDims } from './gridDims';
-export { gridDims } from './gridDims';
 export type { LabProps } from './Lab';
 export { Lab } from './Lab';
 export type { LabContextValue } from './LabContext';

package/src/layers/LayerList.tsx

@@ -1,6 +1,7 @@
 import { type PointerEvent, useRef, useState } from 'react';
 import type { LayerDescriptor } from '../instrument/types';
 
+/** Props for `<LayerList>`. */
 export interface LayerListProps {
   layers: LayerDescriptor[];
   visibility: Record<string, boolean>;
@@ -15,6 +16,8 @@ interface DragState {
   startY: number;
 }
 
+/** A reorderable list of layers with per-layer visibility toggles. Layers
+ *  marked `alwaysOn` are pinned and cannot be reordered or hidden. */
 export function LayerList({ layers, visibility, onReorder, onToggle, className }: LayerListProps) {
   const reorderable = layers.filter((l) => !l.alwaysOn);
   const pinned = layers.filter((l) => l.alwaysOn);

package/src/primitives/FpsMeter.tsx

@@ -3,6 +3,7 @@ import { rollingAverage } from './fpsAverage';
 
 const SAMPLE_WINDOW = 30;
 
+/** A live frame-rate readout, averaged over the last 30 frames. */
 export function FpsMeter() {
   const [fps, setFps] = useState(0);
   const samplesRef = useRef<number[]>([]);

package/src/primitives/ScaleIndicator.tsx

@@ -1,6 +1,7 @@
 import { useContext } from 'react';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
 
+/** Props for `<ScaleIndicator>`. */
 export interface ScaleIndicatorProps {
   /** Current view zoom factor. If omitted, reads from CanvasStackContext. Defaults to 1. */
   zoom?: number;
@@ -25,6 +26,9 @@ function niceNumber(n: number): number {
   return nice * 10 ** exp;
 }
 
+/** A scale bar: a labeled rule showing how far a round number of world units
+ *  is at the current zoom. Reads the zoom from the surrounding canvas stack
+ *  unless one is passed. */
 export function ScaleIndicator({
   zoom,
   pixelsPerUnit = 1,

package/src/primitives/Sidebar.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 
+/** Props for `<Sidebar>`. */
 export interface SidebarProps {
   children: ReactNode;
   title?: string;
@@ -7,6 +8,8 @@ export interface SidebarProps {
   onToggle?: () => void;
 }
 
+/** A collapsible side panel with an optional title. Collapse state is the
+ *  caller's to hold. */
 export function Sidebar({ children, title, collapsed = false, onToggle }: SidebarProps) {
   const className = `lk-sidebar${collapsed ? ' lk-sidebar--collapsed' : ''}`;
   return (

package/src/primitives/StatusBar.tsx

@@ -1,9 +1,11 @@
 import type { ReactNode } from 'react';
 
+/** Props for `<StatusBar>`. */
 export interface StatusBarProps {
   children: ReactNode;
 }
 
+/** A footer strip for readouts. Fill it with `<StatusBar.Section>`. */
 export function StatusBar({ children }: StatusBarProps) {
   return <div className="lk-status-bar">{children}</div>;
 }
@@ -15,4 +17,5 @@ function Section({ children }: SectionProps) {
   return <span className="lk-status-bar-section">{children}</span>;
 }
 
+/** One readout within a status bar. */
 StatusBar.Section = Section;

package/src/primitives/Toolbar.tsx

@@ -1,9 +1,12 @@
 import type { MouseEventHandler, ReactNode } from 'react';
 
+/** Props for `<Toolbar>`. */
 export interface ToolbarProps {
   children: ReactNode;
 }
 
+/** A horizontal bar of controls. Fill it with `<Toolbar.Title>`,
+ *  `<Toolbar.Button>` and `<Toolbar.Spacer>`. */
 export function Toolbar({ children }: ToolbarProps) {
   return <div className="lk-toolbar">{children}</div>;
 }
@@ -39,6 +42,9 @@ function Spacer() {
   return <span className="lk-toolbar-spacer" aria-hidden="true" />;
 }
 
+/** A label within a toolbar. */
 Toolbar.Title = Title;
+/** A button within a toolbar. */
 Toolbar.Button = Button;
+/** Flexible space that pushes what follows to the far end of the toolbar. */
 Toolbar.Spacer = Spacer;

package/src/state/SingletonExperiment.tsx

@@ -5,6 +5,7 @@ import type { StorageAdapter } from './types';
 
 const SINGLETON_INSTRUMENT = '__singleton__';
 
+/** Props for `<SingletonExperimentProvider>`. */
 export interface SingletonExperimentProviderProps<TS, TC> {
   /** Stable id for the synthetic workspace; also doubles as the
    *  WorkspaceIdContext value. */

package/src/state/adapters.ts

@@ -1,6 +1,8 @@
 import { decodeUrlHash, encodeUrlHash } from './helpers';
 import type { StorageAdapter } from './types';
 
+/** Persist to `localStorage` — state survives a reload and a new tab. Falls
+ *  back to no-ops when storage is unavailable. */
 export const localStorageAdapter: StorageAdapter = {
   read: (key) => {
     try {
@@ -25,6 +27,7 @@ export const localStorageAdapter: StorageAdapter = {
   },
 };
 
+/** Persist to `sessionStorage` — state survives a reload but not a new tab. */
 export const sessionStorageAdapter: StorageAdapter = {
   read: (key) => {
     try {
@@ -68,6 +71,8 @@ function writeHashMap(map: Record<string, string>): void {
   window.history.replaceState(null, '', `#${encoded}`);
 }
 
+/** Persist into the URL fragment, so the page's link carries its state and
+ *  can be shared or bookmarked. */
 export const urlHashAdapter: StorageAdapter = {
   read: (key) => readHashMap()[key] ?? null,
   write: (key, value) => {
@@ -82,6 +87,8 @@ export const urlHashAdapter: StorageAdapter = {
   },
 };
 
+/** An in-memory store, discarded on reload. For tests, and for labs that
+ *  should start fresh every time. */
 export function createMemoryAdapter(): StorageAdapter {
   const store = new Map<string, string>();
   return {
@@ -95,6 +102,7 @@ export function createMemoryAdapter(): StorageAdapter {
   };
 }
 
+/** Persists nothing and reads back nothing. */
 export const noneAdapter: StorageAdapter = {
   read: () => null,
   write: () => {},

package/src/state/context.tsx

@@ -5,8 +5,11 @@ import type { LabStoreState } from './types';
 
 type LabStoreCtx = { store: LabStore } | null;
 
+/** Context carrying the lab store. Prefer `useLabStore`; this is exported for
+ *  code that needs to read the context without subscribing. */
 export const LabStoreContext = createContext<LabStoreCtx>(null);
 
+/** Provides a lab store to its subtree. */
 export function LabStoreProvider({
   store,
   children,
@@ -17,14 +20,18 @@ export function LabStoreProvider({
   return <LabStoreContext.Provider value={{ store }}>{children}</LabStoreContext.Provider>;
 }
 
+/** Subscribe to the whole lab store. Throws outside a `<LabStoreProvider>`. */
 export function useLabStore(): LabStoreState & ReturnType<LabStore['getState']> {
   const ctx = useContext(LabStoreContext);
   if (!ctx) throw new Error('[labkit] useLabStore must be used inside <LabStoreProvider>');
   return useStore(ctx.store);
 }
 
+/** Context carrying which workspace the subtree belongs to. */
 export const WorkspaceIdContext = createContext<string | null>(null);
 
+/** Names the workspace its subtree belongs to, so an instrument's hooks can
+ *  find their own record in the store without being passed an id. */
 export function WorkspaceIdProvider({
   workspaceId,
   children,
@@ -35,6 +42,8 @@ export function WorkspaceIdProvider({
   return <WorkspaceIdContext.Provider value={workspaceId}>{children}</WorkspaceIdContext.Provider>;
 }
 
+/** The id of the workspace this component is inside. Throws outside a
+ *  `<WorkspaceIdProvider>`. */
 export function useWorkspaceId(): string {
   const id = useContext(WorkspaceIdContext);
   if (!id) throw new Error('[labkit] useWorkspaceId must be used inside <WorkspaceIdProvider>');

package/src/state/helpers.ts

@@ -1,16 +1,21 @@
 import type { InstrumentSerializers, UndoStack, WorkspaceRecord } from './types';
 
+/** The storage key a lab writes one of its buckets under. Namespaced by
+ *  `storageKey` so two labs sharing an origin do not collide. */
 export function labStorageKey(
   storageKey: string,
-  bucket: 'workspaces' | 'saves' | 'theme',
+  bucket: 'workspaces' | 'saves' | 'theme' | 'layout',
 ): string {
   return `lk:${storageKey}:${bucket}`;
 }
 
+/** Encode a string for the URL fragment. */
 export function encodeUrlHash(value: string): string {
   return btoa(encodeURIComponent(value));
 }
 
+/** Decode a URL fragment written by `encodeUrlHash`, or `null` if it is
+ *  malformed. */
 export function decodeUrlHash(hash: string): string | null {
   if (!hash) return null;
   try {
@@ -20,12 +25,16 @@ export function decodeUrlHash(hash: string): string | null {
   }
 }
 
+/** A fresh, empty undo history. */
 export function emptyUndoStack(): UndoStack {
   return { past: [], future: [] };
 }
 
 type SerializedRecord = Omit<WorkspaceRecord, 'undoStack'>;
 
+/** Serialize workspaces for storage, running each instrument's own serializer
+ *  over its state. Undo history is deliberately dropped — it does not survive
+ *  a reload. */
 export function serializeWorkspaces(
   workspaces: WorkspaceRecord[],
   serializers: InstrumentSerializers,
@@ -40,6 +49,9 @@ export function serializeWorkspaces(
   return JSON.stringify(records);
 }
 
+/** Rebuild workspaces from storage, running each instrument's deserializer
+ *  over its state and starting each with an empty undo history. Returns an
+ *  empty list rather than throwing on malformed input. */
 export function deserializeWorkspaces(
   raw: string,
   deserializers: InstrumentSerializers,

package/src/state/store.test.ts

@@ -245,7 +245,8 @@ describe('persistence — debounced writes', () => {
     vi.advanceTimersByTime(400);
     const writesAfter = writeSpy.mock.calls.length;
 
-    expect(writesAfter - writesBefore).toBe(3);
+    // One flush, one write per storage key: workspaces, saves, theme, layout.
+    expect(writesAfter - writesBefore).toBe(4);
     vi.useRealTimers();
   });
 });

package/src/state/store.ts

@@ -14,6 +14,8 @@ import type {
   WorkspaceRecord,
 } from './types';
 
+/** Every mutation a lab store supports: managing workspaces, saving and
+ *  restoring snapshots, and setting the color mode. */
 export interface LabStoreActions {
   addWorkspace: (record: Omit<WorkspaceRecord, 'undoStack'>) => void;
   removeWorkspace: (id: string) => void;
@@ -32,12 +34,17 @@ export interface LabStoreActions {
   deleteSnapshot: (snapshotId: string) => void;
   listSnapshots: (workspaceId?: string) => SavedSnapshot[];
   setMode: (mode: LabMode) => void;
+  setLayout: (layout: Record<string, unknown>) => void;
 }
 
+/** A lab's store: its state and actions, plus the hook instruments use to
+ *  register how their state is serialized. */
 export type LabStore = StoreApi<LabStoreState & LabStoreActions> & {
   registerSerializers: (s: InstrumentSerializers) => void;
 };
 
+/** Build a lab store, hydrating from storage if anything was saved under the
+ *  same key. Writes back are debounced. */
 export function createLabStore(options: CreateLabStoreOptions): LabStore {
   let serializers: InstrumentSerializers = {};
   let flushTimer: ReturnType<typeof setTimeout> | null = null;
@@ -59,6 +66,17 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     }
   }
 
+  const layoutRaw = options.storage.read(labStorageKey(options.storageKey, 'layout'));
+  let hydratedLayout: Record<string, unknown> = {};
+  if (layoutRaw) {
+    try {
+      hydratedLayout = JSON.parse(layoutRaw) as Record<string, unknown>;
+    } catch {
+      console.warn('[labkit] failed to parse saved layout, starting empty');
+      hydratedLayout = {};
+    }
+  }
+
   const modeRaw = options.storage.read(labStorageKey(options.storageKey, 'theme'));
   // `interstellar` was the dark mode's name back when it was a theme.
   const stored = modeRaw === 'interstellar' ? 'dark' : modeRaw;
@@ -73,6 +91,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     workspaces: hydratedWorkspaces,
     savedSnapshots: hydratedSnapshots,
     mode: hydratedMode,
+    layout: hydratedLayout,
 
     addWorkspace: (record) => {
       set((s) => ({
@@ -201,6 +220,11 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       set({ mode });
       scheduleFlush();
     },
+
+    setLayout: (layout) => {
+      set({ layout });
+      scheduleFlush();
+    },
   }));
 
   function scheduleFlush(): void {
@@ -216,6 +240,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         JSON.stringify(s.savedSnapshots),
       );
       options.storage.write(labStorageKey(options.storageKey, 'theme'), s.mode);
+      options.storage.write(labStorageKey(options.storageKey, 'layout'), JSON.stringify(s.layout));
       flushTimer = null;
     }, 300);
   }

package/src/state/types.ts

@@ -1,8 +1,12 @@
+/** A workspace's undo history, as snapshots of its state either side of the
+ *  present. */
 export interface UndoStack {
   past: unknown[];
   future: unknown[];
 }
 
+/** One workspace as the store holds it: which instrument it runs, that
+ *  instrument's config and state, the camera, and the undo history. */
 export interface WorkspaceRecord<TS = unknown, TC = unknown> {
   id: string;
   instrumentName: string;
@@ -12,6 +16,8 @@ export interface WorkspaceRecord<TS = unknown, TC = unknown> {
   undoStack: UndoStack;
 }
 
+/** A named, saved copy of a workspace's config and state, restorable into any
+ *  workspace running the same instrument. */
 export interface SavedSnapshot {
   id: string;
   name: string;
@@ -25,18 +31,28 @@ export interface SavedSnapshot {
 /** `auto` follows the OS; the other two are an explicit choice. */
 export type LabMode = 'auto' | 'light' | 'dark';
 
+/** Everything a lab persists: its workspaces, its saved snapshots, and the
+ *  chosen color mode. */
 export interface LabStoreState {
   workspaces: WorkspaceRecord[];
   savedSnapshots: SavedSnapshot[];
   mode: LabMode;
+  /** Per-workspace tile extents, keyed by workspace id. Opaque here — the
+   *  shape belongs to whatever lays the workspaces out. */
+  layout: Record<string, unknown>;
 }
 
+/** Where a lab persists itself. Implementations are keyed string storage and
+ *  nothing more, so the same store works against localStorage, the URL hash,
+ *  or memory. */
 export interface StorageAdapter {
   read(key: string): string | null;
   write(key: string, value: string): void;
   delete?(key: string): void;
 }
 
+/** What `useExperimentState` hands an instrument: its state and config, with
+ *  a setter for each. */
 export interface ExperimentStateHandle<TS, TC> {
   state: TS;
   setState: (next: TS | ((prev: TS) => TS)) => void;
@@ -44,12 +60,16 @@ export interface ExperimentStateHandle<TS, TC> {
   setConfig: (key: keyof TC, value: TC[keyof TC]) => void;
 }
 
+/** Options for `createLabStore`. `storageKey` namespaces the keys written, so
+ *  two labs on one origin do not collide. */
 export interface CreateLabStoreOptions {
   storageKey: string;
   storage: StorageAdapter;
   initialMode?: LabMode;
 }
 
+/** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
+ *  instrument whose state is already JSON-safe needs no entry. */
 export type InstrumentSerializers = Record<
   string,
   { serialize?: (state: unknown) => unknown; deserialize?: (data: unknown) => unknown } | undefined

package/src/state/useExperimentState.ts

@@ -3,6 +3,9 @@ import { useStore } from 'zustand/react';
 import { LabStoreContext, WorkspaceIdContext } from './context';
 import type { ExperimentStateHandle } from './types';
 
+/** An instrument's own state and config, plus setters. Reads the surrounding
+ *  workspace id, so an instrument never has to know which workspace it is
+ *  running in. Throws outside a lab store and workspace. */
 export function useExperimentState<TS = unknown, TC = unknown>(): ExperimentStateHandle<TS, TC> {
   const ctx = useContext(LabStoreContext);
   if (!ctx) throw new Error('[labkit] useExperimentState must be used inside <LabStoreProvider>');

package/src/test-setup.ts

@@ -12,6 +12,25 @@ if (jsdomWin && typeof globalThis.localStorage === 'undefined') {
   Object.defineProperty(globalThis, 'sessionStorage', { value: jsdomWin.sessionStorage });
 }
 
+// windease's ContainerHost calls `new ResizeObserver` unguarded, and jsdom
+// ships none. The stub must report a non-zero box: a windease container
+// renders no children at all until something measures it, and jsdom's own
+// geometry is always 0, so every tiled tile would vanish from the DOM.
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = class {
+    #cb: ResizeObserverCallback;
+    constructor(cb: ResizeObserverCallback) {
+      this.#cb = cb;
+    }
+    observe(target: Element) {
+      const contentRect = { width: 1024, height: 768, x: 0, y: 0, top: 0, left: 0 };
+      this.#cb([{ target, contentRect } as ResizeObserverEntry], this);
+    }
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof ResizeObserver;
+}
+
 afterEach(() => {
   cleanup();
 });

package/src/ui/layers/LayerStack.tsx

@@ -1,6 +1,8 @@
 import { type CSSProperties, type ReactNode, type RefCallback, useEffect, useState } from 'react';
 import { dlog, useReorderDragList } from '../../passthrough/weasel-ui';
 
+/** One card in a layer stack: its identity, the label shown when collapsed,
+ *  and the optional select hoisted into its header. */
 export interface LayerStackItem {
   /** Stable id used for keys, onRemove, onReorder. Numeric to match
    *  common id-from-nextId conventions; string ids also work. */
@@ -22,6 +24,7 @@ export interface LayerStackItem {
   defaultExpanded?: boolean;
 }
 
+/** Props for `<LayerStack>`. */
 export interface LayerStackProps {
   title: string;
   items: LayerStackItem[];
@@ -38,6 +41,8 @@ export interface LayerStackProps {
   hideHead?: boolean;
 }
 
+/** A drag-reorderable stack of expandable cards, with a palette in the header
+ *  for adding more. The body of each card is the caller's to render. */
 export function LayerStack({
   title,
   items,