@weasel-js/labkit 1.4.4 → 1.5.1

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.less

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

package/src/lab/LabFit.stories.tsx

@@ -0,0 +1,219 @@
+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 type { LabContribution } from '../chrome/labTypes';
+import type { TrialContribution } from '../chrome/types';
+import type { Instrument } from '../instrument/types';
+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 forge-stories vitest project's real browser.
+
+const Stub: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div>stub</div>,
+};
+
+const floater: TrialContribution = {
+  id: 'floater',
+  region: 'sidebar',
+  item: { title: 'Floater', undockAs: 'floating', body: <p>floating panel</p> },
+};
+
+const sidebarTree: LabContribution = {
+  id: 'tree',
+  region: 'sidebar',
+  item: {
+    title: 'Stories',
+    body: Array.from({ length: 40 }, (_, i) => `Story ${i + 1}`).map((name) => (
+      <p key={name}>{name}</p>
+    )),
+  },
+};
+
+const VIEWPORTS = {
+  wide: { name: '1280x800', styles: { width: '1280px', height: '800px' } },
+  medium: { name: '800x600', styles: { width: '800px', height: '600px' } },
+  narrow: { name: '400x700', styles: { width: '400px', height: '700px' } },
+};
+
+type Host = 'reset' | 'wrapped' | 'framed';
+
+// 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);
+  useLayoutEffect(() => {
+    const outer = document.createElement('div');
+    outer.className = `lk-fit-host lk-fit-host--${host}`;
+    let target = outer;
+    if (host === 'wrapped') {
+      target = document.createElement('div');
+      outer.appendChild(target);
+    }
+    if (host === 'framed') {
+      // apps/site's shape: page content above a fixed-height frame.
+      const heading = document.createElement('div');
+      heading.className = 'lk-fit-heading';
+      target = document.createElement('div');
+      target.className = 'lk-fit-frame';
+      outer.append(heading, target);
+    }
+    document.body.appendChild(outer);
+    setMount(target);
+    return () => outer.remove();
+  }, [host]);
+  return mount ? createPortal(children, mount) : null;
+}
+
+type Fixture = 'fullscreen' | 'floating' | 'wrapped' | 'framed' | 'sidebar';
+
+const HOST: Record<Fixture, Host> = {
+  fullscreen: 'reset',
+  sidebar: 'reset',
+  floating: 'reset',
+  wrapped: 'wrapped',
+  framed: 'framed',
+};
+
+function scrolls(el: Element): string[] {
+  const out: string[] = [];
+  if (el.scrollHeight > el.clientHeight)
+    out.push(`scrollHeight ${el.scrollHeight} > ${el.clientHeight}`);
+  if (el.scrollWidth > el.clientWidth)
+    out.push(`scrollWidth ${el.scrollWidth} > ${el.clientWidth}`);
+  return out;
+}
+
+function fitProblems(fixture: Fixture, viewport: keyof typeof VIEWPORTS): string[] {
+  const problems: string[] = [];
+  const want = VIEWPORTS[viewport].styles;
+  const got = `${window.innerWidth}px x ${window.innerHeight}px`;
+  if (got !== `${want.width} x ${want.height}`) problems.push(`viewport is ${got}`);
+
+  // A box that spills out of the lab is overflow even where the page has room
+  // to absorb it, which is how a 100vh shell hid inside an embedded lab.
+  const labBox = document.querySelector('.lk-lab')?.getBoundingClientRect();
+  const shellBox = document.querySelector('.lk-shell')?.getBoundingClientRect();
+  if (!labBox || !shellBox) return [...problems, 'no .lk-lab or .lk-shell'];
+  if (shellBox.bottom > labBox.bottom + 1 || shellBox.right > labBox.right + 1) {
+    problems.push(
+      `.lk-shell ${shellBox.bottom}/${shellBox.right} spills out of .lk-lab ${labBox.bottom}/${labBox.right}`,
+    );
+  }
+
+  const doc = document.scrollingElement ?? document.documentElement;
+  for (const p of scrolls(doc)) problems.push(`document: ${p}`);
+
+  const body = document.querySelector('.lk-shell-body');
+  if (!body) return ['no .lk-shell-body'];
+  for (const p of scrolls(body)) problems.push(`.lk-shell-body: ${p}`);
+
+  const tiles = [...document.querySelectorAll('.lk-trial-tile')];
+  if (tiles.length === 0) problems.push('no .lk-trial-tile');
+  tiles.forEach((t, i) => {
+    const h = t.getBoundingClientRect().height;
+    if (!(h > 0)) problems.push(`tile ${i}: height ${h}`);
+  });
+
+  if (fixture === 'framed') {
+    const frame = document.querySelector('.lk-fit-frame');
+    const lab = document.querySelector('.lk-lab');
+    const f = frame?.getBoundingClientRect();
+    const l = lab?.getBoundingClientRect();
+    if (!f || !l) return [...problems, 'no frame or lab'];
+    if (Math.abs(l.height - f.height) > 1)
+      problems.push(`lab height ${l.height} != frame ${f.height}`);
+  }
+
+  if (fixture === 'floating') {
+    const panel = document.querySelector('.lk-panel-tile--floating')?.getBoundingClientRect();
+    const host = document.querySelector('.lk-workspace-host')?.getBoundingClientRect();
+    if (!panel || !host) return [...problems, 'no floating panel or workspace host'];
+    if (panel.top < host.top || panel.right > host.right + 1) {
+      problems.push(
+        `floating panel ${panel.top},${panel.right} outside workspace ${host.top},${host.right}`,
+      );
+    }
+  }
+
+  if (fixture === 'sidebar') {
+    const side = document.querySelector('.lk-lab__sidebar')?.getBoundingClientRect();
+    // The host wraps the grid only once a panel is undocked.
+    const work = document
+      .querySelector('.lk-lab__main > .lk-workspace-host, .lk-lab__main > .lk-workspace')
+      ?.getBoundingClientRect();
+    if (!side) return [...problems, 'no .lk-lab__sidebar'];
+    if (!work) return [...problems, 'no workspace in .lk-lab__main'];
+    if (!(side.width > 0)) problems.push(`lab sidebar width ${side.width}`);
+    if (!(work.width > 0)) problems.push(`workspace width ${work.width}`);
+    if (work.left < side.right - 1) {
+      problems.push(`workspace left ${work.left} overlaps sidebar right ${side.right}`);
+    }
+  }
+  return problems;
+}
+
+function fit(fixture: Fixture, viewport: keyof typeof VIEWPORTS): Story {
+  return {
+    globals: { viewport: { value: viewport, isRotated: false } },
+    render: () => (
+      <BodyHost host={HOST[fixture]}>
+        <Lab
+          title={`Fit: ${fixture}`}
+          instruments={[Stub]}
+          defaultInstrument="Stub"
+          chrome={fixture === 'floating' ? [floater] : undefined}
+          labChrome={fixture === 'sidebar' ? [sidebarTree] : undefined}
+        />
+      </BodyHost>
+    ),
+    play: async () => {
+      if (fixture === 'floating') {
+        const undock = await within(document.body).findByRole('button', { name: 'Undock Floater' });
+        await userEvent.click(undock);
+      }
+      await waitFor(
+        () => {
+          const problems = fitProblems(fixture, viewport);
+          if (problems.length > 0) throw new Error(problems.join('; '));
+        },
+        { timeout: 2000 },
+      );
+      await expect(fitProblems(fixture, viewport)).toEqual([]);
+    },
+  };
+}
+
+const meta: Meta<typeof Lab> = {
+  title: 'labkit/Lab/Fit',
+  component: Lab,
+  parameters: { layout: 'fullscreen', viewport: { options: VIEWPORTS } },
+};
+export default meta;
+
+type Story = StoryObj<typeof Lab>;
+
+export const FullscreenWide = fit('fullscreen', 'wide');
+export const FullscreenMedium = fit('fullscreen', 'medium');
+export const FullscreenNarrow = fit('fullscreen', 'narrow');
+
+export const FloatingPanelWide = fit('floating', 'wide');
+export const FloatingPanelMedium = fit('floating', 'medium');
+export const FloatingPanelNarrow = fit('floating', 'narrow');
+
+export const WrappedNoResetWide = fit('wrapped', 'wide');
+export const WrappedNoResetMedium = fit('wrapped', 'medium');
+export const WrappedNoResetNarrow = fit('wrapped', 'narrow');
+
+export const FramedWide = fit('framed', 'wide');
+export const FramedMedium = fit('framed', 'medium');
+export const FramedNarrow = fit('framed', 'narrow');
+
+export const SidebarWide = fit('sidebar', 'wide');
+export const SidebarMedium = fit('sidebar', 'medium');
+export const SidebarNarrow = fit('sidebar', 'narrow');

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';
@@ -268,7 +268,6 @@ export const AllChrome: Story = {
     instruments: [spectrometer, beamProfile, thermalDrift],
     defaultInstrument: 'Spectrometer',
     title: 'Optics bench',
-    storage: null,
     mode: 'dark',
     nebula: ['#3b5bdb', '#7048e8', '#0ca678'],
     children: (
@@ -309,7 +308,6 @@ export const SingleInstrument: Story = {
     instruments: [runLog],
     defaultInstrument: 'Run log',
     title: 'Run log',
-    storage: null,
   },
 };
 
@@ -321,7 +319,6 @@ export const WithFooter: Story = {
     instruments: [spectrometer, beamProfile],
     defaultInstrument: 'Spectrometer',
     title: 'With footer',
-    storage: null,
     mode: 'dark',
     footer: <span className="lk-run-tag">Footer — reached through LabProps.footer</span>,
   },

package/src/lab/LabHeader.test.tsx

@@ -13,28 +13,59 @@ const Other: Instrument = { ...Stub, name: 'Other' };
 
 describe('<LabHeader>', () => {
   it('offers an add-trial button when the lab has one instrument', () => {
-    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" />);
     expect(screen.getByRole('button', { name: /add trial/i })).toBeInTheDocument();
   });
 
-  it('offers a picker instead when the lab has several', () => {
-    render(<Lab instruments={[Stub, Other]} defaultInstrument="Stub" storage={null} />);
-    // A picker, not a button — which instrument to add is now a choice.
-    expect(screen.queryByRole('button', { name: /^add trial$/i })).toBeNull();
-    expect(screen.getByLabelText(/add trial/i)).toBeInTheDocument();
+  it('offers a menu instead when the lab has several', () => {
+    render(<Lab instruments={[Stub, Other]} defaultInstrument="Stub" />);
+    // Which instrument to add is now a choice, so the button opens a list.
+    expect(screen.getByRole('button', { name: 'Add trial' })).toHaveAttribute('aria-haspopup');
+  });
+
+  it('adds a trial of the instrument chosen from the menu', async () => {
+    const { default: userEvent } = await import('@testing-library/user-event');
+    const user = userEvent.setup();
+    render(<Lab instruments={[Stub, Other]} defaultInstrument="Stub" />);
+    expect(screen.queryAllByLabelText(/^Trial Other$/)).toHaveLength(0);
+    await user.click(screen.getByRole('button', { name: 'Add trial' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Other' }));
+    expect(screen.getAllByLabelText(/^Trial Other$/)).toHaveLength(1);
+  });
+
+  it('lists each instrument by its title where it has one', async () => {
+    const { default: userEvent } = await import('@testing-library/user-event');
+    const user = userEvent.setup();
+    const titled: Instrument = { ...Other, title: 'Other / Titled' };
+    render(<Lab instruments={[Stub, titled]} defaultInstrument="Stub" />);
+    await user.click(screen.getByRole('button', { name: 'Add trial' }));
+    expect(screen.getByRole('menuitem', { name: 'Stub' })).toBeInTheDocument();
+    await user.click(screen.getByRole('menuitem', { name: 'Other / Titled' }));
+    expect(screen.getAllByLabelText(/^Trial Other \/ Titled$/)).toHaveLength(1);
   });
 
   it('adds a trial when the button is used', async () => {
     const { default: userEvent } = await import('@testing-library/user-event');
     const user = userEvent.setup();
-    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" />);
     expect(screen.getAllByLabelText(/^Trial Stub$/)).toHaveLength(1);
     await user.click(screen.getByRole('button', { name: /add trial/i }));
     expect(screen.getAllByLabelText(/^Trial Stub$/)).toHaveLength(2);
   });
 
+  it('leaves the add-trial control out when the lab says so', () => {
+    const { unmount } = render(
+      <Lab instruments={[Stub, Other]} defaultInstrument="Stub" addTrial={false} />,
+    );
+    expect(screen.queryByRole('button', { name: /add trial/i })).toBeNull();
+    expect(screen.getByRole('radio', { name: 'Auto' })).toBeInTheDocument();
+    unmount();
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" addTrial={false} />);
+    expect(screen.queryByRole('button', { name: /add trial/i })).toBeNull();
+  });
+
   it('exposes the color mode as a three-way choice', () => {
-    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" />);
     for (const label of ['Auto', 'Light', 'Dark']) {
       expect(screen.getByRole('radio', { name: label })).toBeInTheDocument();
     }
@@ -44,7 +75,7 @@ describe('<LabHeader>', () => {
     // The assertion above passes whether the segment holds text or an icon,
     // because both routes produce the same accessible name. This is the one
     // that can tell them apart.
-    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" />);
     for (const label of ['Auto', 'Light', 'Dark']) {
       const segment = screen.getByRole('radio', { name: label });
       expect(segment.querySelector('svg')).not.toBeNull();

package/src/lab/LabHeader.tsx

@@ -1,5 +1,5 @@
 import { AddIcon, ModeAutoIcon, ModeDarkIcon, ModeLightIcon } from '@weasel-js/ui';
-import { Select, ToggleBar } from '../passthrough/weasel-ui';
+import { MenuButton, ToggleBar } from '../passthrough/weasel-ui';
 import type { LabMode } from '../state/types';
 import { useLabContext } from './LabContext';
 
@@ -21,13 +21,13 @@ const MODE_ITEMS = MODES.map(({ value, label, glyph }) => ({
  *  mode. Both drive `LabContext`, which carried them with no UI at all — so
  *  every consumer rebuilt these two. Rendered before a consumer's own header
  *  content, which still lands beside them. */
-export function LabHeader() {
+export function LabHeader({ addTrial = true }: { addTrial?: boolean }) {
   const lab = useLabContext();
   const only = lab.instruments.length === 1 ? lab.instruments[0] : null;
 
   return (
     <>
-      {only ? (
+      {!addTrial ? null : only ? (
         <button
           type="button"
           className="lk-lab-header__add"
@@ -37,24 +37,17 @@ export function LabHeader() {
           <span>Add trial</span>
         </button>
       ) : (
-        // Held at null so the control stays an "add one" action rather than
-        // reading as the current instrument.
-        <Select
-          className="lk-lab-header__add-select"
+        <MenuButton
           aria-label="Add trial"
-          placeholder="Add trial…"
-          selectedKey={null}
-          options={lab.instruments.map((i) => ({ value: i.name, label: i.name }))}
-          onSelectionChange={(name) => {
-            if (name != null) lab.addTrial(String(name));
-          }}
+          label="Add trial…"
+          items={lab.instruments.map((i) => ({ value: i.name, label: i.title ?? i.name }))}
+          onAction={(name) => lab.addTrial(name)}
         />
       )}
 
       <ToggleBar
         className="lk-lab-header__mode"
         ariaLabel="Color mode"
-        size="sm"
         variant="flat"
         items={MODE_ITEMS}
         value={lab.mode}

package/src/lab/LabPalette.tsx

@@ -1,34 +1,21 @@
-import { useContext } from 'react';
-import { useStore } from 'zustand/react';
+import { labContributions, useLabChromeContext } from '../chrome/LabChrome';
+import type { LabContribution } from '../chrome/labTypes';
 import { PaletteRegion } from '../chrome/regions/PaletteRegion';
-import type { TrialChromeContext, TrialContribution } from '../chrome/types';
-import { LabStoreContext } from '../state/context';
 import type { TrialTool } from '../tools/types';
 
 /** Props for `<LabPalette>`. */
 export interface LabPaletteProps {
-  tools: readonly TrialTool[];
+  /** Tools offered lab-wide. Shorthand for one `palette` contribution each. */
+  tools?: readonly TrialTool[];
+  /** The lab's contributions; the `palette` ones are laid out here. */
+  contributions?: readonly LabContribution[];
 }
 
-/** The lab's tool strip. Writes the lab's tool slot, which every trial whose
- *  instrument declares no tools of its own resolves to. */
-export function LabPalette({ tools }: LabPaletteProps) {
-  const storeCtx = useContext(LabStoreContext);
-  if (!storeCtx) throw new Error('[labkit] LabPalette requires <LabStoreProvider>');
-  const activeToolId = useStore(storeCtx.store, (s) => s.activeToolId);
-  const setLabTool = useStore(storeCtx.store, (s) => s.setLabTool);
-
-  const contributions: TrialContribution[] = tools.map((t) => ({
-    id: t.id,
-    region: 'palette',
-    group: t.group,
-    item: { icon: t.icon, label: t.label, shortcut: t.shortcut },
-  }));
-
-  const ctx = {
-    activeToolId,
-    setActiveTool: setLabTool,
-  } as unknown as TrialChromeContext;
-
-  return <PaletteRegion contributions={contributions} ctx={ctx} />;
+/** The lab's tool rail. Writes the lab's tool slot, which every trial whose
+ *  instrument declares no tools of its own resolves to. Renders nothing when
+ *  the lab contributes no tool rail. */
+export function LabPalette({ tools, contributions }: LabPaletteProps) {
+  const ctx = useLabChromeContext();
+  const all = labContributions(tools, contributions);
+  return <PaletteRegion contributions={all.filter((c) => c.region === 'palette')} ctx={ctx} />;
 }

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>
+  );
+}