@weasel-js/labkit 1.4.4 → 1.5.0

package/src/lab/LabFit.stories.tsx

@@ -0,0 +1,219 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+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';
+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.
+
+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';
+
+// Storybook 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

@@ -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,17 +37,11 @@ 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)}
         />
       )}
 

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

@@ -2,7 +2,11 @@
   display: flex;
   flex-direction: column;
   width: 100%;
+  // Fills a container of definite height. Where the container has none, the
+  // percentage drops out and the shell takes the viewport's height instead.
   height: 100vh;
+  height: 100dvh;
+  max-height: 100%;
   background: var(--wzl-surface);
 }
 
@@ -42,35 +46,72 @@
 }
 
 .lk-shell-body {
+  display: flex;
+  flex-direction: column;
   flex: 1;
   min-height: 0;
+  min-width: 0;
   overflow: auto;
   padding: var(--lk-workspace-pad);
 }
 
-// `.lk-shell-body` is a block container, so `flex: 1` here resolves to nothing
-// and the workspace's `height: 100%` collapses to zero.
 .lk-lab__body {
   display: flex;
-  height: 100%;
+  flex: 1;
   min-height: 0;
   position: relative;
 
-  > .lk-workspace {
+  > .lk-workspace,
+  > .lk-workspace-host {
+    min-width: 0;
+  }
+}
+
+.lk-lab__panes {
+  flex: 1;
+  min-width: 0;
+}
+
+.lk-lab__sidebar {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow-y: auto;
+  background: var(--wzl-surface);
+  border-right: 1px solid var(--wzl-border);
+}
+
+.lk-lab__main {
+  display: flex;
+  min-width: 0;
+  height: 100%;
+
+  > .lk-workspace,
+  > .lk-workspace-host {
+    flex: 1;
     min-width: 0;
   }
 }
 
-// The lab's one shared drawing buffer. Over the trials, because a tile's marks
-// annotate the instrument's own DOM; under the viewport chrome, whose z-overlay
-// outranks it; and inert, because every tile takes input from its own box.
+// The lab's two shared drawing buffers, stacked around the trials: marks that
+// annotate an instrument go over its DOM, an opaque renderer goes under it so
+// the pane can still hold a label or a control. Both sit under the viewport
+// chrome, whose z-overlay outranks them, and both are inert — every tile takes
+// input from its own box.
 .lk-lab__surface {
   position: absolute;
   inset: 0;
-  z-index: 1;
   pointer-events: none;
 }
 
+.lk-lab__surface--under {
+  z-index: 0;
+}
+
+.lk-lab__surface--over {
+  z-index: 1;
+}
+
 .lk-shell-footer {
   border-top: 1px solid var(--wzl-border);
   padding: var(--wzl-space-xs) var(--wzl-space-md);
@@ -98,10 +139,6 @@
 // against a shrink-to-fit header row it swallows the slack, which pushed the
 // consumer's own header content down to min-content and wrapped the row to
 // three lines. See the `.lk-root` prefix convention in theme/base.less.
-.lk-root .lk-lab-header__add-select {
-  width: 160px;
-}
-
 // The mode toggle is a preference, not a primary action: it sits quiet until
 // the pointer is on it.
 .lk-lab-header__mode {

package/src/lab/LabSwitcher.less

@@ -21,6 +21,10 @@
   border: 0;
   padding: 0;
   cursor: pointer;
+  // A title is a click target now, and a consumer's header is usually a
+  // crowded flex row -- left to wrap, `brick-icons corpus` breaks after the
+  // hyphen and the control becomes three ragged lines with a caret adrift.
+  white-space: nowrap;
 
   &:hover { color: var(--wzl-text-accent, var(--wzl-text)); }
 
@@ -55,7 +59,10 @@
   display: flex;
   flex-direction: column;
   padding: var(--wzl-space-xs);
-  background: var(--wzl-surface-raised);
+  // `--wzl-surface-raised` is translucent by design -- it is for panels that
+  // blur what sits behind them. A menu has to be read, so it takes the opaque
+  // surface, the way `FloatingPanel` does.
+  background: var(--wzl-surface);
   border: 1px solid var(--wzl-border);
   border-radius: var(--wzl-radius-md, 6px);
   box-shadow: var(--wzl-shadow-md, 0 6px 20px rgb(0 0 0 / 35%));

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

@@ -10,7 +10,8 @@ function fakeHandle(): SurfaceHandle {
     invalidateAll: vi.fn(),
     invalidateRects: vi.fn(),
     registerTile: vi.fn(),
-    registerPainter: vi.fn(() => () => {}),
+    registerClear: vi.fn(() => () => {}),
+  registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
     getContainer: vi.fn(() => null),
   };

package/src/lab/fitCheck.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { describeElement, findOvershoot } from './fitCheck';
+
+const bound = { top: 0, left: 0, bottom: 600, right: 800 };
+const box = (bottom: number, right: number) => ({ top: 0, left: 0, bottom, right });
+
+describe('findOvershoot', () => {
+  it('returns null when everything is inside the bound', () => {
+    expect(findOvershoot(bound, [{ item: 'a', edges: box(600, 800) }])).toBeNull();
+  });
+
+  it('ignores sub-pixel overshoot within the tolerance', () => {
+    expect(findOvershoot(bound, [{ item: 'a', edges: box(600.8, 800) }])).toBeNull();
+  });
+
+  it('names the item reaching furthest past the bound', () => {
+    const hit = findOvershoot(bound, [
+      { item: 'header', edges: box(640, 800) },
+      { item: 'tile', edges: box(900, 800) },
+      { item: 'footer', edges: box(700, 800) },
+    ]);
+    expect(hit).toEqual({ item: 'tile', by: 300, axis: 'y' });
+  });
+
+  it('compares both axes and reports the worse one', () => {
+    const hit = findOvershoot(bound, [
+      { item: 'tall', edges: box(650, 800) },
+      { item: 'wide', edges: box(600, 1000) },
+    ]);
+    expect(hit).toEqual({ item: 'wide', by: 200, axis: 'x' });
+  });
+
+  it('keeps the first item on a tie, which is the outermost in document order', () => {
+    const hit = findOvershoot(bound, [
+      { item: 'shell', edges: box(616, 800) },
+      { item: 'footer', edges: box(616, 800) },
+    ]);
+    expect(hit?.item).toBe('shell');
+  });
+});
+
+describe('describeElement', () => {
+  it('writes the tag and every class', () => {
+    const el = document.createElement('DIV');
+    el.className = 'lk-shell-body extra';
+    expect(describeElement(el)).toBe('div.lk-shell-body.extra');
+  });
+
+  it('places a classless element by its nearest classed ancestor', () => {
+    const outer = document.createElement('div');
+    outer.className = 'lk-trial';
+    const mid = document.createElement('div');
+    const leaf = document.createElement('canvas');
+    outer.appendChild(mid).appendChild(leaf);
+    expect(describeElement(leaf)).toBe('canvas in div.lk-trial');
+  });
+});