@weasel-js/labkit 1.5.0 → 1.5.1

package/src/index.ts

@@ -1,7 +1,9 @@
-// The property-panel family, LayerStack, ToggleBar and Button live in
+// The property-panel family, LayerStack, Input, Select, TokenPanel, ToggleBar and Button live in
 // `@weasel-js/ui`; labkit re-exports them so chrome built on labkit needs no
 // direct ui dependency. Named, not `export *` — a star re-export of an external
 // package emits no binding in the bundle.
+// The playback glyphs ride along for the same reason: chrome that labels a control with
+// one should not need `@weasel-js/ui` in its manifest to draw a play button.
 export type {
   ButtonProps,
   ButtonSize,
@@ -13,6 +15,9 @@ export type {
   EffectCardListItem,
   EffectCardListProps,
   EffectCardProps,
+  IconProps,
+  InputProps,
+  JogProps,
   LayerStackItem,
   LayerStackProps,
   NumberRowProps,
@@ -25,6 +30,7 @@ export type {
   PropertyRowProps,
   PropertyRowVariant,
   PropertySpanProps,
+  SelectProps,
   SelectRowProps,
   SliderRowProps,
   SubpanelProps,
@@ -34,27 +40,45 @@ export type {
   ToggleBarSize,
   ToggleBarVariant,
   ToggleRowProps,
+  TokenCategory,
+  TokenEntry,
+  TokenPanelProps,
 } from '@weasel-js/ui';
 export {
   Button,
   CheckboxRow,
+  CloseIcon,
+  CollapseIcon,
   ColorRow,
   CurveField,
   EffectCard,
   EffectCardList,
+  ExpandIcon,
+  Icon,
+  Input,
+  inferTokenType,
+  Jog,
   LayerStack,
   NumberRow,
+  PauseIcon,
+  PlayIcon,
   PropertyGroup,
   PropertyList,
   PropertyPanel,
   PropertyRow,
   PropertySpan,
+  ResetIcon,
+  Select,
   SelectRow,
   SliderRow,
+  StepBackIcon,
+  StepForwardIcon,
+  StopIcon,
   Subpanel,
   TextRow,
   ToggleBar,
   ToggleRow,
+  TokenPanel,
 } from '@weasel-js/ui';
 export type {
   Annotation,
@@ -157,6 +181,8 @@ export {
   zoomAt,
 } from './canvas';
 export * from './chrome';
+export { type Auto, auto, isAuto } from './config/auto';
+export { autoPathsOf, resolveAutoConfig } from './config/autoConfig';
 export {
   BaseNode,
   BooleanNode,
@@ -205,6 +231,7 @@ export type {
   ValueAtPath,
 } from './config/types';
 export { useConfigSchema } from './config/useConfigSchema';
+export { useResolvedConfig } from './config/useResolvedConfig';
 export { isLeafVisible } from './config/visible';
 export { ControlPanel } from './controls/ControlPanel';
 export type {
@@ -246,6 +273,7 @@ export type { LayerListProps, LayerTreeNode } from './layers';
 export { LayerList } from './layers';
 export * from './loupe';
 export * from './primitives';
+export { SPECIMEN_SECTIONS, Specimen } from './specimen/Specimen';
 export {
   createIndexedDbAdapter,
   createMemoryAdapter,

package/src/instrument/serializers.ts

@@ -1,5 +1,33 @@
+import { resolveConfigSchema } from '../config/resolve';
+import type { ResolvedConfig } from '../config/types';
 import type { InstrumentSerializers } from '../state/types';
-import type { InstrumentList } from './types';
+import type { Instrument, InstrumentList } from './types';
+
+/**
+ * One instrument's config schema, resolved without the lab's rules — which
+ * neither the store nor a trial composed outside a lab has access to. No rule
+ * can reach `autoResolve`, `unpinned` or `manual`, so for reading those the
+ * two resolutions agree; anything reading the rendered leaves wants
+ * `useConfigSchema` instead. `undefined` for a legacy `configSchema()`
+ * instrument, which declares no auto annotations at all.
+ */
+export function unruledConfigSchema(
+  // biome-ignore lint/suspicious/noExplicitAny: instruments are stored contravariantly; see InstrumentList
+  instrument: Instrument<any, any, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
+): ResolvedConfig | undefined {
+  return instrument.config ? resolveConfigSchema(instrument.config, []) : undefined;
+}
+
+/** Each instrument's unruled config schema, keyed by name — what the store
+ *  reads a leaf's auto annotations off. */
+export function configSchemasOf(instruments: InstrumentList): Record<string, ResolvedConfig> {
+  const out: Record<string, ResolvedConfig> = {};
+  for (const instrument of instruments) {
+    const schema = unruledConfigSchema(instrument);
+    if (schema) out[instrument.name] = schema;
+  }
+  return out;
+}
 
 /**
  * Each instrument's default config, keyed by name — what `createLabStore`

package/src/lab/Lab.chrome.test.tsx

@@ -62,4 +62,20 @@ describe('<Lab> chrome', () => {
     render(<Lab title="T" instruments={[withChrome]} defaultInstrument="Bare" />);
     expect(screen.getByText('ready')).toBeInTheDocument();
   });
+
+  it('renders an aside contribution in its own pane, after the workspace', () => {
+    render(
+      <Lab
+        title="T"
+        instruments={[bare]}
+        defaultInstrument="Bare"
+        labChrome={[{ id: 'notes', region: 'aside', item: { title: 'Notes', body: <p>jot</p> } }]}
+      />,
+    );
+    const body = screen.getByText('jot');
+    const trial = screen.getByRole('region', { name: /trial/i });
+    expect(body.closest('.lk-lab__aside')).not.toBeNull();
+    expect(trial.compareDocumentPosition(body) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(screen.getByRole('separator', { name: /Lab aside/ })).toBeInTheDocument();
+  });
 });

package/src/lab/Lab.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { useEffect } from 'react';
 import type { Instrument } from '../instrument/types';
 import { Lab } from './Lab';

package/src/lab/Lab.surface.test.tsx

@@ -12,7 +12,12 @@ import type { ReactNode } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { SurfaceContext } from '../surface/SurfaceContext';
-import { useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId } from '../surface/useSurfaceTile';
+import {
+  useSurfaceCanvas,
+  useSurfaceOptional,
+  useSurfaceTile,
+  useTileId,
+} from '../surface/useSurfaceTile';
 import type { SurfaceFrame, SurfaceHandle } from '../surface/useTiledSurface';
 import { useTiledSurface } from '../surface/useTiledSurface';
 import { Lab } from './Lab';
@@ -203,7 +208,7 @@ describe('<Lab> tile round trip', () => {
 });
 
 describe('<Lab> pages', () => {
-  it('gives the title a way back to the project\'s other labs', () => {
+  it("gives the title a way back to the project's other labs", () => {
     const { getByRole } = render(
       <Lab
         instruments={[probeInstrument]}

package/src/lab/Lab.test.tsx

@@ -1,4 +1,4 @@
-import { act, render, screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { type ReactNode, useEffect } from 'react';
 import { describe, expect, it } from 'vitest';
 import type { Instrument } from '../instrument/types';
@@ -238,3 +238,81 @@ describe('instruments that change while mounted', () => {
     expect(mounts).toBe(1);
   });
 });
+
+describe('focused trial', () => {
+  const regions = () => screen.getAllByRole('region', { name: /trial/i });
+  const framed: Instrument = {
+    ...stub,
+    name: 'Framed',
+    render: () => <iframe title="story frame" />,
+  };
+
+  it('is the only trial until another opens, then the one that opened', () => {
+    mountLab();
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[0]?.id);
+    act(() => labRef?.addTrial('StubB'));
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[1]?.id);
+    act(() => labRef?.cloneTrial(labRef?.trials[0]?.id ?? ''));
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[1]?.id);
+    expect(labRef?.trials.map((t) => t.instrumentName)).toEqual(['Stub', 'Stub', 'StubB']);
+  });
+
+  it('moves to a trial a pointer goes down in', () => {
+    mountLab();
+    act(() => labRef?.addTrial('StubB'));
+    fireEvent.pointerDown(within(regions()[0] as HTMLElement).getByTestId('stub-content'));
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[0]?.id);
+  });
+
+  it('moves to a trial focus moves into', () => {
+    mountLab();
+    act(() => labRef?.addTrial('StubB'));
+    act(() => (regions()[0] as HTMLElement).focus());
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[0]?.id);
+  });
+
+  it('moves to a trial whose frame takes focus, which fires nothing in the lab’s document', async () => {
+    mountLab({ instruments: [framed, stubB], defaultInstrument: 'Framed' });
+    act(() => labRef?.addTrial('StubB'));
+    act(() => screen.getByTitle('story frame').focus());
+    fireEvent.blur(window);
+    await waitFor(() => expect(labRef?.focusedTrialId).toBe(labRef?.trials[0]?.id));
+  });
+
+  it('falls back to the first trial when the focused one closes', () => {
+    mountLab();
+    act(() => labRef?.addTrial('StubB'));
+    act(() => labRef?.closeTrial(labRef?.trials[1]?.id ?? ''));
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[0]?.id);
+  });
+
+  it('is marked on its trial only when there is more than one', () => {
+    mountLab();
+    expect(regions()[0]).not.toHaveAttribute('data-focused');
+    act(() => labRef?.addTrial('StubB'));
+    expect(regions()[1]).toHaveAttribute('data-focused', 'true');
+    expect(regions()[0]).not.toHaveAttribute('data-focused');
+  });
+});
+
+describe('swapTrial', () => {
+  it('runs another instrument in the trial’s place, and keeps focus on that place', () => {
+    mountLab();
+    act(() => labRef?.addTrial('Stub'));
+    const second = labRef?.trials[1]?.id;
+    act(() => labRef?.focusTrial(labRef?.trials[0]?.id ?? ''));
+    act(() => labRef?.swapTrial(labRef?.trials[0]?.id ?? '', 'StubB'));
+    expect(labRef?.trials.map((t) => t.instrumentName)).toEqual(['StubB', 'Stub']);
+    expect(labRef?.trials[1]?.id).toBe(second);
+    expect(labRef?.focusedTrialId).toBe(labRef?.trials[0]?.id);
+    expect(screen.getByTestId('stub-b-content')).toBeInTheDocument();
+  });
+
+  it('leaves focus where it was when the swapped trial did not have it', () => {
+    mountLab();
+    act(() => labRef?.addTrial('Stub'));
+    const focused = labRef?.focusedTrialId;
+    act(() => labRef?.swapTrial(labRef?.trials[0]?.id ?? '', 'StubB'));
+    expect(labRef?.focusedTrialId).toBe(focused);
+  });
+});

package/src/lab/Lab.tsx

@@ -13,6 +13,7 @@ import { useStore } from 'zustand/react';
 import { AnnotationPreloadContext } from '../annotations/preload';
 import { ANNOTATION_TOOLS } from '../annotations/toolMap';
 import {
+  LabAsideRegion,
   LabFooterRegion,
   LabHeaderRegion,
   LabSidebarRegion,
@@ -44,6 +45,7 @@ import {
   closeTrial as closeTrialOp,
   reorderTrials as reorderTrialsOp,
   resetTrial as resetTrialOp,
+  swapTrial as swapTrialOp,
 } from '../trial/trialOps';
 import { useLabFitWarning } from './fitCheck';
 import { LabContext, type LabContextValue } from './LabContext';
@@ -178,7 +180,7 @@ function LabFallback({
 }: Pick<LabBaseProps, 'title' | 'mode' | 'pages' | 'path'>) {
   const resolvedMode = useResolvedMode(mode ?? 'auto');
   return (
-    <ThemeProvider theme={interstellarTheme} mode={resolvedMode} className="lk-lab">
+    <ThemeProvider theme={interstellarTheme} selection={{ mode: resolvedMode }} className="lk-lab">
       <LabShell
         title={title ?? 'Labkit'}
         mode={mode}
@@ -228,6 +230,32 @@ function LabPanes({
     undefined,
     { scope: 'lab' },
   );
+  const [asideWidth, setAsideWidth] = usePersistedState<number | undefined>(
+    'lk-lab-aside-width',
+    undefined,
+    { scope: 'lab' },
+  );
+  const main = contributions.some((c) => c.region === 'aside') ? (
+    <Split
+      className="lk-lab__panes"
+      side="end"
+      sidebarClassName="lk-lab__aside"
+      contentClassName="lk-lab__main"
+      label="Lab aside"
+      defaultWidth={320}
+      width={asideWidth}
+      onWidthChange={(w) => {
+        setAsideWidth(w);
+        surface?.invalidateRects();
+      }}
+      sidebar={<LabAsideRegion contributions={contributions} />}
+    >
+      {children}
+    </Split>
+  ) : (
+    children
+  );
+  if (!contributions.some((c) => c.region === 'sidebar')) return main;
   return (
     <Split
       className="lk-lab__panes"
@@ -242,7 +270,7 @@ function LabPanes({
       }}
       sidebar={<LabSidebarRegion contributions={contributions} />}
     >
-      {children}
+      {main}
     </Split>
   );
 }
@@ -259,9 +287,8 @@ export function Lab(props: LabProps) {
     storageKey === undefined ? openUnstoredLab(props) : openStoredLab(props, storageKey, storage),
   );
   if (!opened) {
-    return props.fallback !== undefined ? (
-      <>{props.fallback}</>
-    ) : (
+    if (props.fallback !== undefined) return props.fallback;
+    return (
       <LabFallback title={props.title} mode={props.mode} pages={props.pages} path={props.path} />
     );
   }
@@ -295,6 +322,10 @@ function LabRuntime({
   }, [instruments, store]);
 
   const trials = useStore(store, (s) => s.trials);
+  const [focusPick, setFocusPick] = useState<string | null>(null);
+  const focusedTrialId = trials.some((t) => t.id === focusPick)
+    ? focusPick
+    : (trials[0]?.id ?? null);
   const savedSnapshots = useStore(store, (s) => s.savedSnapshots);
   const modeValue = useStore(store, (s) => s.mode);
   const layout = useStore(store, (s) => s.layout);
@@ -359,6 +390,39 @@ function LabRuntime({
     [outerSurface, attachOwnSurface],
   );
   useLabFitWarning(labBody);
+
+  useEffect(() => {
+    if (!labBody) return;
+    const pick = (node: unknown): void => {
+      const owned = new Set(store.getState().trials.map((t) => t.id));
+      const nearest = (from: Element | null | undefined) =>
+        from?.closest<HTMLElement>('.lk-trial[data-trial-id]') ?? null;
+      let trial =
+        typeof (node as Element | null)?.closest === 'function' ? nearest(node as Element) : null;
+      // A trial can hold a lab of its own, whose trials this lab does not own.
+      while (trial && !owned.has(trial.dataset.trialId ?? '')) trial = nearest(trial.parentElement);
+      if (trial?.dataset.trialId) setFocusPick(trial.dataset.trialId);
+    };
+    const onInput = (event: Event): void => pick(event.target);
+    // Focus moving into a frame fires nothing in this document: the window
+    // blurs, and the frame is the active element once it has.
+    let pending: ReturnType<typeof setTimeout> | undefined;
+    const doc = labBody.ownerDocument;
+    const win = doc.defaultView;
+    const onBlur = (): void => {
+      clearTimeout(pending);
+      pending = setTimeout(() => pick(doc.activeElement), 0);
+    };
+    labBody.addEventListener('pointerdown', onInput, true);
+    labBody.addEventListener('focusin', onInput, true);
+    win?.addEventListener('blur', onBlur);
+    return () => {
+      clearTimeout(pending);
+      labBody.removeEventListener('pointerdown', onInput, true);
+      labBody.removeEventListener('focusin', onInput, true);
+      win?.removeEventListener('blur', onBlur);
+    };
+  }, [labBody, store]);
   const surface = outerSurface ?? ownSurface;
   const surfaceCanvases = useMemo(
     () =>
@@ -388,7 +452,7 @@ function LabRuntime({
     [annotates, tools, labChrome],
   );
   const hasFooterChrome = labChromeAll.some((c) => c.region === 'footer');
-  const hasSidebarChrome = labChromeAll.some((c) => c.region === 'sidebar');
+  const hasPaneChrome = labChromeAll.some((c) => c.region === 'sidebar' || c.region === 'aside');
 
   useEffect(() => {
     if (mode && mode !== store.getState().mode) {
@@ -402,17 +466,23 @@ function LabRuntime({
       const merged = next.map((w) => currentById.get(w.id) ?? w);
       store.setState({ trials: merged });
     };
+    const replaceAndFocusAdded = (next: TrialRecord[]): void => {
+      const before = new Set(store.getState().trials.map((w) => w.id));
+      replaceTrials(next);
+      const added = next.find((w) => !before.has(w.id));
+      if (added) setFocusPick(added.id);
+    };
 
     return {
       instruments,
       trials,
       addTrial: (instrumentName, options) => {
-        const next = addTrialOp(store.getState().trials, instruments, instrumentName, options);
-        replaceTrials(next);
+        replaceAndFocusAdded(
+          addTrialOp(store.getState().trials, instruments, instrumentName, options),
+        );
       },
       cloneTrial: (id) => {
-        const next = cloneTrialOp(store.getState().trials, id);
-        replaceTrials(next);
+        replaceAndFocusAdded(cloneTrialOp(store.getState().trials, id));
       },
       closeTrial: (id) => {
         const next = closeTrialOp(store.getState().trials, id);
@@ -421,6 +491,19 @@ function LabRuntime({
       reorderTrials: (ids) => {
         replaceTrials(reorderTrialsOp(store.getState().trials, ids));
       },
+      swapTrial: (id, instrumentName, options) => {
+        const current = store.getState();
+        const next = swapTrialOp(current.trials, instruments, id, instrumentName, options);
+        if (next === current.trials) return;
+        const record = next[current.trials.findIndex((w) => w.id === id)] as TrialRecord;
+        // Written before the tile registers, which is when the grid reads it.
+        const { [id]: extent, ...layoutRest } = current.layout as TrialLayout;
+        if (extent) current.setLayout({ ...layoutRest, [record.id]: extent });
+        replaceTrials(next);
+        if (focusedTrialId === id) setFocusPick(record.id);
+      },
+      focusedTrialId,
+      focusTrial: (id) => setFocusPick(id),
       resetTrial: (id) => {
         const next = resetTrialOp(store.getState().trials, id, instruments);
         const record = next.find((w) => w.id === id);
@@ -451,7 +534,16 @@ function LabRuntime({
       configRules,
       controls,
     };
-  }, [instruments, trials, savedSnapshots, modeValue, store, configRules, controls]);
+  }, [
+    instruments,
+    trials,
+    focusedTrialId,
+    savedSnapshots,
+    modeValue,
+    store,
+    configRules,
+    controls,
+  ]);
 
   // Only override the backdrop in dark, where there is one to override.
   // Setting a CSS custom property is the sanctioned use of inline style.
@@ -483,7 +575,7 @@ function LabRuntime({
           <LabContext.Provider value={contextValue}>
             <ThemeProvider
               theme={interstellarTheme}
-              mode={resolvedMode}
+              selection={{ mode: resolvedMode }}
               className="lk-lab"
               style={backdropStyle}
             >
@@ -537,7 +629,7 @@ function LabRuntime({
                             />
                           </>
                         )}
-                        {hasSidebarChrome ? (
+                        {hasPaneChrome ? (
                           <LabPanes contributions={labChromeAll}>
                             <LabPalette contributions={labChromeAll} />
                             {workspace}

package/src/lab/LabContext.ts

@@ -18,6 +18,14 @@ export interface LabContextValue {
   closeTrial: (id: string) => void;
   resetTrial: (id: string) => void;
   reorderTrials: (ids: readonly string[]) => void;
+  /** Put a fresh trial running `instrumentName` in trial `id`'s place, at its
+   *  size. The replacement has a new id, and takes the focus if `id` had it. */
+  swapTrial: (id: string, instrumentName: string, options?: AddTrialOptions) => void;
+  /** The trial last pointed at or focused, counting focus that moved into a
+   *  frame inside it. A trial `addTrial` or `cloneTrial` opens takes it. Falls
+   *  back to the first trial; null only when there are none. */
+  focusedTrialId: string | null;
+  focusTrial: (id: string) => void;
   savedSnapshots: SavedSnapshot[];
   saveSnapshot: (trialId: string, name?: string) => void;
   loadSnapshot: (trialId: string, snapshotId: string) => void;

package/src/lab/LabFit.stories.tsx

@@ -1,7 +1,7 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { expect, userEvent, waitFor, within } from '@weasel-js/forge/play';
 import { type ReactNode, useLayoutEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { expect, userEvent, waitFor, within } from 'storybook/test';
 import type { LabContribution } from '../chrome/labTypes';
 import type { TrialContribution } from '../chrome/types';
 import type { Instrument } from '../instrument/types';
@@ -9,7 +9,7 @@ import { Lab } from './Lab';
 import './LabFit.stories.less';
 
 // A lab must fit whatever it is mounted in without scrolling. jsdom cannot see
-// layout, so these run in the storybook vitest project's real browser.
+// layout, so these run in the forge-stories vitest project's real browser.
 
 const Stub: Instrument = {
   name: 'Stub',
@@ -43,7 +43,7 @@ const VIEWPORTS = {
 
 type Host = 'reset' | 'wrapped' | 'framed';
 
-// Storybook wraps every story in divs of its own, so a fixture that needs a
+// The frame wraps every story in divs of its own, so a fixture that needs a
 // known ancestor chain builds that chain directly on <body> and portals into it.
 function BodyHost({ host, children }: { host: Host; children: ReactNode }) {
   const [mount, setMount] = useState<HTMLElement | null>(null);

package/src/lab/LabFullChrome.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { useEffect, useRef } from 'react';
 import type { ConfigField } from '../controls/types';
 import { defineInstrument } from '../instrument/defineInstrument';

package/src/lab/LabHeader.tsx

@@ -48,7 +48,6 @@ export function LabHeader({ addTrial = true }: { addTrial?: boolean }) {
       <ToggleBar
         className="lk-lab-header__mode"
         ariaLabel="Color mode"
-        size="sm"
         variant="flat"
         items={MODE_ITEMS}
         value={lab.mode}

package/src/lab/LabRoot.test.tsx

@@ -0,0 +1,56 @@
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '@weasel-js/theme/react';
+import { describe, expect, test } from 'vitest';
+import { interstellarTheme } from '../theme/interstellar';
+import { LabRoot } from './LabRoot';
+
+describe('LabRoot', () => {
+  test('applies lk-root to a labkit piece mounted on its own', () => {
+    const { container } = render(
+      <LabRoot>
+        <div>bare</div>
+      </LabRoot>,
+    );
+    expect(container.querySelector('.lk-root')).not.toBeNull();
+    expect(screen.getByText('bare')).toBeInTheDocument();
+  });
+
+  test('marks lk-root as the portal host for overlays', () => {
+    const { container } = render(<LabRoot>x</LabRoot>);
+    expect(container.querySelector('.lk-root')?.hasAttribute('data-wzl-portal-host')).toBe(true);
+  });
+
+  test('appends className after lk-root on the same element', () => {
+    const { container } = render(<LabRoot className="lk-shell">x</LabRoot>);
+    const root = container.querySelector('.lk-root') as HTMLElement;
+    expect(root.className).toBe('lk-root lk-shell');
+  });
+
+  test('stamps the requested mode under the interstellar theme', () => {
+    const { container } = render(<LabRoot mode="light">x</LabRoot>);
+    const root = container.firstChild as HTMLElement;
+    expect(root.getAttribute('data-wzl-theme')).toBe('interstellar');
+    expect(root.getAttribute('data-wzl-mode')).toBe('light');
+  });
+
+  test('resolves mode="auto" to a concrete mode', () => {
+    const { container } = render(<LabRoot>x</LabRoot>);
+    const root = container.firstChild as HTMLElement;
+    expect(root.getAttribute('data-wzl-mode')).toMatch(/^(light|dark)$/);
+  });
+
+  // The app's theme wins, and no second provider is mounted over it. This
+  // only holds while labkit resolves `@weasel-js/theme` to the same copy the
+  // app does — it is the in-repo half of the peer-externalization the smoke
+  // test's dist audit enforces for a published install.
+  test('defers to a theme the app already applied', () => {
+    const { container } = render(
+      <ThemeProvider theme={interstellarTheme} selection={{ mode: 'dark' }}>
+        <LabRoot mode="light">x</LabRoot>
+      </ThemeProvider>,
+    );
+    const root = container.querySelector('.lk-root') as HTMLElement;
+    expect(root.getAttribute('data-wzl-mode')).toBeNull();
+    expect(container.querySelectorAll('[data-wzl-theme]')).toHaveLength(1);
+  });
+});

package/src/lab/LabRoot.tsx

@@ -0,0 +1,47 @@
+import { ThemeProvider, useThemeOptional } from '@weasel-js/theme/react';
+import type { ReactNode } from 'react';
+import type { LabMode } from '../state/types';
+import { interstellarTheme } from '../theme/interstellar';
+import { useResolvedMode } from './useSystemMode';
+
+/** Props for `<LabRoot>`. */
+export interface LabRootProps {
+  children: ReactNode;
+  /** Color mode. "auto" (default) follows prefers-color-scheme. */
+  mode?: LabMode;
+  /** Added after `lk-root` on the same element. */
+  className?: string;
+}
+
+/** The element every labkit component expects above it: `.lk-root`, which
+ *  carries the design tokens, the font stack, the box-sizing reset and the
+ *  element defaults a lab's bare markup is styled by, plus a theme when the
+ *  app has not already applied one.
+ *
+ *  `<LabShell>` and `<Lab>` render this themselves. Mount it by hand around a
+ *  labkit piece used on its own — a bare `<Workspace>` or `<ControlPanel>` —
+ *  or those components inherit whatever the host page happens to define.
+ *  Pair it with `import '@weasel-js/labkit/styles.css'`, which is what defines
+ *  the rules this element scopes. */
+export function LabRoot({ children, mode = 'auto', className }: LabRootProps) {
+  const resolved = useResolvedMode(mode);
+  const outer = useThemeOptional();
+
+  // Overlays portal here rather than to the themed wrapper above: `.lk-root`
+  // carries the element defaults a lab's bare markup is styled by.
+  const root = (
+    <div className={className ? `lk-root ${className}` : 'lk-root'} data-wzl-portal-host="">
+      {children}
+    </div>
+  );
+
+  // Inside <Lab> the theme is already applied on `.lk-lab`; wrapping again
+  // would only add a div.
+  return outer ? (
+    root
+  ) : (
+    <ThemeProvider theme={interstellarTheme} selection={{ mode: resolved }}>
+      {root}
+    </ThemeProvider>
+  );
+}