@weasel-js/labkit 1.7.0 → 1.7.2

package/src/canvas/Stage.test.tsx

@@ -1,4 +1,5 @@
-import { act, fireEvent, render, screen, within } from '@testing-library/react';
+import { act, fireEvent, screen, within } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { useState } from 'react';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
@@ -47,8 +48,8 @@ describe('fitStage', () => {
 });
 
 describe('<Stage>', () => {
-  it('draws its content through the camera', () => {
-    const { container } = render(
+  it('draws its content through the camera', async () => {
+    const { container } = await renderSettled(
       <Stage
         size={{ width: 300, height: 100 }}
         view={{ zoom: 2, pan: { x: 10, y: 20 } }}
@@ -66,7 +67,7 @@ describe('<Stage>', () => {
     expect(el.style.getPropertyValue('--lk-stage-h')).toBe('100px');
   });
 
-  it('zooms on the wheel', () => {
+  it('zooms on the wheel', async () => {
     function Host() {
       const [view, setView] = useState<ViewTransform>({ zoom: 1, pan: { x: 0, y: 0 } });
       return (
@@ -75,14 +76,14 @@ describe('<Stage>', () => {
         </Stage>
       );
     }
-    const { container } = render(<Host />);
+    const { container } = await renderSettled(<Host />);
     const host = container.querySelector('.lk-stage');
     if (!host) throw new Error('no stage');
     fireEvent.wheel(host, { deltaY: -200, clientX: 0, clientY: 0 });
     expect(zoomOf(content(container))).toBeGreaterThan(1);
   });
 
-  it('zooms on a wheel handed to its camera from outside the stage', () => {
+  it('zooms on a wheel handed to its camera from outside the stage', async () => {
     // What an annotation target's input box does: it is portalled out of the
     // stage, so its wheel never bubbles here.
     const slot: CameraWheelSlot = { current: null };
@@ -96,19 +97,19 @@ describe('<Stage>', () => {
         </CameraWheelContext.Provider>
       );
     }
-    const { container } = render(<Host />);
-    act(() => {
+    const { container } = await renderSettled(<Host />);
+    await act(async () => {
       slot.current?.(new WheelEvent('wheel', { deltaY: -200, cancelable: true }));
     });
     expect(zoomOf(content(container))).toBeGreaterThan(1);
   });
 
-  it('listens for the wheel actively, so it can keep the page from scrolling', () => {
+  it('listens for the wheel actively, so it can keep the page from scrolling', async () => {
     // A proxy: jsdom does not enforce passive listeners, so a preventDefault in
     // a passive one succeeds here and fails in a browser. React registers its
     // wheel listeners passive; asserting the registration is what can fail.
     const add = vi.spyOn(HTMLElement.prototype, 'addEventListener');
-    const { container } = render(
+    const { container } = await renderSettled(
       <Stage
         size={{ width: 100, height: 100 }}
         view={{ zoom: 1, pan: { x: 0, y: 0 } }}
@@ -127,7 +128,7 @@ describe('<Stage>', () => {
     add.mockRestore();
   });
 
-  it('tells the surface its tiles moved when the camera does', () => {
+  it('tells the surface its tiles moved when the camera does', async () => {
     // A transform moves a tile without resizing anything, which is the one
     // kind of move a ResizeObserver never reports.
     const invalidateRects = vi.fn();
@@ -139,7 +140,7 @@ describe('<Stage>', () => {
         </Stage>
       </SurfaceContext.Provider>
     );
-    const { rerender } = render(at({ zoom: 1, pan: { x: 0, y: 0 } }));
+    const { rerender } = await renderSettled(at({ zoom: 1, pan: { x: 0, y: 0 } }));
     invalidateRects.mockClear();
     rerender(at({ zoom: 1.5, pan: { x: 0, y: 0 } }));
     expect(invalidateRects).toHaveBeenCalled();
@@ -162,25 +163,29 @@ const plain = defineInstrument<Record<string, never>, Record<string, never>>({
 });
 
 describe('an instrument that declares a stage', () => {
-  it('renders its DOM on the stage', () => {
-    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+  it('renders its DOM on the stage', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[staged]} defaultInstrument="Staged" />,
+    );
     expect(content(container)).toContainElement(screen.getByTestId('art'));
   });
 
-  it('gets the zoom controls, and they move the stage', () => {
-    const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+  it('gets the zoom controls, and they move the stage', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[staged]} defaultInstrument="Staged" />,
+    );
     const trialView = within(screen.getByRole('toolbar', { name: 'View' }));
-    act(() => {
+    await act(async () => {
       fireEvent.click(trialView.getByRole('button', { name: 'Zoom in' }));
     });
     expect(zoomOf(content(container))).toBeCloseTo(1.25);
-    act(() => {
+    await act(async () => {
       fireEvent.click(trialView.getByRole('button', { name: 'Actual size' }));
     });
     expect(zoomOf(content(container))).toBe(1);
   });
 
-  it('zooms about the middle of the view, not the stage origin', () => {
+  it('zooms about the middle of the view, not the stage origin', async () => {
     const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
       x: 0,
       y: 0,
@@ -193,9 +198,11 @@ describe('an instrument that declares a stage', () => {
       toJSON: () => ({}),
     });
     try {
-      const { container } = render(<Lab instruments={[staged]} defaultInstrument="Staged" />);
+      const { container } = await renderSettled(
+        <Lab instruments={[staged]} defaultInstrument="Staged" />,
+      );
       const trialView = within(screen.getByRole('toolbar', { name: 'View' }));
-      act(() => {
+      await act(async () => {
         fireEvent.click(trialView.getByRole('button', { name: 'Zoom in' }));
       });
       const el = content(container);
@@ -208,12 +215,12 @@ describe('an instrument that declares a stage', () => {
     }
   });
 
-  it('is what earns them: DOM content without one gets none', () => {
-    render(<Lab instruments={[plain]} defaultInstrument="Plain" />);
+  it('is what earns them: DOM content without one gets none', async () => {
+    await renderSettled(<Lab instruments={[plain]} defaultInstrument="Plain" />);
     expect(screen.queryByRole('toolbar', { name: 'View' })).toBeNull();
   });
 
-  it('draws its overlay on the stage, outside the camera', () => {
+  it('draws its overlay on the stage, outside the camera', async () => {
     const overlaid = defineInstrument<{ n: number }, Record<string, never>>({
       name: 'Overlaid',
       defaultConfig: () => ({}),
@@ -224,7 +231,9 @@ describe('an instrument that declares a stage', () => {
         overlay: ({ state }) => <div data-testid="legend">{state.n}</div>,
       },
     });
-    const { container } = render(<Lab instruments={[overlaid]} defaultInstrument="Overlaid" />);
+    const { container } = await renderSettled(
+      <Lab instruments={[overlaid]} defaultInstrument="Overlaid" />,
+    );
     const legend = screen.getByTestId('legend');
     expect(legend).toHaveTextContent('7');
     expect(container.querySelector('.lk-stage')).toContainElement(legend);

package/src/canvas/Stage.tsx

@@ -1,4 +1,5 @@
 import type { Yoke } from '@weasel-js/core';
+import { useLatest } from '@weasel-js/core';
 import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef } from 'react';
 import type { ViewTransform } from '../instrument/types';
 import { normalize2DView } from '../state/view';
@@ -85,8 +86,7 @@ export function Stage({
     [camera, size.width, size.height],
   );
 
-  const onResizeRef = useRef(onResize);
-  onResizeRef.current = onResize;
+  const onResizeRef = useLatest(onResize);
   useEffect(() => {
     const el = host.current;
     if (!el) return;
@@ -101,7 +101,7 @@ export function Stage({
     const ro = new ResizeObserver(measure);
     ro.observe(el);
     return () => ro.disconnect();
-  }, []);
+  }, [onResizeRef]);
 
   // A transform moves every tile inside the content without resizing anything,
   // and a ResizeObserver reports only resizes.

package/src/canvas/cameraRegistry.ts

@@ -15,6 +15,7 @@ export interface CameraRegistry {
   subscribe(listener: () => void): () => void;
 }
 
+/** An empty in-memory `CameraRegistry`. */
 export function createCameraRegistry(): CameraRegistry {
   const stacks = new Map<string, CameraView[]>();
   const listeners = new Set<() => void>();

package/src/canvas/worldSpec.ts

@@ -5,7 +5,7 @@ import type { Point, ViewTransform } from '../instrument/types';
  *  world (0,0) at the element's top-left, y growing downward. */
 export interface WorldSpec {
   /** Where world (0,0) sits at `pan` zero, as a fraction of the viewport.
-   *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` centre. */
+   *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` center. */
   origin?: Point;
   /** Which way the world y axis runs on screen. Default `'down'`. */
   yAxis?: 'down' | 'up';
@@ -25,8 +25,10 @@ export interface WorldFrame {
   yDir: 1 | -1;
 }
 
+/** The frame an absent `WorldSpec` resolves to: origin top-left, y down. */
 export const DEFAULT_FRAME: WorldFrame = { originPx: { x: 0, y: 0 }, yDir: 1 };
 
+/** Resolve `spec` against a viewport of `size`; `undefined` gives `DEFAULT_FRAME`. */
 export function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame {
   if (!spec) return DEFAULT_FRAME;
   const origin = spec.origin ?? { x: 0, y: 0 };

package/src/chrome/builtins.test.ts

@@ -23,6 +23,7 @@ const ctx: TrialChromeContext = {
   canRedo: false,
   undo: () => {},
   redo: () => {},
+  hasLoupe: false,
   loupeOn: false,
   toggleLoupe: () => {},
   configFields: [],
@@ -72,21 +73,21 @@ describe('builtinContributions', () => {
     expect(ids({ ...bare, undo: {} })).toContain('redo');
   });
 
-  it('contributes the loupe toggle only when the instrument declares one', () => {
+  it('contributes the loupe toggle only while a lens is mounted', () => {
     expect(ids(bare)).not.toContain('loupe');
-    expect(ids({ ...bare, loupe: true })).toContain('loupe');
-    expect(ids({ ...bare, loupe: { render: () => null } })).toContain('loupe');
+    const mounted = builtinContributions(bare, { ...ctx, hasLoupe: true });
+    expect(mounted.map((c) => c.id)).toContain('loupe');
   });
 
   it('offers the loupe to a DOM instrument, which declares no canvas', () => {
-    const contributions = builtinContributions({ ...bare, loupe: true }, ctx);
+    const contributions = builtinContributions(bare, { ...ctx, hasLoupe: true });
     const loupe = contributions.find((c) => c.id === 'loupe');
     expect(loupe?.region).toBe('toolbar');
   });
 
   it('reports the loupe switch position, so the button reads as held', () => {
-    const off = builtinContributions({ ...bare, loupe: true }, ctx);
-    const on = builtinContributions({ ...bare, loupe: true }, { ...ctx, loupeOn: true });
+    const off = builtinContributions(bare, { ...ctx, hasLoupe: true });
+    const on = builtinContributions(bare, { ...ctx, hasLoupe: true, loupeOn: true });
     expect(off.find((c) => c.id === 'loupe')?.item).toMatchObject({ pressed: false });
     expect(on.find((c) => c.id === 'loupe')?.item).toMatchObject({ pressed: true });
   });

package/src/chrome/builtins.tsx

@@ -39,6 +39,10 @@ function groupFolds(
   return out;
 }
 
+/** Built-in ids contributed only while runtime state says so — the loupe
+ *  toggle appears once a lens mounts, after the trial's first render. */
+export const TRANSIENT_BUILTINS: ReadonlySet<string> = new Set(['loupe']);
+
 /**
  * The contributions a trial gets from what its instrument declared. This is
  * the whole "declaring a capability provides the chrome" rule — it replaces
@@ -93,7 +97,7 @@ export function builtinContributions(
     });
   }
 
-  if (instrument.loupe != null) {
+  if (ctx.hasLoupe) {
     out.push({
       id: 'loupe',
       region: 'toolbar',

package/src/chrome/index.ts

@@ -1,4 +1,4 @@
-export { builtinContributions } from './builtins';
+export { builtinContributions, TRANSIENT_BUILTINS } from './builtins';
 export type { LabRegionProps } from './LabChrome';
 export {
   contributionsIn,

package/src/chrome/labRegions.test.tsx

@@ -1,4 +1,5 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, it, vi } from 'vitest';
 import type { Instrument } from '../instrument/types';
 import { Lab } from '../lab/Lab';
@@ -19,19 +20,19 @@ function silenceRenderError(): void {
 }
 
 describe('lab-level chrome', () => {
-  it('renders a header contribution beside the lab header', () => {
+  it('renders a header contribution beside the lab header', async () => {
     const contribution: LabContribution = {
       id: 'publish',
       region: 'header',
       item: { icon: Glyph, label: 'Publish', onActivate: () => {} },
     };
-    render(
+    await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
     );
     expect(screen.getByRole('button', { name: 'Publish' })).toBeInTheDocument();
   });
 
-  it('hands a header contribution the lab, not a trial', () => {
+  it('hands a header contribution the lab, not a trial', async () => {
     const contribution: LabContribution = {
       id: 'another',
       region: 'header',
@@ -41,21 +42,23 @@ describe('lab-level chrome', () => {
         onActivate: (ctx) => ctx.addTrial('Bare'),
       },
     };
-    render(
+    await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
     );
     expect(screen.getAllByLabelText(/^Trial /)).toHaveLength(1);
-    fireEvent.click(screen.getByRole('button', { name: 'Another' }));
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'Another' }));
+    });
     expect(screen.getAllByLabelText(/^Trial /)).toHaveLength(2);
   });
 
-  it('renders a palette contribution in the lab rail and selects it', () => {
+  it('renders a palette contribution in the lab rail and selects it', async () => {
     const contribution: LabContribution = {
       id: 'measure',
       region: 'palette',
       item: { icon: Glyph, label: 'Measure' },
     };
-    render(
+    await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
     );
     const button = screen.getByRole('button', { name: 'Measure' });
@@ -63,7 +66,7 @@ describe('lab-level chrome', () => {
     expect(screen.getByRole('button', { name: 'Measure' })).toHaveAttribute('aria-current', 'true');
   });
 
-  it('gives a palette contribution the whole lab context, not a tool slot alone', () => {
+  it('gives a palette contribution the whole lab context, not a tool slot alone', async () => {
     // The shape the `as unknown as TrialChromeContext` cast used to fake: a
     // contribution reading anything past the tool slot got `undefined`.
     const seen: LabChromeContext[] = [];
@@ -75,7 +78,7 @@ describe('lab-level chrome', () => {
         return <span>{`${ctx.trials.length} trial(s), mode ${ctx.mode}`}</span>;
       },
     };
-    render(
+    await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
     );
     expect(screen.getByText('1 trial(s), mode auto')).toBeInTheDocument();
@@ -83,19 +86,19 @@ describe('lab-level chrome', () => {
     expect(typeof seen[0]?.saveSnapshot).toBe('function');
   });
 
-  it('renders a footer contribution', () => {
+  it('renders a footer contribution', async () => {
     const contribution: LabContribution = {
       id: 'count',
       region: 'footer',
       item: { text: 'idle' },
     };
-    render(
+    await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
     );
     expect(screen.getByText('idle')).toBeInTheDocument();
   });
 
-  it('throws when two lab contributions share an id', () => {
+  it('throws when two lab contributions share an id', async () => {
     silenceRenderError();
     const clash: LabContribution[] = [
       { id: 'same', region: 'header', item: { icon: Glyph, label: 'One', onActivate: () => {} } },
@@ -106,7 +109,7 @@ describe('lab-level chrome', () => {
     ).toThrow(/duplicate contribution id "same"/);
   });
 
-  it('keeps the lab tool slot and lab palette contributions in one namespace', () => {
+  it('keeps the lab tool slot and lab palette contributions in one namespace', async () => {
     silenceRenderError();
     const clash: LabContribution = {
       id: 'pick',
@@ -134,8 +137,8 @@ describe('lab sidebar region', () => {
     item: { title: 'Stories', body: <p>story list</p> },
   };
 
-  it('renders a section beside the workspace', () => {
-    const { container } = render(
+  it('renders a section beside the workspace', async () => {
+    const { container } = await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[tree]} />,
     );
     expect(screen.getByText('story list')).toBeInTheDocument();
@@ -143,18 +146,22 @@ describe('lab sidebar region', () => {
     expect(screen.getByRole('separator', { name: /lab sidebar/i })).toBeInTheDocument();
   });
 
-  it('folds a section', () => {
-    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[tree]} />);
+  it('folds a section', async () => {
+    await renderSettled(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[tree]} />,
+    );
     fireEvent.click(screen.getByRole('button', { name: 'Stories' }));
     expect(screen.queryByText('story list')).toBeNull();
   });
 
-  it('offers no tear-out at lab level', () => {
-    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[tree]} />);
+  it('offers no tear-out at lab level', async () => {
+    await renderSettled(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[tree]} />,
+    );
     expect(screen.queryByRole('button', { name: 'Undock Stories' })).toBeNull();
   });
 
-  it('hands a render contribution the lab context', () => {
+  it('hands a render contribution the lab context', async () => {
     const seen: LabChromeContext[] = [];
     const probe: LabContribution = {
       id: 'probe',
@@ -164,13 +171,17 @@ describe('lab sidebar region', () => {
         return <p>probe</p>;
       },
     };
-    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[probe]} />);
+    await renderSettled(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[probe]} />,
+    );
     expect(screen.getByText('probe')).toBeInTheDocument();
     expect(seen[0]?.trials).toHaveLength(1);
   });
 
-  it('adds no strip to a lab without sidebar chrome', () => {
-    const { container } = render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" />);
+  it('adds no strip to a lab without sidebar chrome', async () => {
+    const { container } = await renderSettled(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" />,
+    );
     expect(container.querySelector('.lk-lab__panes')).toBeNull();
   });
 });
@@ -182,7 +193,7 @@ describe('lab chrome without <Lab>', () => {
     undo: () => void;
   }
 
-  it('renders a contribution typed against a consumer context and hands it back', () => {
+  it('renders a contribution typed against a consumer context and hands it back', async () => {
     const undo = vi.fn();
     const ctx: RailCtx = { undo };
     const rail: readonly LabContribution<RailCtx>[] = [
@@ -192,7 +203,7 @@ describe('lab chrome without <Lab>', () => {
         item: { icon: Glyph, label: 'Undo', showLabel: true, onActivate: (c) => c.undo() },
       },
     ];
-    render(
+    await renderSettled(
       <LabShell
         title="Palette lab"
         header={

package/src/chrome/merge.test.ts

@@ -44,6 +44,11 @@ describe('suppressContributions', () => {
     );
   });
 
+  it('passes over an absent id it was told may come and go', () => {
+    const out = suppressContributions([toolbarItem('a')], ['late'], new Set(['late']));
+    expect(out.map((c) => c.id)).toEqual(['a']);
+  });
+
   it('is a no-op for an empty suppress list', () => {
     const bundle = [toolbarItem('a')];
     expect(suppressContributions(bundle, [])).toEqual(bundle);

package/src/chrome/merge.ts

@@ -30,15 +30,17 @@ export function mergeContributions<T extends { id: string }>(
 /**
  * Drop contributions by id. Throws when an id is not present: a typo that
  * silently suppresses nothing is the same class of bug as a duplicate id
- * silently winning.
+ * silently winning. `transient` names ids that are legitimately absent at
+ * times — contributed only while some runtime state holds.
  */
 export function suppressContributions<T extends { id: string }>(
   bundle: readonly T[],
   ids: readonly string[],
+  transient: ReadonlySet<string> = new Set(),
 ): T[] {
   const present = new Set(bundle.map((c) => c.id));
   for (const id of ids) {
-    if (!present.has(id)) {
+    if (!present.has(id) && !transient.has(id)) {
       throw new Error(
         `[labkit] cannot suppress "${id}": no contribution with that id. ` +
           `Present ids: ${[...present].join(', ')}`,

package/src/chrome/regions/PaletteRegion.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import type { RegionContribution, ToolSlotContext } from '../types';
 import { PaletteRegion } from './PaletteRegion';
@@ -62,16 +62,15 @@ describe('PaletteRegion', () => {
 
   it('walks the vertical strip with ArrowDown, and leaves ArrowRight to the page', () => {
     render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
-    const strip = screen.getByRole('toolbar', { name: 'Tools' });
     const brush = screen.getByRole('button', { name: 'brush' });
     const eraser = screen.getByRole('button', { name: 'eraser' });
 
-    brush.focus();
-    fireEvent.keyDown(strip, { key: 'ArrowDown' });
+    act(() => brush.focus());
+    fireEvent.keyDown(brush, { key: 'ArrowDown' });
     expect(document.activeElement).toBe(eraser);
     expect(eraser).toHaveAttribute('tabindex', '0');
 
-    fireEvent.keyDown(strip, { key: 'ArrowRight' });
+    fireEvent.keyDown(eraser, { key: 'ArrowRight' });
     expect(document.activeElement).toBe(eraser);
   });
 });

package/src/chrome/regions/PaletteRegion.tsx

@@ -1,5 +1,4 @@
-import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
-import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
+import { ToolButton, ToolGroup, useRovingTabIndex } from '../../passthrough/weasel-ui';
 import type { RegionContribution, ToolItem, ToolSlotContext, TrialChromeContext } from '../types';
 
 /** Props for `<PaletteRegion>`. */
@@ -19,11 +18,11 @@ export function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>
   ctx,
   region = 'palette',
 }: PaletteRegionProps<TCtx>) {
-  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>('vertical');
+  const { rootRef, onKeyDown } = useRovingTabIndex<HTMLDivElement>({ orientation: 'vertical' });
   if (contributions.length === 0) return null;
   return (
     <div
-      ref={ref}
+      ref={rootRef}
       className="lk-palette-region"
       role="toolbar"
       aria-label="Tools"

package/src/chrome/regions/ViewportRegion.browser.test.less

@@ -0,0 +1,6 @@
+// Narrower than the zoom control's 160px natural width, wider than its floor.
+.lk-viewport-test-well {
+  position: relative;
+  width: 160px;
+  height: 120px;
+}

package/src/chrome/regions/ViewportRegion.browser.test.tsx

@@ -0,0 +1,38 @@
+import '@weasel-js/theme/tokens.css';
+import '../../styles.less';
+import './ViewportRegion.browser.test.less';
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, expect, test } from 'vitest';
+import { ZoomControl } from '../../primitives/ZoomControl';
+import type { TrialChromeContext, TrialContribution } from '../types';
+import { ViewportRegion } from './ViewportRegion';
+
+// Whether a rendered control shrinks to the cluster or runs out past it is
+// layout, which only a real browser has.
+
+afterEach(cleanup);
+
+const ctx = { zoom: 1, setZoom: () => {} } as unknown as TrialChromeContext;
+
+const contributions: TrialContribution[] = [
+  {
+    id: 'zoom-control',
+    region: 'viewport',
+    render: (c) => <ZoomControl zoom={c.zoom ?? 1} onZoomChange={c.setZoom} />,
+  },
+];
+
+test('a zoom control on its own row shrinks its slider to fit a narrow well', () => {
+  const { container } = render(
+    <div className="lk-root">
+      <div className="lk-viewport-test-well">
+        <ViewportRegion contributions={contributions} ctx={ctx} />
+      </div>
+    </div>,
+  );
+  const cluster = container.querySelector('.lk-viewport-controls')?.getBoundingClientRect();
+  const zoom = container.querySelector('.lk-zoom')?.getBoundingClientRect();
+  if (!cluster || !zoom) throw new Error('nothing rendered');
+  expect(zoom.left).toBeGreaterThanOrEqual(cluster.left);
+  expect(zoom.right).toBeLessThanOrEqual(cluster.right);
+});

package/src/chrome/regions/ViewportRegion.less

@@ -17,6 +17,12 @@
   backdrop-filter: blur(var(--wzl-glass-blur));
 }
 
+// Without this a rendered control's floor is its content's min-content, and the
+// zoom slider's fixed width then runs it out past the cluster on a narrow well.
+.lk-viewport-controls__item {
+  min-width: 0;
+}
+
 .lk-viewport-controls__button {
   display: inline-flex;
   align-items: center;

package/src/chrome/regions/ViewportRegion.tsx

@@ -1,4 +1,4 @@
-import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
+import { useRovingTabIndex } from '../../passthrough/weasel-ui';
 import type { TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<ViewportRegion>`. */
@@ -12,18 +12,24 @@ export interface ViewportRegionProps {
  * rather than in the toolbar, which acts on the trial itself.
  */
 export function ViewportRegion({ contributions, ctx }: ViewportRegionProps) {
-  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
+  const { rootRef, onKeyDown } = useRovingTabIndex<HTMLDivElement>({ orientation: 'horizontal' });
   if (contributions.length === 0) return null;
   return (
     <div
-      ref={ref}
+      ref={rootRef}
       className="lk-viewport-controls"
       role="toolbar"
       aria-label="View"
       onKeyDown={onKeyDown}
     >
       {contributions.map((c) => {
-        if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
+        if (c.render) {
+          return (
+            <span key={c.id} className="lk-viewport-controls__item">
+              {c.render(ctx)}
+            </span>
+          );
+        }
         if (c.region !== 'viewport' || !c.item) return null;
         const { icon: Icon, label, disabled, onActivate } = c.item;
         return (

package/src/chrome/types.ts

@@ -162,8 +162,10 @@ export interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext
   undo: () => void;
   redo: () => void;
 
-  /** Whether the trial's loupe is turned on. False for an instrument that
-   *  declares none, whose chrome offers no way to turn one on. */
+  /** Whether a `<TrialLoupe>` following the trial's toggle is mounted in it.
+   *  The loupe toggle is offered only while one is. */
+  hasLoupe: boolean;
+  /** Whether the trial's loupe is turned on. */
   loupeOn: boolean;
   toggleLoupe: () => void;