@weasel-js/labkit 1.4.4 → 1.5.1

package/src/surface/useTiledSurface.test.tsx

@@ -1,4 +1,4 @@
-import { act, render } from '@testing-library/react';
+import { act, render, renderHook } from '@testing-library/react';
 import { useEffect } from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { SurfaceFrame, SurfaceHandle } from './useTiledSurface';
@@ -286,4 +286,234 @@ describe('useTiledSurface', () => {
     flushFrames();
     expect(paint).toHaveBeenCalledTimes(1);
   });
+
+  /**
+   * The surface owner resizes the shared buffer from inside `onFrame`, which
+   * costs every tile its pixels. Both tests below are about the two ways that
+   * loss goes unrepaired.
+   */
+  describe('when the buffer loses its contents', () => {
+    it('keeps an invalidation the owner makes from inside onFrame', () => {
+      let handle: SurfaceHandle | null = null;
+      let claimAll = false;
+      function Owner() {
+        const surface = useTiledSurface({
+          onFrame: () => {
+            if (!claimAll) return;
+            claimAll = false;
+            // What `Lab` does after sizing the canvas: the buffer is blank, so
+            // every tile owes a repaint, not only the one that moved.
+            surface.invalidateAll();
+          },
+        });
+        handle = surface;
+        return (
+          <div
+            ref={(el) => {
+              if (!el) return;
+              stubBox(el, 0, 0, 800, 600);
+              surface.containerRef(el);
+            }}
+          >
+            <div
+              ref={(el) => {
+                if (!el) return;
+                stubBox(el, 0, 0, 400, 600);
+                surface.registerTile('a', el);
+              }}
+            />
+            <div
+              ref={(el) => {
+                if (!el) return;
+                stubBox(el, 400, 0, 400, 600);
+                surface.registerTile('b', el);
+              }}
+            />
+          </div>
+        );
+      }
+      render(<Owner />);
+      flushFrames();
+
+      const paintA = vi.fn();
+      act(() => {
+        handle?.registerPainter('a', paintA);
+        handle?.registerPainter('b', vi.fn());
+      });
+      flushFrames();
+      paintA.mockClear();
+
+      // Only b is dirty; the owner resizes the buffer during the frame, which
+      // blanks a as well.
+      claimAll = true;
+      act(() => handle?.invalidate('b'));
+      flushFrames();
+      flushFrames();
+
+      expect(paintA).toHaveBeenCalled();
+    });
+
+    it('tells the owner when the tile geometry changed, so it can clear', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
+      );
+      flushFrames();
+      frames.length = 0;
+
+      // A plain repaint leaves every tile where it was.
+      act(() => handle?.invalidate('a'));
+      flushFrames();
+      expect(frames[0]?.retiled).toBe(false);
+      frames.length = 0;
+
+      // A tile moving strands its old pixels in the gutter; nothing but the
+      // owner can clear those, and this is how it hears about it.
+      stubBox(getByTestId('b'), 300, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+      expect(frames[0]?.retiled).toBe(true);
+    });
+
+    it('runs every registered clear before any painter, and only on a re-tile', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
+      );
+      flushFrames();
+
+      const order: string[] = [];
+      const clearA = vi.fn(() => order.push('clearA'));
+      const clearB = vi.fn(() => order.push('clearB'));
+      act(() => {
+        handle?.registerClear('a', clearA);
+        handle?.registerClear('b', clearB);
+        handle?.registerPainter('a', () => order.push('paintA'));
+        handle?.registerPainter('b', () => order.push('paintB'));
+      });
+      flushFrames();
+      order.length = 0;
+      clearA.mockClear();
+
+      // A repaint of one tile leaves every other tile's pixels valid.
+      act(() => handle?.invalidate('a'));
+      flushFrames();
+      expect(clearA).not.toHaveBeenCalled();
+      expect(order).toEqual(['paintA']);
+      order.length = 0;
+
+      stubBox(getByTestId('b'), 300, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+
+      // Both tenants share the buffer, so both clears run — and a clear after
+      // a painter would erase the tile that just drew.
+      expect(order.slice(0, 2).sort()).toEqual(['clearA', 'clearB']);
+      expect(order.slice(2).sort()).toEqual(['paintA', 'paintB']);
+      expect(clearA).toHaveBeenCalledWith({ width: 800, height: 600 }, expect.any(Number));
+    });
+
+    it('keeps measuring while a tile is still moving, and stops when it settles', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
+      );
+      flushFrames();
+
+      const seen: number[] = [];
+      act(() => {
+        handle?.registerPainter('b', (rect) => seen.push(rect.x));
+      });
+
+      // A panel whose size is already final but whose position is still
+      // animating: `ResizeObserver` has nothing left to report, so the only
+      // thing that can catch the last 60px is the surface measuring again.
+      const b = getByTestId('b');
+      const stops = [340, 370, 400, 400, 400];
+      let call = 0;
+      vi.spyOn(b, 'getBoundingClientRect').mockImplementation(() => {
+        const left = stops[Math.min(call++, stops.length - 1)] ?? 0;
+        return {
+          left,
+          top: 0,
+          width: 400,
+          height: 600,
+          right: left + 400,
+          bottom: 600,
+          x: left,
+          y: 0,
+          toJSON: () => ({}),
+        } as DOMRect;
+      });
+
+      seen.length = 0;
+      act(() => handle?.invalidateRects());
+      // One flush per animation frame; nothing else invalidates in between.
+      flushFrames();
+      flushFrames();
+      flushFrames();
+      flushFrames();
+
+      expect(seen.at(-1)).toBe(400);
+    });
+
+    it('stops calling a clear that unregisters', () => {
+      const frames: SurfaceFrame[] = [];
+      let handle: SurfaceHandle | null = null;
+      const { getByTestId } = render(
+        <Harness
+          frames={frames}
+          onHandle={(h) => {
+            handle = h;
+          }}
+        />,
+      );
+      flushFrames();
+
+      const clear = vi.fn();
+      let off: (() => void) | undefined;
+      act(() => {
+        off = handle?.registerClear('a', clear);
+      });
+      stubBox(getByTestId('b'), 310, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+      expect(clear).toHaveBeenCalledTimes(1);
+
+      act(() => off?.());
+      stubBox(getByTestId('b'), 320, 0, 400, 600);
+      act(() => handle?.invalidateRects());
+      flushFrames();
+      expect(clear).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+
+describe('useTiledSurface handle identity', () => {
+  it('returns the same handle across renders', () => {
+    // A new handle per render reaches useSurfaceTile through context as a new
+    // ref callback, which unregisters and re-registers every tile and retiles.
+    const { result, rerender } = renderHook(() => useTiledSurface({ onFrame: () => {} }));
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
 });

package/src/surface/useTiledSurface.ts

@@ -1,5 +1,5 @@
 import { useVisibleRaf } from '@weasel-js/core';
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { composeRects, rectsEqual } from './composeRects';
 import type { Box, Rect } from './rect';
 
@@ -14,6 +14,11 @@ export interface SurfaceFrame {
   rects: ReadonlyMap<string, Rect>;
   dpr: number;
   size: { width: number; height: number };
+  /** The tile geometry changed this frame — a tile moved, resized, appeared or
+   *  went away, or the dpr did. Every tile is dirty on such a frame, but the
+   *  pixels a tile vacated are in no tile's scissor now, so the owner clears
+   *  the whole buffer. `<Lab>` does; a host owning its own surface must too. */
+  retiled: boolean;
 }
 
 /** The invalidators and the two ref callbacks that publish geometry. */
@@ -26,6 +31,12 @@ export interface SurfaceHandle {
    *  moved something a ResizeObserver cannot see. */
   invalidateRects: () => void;
   registerTile: (id: string, el: HTMLElement | null) => void;
+  /** Register a tenant's whole-buffer clear. Every one registered runs, before
+   *  any painter, on a frame where the tile geometry changed — the pixels a
+   *  tile vacated are in no scissor now, and only the context that drew them
+   *  can erase them. Backend-agnostic by necessity: labkit owns the canvas,
+   *  never the context. */
+  registerClear: (id: string, clear: SurfaceClear) => () => void;
   /** Subscribe a tile to the frames it is dirty on. A tile paints on its own
    *  loop, so this is how the surface wakes one: a resize of the shared buffer
    *  clears every tile, not only the one that moved. */
@@ -40,6 +51,10 @@ export interface SurfaceHandle {
  *  frame that dirtied it. */
 export type TilePainter = (rect: Rect, frame: SurfaceFrame) => void;
 
+/** Erase the whole shared buffer. Device pixels, because that is what a GL
+ *  viewport takes. */
+export type SurfaceClear = (size: { width: number; height: number }, dpr: number) => void;
+
 export interface UseTiledSurfaceOptions {
   onFrame: (frame: SurfaceFrame) => void;
 }
@@ -50,6 +65,7 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
   const rects = useRef(new Map<string, Rect>());
   const dirty = useRef(new Set<string>());
   const painters = useRef(new Map<string, TilePainter>());
+  const clears = useRef(new Map<string, SurfaceClear>());
   const needsMeasure = useRef(true);
   const observer = useRef<ResizeObserver | null>(null);
   const lastDpr = useRef(0);
@@ -80,13 +96,25 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
         dirty.current.clear();
         return;
       }
+      let retiled = false;
       if (needsMeasure.current) {
         needsMeasure.current = false;
-        if (measure()) for (const id of rects.current.keys()) dirty.current.add(id);
+        if (measure()) {
+          retiled = true;
+          for (const id of rects.current.keys()) dirty.current.add(id);
+          // Geometry that changed may still be moving: a panel whose size has
+          // settled while its position animates gives `ResizeObserver` nothing
+          // more to report, and the tile would hold the frame it was caught
+          // mid-flight at. Measure again next frame, and keep going until a
+          // measurement finds nothing moved.
+          needsMeasure.current = true;
+          schedule();
+        }
       }
       const dpr = globalThis.devicePixelRatio ?? 1;
       if (dpr !== lastDpr.current) {
         lastDpr.current = dpr;
+        retiled = true;
         for (const id of rects.current.keys()) dirty.current.add(id);
       }
       if (dirty.current.size === 0) return;
@@ -96,14 +124,27 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
         rects: new Map(rects.current),
         dpr,
         size: { width: box.width, height: box.height },
+        retiled,
       };
+      // Cleared before the owner runs, not after the painters: sizing the
+      // buffer blanks every tile, so the owner answers with `invalidateAll`,
+      // and a set cleared at the end of the frame would swallow it.
+      dirty.current.clear();
       onFrameRef.current(frame);
-      // After the owner, which is what resized the buffer this frame.
-      for (const id of frame.dirty) {
-        const rect = frame.rects.get(id);
-        if (rect) painters.current.get(id)?.(rect, frame);
+      // After the owner sized the buffer, before anything paints into it.
+      if (retiled) {
+        for (const clear of clears.current.values()) clear(frame.size, dpr);
       }
+      // After the owner, which is what resized the buffer this frame — and
+      // whatever it just dirtied paints now rather than a frame later.
+      const painting = new Set(frame.dirty);
+      for (const id of dirty.current) painting.add(id);
       dirty.current.clear();
+      const paintFrame: SurfaceFrame = { ...frame, dirty: painting };
+      for (const id of painting) {
+        const rect = frame.rects.get(id);
+        if (rect) painters.current.get(id)?.(rect, paintFrame);
+      }
     },
     // The host attaches its container through `containerRef`, which may land
     // well after this hook's first effect; the gate re-resolves it per request.
@@ -151,6 +192,13 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     [schedule],
   );
 
+  const registerClear = useCallback((id: string, clear: SurfaceClear) => {
+    clears.current.set(id, clear);
+    return () => {
+      if (clears.current.get(id) === clear) clears.current.delete(id);
+    };
+  }, []);
+
   const registerPainter = useCallback((id: string, paint: TilePainter) => {
     painters.current.set(id, paint);
     return () => {
@@ -187,13 +235,26 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     };
   }, [schedule, frameLoop]);
 
-  return {
-    invalidate,
-    invalidateAll,
-    invalidateRects,
-    registerTile,
-    registerPainter,
-    containerRef,
-    getContainer,
-  };
+  return useMemo(
+    () => ({
+      invalidate,
+      invalidateAll,
+      invalidateRects,
+      registerTile,
+      registerClear,
+      registerPainter,
+      containerRef,
+      getContainer,
+    }),
+    [
+      invalidate,
+      invalidateAll,
+      invalidateRects,
+      registerTile,
+      registerClear,
+      registerPainter,
+      containerRef,
+      getContainer,
+    ],
+  );
 }

package/src/theme/Interstellar.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import type { TokenName } from '@weasel-js/theme';
 import { useTheme } from '@weasel-js/theme/react';
 import {
@@ -18,7 +18,7 @@ const meta: Meta = {
       description: {
         component:
           'The interstellar theme: deep-space cosmic gradient + starscape backdrop, glass surfaces, Oswald display type, purple accent. ' +
-          'Authored as DTCG in `src/theme/interstellar.tokens.json` and loaded with `loadDTCG`; it extends the built-in weasel theme, overriding values rather than adding tokens.',
+          'A pins-only theme definition in `src/theme/interstellar.theme.json`, loaded with `defineTheme`; it extends the built-in weasel theme, overriding values rather than adding tokens.',
       },
     },
   },
@@ -55,16 +55,16 @@ const ACCENT_TOKENS: Swatch[] = [
 ];
 
 const PALETTE_TOKENS: Swatch[] = [
+  { name: 'fuchsia', cssVar: '--wzl-swatch-fuchsia' },
   { name: 'green', cssVar: '--wzl-swatch-green' },
-  { name: 'pink', cssVar: '--wzl-swatch-pink' },
-  { name: 'cyan', cssVar: '--wzl-swatch-cyan' },
-  { name: 'gold', cssVar: '--wzl-swatch-gold' },
+  { name: 'sky', cssVar: '--wzl-swatch-sky' },
   { name: 'amber', cssVar: '--wzl-swatch-amber' },
+  { name: 'teal', cssVar: '--wzl-swatch-teal' },
+  { name: 'red', cssVar: '--wzl-swatch-red' },
+  { name: 'blue', cssVar: '--wzl-swatch-blue' },
+  { name: 'citron', cssVar: '--wzl-swatch-citron' },
+  { name: 'rose', cssVar: '--wzl-swatch-rose' },
   { name: 'violet', cssVar: '--wzl-swatch-violet' },
-  { name: 'mint', cssVar: '--wzl-swatch-mint' },
-  { name: 'sky', cssVar: '--wzl-swatch-sky' },
-  { name: 'orange', cssVar: '--wzl-swatch-orange' },
-  { name: 'magenta', cssVar: '--wzl-swatch-magenta' },
 ];
 
 function SwatchGrid({ tokens, title }: { tokens: readonly Swatch[]; title: string }) {

package/src/theme/interstellar.test.ts

@@ -1,11 +1,20 @@
-import { resolveTheme } from '@weasel-js/theme';
+import { resolveTheme, THEME_SOURCES, type ThemeDefinition } from '@weasel-js/theme';
+import { derive } from '@weasel-js/theme/engine';
 import { describe, expect, it } from 'vitest';
 import { interstellarTheme } from './interstellar';
+import definition from './interstellar.theme.json' with { type: 'json' };
 
 describe('interstellarTheme', () => {
+  it('derives as a definition extending weasel with no issues', () => {
+    const lookup = (name: string) => (name === 'weasel' ? THEME_SOURCES.weasel : undefined);
+    for (const mode of ['dark', 'light']) {
+      expect(derive(definition as ThemeDefinition, { mode }, lookup).issues, mode).toEqual([]);
+    }
+  });
+
   it('extends weasel and resolves both modes', () => {
-    const dark = resolveTheme(interstellarTheme, 'dark');
-    const light = resolveTheme(interstellarTheme, 'light');
+    const dark = resolveTheme(interstellarTheme, { mode: 'dark' });
+    const light = resolveTheme(interstellarTheme, { mode: 'light' });
 
     // Values carried over verbatim from the retired Less.
     expect(dark['--wzl-surface']).toBe('#0a0a14');
@@ -15,7 +24,7 @@ describe('interstellarTheme', () => {
 
     // Inherited from weasel — interstellar overrides values, not the token set.
     expect(dark['--wzl-space-md']).toBe('12px');
-    expect(dark['--wzl-swatch-cyan']).toBe('#00dfff');
+    expect(dark['--wzl-swatch-teal']).toBe('#3ee1cb');
 
     // Deliberate divergences from the base.
     expect(dark['--wzl-radius-md']).toBe('6px');
@@ -24,7 +33,9 @@ describe('interstellarTheme', () => {
   });
 
   it('carries the cosmic backdrop in dark and drops it in light', () => {
-    expect(resolveTheme(interstellarTheme, 'dark')['--wzl-backdrop']).toContain('radial-gradient');
-    expect(resolveTheme(interstellarTheme, 'light')['--wzl-backdrop']).toBe('none');
+    expect(resolveTheme(interstellarTheme, { mode: 'dark' })['--wzl-backdrop']).toContain(
+      'radial-gradient',
+    );
+    expect(resolveTheme(interstellarTheme, { mode: 'light' })['--wzl-backdrop']).toBe('none');
   });
 });

package/src/theme/interstellar.theme.json

@@ -0,0 +1,180 @@
+{
+  "name": "interstellar",
+  "extends": "weasel",
+  "pins": {
+    "radius-md": {
+      "value": "6px",
+      "type": "dimension"
+    },
+    "glass-blur": {
+      "value": "12px",
+      "type": "dimension"
+    },
+    "font-weight-light": {
+      "value": 300,
+      "type": "fontWeight"
+    },
+    "font-weight-medium": {
+      "value": 500,
+      "type": "fontWeight"
+    },
+    "font-weight-bold": {
+      "value": 700,
+      "type": "fontWeight"
+    },
+    "surface": {
+      "by": "mode",
+      "dark": {
+        "value": "#0a0a14",
+        "type": "color"
+      },
+      "light": {
+        "value": "#fafaf7",
+        "type": "color"
+      }
+    },
+    "surface-raised": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(20, 20, 36, 0.55)",
+        "type": "color"
+      },
+      "light": {
+        "value": "#ffffff",
+        "type": "color"
+      }
+    },
+    "surface-sunken": {
+      "by": "mode",
+      "dark": {
+        "value": "#02020a",
+        "type": "color"
+      },
+      "light": {
+        "value": "#f0ebe2",
+        "type": "color"
+      }
+    },
+    "border": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(255, 255, 255, 0.14)",
+        "type": "color"
+      },
+      "light": {
+        "value": "#c9bba5",
+        "type": "color"
+      }
+    },
+    "line-subtle": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(255, 255, 255, 0.08)",
+        "type": "color"
+      },
+      "light": {
+        "value": "rgba(0, 0, 0, 0.08)",
+        "type": "color"
+      }
+    },
+    "fg": {
+      "by": "mode",
+      "dark": {
+        "value": "#e8e8f0",
+        "type": "color"
+      },
+      "light": {
+        "value": "#2a2018",
+        "type": "color"
+      }
+    },
+    "fg-muted": {
+      "by": "mode",
+      "dark": {
+        "value": "#a8a8c0",
+        "type": "color"
+      },
+      "light": {
+        "value": "#6b5c4a",
+        "type": "color"
+      }
+    },
+    "fg-subtle": {
+      "by": "mode",
+      "dark": {
+        "value": "#5a5a78",
+        "type": "color"
+      },
+      "light": {
+        "value": "#a89b85",
+        "type": "color"
+      }
+    },
+    "accent": {
+      "by": "mode",
+      "dark": {
+        "value": "#b08adb",
+        "type": "color"
+      },
+      "light": {
+        "value": "#a86f3c",
+        "type": "color"
+      }
+    },
+    "accent-hover": {
+      "by": "mode",
+      "dark": {
+        "value": "#c6a3ee",
+        "type": "color"
+      },
+      "light": {
+        "value": "#c2854f",
+        "type": "color"
+      }
+    },
+    "focus-ring": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(176, 138, 219, 0.45)",
+        "type": "color"
+      },
+      "light": {
+        "value": "rgba(168, 111, 60, 0.35)",
+        "type": "color"
+      }
+    },
+    "shadow": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(0, 0, 0, 0.7)",
+        "type": "color"
+      },
+      "light": {
+        "value": "rgba(80, 60, 40, 0.18)",
+        "type": "color"
+      }
+    },
+    "border-strong": {
+      "by": "mode",
+      "dark": {
+        "value": "rgba(255, 255, 255, 0.36)",
+        "type": "color"
+      },
+      "light": {
+        "value": "#9e8b71",
+        "type": "color"
+      }
+    },
+    "backdrop": {
+      "by": "mode",
+      "dark": {
+        "value": "radial-gradient(ellipse 60% 80% at 18% 30%, rgba(150, 80, 200, 0.22), transparent 70%), radial-gradient(ellipse 55% 90% at 78% 70%, rgba(220, 100, 140, 0.18), transparent 65%), radial-gradient(ellipse 50% 70% at 50% 50%, rgba(60, 110, 200, 0.18), transparent 75%), radial-gradient(ellipse at center, #0a0a18 0%, #02020a 100%)",
+        "type": "gradient"
+      },
+      "light": {
+        "value": "none",
+        "type": "gradient"
+      }
+    }
+  }
+}

package/src/theme/interstellar.ts

@@ -1,9 +1,12 @@
-import { loadDTCG, type Theme } from '@weasel-js/theme';
-import doc from './interstellar.tokens.json' with { type: 'json' };
+import { defineTheme, type Theme, type ThemeInput, weaselTheme } from '@weasel-js/theme';
+import definition from './interstellar.theme.json' with { type: 'json' };
 
 /**
  * labkit's theme: a cosmic dark and a warm parchment light, extending the
- * built-in weasel theme. Authored as DTCG and loaded at import time — the
- * interchange path a theme exported from a design tool would take.
+ * built-in weasel theme. A pins-only theme definition: nothing in it is
+ * derived, so it loads without the engine.
  */
-export const interstellarTheme: Theme = loadDTCG(doc);
+export const interstellarTheme: Theme = defineTheme({
+  ...definition,
+  extends: weaselTheme,
+} as ThemeInput);

package/src/tools/labTool.ts

@@ -0,0 +1,11 @@
+import type { InstrumentList } from '../instrument/types';
+
+/**
+ * The tool the lab's slot holds, once its default is applied: a lab with any
+ * annotating instrument starts in `pointer`, so a first click reaches the
+ * instrument rather than the marks over it.
+ */
+export function resolveLabTool(slot: string | null, instruments: InstrumentList): string | null {
+  if (slot !== null) return slot;
+  return instruments.some((i) => i.annotations != null) ? 'pointer' : null;
+}