@weasel-js/labkit 1.7.3 → 1.8.1

package/dist/index.d.ts

@@ -1,17 +1,17 @@
-export { Button, ButtonProps, ButtonSize, ButtonVariant, CloseIcon, CollapseIcon, CurveField, CurveFieldProps, CurveMark, DetailList, DetailListLayout, DetailListProps, DetailListValues, DetailRow, DetailRowProps, DetailRowStatus, ExpandIcon, Icon, IconProps, Input, InputProps, Jog, JogProps, LayerList, LayerListItem, LayerListProps, LayerMove, PauseIcon, PlayIcon, PropertyControl, PropertyControlProps, PropertyField, PropertyFieldProps, PropertyGroup, PropertyGroupProps, PropertyList, PropertyListPack, PropertyListProps, PropertyOption, PropertyPanel, PropertyPanelProps, PropertyRow, PropertyRowLayout, PropertyRowProps, PropertyRowVariant, PropertySpan, PropertySpanProps, ResetIcon, Select, SelectProps, StepBackIcon, StepForwardIcon, StopIcon, Subpanel, SubpanelProps, ToggleBar, ToggleBarItem, ToggleBarProps, ToggleBarSize, ToggleBarVariant, TokenCategory, TokenEntry, TokenPanel, TokenPanelProps, TokenScale, TokenScaleRule, inferTokenType, moveLayers, refitScale } from '@weasel-js/ui';
+export { Button, ButtonProps, ButtonSize, ButtonVariant, CloseIcon, CollapseIcon, CurveField, CurveFieldProps, CurveMark, DetailList, DetailListLayout, DetailListProps, DetailListValues, DetailRow, DetailRowProps, DetailRowStatus, ExpandIcon, Icon, IconProps, Input, InputProps, Jog, JogProps, LayerList, LayerListItem, LayerListProps, LayerMove, PauseIcon, PlayIcon, PropertyControl, PropertyControlProps, PropertyField, PropertyFieldProps, PropertyGroup, PropertyGroupProps, PropertyList, PropertyListPack, PropertyListProps, PropertyOption, PropertyPanel, PropertyPanelProps, PropertyRow, PropertyRowLayout, PropertyRowProps, PropertyRowVariant, PropertySpan, PropertySpanProps, ResetIcon, Select, SelectProps, StatusBar, StatusBarItem, StatusBarItemProps, StatusBarProps, StatusBarSpacer, StepBackIcon, StepForwardIcon, StopIcon, Subpanel, SubpanelProps, ToggleBar, ToggleBarItem, ToggleBarProps, ToggleBarSize, ToggleBarVariant, TokenCategory, TokenEntry, TokenPanel, TokenPanelProps, TokenScale, TokenScaleRule, inferTokenType, moveLayers, refitScale } from '@weasel-js/ui';
 import { SceneNode, View, DrawCommand, BuiltinToolId } from '@weasel-js/core';
-import { A as AnnotationMeaning, t as AnnotationData, v as WorldRect, w as MarkStyle, x as MarkScene, y as CaptureSource, z as CaptureOptions, B as CaptureResult, E as PaintableMark, F as AnnotationTarget, G as AnnotationsApi, H as AnnotationsCapability, J as TrialInfo, K as TrialTool, N as AnnotationKind, a as ViewTransform, O as Instrument, q as InstrumentList, o as LabMode, Q as LabDensity, R as TrialContribution, c as StorageAdapter, T as TrialRecord } from './_dts/index-DCMA4Fy1.js';
-export { X as Annotation, Y as AnnotationInit, Z as AnnotationPatch, _ as AnnotationQuery, $ as AnnotationSelectionMode, a0 as AnnotationStatus, a1 as AnnotationStoreOptions, a2 as AnnotationTargetInfo, a3 as AnnotationToolId, a4 as Auto, a5 as CanvasCapability, a6 as CanvasLayer, a7 as CaptureDeps, a8 as ContributionBase, C as CreateLabStoreOptions, D as DEFAULT_FRAME, n as DragDropCapability, m as DragFeedback, a9 as FracPoint, aa as FracRect, ab as HitResult, ac as IconComponent, L as LabDocument, d as LabStoreState, ad as LayerCapability, ae as LayerDescriptor, l as PaletteItem, P as Point, af as RegionContribution, ag as RenderContext, e as SavedSnapshot, ah as SerializedAnnotations, S as SerializedTrial, ai as SidebarSection, aj as SidebarSlotContext, ak as StageCapability, al as StatusReadout, f as StorageChange, am as SystemEvent, an as ToolCapability, ao as ToolItem, ap as ToolSlotContext, aq as ToolbarItem, ar as TrialChromeContext, as as TrialRegion, g as TrialStateHandle, at as UndoCapability, U as UndoStack, h as UndockedPanel, i as UndockedPanels, au as ViewportControl, V as ViewportSize, W as WorldFrame, b as WorldSpec, av as annotationsFromJSON, k as applyCamera, aw as auto, ax as createAnnotationScene, ay as createAnnotationStore, j as dockPanel, az as fracContains, aA as fracEncloses, aB as fracToWorld, aC as isAuto, aD as markCommands, p as panelKey, r as resolveFrame, aE as roundFrac, u as undockPanel, aF as worldToFrac } from './_dts/index-DCMA4Fy1.js';
+import { A as AnnotationMeaning, s as AnnotationData, t as WorldRect, v as MarkStyle, w as MarkScene, x as CaptureSource, y as CaptureOptions, z as CaptureResult, B as PaintableMark, E as AnnotationTarget, F as AnnotationsApi, G as AnnotationsCapability, H as TrialInfo, J as TrialTool, K as AnnotationKind, a as ViewTransform, N as TrialClock, O as Instrument, o as InstrumentList, n as LabMode, Q as LabDensity, R as TrialContribution, T as TrialRecord, c as StorageAdapter } from './_dts/index-8geQNQet.js';
+export { X as Annotation, Y as AnnotationInit, Z as AnnotationPatch, _ as AnnotationQuery, $ as AnnotationSelectionMode, a0 as AnnotationStatus, a1 as AnnotationStoreOptions, a2 as AnnotationTargetInfo, a3 as AnnotationToolId, a4 as Auto, a5 as CanvasCapability, a6 as CanvasLayer, a7 as CaptureDeps, a8 as ClockCapability, a9 as ContributionBase, C as CreateLabStoreOptions, D as DEFAULT_FRAME, m as DragDropCapability, l as DragFeedback, aa as FracPoint, ab as FracRect, ac as HitResult, ad as IconComponent, L as LabDocument, d as LabStoreState, ae as LayerCapability, af as LayerDescriptor, k as PaletteItem, P as Point, ag as RegionContribution, ah as RenderContext, e as SavedSnapshot, ai as SerializedAnnotations, S as SerializedTrial, aj as SidebarSection, ak as SidebarSlotContext, al as StageCapability, am as StatusReadout, f as StorageChange, an as SystemEvent, ao as ToolCapability, ap as ToolItem, aq as ToolSlotContext, ar as ToolbarItem, as as TrialChromeContext, at as TrialRegion, g as TrialStateHandle, au as UndoCapability, U as UndockedPanel, h as UndockedPanels, av as ViewportControl, V as ViewportSize, W as WorldFrame, b as WorldSpec, aw as annotationsFromJSON, j as applyCamera, ax as auto, ay as createAnnotationScene, az as createAnnotationStore, i as dockPanel, aA as fracContains, aB as fracEncloses, aC as fracToWorld, aD as isAuto, aE as markCommands, p as panelKey, r as resolveFrame, aF as roundFrac, u as undockPanel, aG as worldToFrac } from './_dts/index-8geQNQet.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { SvgNode } from '@weasel-js/svg';
-export { C as CameraContext, a as CameraContextValue, b as CameraInput, d as CameraPublishContext, e as CameraRegistry, f as CameraRegistryContext, g as CameraScope, h as CameraView, j as CanvasStack, k as CanvasStackProps, l as Stage, m as StageProps, Z as ZoomAtOptions, n as ZoomRange, o as centerOn, p as createCameraRegistry, q as fitStage, s as screenToWorld, r as usePublishCamera, w as worldToScreen, z as zoomAt } from './_dts/Stage-D6t7o0pF.js';
-export { C as CanvasLayerDescriptor, a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from './_dts/CanvasStackContext-Cjy6I-Iv.js';
-import { L as LabContribution } from './_dts/index-BTmaRy6a.js';
-export { A as AddTrialOptions, a as LabAsideRegion, b as LabChromeContext, c as LabContext, d as LabContextValue, e as LabFooterRegion, f as LabHeaderRegion, g as LabRegion, h as LabRegionProps, i as LabSidebarRegion, P as PaletteRegion, j as PaletteRegionProps, S as SidebarRegion, k as SidebarRegionProps, l as StatusRegion, m as StatusRegionProps, T as TRANSIENT_BUILTINS, n as TitleBarPlacement, o as TitleBarRegion, p as TitleBarRegionProps, q as ToolbarRegion, r as ToolbarRegionProps, V as ViewportRegion, s as ViewportRegionProps, t as addTrial, u as builtinContributions, v as cloneTrial, w as closeTrial, x as contributionsIn, y as labContributions, z as mergeContributions, B as reorderTrials, C as resetTrial, D as suppressContributions, E as toolContributions, F as useLabChromeContext, G as useLabContext } from './_dts/index-BTmaRy6a.js';
+export { C as CameraContext, a as CameraContextValue, b as CameraInput, d as CameraPublishContext, e as CameraRegistry, f as CameraRegistryContext, g as CameraScope, h as CameraView, j as CanvasStack, k as CanvasStackProps, l as Stage, m as StageProps, Z as ZoomAtOptions, n as ZoomRange, o as centerOn, p as createCameraRegistry, q as fitStage, s as screenToWorld, r as usePublishCamera, w as worldToScreen, z as zoomAt } from './_dts/Stage-CIJlbjrE.js';
+export { C as CanvasLayerDescriptor, a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from './_dts/CanvasStackContext-B05ZM04l.js';
+import { L as LabContribution } from './_dts/index-DRi3V5sN.js';
+export { A as AddTrialOptions, a as LabAsideRegion, b as LabChromeContext, c as LabContext, d as LabContextValue, e as LabFooterRegion, f as LabHeaderRegion, g as LabRegion, h as LabRegionProps, i as LabSidebarRegion, P as PaletteRegion, j as PaletteRegionProps, S as SidebarRegion, k as SidebarRegionProps, l as StatusRegion, m as StatusRegionProps, T as TRANSIENT_BUILTINS, n as TitleBarPlacement, o as TitleBarRegion, p as TitleBarRegionProps, q as ToolbarRegion, r as ToolbarRegionProps, V as ViewportRegion, s as ViewportRegionProps, t as addTrial, u as builtinContributions, v as cloneTrial, w as closeTrial, x as contributionsIn, y as labContributions, z as mergeContributions, B as reorderTrials, C as resetTrial, D as suppressContributions, E as toolContributions, F as useLabChromeContext, G as useLabContext } from './_dts/index-DRi3V5sN.js';
 export { BaseNode, BooleanNode, ColorNode, CustomNode, EnumNode, GroupNode, ListNode, NumberNode, SectionTree, StringNode, ValueNode, applyRules, autoPathsOf, builtinRules, f, fillConfigDefaults, fromConfigFields, hasConfigPath, isConfigBranch, isLeafVisible, resolveAutoConfig, resolveConfigSchema, schemaNodeAtPath, sectionTree, titleCase, useConfigSchema, useResolvedConfig, valueAtPath, withValueAtPath } from './config/index.js';
-import { C as ConfigSchema, a as ConfigField, b as ConfigRule, c as ControlRenderer } from './_dts/types-BUBSIZuV.js';
-export { A as Annotations, B as BranchAnnotations, d as BranchOptions, e as CheckboxField, f as ColorField, g as ConfigBranch, h as ConfigEntry, i as ConfigFieldBase, j as ConfigFieldType, k as ConfigNode, l as ConfigOf, m as ConfigOption, n as ConfigPath, o as ConfigRuleContext, p as ConfigShape, D as DialogSpec, E as EntryValue, I as InDialogOptions, q as InferConfig, L as LeafPatch, N as NodeOptions, r as NodeValue, s as NumberField, R as ResolvedConfig, S as SectionOption, t as SectionSpec, u as SelectField, v as SelectOption, w as SliderField, T as TextField, V as ValueAtPath } from './_dts/types-BUBSIZuV.js';
+import { C as ConfigSchema, a as ConfigField, b as ConfigRule, c as ControlRenderer } from './_dts/types-DUfQ0isU.js';
+export { A as Annotations, B as BranchAnnotations, d as BranchOptions, e as CheckboxField, f as ColorField, g as ConfigBranch, h as ConfigEntry, i as ConfigFieldBase, j as ConfigFieldType, k as ConfigNode, l as ConfigOf, m as ConfigOption, n as ConfigPath, o as ConfigRuleContext, p as ConfigShape, D as DialogSpec, E as EntryValue, I as InDialogOptions, q as InferConfig, L as LeafPatch, N as NodeOptions, r as NodeValue, s as NumberField, R as ResolvedConfig, S as SectionOption, t as SectionSpec, u as SelectField, v as SelectOption, w as SliderField, T as TextField, V as ValueAtPath } from './_dts/types-DUfQ0isU.js';
 export { ControlMatrix, ControlMatrixColumn, ControlMatrixProps, ControlMatrixRow, ControlPanel, inDialog, summarizeValue } from './controls/index.js';
 import { J as JobHandle } from './_dts/types-DJ79Tg5J.js';
 export { a as JobCapability, b as JobEvent, c as JobFailure, d as JobStatus } from './_dts/types-DJ79Tg5J.js';
@@ -19,10 +19,10 @@ export { UseJobOptions, useJob } from './job/index.js';
 import { Theme, ColorList } from '@weasel-js/theme';
 export { a as FloatingPanel, F as FloatingPanelProps } from './_dts/FloatingPanel-7j0IcXwz.js';
 import { SplitProps } from './primitives/index.js';
-export { FpsMeter, JobProgress, JobProgressProps, Legend, LegendEntry, LegendMark, LegendProps, Readout, ReadoutProps, ReadoutRow, ScaleIndicator, ScaleIndicatorProps, Split, StatusBar, StatusBarProps, StatusBarSectionProps, Toolbar, ToolbarButtonProps, ToolbarGroupProps, ToolbarProps, ZoomControl, ZoomControlProps } from './primitives/index.js';
-export { C as CURRENT_DOCUMENT_VERSION, I as IndexedDbAdapterOptions, b as LabStoreContext, c as LabStoreProvider, O as OpenLabStoreOptions, d as OpenedLabStore, P as PersistedStateOptions, e as Persistence, f as PersistenceProps, R as RecordCache, g as RecordChange, T as TrialIdContext, h as TrialIdProvider, i as createIndexedDbAdapter, k as createMemoryAdapter, l as indexedDbAdapter, m as labDocumentKey, n as localStorageAdapter, o as noneAdapter, p as openLabStore, q as quarantineKey, s as sessionStorageAdapter, u as urlHashAdapter, r as useLabStore, t as usePersistedState, v as useTrialId, w as useTrialState } from './_dts/useTrialState-Bh8bzFgE.js';
-export { Box, Rect, SurfaceCanvasContext, SurfaceCanvases, SurfaceClear, SurfaceContext, SurfaceFrame, SurfaceHandle, SurfaceLayer, TilePainter, UseTiledSurfaceOptions, composeRects, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTiledSurface } from './surface/index.js';
-export { EventBus, EventListener, clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo/index.js';
+export { FpsMeter, JobProgress, JobProgressProps, Legend, LegendEntry, LegendMark, LegendProps, Readout, ReadoutProps, ReadoutRow, ScaleIndicator, ScaleIndicatorProps, Split, Toolbar, ToolbarButtonProps, ToolbarGroupProps, ToolbarProps, ZoomControl, ZoomControlProps } from './primitives/index.js';
+export { C as CURRENT_DOCUMENT_VERSION, I as IndexedDbAdapterOptions, b as LabStoreContext, c as LabStoreProvider, O as OpenLabStoreOptions, d as OpenedLabStore, P as PersistedStateOptions, e as Persistence, f as PersistenceProps, R as RecordCache, g as RecordChange, T as TrialIdContext, h as TrialIdProvider, i as createIndexedDbAdapter, k as createMemoryAdapter, l as indexedDbAdapter, m as labDocumentKey, n as localStorageAdapter, o as noneAdapter, p as openLabStore, q as quarantineKey, s as sessionStorageAdapter, u as urlHashAdapter, r as useLabStore, t as usePersistedState, v as useTrialId, w as useTrialState } from './_dts/useTrialState-Ar0AFpCe.js';
+export { Box, Rect, SurfaceCanvasContext, SurfaceCanvases, SurfaceClear, SurfaceContext, SurfaceFrame, SurfaceHandle, SurfaceLayer, TilePainter, UseTiledSurfaceOptions, composeRects, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTileInScope, useTiledSurface } from './surface/index.js';
+export { EventBus, EventListener, UndoStack, clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo/index.js';
 import '@weasel-js/geom';
 import '@weasel-js/quantity';
 import 'windease';
@@ -243,6 +243,20 @@ declare function fromWeaselView(v: View): ViewTransform;
  */
 declare function fitView(content: ContentSize, pane: PaneSize): ViewTransform;
 
+/**
+ * A trial's clock: `trialId`'s, else the one of the trial this renders inside,
+ * else the lab's focused trial's. `null` when that trial declares no clock.
+ * Re-renders on rate, seek and loop changes, never per frame — read `elapsed`
+ * per frame through {@link useClockFrame}.
+ */
+declare function useTrialClock(trialId?: string): TrialClock | null;
+/**
+ * Run `fn` after each frame the clock of the trial this renders inside moves,
+ * with its `elapsed` and `pass`, outside React's render — for a renderer that
+ * draws imperatively, or text that changes every frame written into a ref.
+ */
+declare function useClockFrame(fn: (elapsed: number, pass: number) => void): void;
+
 /** An instrument as it is written: either the legacy `defaultConfig` (plus an
  *  optional `configSchema`), or a `config` schema that supplies both. */
 type InstrumentSpec<TS, TC, TItem = unknown> = Instrument<TS, TC, TItem> | (Omit<Instrument<TS, TC, TItem>, 'defaultConfig'> & {
@@ -321,6 +335,17 @@ declare function currentPage(path: string, pages: readonly LabPage[]): number;
  *  bench -- and a tab strip is the layout that stops working first. */
 declare function LabSwitcher({ title, pages, path, className }: LabSwitcherProps): react.JSX.Element;
 
+/** The trial a presented lab opens on. `config` is overlaid on the
+ *  instrument's defaults the way `addTrial`'s is, so Reset returns to it;
+ *  `state` and `view` replace what that config would give. */
+interface PresentationSeed<TC = Record<string, unknown>, TS = unknown, TV = unknown> {
+    /** Default: the lab's `defaultInstrument`. */
+    instrument?: string;
+    config?: Partial<TC>;
+    state?: TS;
+    view?: TV;
+}
+
 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
@@ -365,6 +390,10 @@ interface LabBaseProps {
     labChrome?: readonly LabContribution[];
     /** Built-in contribution ids to drop. Throws on an id that is not there. */
     suppress?: readonly string[];
+    /** Whether a double-click on a trial also opens it in its lightbox, beside
+     *  the title bar's expand toggle every trial has. Off by default; a
+     *  function decides per trial, by its record. */
+    expandOnDoubleClick?: boolean | ((trial: TrialRecord) => boolean);
     /** Offer the header's add-trial control. Default `true`; a lab that opens
      *  trials some other way passes `false`. */
     addTrial?: boolean;
@@ -382,6 +411,15 @@ interface LabBaseProps {
      *  Keys are config paths (checked first) or leaf kinds. Memoize or hoist. */
     controls?: Record<string, ControlRenderer>;
     children?: ReactNode;
+    /** Start presenting: one trial, opened on `seed`, without the lab's chrome or
+     *  its own. `?present` in the page's URL does the same. Read once, at mount.
+     *  A stored lab presents from its own records, under `storageKey` +
+     *  `':present'`, so an embed never shows or changes the full lab's trials. */
+    present?: boolean;
+    /** The trial a lab that starts presenting opens on. A store that already
+     *  holds a trial opened on this same seed keeps it; a changed seed replaces
+     *  it. Ignored unless the lab starts presenting. */
+    seed?: PresentationSeed;
 }
 /** Props for `<Lab>`. With a `storageKey` the lab persists — to IndexedDB
  *  unless `storage` names another substrate — and both are read once, at
@@ -479,6 +517,16 @@ declare function LabShell({ title, children, header, footer, mode, pages, path,
  */
 declare function LabZoom(): react.JSX.Element;
 
+/** A lab's presentation mode: one trial, without the lab's chrome or its own. */
+interface Presentation {
+    active: boolean;
+    /** Present the focused trial. Escape returns to the workspace. */
+    enter(): void;
+    exit(): void;
+}
+/** The presentation mode of the `<Lab>` around the caller. */
+declare function usePresentation(): Presentation;
+
 /** 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. */
 type TrialLayout = Record<string, {
@@ -523,6 +571,19 @@ interface WorkspaceProps {
      *  floating zone above it. The body is portaled in by the trial that owns
      *  it, so all this renders is the frame and the host. */
     panels?: readonly PanelDescriptor[];
+    /**
+     * Whether a tile can open in a `<Lightbox>` — shown large over the page from
+     * the expand button in its corner — without being remounted. On by default;
+     * `false` turns it off for every tile, and a function decides per tile id.
+     */
+    lightbox?: boolean | ((id: string) => boolean);
+    /**
+     * Whether a double-click on a tile's content also opens its lightbox. Off by
+     * default, since most content has its own use for a double-click; give it
+     * to a tile whose content has none, such as an image, with a function of
+     * the tile id.
+     */
+    expandOnDoubleClick?: boolean | ((id: string) => boolean);
     /**
      * 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
@@ -554,7 +615,88 @@ interface PanelDescriptor {
  * the trial that owns it, which is what keeps a torn-out section inside its
  * trial's React tree instead of rebuilding it as a sibling.
  */
-declare function Workspace({ children, ids, panels, resizable, reorderable, onReorder, layout, onLayoutChange, gap, padding, viewport, }: WorkspaceProps): react.JSX.Element;
+declare function Workspace({ children, ids, panels, resizable, reorderable, onReorder, layout, onLayoutChange, gap, padding, viewport, lightbox, expandOnDoubleClick, }: WorkspaceProps): react.JSX.Element;
+
+/** Props for `<Lightbox>`. */
+interface LightboxProps {
+    children: ReactNode;
+    /** Names the expanded view for assistive tech. */
+    label?: string;
+    /** Turns the lightbox off: no expand button, no double-click, and an open
+     *  one closes. The content stays mounted either way. */
+    disabled?: boolean;
+    /** Let a double-click on the content open it, and another close it. Off by
+     *  default — the expand button is always there; a double-click is for
+     *  content that has no other use for one, such as an image. */
+    expandOnDoubleClick?: boolean;
+    /** Controlled open state. Omit to let the lightbox keep its own. */
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    /** Extra class on the outer element. */
+    className?: string;
+}
+/**
+ * Shows its content large, over a dimmed page, from the expand button in its
+ * corner — or a double-click, where `expandOnDoubleClick` asks for one —
+ * without remounting it. The same element is lifted into the browser's top
+ * layer (`popover="manual"`), so a WebGL context or a scene inside keeps
+ * running and sees only a bigger box: anything sizing itself from a
+ * `ResizeObserver` follows on its own. The top layer also escapes an
+ * ancestor's transform, clipping, and stacking.
+ *
+ * Layers declared by a `<LightboxLayers>` above are lifted around it, and a
+ * labkit surface above is scoped to it while it is open, so pixels drawn for
+ * the content from outside it come along.
+ *
+ * Escape, a click on the dimmed margin, the close button, or another
+ * double-click where those open it closes it, and focus returns to wherever it
+ * was. A double-click on a control, inside `[data-lk-lightbox-ignore]`, or one
+ * a handler further in called `preventDefault()` on does not open it.
+ */
+declare function Lightbox({ children, label, disabled, expandOnDoubleClick, expanded: expandedProp, onExpandedChange, className, }: LightboxProps): react.JSX.Element;
+
+/** What a `<Lightbox>` offers the content inside it. */
+interface LightboxApi {
+    /** Whether the content is showing in the lightbox right now. */
+    expanded: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+/** The nearest `<Lightbox>`, or `null` outside one. Reading it changes
+ *  nothing; see `useLightboxControl` to replace the default expand button. */
+declare function useLightbox(): LightboxApi | null;
+/**
+ * The nearest `<Lightbox>`, for a component that draws its own expand
+ * control: while a caller is mounted, the lightbox hides its default corner
+ * button so the tile does not offer two. `<Trial>` uses this to put the
+ * control in its title bar.
+ */
+declare function useLightboxControl(): LightboxApi | null;
+
+/** Elements a lightbox lifts with it, in top-layer order around itself. A
+ *  null entry is skipped, so a ref that has not landed yet can be passed as
+ *  it is. */
+interface LightboxLayerSet {
+    below: readonly (HTMLElement | null)[];
+    above: readonly (HTMLElement | null)[];
+}
+/** Props for `<LightboxLayers>`. Keep the arrays stable across renders. */
+interface LightboxLayersProps extends Partial<LightboxLayerSet> {
+    children: ReactNode;
+}
+/**
+ * Declares layers that belong to every lightbox below it: something drawn
+ * for the content from outside it, such as a shared buffer the tiles paint
+ * into. An open lightbox lifts each `below` layer, then itself, then each
+ * `above` layer into the top layer, each covering the window, so they keep
+ * stacking as they did. A layer is measured against the window while lifted,
+ * so whatever positions things inside it must re-measure — a labkit surface
+ * whose container is one of the layers does.
+ */
+declare function LightboxLayers({ below, above, children }: LightboxLayersProps): react.JSX.Element;
+/** The layers declared above, or none. */
+declare function useLightboxLayers(): LightboxLayerSet;
 
 /** The specimen's sections, in page order. */
 declare const SPECIMEN_SECTIONS: readonly ["Buttons & toggles", "Fields & pickers", "Panels & property rows", "Overlays & feedback", "Lists & data", "Tool chrome", "Editors & plots", "Lab chrome"];
@@ -665,5 +807,5 @@ interface TrialChromeProps {
  *  each region its slice. */
 declare function TrialChrome({ trialId, record, instrument, isLastTrial, undoBindings, job, loupe, trialChrome, chrome, suppress, activeToolId, setActiveTool, children, }: TrialChromeProps): react.JSX.Element;
 
-export { ANNOTATION_TOOLS, ANNOTATION_WEASEL_TOOLS, AnnotationData, AnnotationKind, AnnotationMeaning, AnnotationOverlay, AnnotationTarget, AnnotationTargets, AnnotationsApi, AnnotationsCapability, AnnotationsContext, CaptureOptions, CaptureResult, CaptureSource, ConfigField, ConfigRule, ConfigSchema, ControlRenderer, DEFAULT_VIEW, ExportMenu, Instrument, InstrumentList, JobHandle, Lab, LabBoundary, LabContribution, LabDensity, LabMode, LabPalette, LabRoot, LabShell, LabSwitcher, LabZoom, LoupeSwitchContext, MarkList, MarkScene, MarkStyle, PaintableMark, SPECIMEN_SECTIONS, Specimen, SplitProps, StorageAdapter, Trial, TrialBody, TrialChrome, TrialContribution, TrialInfo, TrialRecord, TrialTool, ViewTransform, Workspace, WorldRect, annotationToolInfo, as2DView, capturePlan, captureTarget, composeCaptureSvg, createMarkDrawOne, currentPage, defineInstrument, fitView, fromWeaselView, interstellarTheme, isStale, markSvgNodes, resolveMarkStyle, seenFrom, toWeaselView, useAnnotations, useAnnotationsOptional, validateConfigSchema };
-export type { AnnotationOverlayProps, AnnotationTargetsProps, AnnotationToolInfo, CaptureArgs, CapturePlan, ComposeSvgArgs, ContentSize, InstrumentSpec, LabBoundaryProps, LabPage, LabPaletteProps, LabProps, LabRootProps, LabShellProps, LabSwitcherProps, LoupeSwitch, MarkDrawOptions, MarkListProps, PaneSize, PanelDescriptor, TrialBodyProps, TrialChromeProps, TrialLayout, TrialProps, UndoBindings, ValidationResult, ViewTransform2D, WorkspaceProps };
+export { ANNOTATION_TOOLS, ANNOTATION_WEASEL_TOOLS, AnnotationData, AnnotationKind, AnnotationMeaning, AnnotationOverlay, AnnotationTarget, AnnotationTargets, AnnotationsApi, AnnotationsCapability, AnnotationsContext, CaptureOptions, CaptureResult, CaptureSource, ConfigField, ConfigRule, ConfigSchema, ControlRenderer, DEFAULT_VIEW, ExportMenu, Instrument, InstrumentList, JobHandle, Lab, LabBoundary, LabContribution, LabDensity, LabMode, LabPalette, LabRoot, LabShell, LabSwitcher, LabZoom, Lightbox, LightboxLayers, LoupeSwitchContext, MarkList, MarkScene, MarkStyle, PaintableMark, SPECIMEN_SECTIONS, Specimen, SplitProps, StorageAdapter, Trial, TrialBody, TrialChrome, TrialClock, TrialContribution, TrialInfo, TrialRecord, TrialTool, ViewTransform, Workspace, WorldRect, annotationToolInfo, as2DView, capturePlan, captureTarget, composeCaptureSvg, createMarkDrawOne, currentPage, defineInstrument, fitView, fromWeaselView, interstellarTheme, isStale, markSvgNodes, resolveMarkStyle, seenFrom, toWeaselView, useAnnotations, useAnnotationsOptional, useClockFrame, useLightbox, useLightboxControl, useLightboxLayers, usePresentation, useTrialClock, validateConfigSchema };
+export type { AnnotationOverlayProps, AnnotationTargetsProps, AnnotationToolInfo, CaptureArgs, CapturePlan, ComposeSvgArgs, ContentSize, InstrumentSpec, LabBoundaryProps, LabPage, LabPaletteProps, LabProps, LabRootProps, LabShellProps, LabSwitcherProps, LightboxApi, LightboxLayerSet, LightboxLayersProps, LightboxProps, LoupeSwitch, MarkDrawOptions, MarkListProps, PaneSize, PanelDescriptor, Presentation, PresentationSeed, TrialBodyProps, TrialChromeProps, TrialLayout, TrialProps, UndoBindings, ValidationResult, ViewTransform2D, WorkspaceProps };