@weasel-js/labkit 1.8.0 → 1.8.1

package/src/loupe/useLoupe.ts

@@ -8,7 +8,7 @@ import {
 import { type RefObject, useCallback, useEffect, useReducer, useRef } from 'react';
 import type { LoupeInputApi } from './loupeActions';
 import { WHEEL_RATE } from './loupeActions';
-import type { ResolvedLoupe } from './types';
+import type { LoupeLens, ResolvedLoupe } from './types';
 
 /** Options for {@link useLoupe}. */
 export interface UseLoupeOptions {
@@ -20,6 +20,12 @@ export interface UseLoupeOptions {
   /** Hex color at a host point. Omitted, the loupe reports no color — which
    *  is the honest answer for a surface with no pixels to read. */
   sample?: (p: LoupePoint) => string | null;
+  /** Run `fn` whenever what `sample` reads changes without the aim moving — a
+   *  canvas that animates, or a frame that arrives after the aim did; returns
+   *  an unsubscribe. While the lens is up, each call samples the aim again, on
+   *  top of the sample every aim takes at once. Omitted, color changes only on
+   *  an aim. */
+  subscribeResample?: (fn: () => void) => () => void;
 }
 
 /** A loupe as a React view reads it. */
@@ -28,11 +34,16 @@ export interface LoupeState {
   visible: boolean;
   /** Where it is aimed, in the host's own pixels. */
   aim: LoupePoint;
+  /** The wheel's magnification. What the lens shows at is `lens.factor`. */
   factor: number;
+  /** The box the lens is drawn in, and what it shows. */
+  lens: LoupeLens;
   mode: LoupeMode;
   color: string | null;
   setMode: (mode: LoupeMode) => void;
   setFactor: (factor: number) => void;
+  /** Sample the aim again, for pixels that changed under a still aim. */
+  resample: () => void;
   /** Sample what the lens shows at a point inside it. */
   pick: (p?: LoupePoint) => string | null;
   /** What `<LoupeGestures>` drives the lens through. Stable for the life of
@@ -56,10 +67,19 @@ function lensShown(over: boolean, enabled: boolean, peeking: boolean): boolean {
  * has no continuous-motion entry, and inventing one to carry the lens' aim
  * would be an input taxonomy change, not a loupe change.
  */
-export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions): LoupeState {
+export function useLoupe({
+  options,
+  hostRef,
+  enabled,
+  sample,
+  subscribeResample,
+}: UseLoupeOptions): LoupeState {
   const [, bump] = useReducer((n: number) => n + 1, 0);
 
   const overRef = useRef(false);
+  // Where the pointer last was over the host, in client px. The model ignores
+  // aims while the lens is down, so this is what the lens opens at.
+  const pointerRef = useRef<{ clientX: number; clientY: number } | null>(null);
   const peekingRef = useRef(false);
   const enabledRef = useLatest(enabled);
   const sampleRef = useLatest(sample);
@@ -81,9 +101,15 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
       onColorChange: (hex) => onColorChangeRef.current?.(hex),
       surface: {
         lens: () => {
-          const d = diameterRef.current;
-          const { x, y } = modelRef.current?.aim ?? { x: 0, y: 0 };
-          return { x: x - d / 2, y: y - d / 2, w: d, h: d };
+          const { center, shows, width, height, factor } = lensRef.current;
+          return {
+            x: center.x - width / 2,
+            y: center.y - height / 2,
+            w: width,
+            h: height,
+            shows,
+            factor,
+          };
         },
         // The lens follows the pointer and is painted over the host rather than
         // into it, so it is never part of the picture being magnified.
@@ -97,7 +123,6 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
   }
   const model = modelRef.current;
 
-  const diameterRef = useLatest(options.diameter);
   const goneRef = useRef(false);
 
   // The model holds no resources, and `dispose` is one-way — so unmounting only
@@ -111,11 +136,25 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
     };
   }, []);
 
+  // Aim at the pointer's last spot over the host, for a lens that has just
+  // come up under a pointer that has not moved since. Stable, because `input`
+  // captures it once.
+  const hostRefRef = useLatest(hostRef);
+  const aimAtPointer = useCallback((): void => {
+    const host = hostRefRef.current.current;
+    const p = pointerRef.current;
+    if (!host || !p) return;
+    const rect = host.getBoundingClientRect();
+    modelRef.current?.aimAt({ x: p.clientX - rect.left, y: p.clientY - rect.top });
+  }, [hostRefRef]);
+
   // Turning the loupe off with the pointer still inside must put the lens away,
-  // and the model only reconsiders on an aim.
+  // and the model only reconsiders on an aim; turning it on must open the lens
+  // where the pointer already is.
   useEffect(() => {
-    if (!enabled && !peekingRef.current) bump();
-  }, [enabled]);
+    if (enabled) aimAtPointer();
+    else if (!peekingRef.current) bump();
+  }, [enabled, aimAtPointer]);
 
   useEffect(() => {
     const host = hostRef.current;
@@ -123,6 +162,7 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
 
     const onPointerMove = (e: PointerEvent): void => {
       overRef.current = true;
+      pointerRef.current = { clientX: e.clientX, clientY: e.clientY };
       const rect = host.getBoundingClientRect();
       model.aimAt({ x: e.clientX - rect.left, y: e.clientY - rect.top });
       if (!shown()) return;
@@ -130,6 +170,7 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
     };
     const onPointerLeave = (): void => {
       overRef.current = false;
+      pointerRef.current = null;
       bump();
     };
 
@@ -141,6 +182,58 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
     };
   }, [hostRef, model, shown]);
 
+  // Subscribed while the lens is up, and before any effect the caller declares
+  // after this hook runs — so a frame its own effect provokes is not missed.
+  // This render's `enabled`: `enabledRef` holds the last committed one.
+  const visible = lensShown(overRef.current, enabled, peekingRef.current);
+
+  // Asked only while the lens is up: a host's `place` may measure its layout.
+  const placed = visible
+    ? (options.place?.({ aim: model.aim, factor: model.factor }) ?? null)
+    : null;
+  const lens: LoupeLens = placed
+    ? {
+        center: placed.center,
+        shows: placed.shows ?? placed.center,
+        width: placed.width,
+        height: placed.height,
+        factor: placed.factor ?? model.factor,
+        shape: options.shape,
+      }
+    : {
+        center: model.aim,
+        shows: model.aim,
+        width: options.diameter,
+        height: options.diameter,
+        factor: model.factor,
+        shape: options.shape,
+      };
+  const lensRef = useLatest(lens);
+
+  // Told on a change in value, not on every render: a host drawing into this
+  // box would otherwise redraw for each one.
+  const onLensRef = useLatest(options.onLens);
+  const reportedRef = useRef<string>(JSON.stringify(null));
+  const report = useCallback(
+    (next: LoupeLens | null): void => {
+      const key = JSON.stringify(next);
+      if (key === reportedRef.current) return;
+      reportedRef.current = key;
+      onLensRef.current?.(next);
+    },
+    [onLensRef],
+  );
+  const shownLens = visible ? lens : null;
+  const shownKey = JSON.stringify(shownLens);
+  useEffect(() => {
+    report(JSON.parse(shownKey) as LoupeLens | null);
+  }, [shownKey, report]);
+  useEffect(() => () => report(null), [report]);
+  useEffect(() => {
+    if (!visible || !subscribeResample) return;
+    return subscribeResample(() => model.resample());
+  }, [visible, subscribeResample, model]);
+
   const inputRef = useRef<LoupeInputApi | null>(null);
   if (inputRef.current === null) {
     inputRef.current = {
@@ -148,6 +241,7 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
       setPeeking: (on) => {
         if (peekingRef.current === on) return;
         peekingRef.current = on;
+        if (on) aimAtPointer();
         bump();
       },
       magnifyBy: (deltaY) => {
@@ -158,14 +252,15 @@ export function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions)
   }
 
   return {
-    // This render's `enabled`: `enabledRef` holds the last committed one.
-    visible: lensShown(overRef.current, enabled, peekingRef.current),
+    visible,
     aim: model.aim,
     factor: model.factor,
+    lens,
     mode: model.mode,
     color: model.color,
     setMode: model.setMode,
     setFactor: model.setFactor,
+    resample: model.resample,
     pick: model.pick,
     input: inputRef.current,
   };

package/src/primitives/index.ts

@@ -1,3 +1,5 @@
+export type { StatusBarItemProps, StatusBarProps } from '@weasel-js/ui';
+export { StatusBar, StatusBarItem, StatusBarSpacer } from '@weasel-js/ui';
 export type { FloatingPanelProps } from './FloatingPanel';
 export { FloatingPanel } from './FloatingPanel';
 export { FpsMeter } from './FpsMeter';
@@ -11,8 +13,6 @@ export type { ScaleIndicatorProps } from './ScaleIndicator';
 export { ScaleIndicator } from './ScaleIndicator';
 export type { SplitProps } from './Split';
 export { Split } from './Split';
-export type { StatusBarProps, StatusBarSectionProps } from './StatusBar';
-export { StatusBar } from './StatusBar';
 export type { ToolbarButtonProps, ToolbarGroupProps, ToolbarProps } from './Toolbar';
 export { Toolbar } from './Toolbar';
 export type { ZoomControlProps } from './ZoomControl';

package/src/specimen/Specimen.tsx

@@ -72,7 +72,6 @@ import { JobProgress } from '../primitives/JobProgress';
 import { Legend, type LegendEntry } from '../primitives/Legend';
 import { ScaleIndicator } from '../primitives/ScaleIndicator';
 import { Split } from '../primitives/Split';
-import { StatusBar } from '../primitives/StatusBar';
 import { Toolbar } from '../primitives/Toolbar';
 import { ZoomControl } from '../primitives/ZoomControl';
 
@@ -831,12 +830,6 @@ function LabChrome() {
           </Toolbar.Group>
         </Toolbar>
       </Cell>
-      <Cell label="StatusBar">
-        <StatusBar>
-          <StatusBar.Section>Items: 12</StatusBar.Section>
-          <StatusBar.Section>Zoom: 100%</StatusBar.Section>
-        </StatusBar>
-      </Cell>
       <Cell label="Legend, JobProgress">
         <Legend entries={LEGEND} />
         <JobProgress job={JOB} />

package/src/state/helpers.test.ts

@@ -1,8 +1,8 @@
+import { createHistory } from '@weasel-js/core';
 import { describe, expect, it } from 'vitest';
 import {
   decodeUrlHash,
   deserializeTrials,
-  emptyUndoStack,
   encodeUrlHash,
   labStorageKey,
   newId,
@@ -29,12 +29,6 @@ describe('encodeUrlHash / decodeUrlHash', () => {
   });
 });
 
-describe('emptyUndoStack', () => {
-  it('returns an empty stack', () => {
-    expect(emptyUndoStack()).toEqual({ past: [], future: [] });
-  });
-});
-
 describe('serializeTrials', () => {
   it('returns records with the undo stack dropped', () => {
     const records = serializeTrials(
@@ -45,7 +39,7 @@ describe('serializeTrials', () => {
           config: { a: 1 },
           state: { b: 2 },
           view: { zoom: 1, pan: { x: 0, y: 0 } },
-          undoStack: { past: [{ b: 1 }], future: [] },
+          history: createHistory(null),
         },
       ],
       {},
@@ -70,7 +64,6 @@ describe('serializeTrials', () => {
           config: {},
           state: { n: 2 },
           view: { zoom: 1, pan: { x: 0, y: 0 } },
-          undoStack: { past: [], future: [] },
         },
       ],
       { Test: { serialize: (s) => ({ doubled: (s as { n: number }).n * 2 }) } },
@@ -80,7 +73,7 @@ describe('serializeTrials', () => {
 });
 
 describe('deserializeTrials', () => {
-  it('rebuilds records with an empty undo stack', () => {
+  it('rebuilds records with no undo history', () => {
     const out = deserializeTrials(
       [
         {
@@ -93,7 +86,7 @@ describe('deserializeTrials', () => {
       ],
       {},
     );
-    expect(out[0].undoStack).toEqual({ past: [], future: [] });
+    expect(out[0].history).toBeUndefined();
   });
 
   it('runs the instrument deserializer over the state', () => {

package/src/state/helpers.ts

@@ -1,4 +1,4 @@
-import type { InstrumentSerializers, SerializedTrial, TrialRecord, UndoStack } from './types';
+import type { InstrumentSerializers, SerializedTrial, TrialRecord } 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. */
@@ -41,11 +41,6 @@ export function newId(): string {
   return `lk-${Date.now().toString(36)}-${idCounter++}`;
 }
 
-/** A fresh, empty undo history. */
-export function emptyUndoStack(): UndoStack {
-  return { past: [], future: [] };
-}
-
 /** Serialize trials for storage, running each instrument's own serializer
  *  over its state. Undo history is deliberately dropped — it does not survive
  *  a reload. */
@@ -53,7 +48,7 @@ export function serializeTrials(
   trials: TrialRecord[],
   serializers: InstrumentSerializers,
 ): SerializedTrial[] {
-  return trials.map(({ undoStack: _undo, ...w }) => {
+  return trials.map(({ history: _history, ...w }) => {
     const s = serializers[w.instrumentName];
     return { ...w, state: s?.serialize ? s.serialize(w.state) : w.state };
   });
@@ -75,7 +70,6 @@ export function deserializeTrials(
     return {
       ...r,
       state: d?.deserialize ? d.deserialize(r.state, r.config) : r.state,
-      undoStack: emptyUndoStack(),
     };
   });
 }

package/src/state/index.ts

@@ -24,7 +24,6 @@ export {
 export {
   decodeUrlHash,
   deserializeTrials,
-  emptyUndoStack,
   encodeUrlHash,
   labStorageKey,
   serializeTrials,
@@ -50,7 +49,6 @@ export type {
   StorageChange,
   TrialRecord,
   TrialStateHandle,
-  UndoStack,
 } from './types';
 export type { UndockedPanel, UndockedPanels } from './undock';
 export { dockPanel, panelKey, undockPanel } from './undock';

package/src/state/openLabStore.test.ts

@@ -1,3 +1,4 @@
+import { createHistory } from '@weasel-js/core';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { Instrument } from '../instrument/types';
 import { createMemoryAdapter } from './adapters';
@@ -61,13 +62,13 @@ describe('openLabStore — round trips', () => {
     const backing = new Map<string, unknown>();
     const first = await open(backing);
     first.store.getState().addTrial(trial('w1', { state: { n: 7 } }));
-    first.store.getState().updateTrialUndoStack('w1', { past: [{ n: 6 }], future: [] });
+    first.store.getState().setTrialHistory('w1', createHistory(null));
     await first.close();
 
     const again = await open(backing);
     expect(again.store.getState().trials).toHaveLength(1);
     expect(again.store.getState().trials[0]).toMatchObject({ id: 'w1', state: { n: 7 } });
-    expect(again.store.getState().trials[0]?.undoStack).toEqual({ past: [], future: [] });
+    expect(again.store.getState().trials[0]?.history).toBeUndefined();
   });
 
   // An instrument holding a Map, a Set or anything else storage cannot keep
@@ -321,7 +322,7 @@ describe('openLabStore — what a change writes', () => {
     storeLab(backing, { trials: [trial('a')] });
     const { storage, set } = counting(backing);
     const opened = await openLabStore({ storageKey: 'test', storage });
-    opened.store.getState().updateTrialUndoStack('a', { past: [{}], future: [] });
+    opened.store.getState().setTrialHistory('a', createHistory(null));
     await opened.close();
     expect(set).not.toHaveBeenCalled();
   });
@@ -380,7 +381,7 @@ describe('openLabStore — trial order', () => {
     storeLab(backing, { trials: [trial('a'), trial('c')] });
     const opened = await open(backing);
     const [a, c] = opened.store.getState().trials as [TrialRecord, TrialRecord];
-    const b: TrialRecord = { ...trial('b'), undoStack: { past: [], future: [] } };
+    const b: TrialRecord = trial('b');
     opened.store.setState({ trials: [a, b, c] });
     await opened.close();
     const ids = (await open(backing)).store.getState().trials.map((t) => t.id);
@@ -409,8 +410,9 @@ describe('openLabStore — two tabs', () => {
     storeLab(backing, { trials: [trial('t1', { state: { n: 0 } }), trial('t2')] });
     const tabA = await open(backing);
     const tabB = await open(backing);
-    tabA.store.getState().updateTrialUndoStack('t1', { past: [{ n: -1 }], future: [] });
-    tabA.store.getState().updateTrialUndoStack('t2', { past: [{ n: -2 }], future: [] });
+    const kept = createHistory(null);
+    tabA.store.getState().setTrialHistory('t1', createHistory(null));
+    tabA.store.getState().setTrialHistory('t2', kept);
 
     tabB.store.getState().updateTrialState('t1', { n: 5 });
     await tabB.records.flush();
@@ -418,8 +420,8 @@ describe('openLabStore — two tabs', () => {
 
     const [t1, t2] = tabA.store.getState().trials;
     expect(t1?.state).toEqual({ n: 5 });
-    expect(t1?.undoStack).toEqual({ past: [], future: [] });
-    expect(t2?.undoStack).toEqual({ past: [{ n: -2 }], future: [] });
+    expect(t1?.history).toBeUndefined();
+    expect(t2?.history).toBe(kept);
   });
 
   it("applies another tab's delete, snapshot, layout and mode without writing them back", async () => {

package/src/state/openLabStore.ts

@@ -212,7 +212,7 @@ function persistedFieldsDiffer(a: TrialRecord, b: TrialRecord): boolean {
   const left = a as unknown as Record<string, unknown>;
   const right = b as unknown as Record<string, unknown>;
   for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) {
-    if (key !== 'undoStack' && !Object.is(left[key], right[key])) return true;
+    if (key !== 'history' && !Object.is(left[key], right[key])) return true;
   }
   return false;
 }

package/src/state/store.test.ts

@@ -29,7 +29,7 @@ describe('createLabStore — initial state', () => {
 });
 
 describe('addTrial', () => {
-  it('adds a trial with an empty undoStack', () => {
+  it('adds a trial with no undo history', () => {
     const s = makeStore();
     s.getState().addTrial({
       id: 'w1',
@@ -39,7 +39,7 @@ describe('addTrial', () => {
       view: { zoom: 1, pan: { x: 0, y: 0 } },
     });
     expect(s.getState().trials).toHaveLength(1);
-    expect(s.getState().trials[0]?.undoStack).toEqual({ past: [], future: [] });
+    expect(s.getState().trials[0]?.history).toBeUndefined();
   });
 });
 

package/src/state/store.ts

@@ -1,3 +1,4 @@
+import type { History } from '@weasel-js/core';
 import { createStore, type StoreApi } from 'zustand/vanilla';
 import { applyConfigWrite } from '../config/autoConfig';
 import { fillConfigDefaults } from '../config/path';
@@ -9,7 +10,7 @@ import {
 } from '../instrument/serializers';
 import type { InstrumentList } from '../instrument/types';
 import { emptyDocument } from './document';
-import { deserializeTrials, emptyUndoStack, newId } from './helpers';
+import { deserializeTrials, newId } from './helpers';
 import type {
   CreateLabStoreOptions,
   InstrumentHooks,
@@ -29,7 +30,7 @@ import {
 /** Every mutation a lab store supports: managing trials, saving and
  *  restoring snapshots, and setting the color mode. */
 export interface LabStoreActions {
-  addTrial: (record: Omit<TrialRecord, 'undoStack'>) => void;
+  addTrial: (record: Omit<TrialRecord, 'history'>) => void;
   removeTrial: (id: string) => void;
   updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
   /** Write one config value. `path` is dotted for a value nested under an
@@ -42,10 +43,10 @@ export interface LabStoreActions {
   /** Fold or unfold one of a trial's sections. */
   setTrialSectionCollapsed: (id: string, key: string, collapsed: boolean) => void;
   updateTrialAnnotations: (id: string, doc: unknown) => void;
-  updateTrialUndoStack: (
-    id: string,
-    next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack']),
-  ) => void;
+  /** Give a trial the undo history it made on its first snapshot. */
+  setTrialHistory: (id: string, history: History) => void;
+  /** Record where a trial's clock stands. */
+  updateTrialClock: (id: string, clock: { elapsed: number; rate: number }) => void;
   setTrialInstrument: (id: string, instrumentName: string) => void;
   saveSnapshot: (trialId: string, name: string) => void;
   loadSnapshot: (snapshotId: string, trialId: string) => void;
@@ -96,7 +97,7 @@ export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
 
     addTrial: (record) => {
       set((s) => ({
-        trials: [...s.trials, { ...record, undoStack: emptyUndoStack() }],
+        trials: [...s.trials, record],
       }));
     },
 
@@ -182,16 +183,14 @@ export function createLabStore(options: CreateLabStoreOptions = {}): LabStore {
       }));
     },
 
-    updateTrialUndoStack: (id, next) => {
+    updateTrialClock: (id, clock) => {
       set((s) => ({
-        trials: s.trials.map((w) => {
-          if (w.id !== id) return w;
-          const undoStack =
-            typeof next === 'function'
-              ? (next as (prev: TrialRecord['undoStack']) => TrialRecord['undoStack'])(w.undoStack)
-              : next;
-          return { ...w, undoStack };
-        }),
+        trials: s.trials.map((w) => (w.id === id ? { ...w, clock } : w)),
+      }));
+    },
+    setTrialHistory: (id, history) => {
+      set((s) => ({
+        trials: s.trials.map((w) => (w.id === id ? { ...w, history } : w)),
       }));
     },
 

package/src/state/types.ts

@@ -1,15 +1,9 @@
+import type { History } from '@weasel-js/core';
 import type { ColorModePreference } from '@weasel-js/theme';
 import type { Auto } from '../config/auto';
 import type { ConfigPath, ResolvedConfig, ValueAtPath } from '../config/types';
 import type { InstrumentList } from '../instrument/types';
 import type { UndockedPanels } from './undock';
-/** A trial's undo history, as snapshots of its state either side of the
- *  present. */
-export interface UndoStack {
-  past: unknown[];
-  future: unknown[];
-}
-
 /** The trial a per-trial call is coming from. `id` is the id `useTileId`
  *  scopes a surface tile under, so a consumer keying its own per-trial
  *  registry and labkit's tiles agree on the key. */
@@ -59,7 +53,13 @@ export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
    *  no `annotations` — or declares its own `storage`. Not in `state`, which
    *  belongs to the instrument and is typed as such. */
   annotations?: unknown;
-  undoStack: UndoStack;
+  /** This trial's undo history over `state`, made by the trial on its first
+   *  snapshot. Session-only: absent on a new, cloned, swapped or reloaded
+   *  trial, which is how each starts with an empty history. */
+  history?: History;
+  /** Where the trial's clock stood at its last rate or seek change, for a
+   *  trial whose instrument declares `clock`. */
+  clock?: { elapsed: number; rate: number };
 }
 
 /** A named, saved copy of a trial's config and state, restorable into any
@@ -190,7 +190,7 @@ export type InstrumentSerializers = Record<
 
 /** A trial as it is persisted: everything but the undo history, which is
  *  session-only. */
-export type SerializedTrial = Omit<TrialRecord, 'undoStack'>;
+export type SerializedTrial = Omit<TrialRecord, 'history'>;
 
 /** Everything a lab persists, under one key, at a known version. */
 export interface LabDocument {

package/src/styles.less

@@ -8,12 +8,12 @@
 @import (reference, less) '@weasel-js/theme/inherited.module.css';
 @import './theme/base.less';
 @import './lab/Workspace.less';
+@import './lightbox/Lightbox.less';
 @import './lab/LabShell.less';
 @import './lab/LabSwitcher.less';
 @import './primitives/Toolbar.less';
 @import './primitives/Split.less';
 @import './primitives/ZoomControl.less';
-@import './primitives/StatusBar.less';
 @import './primitives/JobProgress.less';
 @import './primitives/FpsMeter.less';
 @import './primitives/ScaleIndicator.less';
@@ -36,3 +36,4 @@
 @import './dragdrop/Palette.less';
 @import './dragdrop/DragGhost.less';
 @import './specimen/Specimen.less';
+@import './lab/presentation.less';

package/src/surface/AGENTS.md

@@ -58,6 +58,19 @@ was the only trial open.
 trial may register one, or none: a trial holding a drawn pane beside an undrawn
 one contributes a single rect, and a trial with nothing to draw contributes none.
 
+## An expanded tile
+
+A `<Lightbox>` lifts its tile into the browser's top layer, which takes it out
+from under the buffers. So the lab declares its two buffer layers with
+`<LightboxLayers>` (`src/lab/LabSurface.tsx`), and an open lightbox lifts the
+under layer, then itself, then the over layer — the same stacking as before,
+each covering the window. The over layer is the surface container, so the
+surface re-measures against the window and the buffers resize. The lightbox
+also calls `scope(el)`: tiles outside it leave `rects`, are not painted, and
+the retile clears them; `useTileInScope` tells a tenant's own chrome on the
+surface (the annotation input box) to hide. A host owning its own surface does
+the same for its buffers, or an expanded tile shows without them.
+
 ## Traps
 
 - **`preserveDrawingBuffer` is the consumer's job and is usually required.** A

package/src/surface/index.ts

@@ -9,6 +9,7 @@ export {
   useSurfaceOptional,
   useSurfaceTile,
   useTileId,
+  useTileInScope,
 } from './useSurfaceTile';
 export type {
   SurfaceClear,

package/src/surface/useSurfaceTile.test.tsx

@@ -9,11 +9,15 @@ function fakeHandle(): SurfaceHandle {
     invalidate: vi.fn(),
     invalidateAll: vi.fn(),
     invalidateRects: vi.fn(),
+    invalidateBox: vi.fn(),
     registerTile: vi.fn(),
     registerClear: vi.fn(() => () => {}),
     registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
     getContainer: vi.fn(() => null),
+    scope: vi.fn(),
+    inScope: vi.fn(() => true),
+    subscribeScope: vi.fn(() => () => {}),
   };
 }
 

package/src/surface/useSurfaceTile.ts

@@ -1,4 +1,4 @@
-import { useCallback, useContext } from 'react';
+import { useCallback, useContext, useSyncExternalStore } from 'react';
 import { TrialIdContext } from '../state/context';
 import { SurfaceCanvasContext, SurfaceContext, type SurfaceLayer } from './SurfaceContext';
 import type { SurfaceHandle } from './useTiledSurface';
@@ -55,3 +55,19 @@ export function useSurfaceTile(id: string): (el: HTMLElement | null) => void {
     [surface, tileId],
   );
 }
+
+const noSubscribe = (): (() => void) => () => {};
+
+/**
+ * Whether the tile registered under `tileId` — the key `useTileId` returns —
+ * is inside the surface's scope. A tenant with chrome of its own on the
+ * surface hides it while this is false, since nothing paints that tile then.
+ * True with no surface above.
+ */
+export function useTileInScope(tileId: string): boolean {
+  const surface = useSurfaceOptional();
+  return useSyncExternalStore(
+    surface?.subscribeScope ?? noSubscribe,
+    () => surface?.inScope(tileId) ?? true,
+  );
+}