@weasel-js/labkit 1.5.2 → 1.6.1

package/src/lab/LabBoundary.tsx

@@ -0,0 +1,56 @@
+import { ThemeContext } from '@weasel-js/theme/react';
+import type { ReactNode } from 'react';
+import { AnnotationsContext } from '../annotations/AnnotationsContext';
+import { AnnotationPreloadContext } from '../annotations/preload';
+import { CameraWheelContext } from '../canvas/CameraWheelContext';
+import { CanvasStackContext } from '../canvas/CanvasStackContext';
+import { LabStoreContext, TrialIdContext } from '../state/context';
+import { PersistenceContext } from '../state/Persistence';
+import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
+import { TrialDragContext } from '../trial/TrialDragContext';
+import { LabContext } from './LabContext';
+import { PanelHostContext } from './panelHost';
+
+/** Props for `<LabBoundary>`. */
+export interface LabBoundaryProps {
+  children: ReactNode;
+}
+
+/**
+ * Renders its children as though no lab, trial or theme were above them: every context a `<Lab>` or a
+ * `<Trial>` publishes reads as absent below it, so a labkit piece mounted inside a trial behaves the way it
+ * does on a bare page. A `<LabRoot>` under it applies its own theme instead of deferring to the lab's, and a
+ * `usePersistedState` under it keeps local state instead of writing into the enclosing lab's records.
+ *
+ * For a host that shows arbitrary content inside a trial, such as a component workshop; a lab's own chrome
+ * never needs it.
+ */
+export function LabBoundary({ children }: LabBoundaryProps) {
+  return (
+    <LabStoreContext.Provider value={null}>
+      <PersistenceContext.Provider value={null}>
+        <AnnotationPreloadContext.Provider value={null}>
+          <LabContext.Provider value={null}>
+            <PanelHostContext.Provider value={null}>
+              <SurfaceContext.Provider value={null}>
+                <SurfaceCanvasContext.Provider value={{ over: null, under: null }}>
+                  <TrialIdContext.Provider value={null}>
+                    <AnnotationsContext.Provider value={null}>
+                      <CameraWheelContext.Provider value={null}>
+                        <CanvasStackContext.Provider value={null}>
+                          <TrialDragContext.Provider value={null}>
+                            <ThemeContext.Provider value={null}>{children}</ThemeContext.Provider>
+                          </TrialDragContext.Provider>
+                        </CanvasStackContext.Provider>
+                      </CameraWheelContext.Provider>
+                    </AnnotationsContext.Provider>
+                  </TrialIdContext.Provider>
+                </SurfaceCanvasContext.Provider>
+              </SurfaceContext.Provider>
+            </PanelHostContext.Provider>
+          </LabContext.Provider>
+        </AnnotationPreloadContext.Provider>
+      </PersistenceContext.Provider>
+    </LabStoreContext.Provider>
+  );
+}

package/src/lab/LabHeader.tsx

@@ -1,22 +1,7 @@
-import { AddIcon, ModeAutoIcon, ModeDarkIcon, ModeLightIcon } from '@weasel-js/ui';
-import { MenuButton, ToggleBar } from '../passthrough/weasel-ui';
-import type { LabMode } from '../state/types';
+import { AddIcon } from '@weasel-js/ui';
+import { ColorModeControl, MenuButton } from '../passthrough/weasel-ui';
 import { useLabContext } from './LabContext';
 
-// The glyph is the segment's content and the word is its accessible name, so
-// the bar stays a three-way radiogroup announcing Auto / Light / Dark.
-const MODES = [
-  { value: 'auto' as LabMode, label: 'Auto', glyph: <ModeAutoIcon size={14} /> },
-  { value: 'light' as LabMode, label: 'Light', glyph: <ModeLightIcon size={14} /> },
-  { value: 'dark' as LabMode, label: 'Dark', glyph: <ModeDarkIcon size={14} /> },
-];
-
-const MODE_ITEMS = MODES.map(({ value, label, glyph }) => ({
-  value,
-  label: glyph,
-  ariaLabel: label,
-}));
-
 /** The controls `<Lab>` puts in its header: add a trial, and choose the color
  *  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
@@ -45,15 +30,11 @@ export function LabHeader({ addTrial = true }: { addTrial?: boolean }) {
         />
       )}
 
-      <ToggleBar
+      <ColorModeControl
         className="lk-lab-header__mode"
-        ariaLabel="Color mode"
         variant="flat"
-        items={MODE_ITEMS}
         value={lab.mode}
-        onChange={(next) => {
-          if (next) lab.setMode(next);
-        }}
+        onChange={lab.setMode}
       />
     </>
   );

package/src/lab/LabRoot.tsx

@@ -1,8 +1,7 @@
-import { ThemeProvider, useThemeOptional } from '@weasel-js/theme/react';
+import { ThemeProvider, useResolvedColorMode, 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 {
@@ -24,7 +23,7 @@ export interface LabRootProps {
  *  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 resolved = useResolvedColorMode(mode);
   const outer = useThemeOptional();
 
   // Overlays portal here rather than to the themed wrapper above: `.lk-root`

package/src/lab/LabShell.less

@@ -64,7 +64,6 @@
   min-height: 0;
   min-width: 0;
   overflow: auto;
-  padding: var(--lk-workspace-pad);
 }
 
 .lk-lab__body {

package/src/lab/LabShell.stories.tsx

@@ -86,3 +86,18 @@ export const HeaderControlsLineUp: Story = {
     await expect(middles).toEqual(middles.map(() => middles[0]));
   },
 };
+
+// One document serving its pages from the hash: the open route is the one the
+// switcher marks, and each entry is a link to its fragment.
+export const HashRoutedPages: Story = {
+  args: {
+    title: 'Registry',
+    pages: [
+      { href: '/app/', label: 'App' },
+      { href: '#/dev/tools', label: 'Tools' },
+      { href: '#/dev/registry', label: 'Registry' },
+    ],
+    path: '/app/#/dev/registry?entry=rect',
+    children: <p>Open the title to see the current route marked.</p>,
+  },
+};

package/src/lab/LabShell.test.tsx

@@ -47,6 +47,24 @@ describe('LabShell', () => {
     expect(container.querySelector('.lk-root')?.hasAttribute('data-wzl-portal-host')).toBe(true);
   });
 
+  test('holds the document title while mounted when asked to', () => {
+    document.title = 'before';
+    const { unmount } = render(
+      <LabShell title="t" documentTitle="Page title">
+        x
+      </LabShell>,
+    );
+    expect(document.title).toBe('Page title');
+    unmount();
+    expect(document.title).toBe('before');
+  });
+
+  test('leaves the document title alone by default', () => {
+    document.title = 'before';
+    render(<LabShell title="t">x</LabShell>);
+    expect(document.title).toBe('before');
+  });
+
   test('always applies lk-root class', () => {
     const { container } = render(<LabShell title="t">x</LabShell>);
     expect(container.querySelector('.lk-root')).not.toBeNull();

package/src/lab/LabShell.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import { type ReactNode, useEffect } from 'react';
 import type { LabMode } from '../state/types';
 import { LabRoot } from './LabRoot';
 import type { LabPage } from './LabSwitcher';
@@ -20,6 +20,9 @@ export interface LabShellProps {
   /** The path the switcher reads to mark the open page. Defaults to the
    *  current location. */
   path?: string;
+  /** Set as `document.title` while the shell is mounted, and the previous
+   *  title restored after. Omitted, the document's title is left alone. */
+  documentTitle?: string;
 }
 
 /** Page frame for a lab: a titled header, a body, and an optional footer,
@@ -33,7 +36,17 @@ export function LabShell({
   mode = 'auto',
   pages,
   path,
+  documentTitle,
 }: LabShellProps) {
+  useEffect(() => {
+    if (documentTitle === undefined) return;
+    const previous = document.title;
+    document.title = documentTitle;
+    return () => {
+      document.title = previous;
+    };
+  }, [documentTitle]);
+
   return (
     <LabRoot mode={mode} className="lk-shell">
       <header className="lk-shell-header">

package/src/lab/LabSwitcher.less

@@ -26,7 +26,7 @@
   // hyphen and the control becomes three ragged lines with a caret adrift.
   white-space: nowrap;
 
-  &:hover { color: var(--wzl-accent); }
+  &:hover { color: var(--wzl-accent-fg); }
 
   &:focus-visible {
     outline: 2px solid var(--wzl-focus-ring, currentColor);

package/src/lab/LabSwitcher.test.tsx

@@ -9,6 +9,8 @@ const PAGES = [
   { href: '/ingest', label: 'Ingestion' },
 ];
 
+const open2 = (name: string) =>
+  fireEvent.click(screen.getByRole('button', { name: new RegExp(name) }));
 const open = () => fireEvent.click(screen.getByRole('button', { name: /corpus stats/ }));
 
 describe('currentPage', () => {
@@ -27,6 +29,45 @@ describe('currentPage', () => {
   it('reports -1 for a page that is not one of them', () => {
     expect(currentPage('/bench', PAGES)).toBe(-1);
   });
+
+  // One document serving its pages from the hash: every href shares a path, so
+  // only the fragment can tell them apart.
+  const ROUTES = [
+    { href: '/app/', label: 'App' },
+    { href: '#/dev/tools', label: 'Tools' },
+    { href: '#/dev/registry', label: 'Registry' },
+  ];
+
+  it('tells hash routes on one document apart', () => {
+    expect(currentPage('/app/#/dev/registry', ROUTES)).toBe(2);
+    expect(currentPage('/app/#/dev/tools', ROUTES)).toBe(1);
+  });
+
+  it('matches a hash route through its own query and sub-routes', () => {
+    expect(currentPage('/app/#/dev/tools?bundle=minimal', ROUTES)).toBe(1);
+    expect(currentPage('/app/#/dev/tools/', ROUTES)).toBe(1);
+    expect(currentPage('/app/#/dev/registry/tool/rect', ROUTES)).toBe(2);
+    expect(currentPage('/app/#/dev/toolsets', ROUTES)).toBe(0);
+  });
+
+  it('falls back to the page without a hash when no route matches', () => {
+    expect(currentPage('/app/', ROUTES)).toBe(0);
+    expect(currentPage('/app/#/elsewhere', ROUTES)).toBe(0);
+  });
+
+  it('reads the hash off the current location by default', () => {
+    window.history.replaceState(null, '', '/app/#/dev/registry');
+    try {
+      render(<LabSwitcher title="Registry" pages={ROUTES} />);
+      open2('Registry');
+      expect(screen.getByRole('menuitem', { name: 'Registry' })).toHaveAttribute(
+        'aria-current',
+        'page',
+      );
+    } finally {
+      window.history.replaceState(null, '', '/');
+    }
+  });
 });
 
 describe('<LabSwitcher>', () => {

package/src/lab/LabSwitcher.tsx

@@ -2,7 +2,8 @@ import { useCallback, useEffect, useId, useRef, useState } from 'react';
 
 /** One page in a project's set of labs. */
 export interface LabPage {
-  /** The page's own URL, and how the switcher knows which page is open. */
+  /** The page's own URL, and how the switcher knows which page is open. A
+   *  hash route (`#/dev/tools`) names a page on the current document. */
   href: string;
   label: string;
 }
@@ -18,18 +19,39 @@ export interface LabSwitcherProps {
   className?: string;
 }
 
+/** A URL split into the document it names and the hash route on it, each
+ *  without its query, trailing slash or `.html`. */
+function locate(url: string): { doc: string; route: string } {
+  const hash = url.indexOf('#');
+  const trim = (part: string) => part.replace(/\?.*$/, '').replace(/\/$/, '');
+  return {
+    doc: trim(hash < 0 ? url : url.slice(0, hash)).replace(/\.html$/, ''),
+    route: hash < 0 ? '' : trim(url.slice(hash + 1)),
+  };
+}
+
 /** Which of `pages` a path is on, or -1.
  *
  *  Matched on the end of the path so a query string, a trailing slash or a
  *  leftover `.html` cannot lose it: a project whose dev server maps `/stats`
  *  to `stats.html` serves both spellings, and a bookmark from before the URLs
- *  lost their extension still resolves to the same page. */
+ *  lost their extension still resolves to the same page.
+ *
+ *  A page whose `href` carries a hash is a route on a single document and wins
+ *  when the path's hash is that route or one under it. A page without one
+ *  ignores the hash, so an in-page anchor does not lose it. */
 export function currentPage(path: string, pages: readonly LabPage[]): number {
-  const here = path
-    .replace(/[?#].*$/, '')
-    .replace(/\/$/, '')
-    .replace(/\.html$/, '');
-  return pages.findIndex((p) => here.endsWith(p.href.replace(/\.html$/, '')));
+  const here = locate(path);
+  const onDoc = (doc: string) => here.doc.endsWith(doc);
+  const routed = pages.findIndex((p) => {
+    if (!p.href.includes('#')) return false;
+    const page = locate(p.href);
+    return (
+      onDoc(page.doc) && (here.route === page.route || here.route.startsWith(`${page.route}/`))
+    );
+  });
+  if (routed >= 0) return routed;
+  return pages.findIndex((p) => !p.href.includes('#') && onDoc(locate(p.href).doc));
 }
 
 /** A project's lab title, doubling as the way to reach its other labs.
@@ -47,7 +69,7 @@ export function LabSwitcher({ title, pages, path, className }: LabSwitcherProps)
   const root = useRef<HTMLDivElement>(null);
   const menuId = useId();
   const here = currentPage(
-    path ?? (typeof window === 'undefined' ? '' : window.location.pathname),
+    path ?? (typeof window === 'undefined' ? '' : window.location.pathname + window.location.hash),
     pages,
   );
 

package/src/lab/index.ts

@@ -1,5 +1,6 @@
 export type { LabProps } from './Lab';
 export { Lab } from './Lab';
+export { LabBoundary, type LabBoundaryProps } from './LabBoundary';
 export type { LabContextValue } from './LabContext';
 export { LabContext, useLabContext } from './LabContext';
 export type { LabPaletteProps } from './LabPalette';

package/src/layers/AGENTS.md

@@ -1,33 +1,11 @@
 # Layers — Agent Guide
 
-The `src/layers/` directory implements the `<LayerList>` UI used by the `layers` instrument capability.
+`src/layers/` re-exports `<LayerList>` from `@weasel-js/ui`, along with the
+`layers` capability types. The component itself — rows, cards, nesting,
+selection, visibility, reorder — is documented at its source in
+`packages/ui/src/components/LayerList/`.
 
-## Files
-
-| File | Role |
-|---|---|
-| `LayerList.tsx` | Layer toggle/reorder list, flat or nested (sidebar widget) |
-| `LayerList.less` | Row styling, drag handle, pinned-row variant, subtree indent |
-| `LayerList.stories.tsx` | Flat and nested renderings |
-
-## Props
-
-```ts
-interface LayerListProps {
-  layers: LayerTreeNode[];                      // LayerDescriptor + { children?, defaultCollapsed? }
-  visibility: Record<string, boolean>;          // missing key → visible
-  onReorder: (newOrder: LayerTreeNode[]) => void;
-  onToggle: (id: string, visible: boolean) => void;
-  collapsedIds?: readonly string[];             // supplying it makes collapse controlled
-  onCollapsedChange?: (ids: string[]) => void;
-  className?: string;
-}
-```
-
-`LayerDescriptor` lives in `src/instrument/types.ts`; `LayerTreeNode` extends it
-in `LayerList.tsx`, so a plain `LayerDescriptor[]` is still a valid `layers`.
-
-## How it integrates
+## How the capability uses it
 
 The instrument declares layer ids:
 
@@ -35,53 +13,19 @@ The instrument declares layer ids:
 layers: { ids: ['grid', 'plants'] }
 ```
 
-`Trial.tsx` converts each id into a `LayerDescriptor` (with `label === id` by default) and tracks `visibility` and a derived `layerOrder` in local state. The order produced by `onReorder` is then applied to `instrument.canvas.layers` before they're passed to `<CanvasStack>`.
-
-There is no transitive coupling between `layers.ids` and `canvas.layers[].id` — the trial assumes the ids match. If you declare a layer in `canvas` that isn't in `layers.ids`, it stays in default order and is always visible.
-
-## `alwaysOn` semantics
-
-Setting `alwaysOn: true` on a `LayerDescriptor` does two things:
-
-1. The row renders with a 🔒 badge instead of a drag handle and visibility checkbox.
-2. The row is excluded from reorder operations — pinned rows always sort to the bottom of the rendered list.
-
-This is intended for legend/HUD layers that should never be toggled off. Visibility for pinned rows is **not** read from the `visibility` prop; they always render.
-
-## Nesting
-
-A node with `children` renders an expandable subtree. The expand control is
-`<Disclosure>` from `@weasel-js/ui` — the same twisty every other collapsible
-surface uses.
-
-Reordering is scoped to siblings: a drag moves a row within its own parent's
-child list and never reparents it. `onReorder` still receives the whole tree,
-with only that sibling group's order changed.
-
-The twisty column appears only when some node in the tree has children — a flat
-list renders exactly the rows it always did. Within a tree, childless rows get
-`.lk-layer-list__twisty-gap` so labels stay aligned down a level.
-
-Collapse is uncontrolled by default, seeded once from each node's
-`defaultCollapsed`. Pass `collapsedIds` to own it; `onCollapsedChange` fires
-either way.
-
-## Drag handle customization
-
-The drag handle is a button with class `lk-layer-list__handle` holding `<DragHandleGlyph>` (from `@weasel-js/ui`), the same grip `LayerStack` uses. Its padding is transparent and cancelled by an equal negative margin, so the grab target is larger than the drawn dots without widening the row. Row pitch — height plus row gap — is measured from the DOM when a drag starts, so restyling the row does not skew drag distance. It used to be a hardcoded `28`, which had already drifted from the rendered height by the time it was found.
-
-Pointer capture is acquired on `pointerdown` and released on `pointerup`, so dragging works across the document without requiring window-level listeners.
-
-## Empty state
-
-If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No layers". Trial already guards this case (`layerDescriptors.length > 0`) so the empty state is rare in practice.
+`Trial.tsx` turns each id into a `LayerDescriptor` (`label === id` unless the
+entry is a descriptor), keeps `visibility` and `layerOrder` in local state, and
+builds the list's items from them in the order the canvas draws. The order a
+drag produces is applied to `instrument.canvas.layers` before they reach
+`<CanvasStack>`, and each toggle and reorder emits `layers.toggle` /
+`layers.reorder` on the bus.
 
-## When to fork
+`layers.ids` and `canvas.layers[].id` are assumed to match. A canvas layer not
+in `layers.ids` keeps its default order and is always visible.
 
-Fork this component if you need:
-- Multi-select reorder (current implementation is single-row)
-- Right-click context menu
-- Reparenting by drag (nesting renders, but a drag stays within one parent)
-- Solo/mute UI common in DAW-style apps
+## `alwaysOn`
 
-It is self-contained: `LayerDescriptor` from instrument types and `Disclosure`/`DragHandleGlyph` from `@weasel-js/ui`.
+A descriptor with `alwaysOn: true` becomes a `locked` item, pinned below the
+rest: it shows a lock in place of the grip and has no visibility checkbox,
+cannot be dragged, and no drag can cross it. It always renders, whatever
+`visibility` says. Intended for legend and HUD layers.

package/src/layers/index.ts

@@ -1,3 +1,5 @@
+// LayerList lives in `@weasel-js/ui`. Named, not `export *` — a star re-export
+// of an external package emits no binding in the bundle.
+export type { LayerListItem, LayerListProps, LayerMove } from '@weasel-js/ui';
+export { LayerList, moveLayers } from '@weasel-js/ui';
 export type { LayerCapability, LayerDescriptor } from '../instrument/types';
-export type { LayerListProps, LayerTreeNode } from './LayerList';
-export { LayerList } from './LayerList';

package/src/loupe/AGENTS.md

@@ -14,7 +14,7 @@ This directory binds that model to a labkit trial and draws it.
 | `types.ts` | `LoupeCapability`, and `resolveLoupe` filling in every default |
 | `useLoupe.ts` | The model over a host element, and pointer aiming |
 | `loupeActions.ts` | `loupe.peek` and `loupe.magnify`, as `Action` descriptors |
-| `LoupeGestures.tsx` | Registers those and mounts the dispatcher on the host |
+| `LoupeGestures.tsx` | Registers those, and mounts a dispatcher on the host when no camera has one there |
 | `TrialLoupe.tsx` | Picks the painter and mounts the lens |
 | `LoupeBubble.tsx` | The circular clip, positioned on the aim |
 | `CanvasLoupe.tsx` | Painter for a `<CanvasStack>` |
@@ -46,11 +46,12 @@ StrictMode mounts / unmounts / mounts every effect — so disposing in the
 cleanup leaves a magnifier that draws but silently ignores every aim. It owns
 no resources; unmounting only reports the lens gone.
 
-**The wheel is taken from pan/zoom by declining it, not by capturing it.**
-`loupe.magnify`'s `enabled` returns a disabled reason while the lens is down, so
-the dispatcher leaves the event unhandled and `usePanZoom` — a React handler on
-the same element — sees it as usual. While the lens is up the action fires, the
-dispatcher stops propagation, and React's root listener never runs.
+**The wheel is taken from the camera by rank, and handed back by declining.**
+In a trial the loupe's actions join the camera's dispatcher (`CameraInput`).
+`loupe.magnify` sits in the hotkey tier, so while the lens is up it outranks
+the camera's wheel zoom; while it is down its `enabled` returns a disabled
+reason and the dispatcher falls through to the zoom. Outside a camera — the DOM
+`.lk-trial__loupe-host` — `<LoupeGestures>` mounts a dispatcher of its own.
 
 **Aiming is a plain listener because a hover is not a gesture.**
 `GESTURE_DESCRIPTORS` names no continuous-motion gesture, so `pointermove` /

package/src/loupe/LoupeGestures.tsx

@@ -1,7 +1,7 @@
 /**
- * Mounts the gesture dispatcher on a loupe's host and registers the loupe's
- * actions on it, so the peek key and the wheel route the way every other
- * weasel binding does.
+ * Registers the loupe's actions, and mounts the gesture dispatcher on the
+ * loupe's host when no camera already has one there, so the peek key and the
+ * wheel route the way every other weasel binding does.
  *
  * Three of the dispatcher's four element channels are off. Only `wheel` is
  * wanted here; `contextMenu` suppresses the native menu unconditionally and
@@ -14,7 +14,8 @@ import {
   useActionsRegistry,
   useGestureDispatcher,
 } from '@weasel-js/core';
-import { type RefObject, useEffect, useMemo } from 'react';
+import { type RefObject, useContext, useEffect, useMemo } from 'react';
+import { CameraContext } from '../canvas/CameraInput';
 import { createLoupeActions, type LoupeInputApi } from './loupeActions';
 
 /** Props for `<LoupeGestures>`. */
@@ -35,7 +36,8 @@ function LoupeDispatch({
   input,
   peekKey,
   registry,
-}: LoupeGesturesProps & { registry: ActionsRegistry }) {
+  ownDispatcher,
+}: LoupeGesturesProps & { registry: ActionsRegistry; ownDispatcher: boolean }) {
   const actions = useMemo(() => createLoupeActions(input, peekKey), [input, peekKey]);
 
   useEffect(() => {
@@ -50,18 +52,21 @@ function LoupeDispatch({
     actions: registry,
     toolsById: NO_TOOLS,
     channels: CHANNELS,
+    enabled: ownDispatcher,
   });
 
   return null;
 }
 
 /**
- * The loupe's input, routed. Render it inside a `<WeaselProvider isolate>` —
- * with no registry in scope it renders nothing rather than registering
- * actions that could never fire.
+ * The loupe's input, routed. Inside a camera (`<CanvasStack>`, `<Stage>`) its
+ * actions join the camera's dispatcher, which already listens on the host;
+ * elsewhere it mounts a dispatcher of its own. With no registry in scope it
+ * renders nothing rather than registering actions that could never fire.
  */
 export function LoupeGestures(props: LoupeGesturesProps) {
   const registry = useActionsRegistry();
+  const camera = useContext(CameraContext);
   if (!registry) return null;
-  return <LoupeDispatch {...props} registry={registry} />;
+  return <LoupeDispatch {...props} registry={registry} ownDispatcher={camera === null} />;
 }

package/src/loupe/TrialLoupe.tsx

@@ -1,5 +1,5 @@
-import { WeaselProvider } from '@weasel-js/core';
 import { type RefObject, useContext, useMemo } from 'react';
+import { CameraScope } from '../canvas/CameraInput';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
 import type { WorldSpec } from '../canvas/worldSpec';
 import type { ViewTransform } from '../instrument/types';
@@ -63,12 +63,12 @@ export function TrialLoupe({
 
   // The gestures mount outside the visibility gate: hold-to-peek is what
   // raises a lens that is down, so its binding has to be live while it is.
-  // One isolated scope per loupe, for the reason `<AnnotationOverlay>` gives
-  // — an actions registry holds one dispatcher.
+  // In a trial they join the trial's scope, and with it the camera's
+  // dispatcher; outside one, `<CameraScope>` gives them an isolated scope.
   const gestures = (
-    <WeaselProvider isolate>
+    <CameraScope>
       <LoupeGestures hostRef={host} input={loupe.input} peekKey={capability.peekKey ?? null} />
-    </WeaselProvider>
+    </CameraScope>
   );
 
   if (!loupe.visible) return gestures;

package/src/loupe/index.ts

@@ -1,3 +1,4 @@
+export type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
 export type { CanvasLoupeProps } from './CanvasLoupe';
 export { CanvasLoupe } from './CanvasLoupe';
 export type { LensCamera, SourceRect } from './canvasLens';

package/src/loupe/loupeActions.ts

@@ -21,8 +21,8 @@ export const WHEEL_RATE = 0.002;
  *  registration. */
 export interface LoupeInputApi {
   /** Whether the lens is up. The wheel belongs to the loupe only while it is;
-   *  otherwise `loupe.magnify` declines and the dispatcher leaves the event
-   *  unhandled, which is what hands it back to the lab's own pan/zoom. */
+   *  otherwise `loupe.magnify` declines and the dispatcher falls through to
+   *  the trial camera's zoom. */
   shown: () => boolean;
   /** Raise or drop the hold-to-peek flag. */
   setPeeking: (on: boolean) => void;
@@ -43,6 +43,10 @@ export function createLoupeActions(
     id: LOUPE_MAGNIFY_ID,
     label: 'Magnify (loupe)',
     group: 'loupe',
+    // Hotkey scope, so while the lens is up it outranks the trial camera's
+    // wheel zoom on the same dispatcher; while it is down `enabled` declines
+    // and the zoom runs.
+    scope: 'hotkey',
     // Every modifier optional: the lens claims the wheel whenever it is up,
     // which is what the hand-rolled capture-phase listener did. A bare spec
     // would forbid modifiers and hand Cmd+wheel back to the lab mid-peek.

package/src/overview/AGENTS.md

@@ -0,0 +1,38 @@
+# Overview — Agent Guide
+
+`src/overview/` is `@weasel-js/labkit/overview`: `<TrialOverview>`, a trial's
+whole content in a floating panel. Its own bundle entry; nothing in the main
+bundle imports it.
+
+| File | Role |
+|---|---|
+| `TrialOverview.tsx` | The panel: content, chrome canvas, and its own dispatcher |
+| `OverviewMarks.tsx` | Every annotation target's marks, read-only, as SVG |
+
+## How it reads the trial
+
+Only through `CameraContext`, which `<CanvasStack>` and `<Stage>` set: the
+camera as a weasel `ViewApi` over frame-local coordinates, the frame, the
+camera's element, a stage's content rect. A canvas instrument's layers come
+from `CanvasStackContext`, marks from `AnnotationsContext`. So it works
+anywhere inside a camera — `stage.overlay`, or a canvas instrument's `render`.
+
+Input is core's `minimap.center` / `minimap.pan` on a dispatcher of its own,
+with the camera as `rootView`; the pointer store is the trial's, shared.
+
+## Traps
+
+**It sits inside the stage's element.** Every event that bubbles out of the box
+reaches the stage's dispatcher, the loupe's aim and the stage's pointer
+publisher. The box stops them; drop that and a drag in the overview also pans
+the stage, and the pointer flips between `'overview'` and `'stage'` each move.
+
+**Marks are placed by measuring.** A target's rect on the overview is its
+element's rect against the camera's element, through the camera — never the
+target's content size, which is the mark's world and not where it is drawn.
+jsdom measures zero; a test mocks `getBoundingClientRect`, and the picture is a
+screenshot.
+
+**Never render the instrument's own `render` in it.** Its effects — a pane
+ref, an annotation target — would run twice. `render` is a separate, lighter
+copy the instrument supplies.