@weasel-js/labkit 1.4.4 → 1.5.1

package/src/canvas/usePanZoom.ts

@@ -7,6 +7,7 @@ import {
   type WheelEvent,
 } from 'react';
 import type { ViewTransform } from '../instrument/types';
+import { normalize2DView } from '../state/view';
 import { zoomAt } from './camera';
 import { DEFAULT_FRAME, type WorldFrame } from './worldSpec';
 
@@ -28,7 +29,9 @@ export interface UsePanZoomOptions {
 }
 
 export interface PanZoomHandlers {
-  onWheel: (e: WheelEvent<HTMLElement>) => void;
+  /** Zoom about the pointer. `anchor` is the element the pointer position is
+   *  measured against, for an event whose `currentTarget` is some other box. */
+  onWheel: (e: WheelEvent<HTMLElement> | globalThis.WheelEvent, anchor?: Element) => void;
   onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
   isDragging: () => boolean;
 }
@@ -56,8 +59,8 @@ export function usePanZoom({
 }: UsePanZoomOptions): PanZoomHandlers {
   const dragRef = useRef<DragState | null>(null);
   const sessionRef = useRef<PointerSession | null>(null);
-  const viewRef = useRef(view);
-  viewRef.current = view;
+  const viewRef = useRef(normalize2DView(view));
+  viewRef.current = normalize2DView(view);
   const onViewChangeRef = useRef(onViewChange);
   onViewChangeRef.current = onViewChange;
   const onTapRef = useRef(onTap);
@@ -67,12 +70,21 @@ export function usePanZoom({
   // view unreachable behind it.
   const initialZoomRef = useRef(isPositiveFinite(view.zoom) ? view.zoom : null);
 
+  // Written ahead of the render so a second event inside one commit steps
+  // from this one; the render-time assignment above still lets the prop win.
+  const commit = useCallback((next: ViewTransform) => {
+    viewRef.current = normalize2DView(next);
+    onViewChangeRef.current(next);
+  }, []);
+
   const onWheel = useCallback(
-    (e: WheelEvent<HTMLElement>) => {
+    (e: WheelEvent<HTMLElement> | globalThis.WheelEvent, anchor?: Element) => {
+      const el = anchor ?? (e.currentTarget as Element | null);
+      if (!el) return;
       e.preventDefault();
-      const rect = e.currentTarget.getBoundingClientRect();
+      const rect = el.getBoundingClientRect();
       const initialZoom = initialZoomRef.current;
-      onViewChange(
+      commit(
         zoomAt(
           viewRef.current,
           Math.exp(-e.deltaY * 0.001),
@@ -85,7 +97,7 @@ export function usePanZoom({
         ),
       );
     },
-    [onViewChange, minZoom, maxZoom, frame],
+    [commit, minZoom, maxZoom, frame],
   );
 
   const clearDrag = useCallback(() => {
@@ -109,7 +121,7 @@ export function usePanZoom({
           const dy = ev.clientY - drag.startScreenY;
           if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
           drag.moved = true;
-          onViewChangeRef.current({
+          commit({
             zoom: viewRef.current.zoom,
             pan: { x: drag.startPan.x + dx, y: drag.startPan.y + dy },
           });
@@ -124,7 +136,7 @@ export function usePanZoom({
         onCancel: clearDrag,
       });
     },
-    [clearDrag],
+    [clearDrag, commit],
   );
 
   useEffect(() => () => sessionRef.current?.cancel(), []);

package/src/chrome/ChromeRegions.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { CrosshairIcon, HandIcon, PencilIcon, SnapshotIcon } from '@weasel-js/ui';
 import type { ConfigField } from '../controls/types';
 import type { Instrument } from '../instrument/types';
@@ -76,7 +76,6 @@ export const EveryRegion: Story = {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',
     title: 'Chrome Regions',
-    storage: null,
   },
 };
 
@@ -86,7 +85,6 @@ export const SuppressedAndReplaced: Story = {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',
     title: 'Suppress + Replace',
-    storage: null,
     suppress: ['snapshot'],
     chrome: [
       {
@@ -116,7 +114,6 @@ export const SubjectTitleAndLead: Story = {
     instruments: [FullInstrument],
     defaultInstrument: 'Every Region',
     title: 'Title Bar Lead',
-    storage: null,
     suppress: ['snapshot'],
     chrome: [
       {

package/src/chrome/LabChrome.tsx

@@ -0,0 +1,130 @@
+import { useContext, useMemo } from 'react';
+import { useStore } from 'zustand/react';
+import { useLabContext } from '../lab/LabContext';
+import { LabStoreContext } from '../state/context';
+import { usePersistedState } from '../state/usePersistedState';
+import { resolveLabTool } from '../tools/labTool';
+import type { TrialTool } from '../tools/types';
+import type { LabChromeContext, LabContribution, LabRegion } from './labTypes';
+import { mergeContributions } from './merge';
+import { SidebarRegion } from './regions/SidebarRegion';
+import { StatusRegion } from './regions/StatusRegion';
+import { ToolbarRegion } from './regions/ToolbarRegion';
+
+/** The lab's chrome context: the lab itself, plus the lab's tool slot. Throws
+ *  outside a `<Lab>`. */
+export function useLabChromeContext(): LabChromeContext {
+  const lab = useLabContext();
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] lab chrome requires <LabStoreProvider>');
+  const slot = useStore(storeCtx.store, (s) => s.activeToolId);
+  const storeInstruments = useStore(storeCtx.store, (s) => s.instruments);
+  const activeToolId = resolveLabTool(slot, storeInstruments ?? lab.instruments);
+  const setLabTool = useStore(storeCtx.store, (s) => s.setLabTool);
+  return useMemo(
+    () => ({ ...lab, activeToolId, setActiveTool: setLabTool }),
+    [lab, activeToolId, setLabTool],
+  );
+}
+
+/** The lab's contributions for one region, in declaration order. */
+export function contributionsIn<TCtx = LabChromeContext>(
+  contributions: readonly LabContribution<TCtx>[],
+  region: LabRegion,
+): LabContribution<TCtx>[] {
+  return contributions.filter((c) => c.region === region);
+}
+
+/** The palette contributions a lab's `tools` stand for. Declaring a tool is
+ *  shorthand for contributing a palette item that writes the lab's tool
+ *  slot. */
+export function toolContributions(tools: readonly TrialTool[]): LabContribution[] {
+  return tools.map((t) => ({
+    id: t.id,
+    region: 'palette' as const,
+    ...(t.group === undefined ? {} : { group: t.group }),
+    item: {
+      icon: t.icon,
+      label: t.label,
+      ...(t.shortcut === undefined ? {} : { shortcut: t.shortcut }),
+    },
+  }));
+}
+
+/** Everything the lab's chrome renders, from both of the ways a lab declares
+ *  it. Tools and contributions share one id namespace, so a tool colliding
+ *  with a contribution throws here rather than one of them silently losing. */
+export function labContributions(
+  tools: readonly TrialTool[] | undefined,
+  chrome: readonly LabContribution[] | undefined,
+): LabContribution[] {
+  return mergeContributions<LabContribution>(toolContributions(tools ?? []), [...(chrome ?? [])]);
+}
+
+/** Props shared by the lab's region mounts. Each takes the lab's whole
+ *  contribution list and lays out the part addressed to it. */
+export interface LabRegionProps {
+  contributions: readonly LabContribution[];
+}
+
+/** The lab's action bar, in the shell header beside the title. */
+export function LabHeaderRegion({ contributions }: LabRegionProps) {
+  const ctx = useLabChromeContext();
+  return (
+    <ToolbarRegion
+      region="header"
+      label="Lab actions"
+      contributions={contributionsIn(contributions, 'header')}
+      ctx={ctx}
+    />
+  );
+}
+
+function LabSections({ contributions, region }: LabRegionProps & { region: 'sidebar' | 'aside' }) {
+  const lab = useLabChromeContext();
+  const [collapsedSections, setFolds] = usePersistedState<Record<string, boolean>>(
+    `lk-lab-${region}-folds`,
+    {},
+    { scope: 'lab' },
+  );
+  const ctx = useMemo(
+    () => ({
+      ...lab,
+      collapsedSections,
+      setSectionCollapsed: (key: string, collapsed: boolean) =>
+        setFolds((f) => ({ ...f, [key]: collapsed })),
+    }),
+    [lab, collapsedSections, setFolds],
+  );
+  return (
+    <SidebarRegion
+      contributions={contributionsIn(contributions, region)}
+      ctx={ctx}
+      region={region}
+    />
+  );
+}
+
+/** The lab's sidebar sections. Fold state is a lab-scoped persisted value, so it
+ *  survives a reload in a stored lab and lasts the session in an unstored one. */
+export function LabSidebarRegion({ contributions }: LabRegionProps) {
+  return <LabSections contributions={contributions} region="sidebar" />;
+}
+
+/** The lab's aside sections, on the far side of the workspace from the sidebar.
+ *  Fold state persists the way the sidebar's does. */
+export function LabAsideRegion({ contributions }: LabRegionProps) {
+  return <LabSections contributions={contributions} region="aside" />;
+}
+
+/** The lab's readouts, in the shell footer below the workspace. */
+export function LabFooterRegion({ contributions }: LabRegionProps) {
+  const ctx = useLabChromeContext();
+  return (
+    <StatusRegion
+      region="footer"
+      contributions={contributionsIn(contributions, 'footer')}
+      ctx={ctx}
+    />
+  );
+}

package/src/chrome/builtins.test.ts

@@ -28,6 +28,7 @@ const ctx: TrialChromeContext = {
   configFields: [],
   configSchema: fromConfigFields([]),
   config: {},
+  auto: new Set<string>(),
   setConfig: () => {},
   savedSnapshots: [],
   saveSnapshot: () => {},

package/src/chrome/builtins.tsx

@@ -12,11 +12,10 @@ import {
 } from '@weasel-js/ui';
 import { ExportMenu } from '../annotations/ExportMenu';
 import { MarkList } from '../annotations/MarkList';
-import { ANNOTATION_TOOLS } from '../annotations/toolMap';
 import type { ControlRenderer } from '../config/types';
 import { ControlPanel } from '../controls/ControlPanel';
 import type { Instrument } from '../instrument/types';
-import { Select } from '../passthrough/weasel-ui';
+import { MenuButton } from '../passthrough/weasel-ui';
 import { FpsMeter } from '../primitives/FpsMeter';
 import { ScaleIndicator } from '../primitives/ScaleIndicator';
 import { ZoomControl } from '../primitives/ZoomControl';
@@ -82,16 +81,10 @@ export function builtinContributions(
     });
   }
 
-  // Declaring `annotations` provides the drawing palette, the way declaring
-  // `tools` provides the instrument's own; both write the same tool slot.
   // A tool id shares the contribution namespace, so a tool called `close`
-  // collides with the built-in close button and throws — and so do two tools
-  // of the same name from these two sources.
-  const tools = [
-    ...(instrument.annotations ? ANNOTATION_TOOLS : []),
-    ...(instrument.tools?.tools ?? []),
-  ];
-  for (const t of tools) {
+  // collides with the built-in close button and throws. Annotation tools are
+  // not here: the lab's rail carries them.
+  for (const t of instrument.tools?.tools ?? []) {
     out.push({
       id: t.id,
       region: 'palette',
@@ -116,7 +109,7 @@ export function builtinContributions(
 
   // Zoom acts on the view of the trial, so it is a viewport control. A trial
   // holding a non-2D view reports zoom as null and gets none of this.
-  if (instrument.canvas != null && zoom !== null) {
+  if ((instrument.canvas != null || instrument.stage != null) && zoom !== null) {
     out.push({
       id: 'zoom-out',
       region: 'viewport',
@@ -153,15 +146,17 @@ export function builtinContributions(
       id: 'scale',
       region: 'status',
       group: 'view',
-      render: () => <ScaleIndicator />,
-    });
-    out.push({
-      id: 'fps',
-      region: 'status',
-      group: 'view',
-      end: true,
-      render: () => <FpsMeter />,
+      render: (c) => <ScaleIndicator zoom={c.zoom ?? 1} />,
     });
+    if (instrument.canvas != null) {
+      out.push({
+        id: 'fps',
+        region: 'status',
+        group: 'view',
+        end: true,
+        render: () => <FpsMeter />,
+      });
+    }
   }
 
   if (instrument.annotations != null) {
@@ -194,6 +189,7 @@ export function builtinContributions(
           <ControlPanel
             schema={ctx.configSchema}
             config={ctx.config as Record<string, unknown>}
+            auto={ctx.auto}
             setConfig={(key, value) => ctx.setConfig(String(key), value)}
             renderers={controls}
             collapsed={groupFolds(ctx.collapsedSections, 'settings')}
@@ -205,24 +201,18 @@ export function builtinContributions(
   }
 
   if (ctx.savedSnapshots.length > 0) {
-    // A picker is not an icon button, so it takes the render escape. Held at
-    // `selectedKey={null}` so it stays a "load one" action rather than
-    // drifting into a display of what was loaded last.
+    // A menu is not an icon button, so it takes the render escape.
     out.push({
       id: 'snapshot-load',
       region: 'toolbar',
       group: 'trial',
       end: true,
       render: (c) => (
-        <Select
-          className="lk-toolbar__load-select"
+        <MenuButton
           aria-label="Load snapshot"
-          placeholder="Load…"
-          selectedKey={null}
-          options={c.savedSnapshots.map((sn) => ({ value: sn.id, label: sn.name }))}
-          onSelectionChange={(id) => {
-            if (id != null) c.loadSnapshot(String(id));
-          }}
+          label="Load…"
+          items={c.savedSnapshots.map((sn) => ({ value: sn.id, label: sn.name }))}
+          onAction={(id) => c.loadSnapshot(id)}
         />
       ),
     });

package/src/chrome/index.ts

@@ -1,4 +1,16 @@
 export { builtinContributions } from './builtins';
+export type { LabRegionProps } from './LabChrome';
+export {
+  contributionsIn,
+  LabAsideRegion,
+  LabFooterRegion,
+  LabHeaderRegion,
+  LabSidebarRegion,
+  labContributions,
+  toolContributions,
+  useLabChromeContext,
+} from './LabChrome';
+export type { LabChromeContext, LabContribution, LabRegion } from './labTypes';
 export { mergeContributions, suppressContributions } from './merge';
 export type { PaletteRegionProps } from './regions/PaletteRegion';
 export { PaletteRegion } from './regions/PaletteRegion';
@@ -13,11 +25,15 @@ export { ToolbarRegion } from './regions/ToolbarRegion';
 export type { ViewportRegionProps } from './regions/ViewportRegion';
 export { ViewportRegion } from './regions/ViewportRegion';
 export type {
+  ContributionBase,
   IconComponent,
+  RegionContribution,
   SidebarSection,
+  SidebarSlotContext,
   StatusReadout,
   ToolbarItem,
   ToolItem,
+  ToolSlotContext,
   TrialChromeContext,
   TrialContribution,
   TrialRegion,

package/src/chrome/labRegions.test.tsx

@@ -0,0 +1,208 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+import { LabShell } from '../lab/LabShell';
+import type { LabChromeContext, LabContribution } from './labTypes';
+import { ToolbarRegion } from './regions/ToolbarRegion';
+
+const Glyph = () => <svg />;
+const bare: Instrument = {
+  name: 'Bare',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+
+function silenceRenderError(): void {
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+}
+
+describe('lab-level chrome', () => {
+  it('renders a header contribution beside the lab header', () => {
+    const contribution: LabContribution = {
+      id: 'publish',
+      region: 'header',
+      item: { icon: Glyph, label: 'Publish', onActivate: () => {} },
+    };
+    render(
+      <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', () => {
+    const contribution: LabContribution = {
+      id: 'another',
+      region: 'header',
+      item: {
+        icon: Glyph,
+        label: 'Another',
+        onActivate: (ctx) => ctx.addTrial('Bare'),
+      },
+    };
+    render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
+    );
+    expect(screen.getAllByLabelText(/^Trial /)).toHaveLength(1);
+    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', () => {
+    const contribution: LabContribution = {
+      id: 'measure',
+      region: 'palette',
+      item: { icon: Glyph, label: 'Measure' },
+    };
+    render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
+    );
+    const button = screen.getByRole('button', { name: 'Measure' });
+    fireEvent.click(button);
+    expect(screen.getByRole('button', { name: 'Measure' })).toHaveAttribute('aria-current', 'true');
+  });
+
+  it('gives a palette contribution the whole lab context, not a tool slot alone', () => {
+    // The shape the `as unknown as TrialChromeContext` cast used to fake: a
+    // contribution reading anything past the tool slot got `undefined`.
+    const seen: LabChromeContext[] = [];
+    const contribution: LabContribution = {
+      id: 'readout',
+      region: 'palette',
+      render: (ctx) => {
+        seen.push(ctx);
+        return <span>{`${ctx.trials.length} trial(s), mode ${ctx.mode}`}</span>;
+      },
+    };
+    render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
+    );
+    expect(screen.getByText('1 trial(s), mode auto')).toBeInTheDocument();
+    expect(seen[0]?.activeToolId).toBeNull();
+    expect(typeof seen[0]?.saveSnapshot).toBe('function');
+  });
+
+  it('renders a footer contribution', () => {
+    const contribution: LabContribution = {
+      id: 'count',
+      region: 'footer',
+      item: { text: 'idle' },
+    };
+    render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[contribution]} />,
+    );
+    expect(screen.getByText('idle')).toBeInTheDocument();
+  });
+
+  it('throws when two lab contributions share an id', () => {
+    silenceRenderError();
+    const clash: LabContribution[] = [
+      { id: 'same', region: 'header', item: { icon: Glyph, label: 'One', onActivate: () => {} } },
+      { id: 'same', region: 'footer', item: { text: 'two' } },
+    ];
+    expect(() =>
+      render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={clash} />),
+    ).toThrow(/duplicate contribution id "same"/);
+  });
+
+  it('keeps the lab tool slot and lab palette contributions in one namespace', () => {
+    silenceRenderError();
+    const clash: LabContribution = {
+      id: 'pick',
+      region: 'palette',
+      item: { icon: Glyph, label: 'Mine' },
+    };
+    expect(() =>
+      render(
+        <Lab
+          title="T"
+          instruments={[bare]}
+          defaultInstrument="Bare"
+          tools={[{ id: 'pick', label: 'Pick', icon: Glyph }]}
+          labChrome={[clash]}
+        />,
+      ),
+    ).toThrow(/duplicate contribution id "pick"/);
+  });
+});
+
+describe('lab sidebar region', () => {
+  const tree: LabContribution = {
+    id: 'tree',
+    region: 'sidebar',
+    item: { title: 'Stories', body: <p>story list</p> },
+  };
+
+  it('renders a section beside the workspace', () => {
+    const { container } = render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" labChrome={[tree]} />,
+    );
+    expect(screen.getByText('story list')).toBeInTheDocument();
+    expect(container.querySelector('.lk-lab__sidebar')).not.toBeNull();
+    expect(screen.getByRole('separator', { name: /lab sidebar/i })).toBeInTheDocument();
+  });
+
+  it('folds a section', () => {
+    render(<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]} />);
+    expect(screen.queryByRole('button', { name: 'Undock Stories' })).toBeNull();
+  });
+
+  it('hands a render contribution the lab context', () => {
+    const seen: LabChromeContext[] = [];
+    const probe: LabContribution = {
+      id: 'probe',
+      region: 'sidebar',
+      render: (ctx) => {
+        seen.push(ctx);
+        return <p>probe</p>;
+      },
+    };
+    render(<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" />);
+    expect(container.querySelector('.lk-lab__panes')).toBeNull();
+  });
+});
+
+describe('lab chrome without <Lab>', () => {
+  // The rail `apps/theme-editor` mounts: `<LabShell>` with no trial runtime
+  // above it, so the context handed to `onActivate` is the consumer's own.
+  interface RailCtx {
+    undo: () => void;
+  }
+
+  it('renders a contribution typed against a consumer context and hands it back', () => {
+    const undo = vi.fn();
+    const ctx: RailCtx = { undo };
+    const rail: readonly LabContribution<RailCtx>[] = [
+      {
+        id: 'undo',
+        region: 'header',
+        item: { icon: Glyph, label: 'Undo', showLabel: true, onActivate: (c) => c.undo() },
+      },
+    ];
+    render(
+      <LabShell
+        title="Palette lab"
+        header={
+          <ToolbarRegion region="header" label="Lab actions" contributions={rail} ctx={ctx} />
+        }
+      >
+        <div />
+      </LabShell>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Undo' }));
+    expect(undo).toHaveBeenCalledTimes(1);
+  });
+});

package/src/chrome/labTypes.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+import type { LabContextValue } from '../lab/LabContext';
+import type {
+  ContributionBase,
+  SidebarSection,
+  StatusReadout,
+  ToolbarItem,
+  ToolItem,
+  ToolSlotContext,
+} from './types';
+
+/**
+ * A named position in the lab's own chrome — a box the shell owns, outside any
+ * one trial. `header` and `footer` are the shell's two bars, named as
+ * `<LabShell>` names them; `palette` is the tool rail down the side of the
+ * workspace; `sidebar` is a column of sections left of the tool rail.
+ */
+export type LabRegion = 'header' | 'palette' | 'sidebar' | 'aside' | 'footer';
+
+/**
+ * Everything a lab-level contribution can read and command: the lab's own
+ * state and operations, plus the lab's tool slot — which every trial whose
+ * instrument declares no tools of its own reflects and writes.
+ */
+export interface LabChromeContext extends LabContextValue, ToolSlotContext {}
+
+/**
+ * A contribution to the lab's chrome. Shaped as `TrialContribution` is, and
+ * merged and suppressed by the same rules, but keyed to the lab's regions and
+ * rendered with the lab's context. Supplying `render` instead of `item` opts
+ * out of the region's layout.
+ *
+ * `TCtx` is what the chrome hands a handler. It defaults to `LabChromeContext`,
+ * which is what `<Lab>` renders its regions with; a consumer mounting the
+ * regions under a bare `<LabShell>` names whatever it passes as `ctx` instead.
+ */
+export type LabContribution<TCtx = LabChromeContext> =
+  | (ContributionBase & {
+      region: 'header';
+      item: ToolbarItem<TCtx>;
+      render?: never;
+    })
+  | (ContributionBase & { region: 'palette'; item: ToolItem; render?: never })
+  | (ContributionBase & { region: 'sidebar' | 'aside'; item: SidebarSection; render?: never })
+  | (ContributionBase & { region: 'footer'; item: StatusReadout; render?: never })
+  | (ContributionBase & {
+      region: LabRegion;
+      item?: never;
+      render: (ctx: TCtx) => ReactNode;
+    });

package/src/chrome/merge.ts

@@ -1,5 +1,3 @@
-import type { TrialContribution } from './types';
-
 /**
  * Concatenate contribution bundles into one list, preserving order — order
  * decides how a region lays its contributions out, so it is part of the
@@ -8,10 +6,10 @@ import type { TrialContribution } from './types';
  * Throws on a duplicate id rather than dropping one: a contribution silently
  * losing to a later bundle is the failure a registry exists to prevent.
  */
-export function mergeContributions(
-  ...bundles: readonly TrialContribution[][]
-): TrialContribution[] {
-  const out: TrialContribution[] = [];
+export function mergeContributions<T extends { id: string }>(
+  ...bundles: readonly (readonly T[])[]
+): T[] {
+  const out: T[] = [];
   const seen = new Set<string>();
   for (const bundle of bundles) {
     for (const entry of bundle) {
@@ -34,10 +32,10 @@ export function mergeContributions(
  * silently suppresses nothing is the same class of bug as a duplicate id
  * silently winning.
  */
-export function suppressContributions(
-  bundle: readonly TrialContribution[],
+export function suppressContributions<T extends { id: string }>(
+  bundle: readonly T[],
   ids: readonly string[],
-): TrialContribution[] {
+): T[] {
   const present = new Set(bundle.map((c) => c.id));
   for (const id of ids) {
     if (!present.has(id)) {