@weasel-js/labkit 1.3.0 → 1.4.0-pre.0

package/src/lab/Workspace.tsx

@@ -7,7 +7,7 @@ import {
   useMemo,
   useRef,
 } from 'react';
-import { asNodeId, createNode, gridStrategy, type NodeId, Store } from 'windease';
+import { asNodeId, createNode, floatingStrategy, gridStrategy, type NodeId, Store } from 'windease';
 import {
   type ChromeMap,
   Container,
@@ -18,9 +18,12 @@ import {
 
 import { useSurfaceOptional } from '../surface/useSurfaceTile';
 import { TrialDragContext } from '../trial/TrialDragContext';
+import { usePanelHosts } from './panelHost';
 
 const ZONE_ID = asNodeId('lk-workspace');
-const STRATEGIES = { grid: gridStrategy as never };
+const STRATEGIES = { grid: gridStrategy as never, floating: floatingStrategy as never };
+const FLOAT_ZONE_ID = asNodeId('lk-workspace-floating');
+const PANEL_KIND = 'panel';
 const KIND = 'trial';
 
 /** A tile's persisted extent, keyed by the id its caller gave it. Grid resizes
@@ -56,6 +59,11 @@ export interface WorkspaceProps {
   onLayoutChange?: (layout: TrialLayout) => void;
   gap?: number;
   padding?: number;
+  /** Undocked sidebar panels to render alongside the trials. A `'tile'` panel
+   *  joins the grid as a peer of the trials; a `'floating'` one goes into the
+   *  floating zone above it. The body is portalled in by the trial that owns
+   *  it, so all this renders is the frame and the host. */
+  panels?: readonly PanelDescriptor[];
   /**
    * Fixed tiling extent. Omit in an app — the grid measures its own box. Supply
    * it where nothing measures, notably jsdom: at a zero measurement the grid
@@ -79,10 +87,39 @@ function extentOf(store: Store, id: NodeId): TrialLayout[string] | null {
  * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
  * laid out by CSS — `windease/styles.css` (folded into
  * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
+ *
+ * `panels` are undocked sidebar sections. A `'tile'` panel is registered as a
+ * peer of the trials under `PANEL_KIND`, so the grid places and resizes it like
+ * one; a `'floating'` panel goes in the overlay above. Either way this renders
+ * only the frame and an empty host: the section's content is portalled in by
+ * the trial that owns it, which is what keeps a torn-out section inside its
+ * trial's React tree instead of rebuilding it as a sibling.
  */
+
+/** The frame an undocked panel gets: a box, and the host element its trial
+ *  portals into. The title and the dock control come through the portal with
+ *  the body — the workspace knows a panel's key, not what is in it. */
+function PanelFrame({ panel, floating = false }: { panel: PanelDescriptor; floating?: boolean }) {
+  const hosts = usePanelHosts();
+  return (
+    <div className={floating ? 'lk-panel-tile lk-panel-tile--floating' : 'lk-panel-tile'}>
+      <div className="lk-panel-tile__body" ref={(el) => hosts?.set(panel.key, el)} />
+    </div>
+  );
+}
+
+/** One undocked panel, as the workspace needs to know it. */
+export interface PanelDescriptor {
+  /** Stable key; also the portal host key the owning trial writes into. */
+  key: string;
+  title: string;
+  as: 'tile' | 'floating';
+}
+
 export function Workspace({
   children,
   ids,
+  panels,
   resizable = false,
   reorderable = false,
   onReorder,
@@ -93,9 +130,24 @@ export function Workspace({
   viewport,
 }: WorkspaceProps) {
   const items = Children.toArray(children);
-  const idKey = ids ? ids.join(',') : `#${items.length}`;
-  // biome-ignore lint/correctness/useExhaustiveDependencies: idKey is the stable projection of items/ids; depending on those directly rebuilds every render and re-runs the sync effect forever
-  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]); // eslint-disable-line react-hooks/exhaustive-deps
+  const tilePanels = useMemo(() => (panels ?? []).filter((p) => p.as === 'tile'), [panels]);
+  const floatPanels = useMemo(() => (panels ?? []).filter((p) => p.as === 'floating'), [panels]);
+  // Identity has to be stable while the id *contents* are unchanged: the sync
+  // effect below keys off it, and a fresh array every render would re-register
+  // every tile forever. A ref keyed on the joined ids says that directly, where
+  // a `useMemo` on the same key can only say it by suppressing both linters.
+  const wantedIds = [
+    ...items.map((_, i) => ids?.[i] ?? `lk-ws-${i}`),
+    ...tilePanels.map((p) => `lk-panel-${p.key}`),
+  ];
+  const idKey = wantedIds.join(',');
+  const idKeyRef = useRef<string | null>(null);
+  const nodeIdsRef = useRef<NodeId[]>([]);
+  if (idKeyRef.current !== idKey) {
+    idKeyRef.current = idKey;
+    nodeIdsRef.current = wantedIds.map(asNodeId);
+  }
+  const nodeIds = nodeIdsRef.current;
 
   // Held in refs rather than depended on: a fresh object each render would
   // re-run the sync effect, and only a newly registered tile reads `layout`.
@@ -117,6 +169,13 @@ export function Workspace({
         container: { strategyId: 'grid', config: { resizable, gap, padding } },
       }),
     );
+    store.registerNode(
+      createNode({
+        kind: 'zone',
+        id: FLOAT_ZONE_ID,
+        container: { strategyId: 'floating', config: {} },
+      }),
+    );
     storeRef.current = store;
   }
   const store = storeRef.current;
@@ -137,7 +196,8 @@ export function Workspace({
     }
     for (const id of nodeIds) {
       if (present.has(id)) continue;
-      store.registerNode(createNode({ kind: KIND, id, parentId: ZONE_ID, focus: true }));
+      const kind = String(id).startsWith('lk-panel-') ? PANEL_KIND : KIND;
+      store.registerNode(createNode({ kind, id, parentId: ZONE_ID, focus: true }));
       store.showNode(id);
       const saved = layoutRef.current?.[id];
       if (saved) store.patchPlacement(id, saved);
@@ -171,7 +231,15 @@ export function Workspace({
 
   const chrome = useMemo<ChromeMap>(() => {
     const byId = new Map<string, ReactNode>(nodeIds.map((id, i) => [id, items[i]]));
+    const panelByNode = new Map<string, PanelDescriptor>(
+      tilePanels.map((p) => [`lk-panel-${p.key}`, p]),
+    );
     return {
+      [PANEL_KIND]: ({ node }) => {
+        const panel = panelByNode.get(String(node.id));
+        if (!panel) return null;
+        return <PanelFrame panel={panel} />;
+      },
       [KIND]: ({ node }) => {
         const content = byId.get(node.id) ?? null;
         if (!reorderable) return content;
@@ -183,7 +251,16 @@ export function Workspace({
         );
       },
     };
-  }, [nodeIds, items, reorderable]);
+  }, [nodeIds, items, reorderable, tilePanels]);
+
+  const floatingLayer =
+    floatPanels.length === 0 ? null : (
+      <div className="lk-workspace__floating">
+        {floatPanels.map((p) => (
+          <PanelFrame key={p.key} panel={p} floating />
+        ))}
+      </div>
+    );
 
   const grid = (
     <Container
@@ -199,7 +276,19 @@ export function Workspace({
   return (
     <Provider store={store}>
       <StrategyRegistryProvider strategies={STRATEGIES}>
-        {reorderable ? <DragProvider>{grid}</DragProvider> : grid}
+        {floatingLayer ? (
+          // The floating layer insets against the workspace, so it needs a
+          // positioned box around both. Without one it insets against the page
+          // and lands over the lab header.
+          <div className="lk-workspace-host">
+            {reorderable ? <DragProvider>{grid}</DragProvider> : grid}
+            {floatingLayer}
+          </div>
+        ) : reorderable ? (
+          <DragProvider>{grid}</DragProvider>
+        ) : (
+          grid
+        )}
       </StrategyRegistryProvider>
     </Provider>
   );

package/src/lab/index.ts

@@ -6,5 +6,5 @@ export type { LabPaletteProps } from './LabPalette';
 export { LabPalette } from './LabPalette';
 export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
-export type { TrialLayout, WorkspaceProps } from './Workspace';
+export type { PanelDescriptor, TrialLayout, WorkspaceProps } from './Workspace';
 export { Workspace } from './Workspace';

package/src/lab/panelHost.ts

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react';
+
+/** Where an undocked panel's DOM lives. The panel's *content* stays owned by
+ *  its trial — it is React-portalled into the host — so a torn-out section
+ *  keeps the trial's context, state and subscriptions instead of being rebuilt
+ *  as a sibling of the trial it came from. */
+export interface PanelHostRegistry {
+  set: (key: string, el: HTMLElement | null) => void;
+  get: (key: string) => HTMLElement | null;
+  subscribe: (fn: () => void) => () => void;
+}
+
+export function createPanelHostRegistry(): PanelHostRegistry {
+  const hosts = new Map<string, HTMLElement>();
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const fn of listeners) fn();
+  };
+  return {
+    set: (key, el) => {
+      if (el) hosts.set(key, el);
+      else hosts.delete(key);
+      notify();
+    },
+    get: (key) => hosts.get(key) ?? null,
+    subscribe: (fn) => {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+}
+
+export const PanelHostContext = createContext<PanelHostRegistry | null>(null);
+
+export function usePanelHosts(): PanelHostRegistry | null {
+  return useContext(PanelHostContext);
+}

package/src/loupe/AGENTS.md

@@ -0,0 +1,49 @@
+# Loupe — Agent Guide
+
+`src/loupe/` is the `loupe` instrument capability: a magnifier a trial can turn
+on, painted by whichever painter suits the instrument's content.
+
+The magnifier itself is not here. `@weasel-js/loupe` holds the model — aim,
+factor, mode, colour, picking — over a `LoupeSurface` it asks five questions.
+This directory binds that model to a labkit trial and draws it.
+
+## Files
+
+| File | Role |
+|---|---|
+| `types.ts` | `LoupeCapability`, and `resolveLoupe` filling in every default |
+| `useLoupe.ts` | The model over a host element, plus all of the input |
+| `TrialLoupe.tsx` | Picks the painter and mounts the lens |
+| `LoupeBubble.tsx` | The circular clip, positioned on the aim |
+| `CanvasLoupe.tsx` | Painter for a `<CanvasStack>` |
+| `canvasLens.ts` | That painter's geometry and drawing, with no React in it |
+| `DomLoupe.tsx` | Painter for DOM content |
+| `useHostSize.ts` | The host's measured box, for the DOM stage |
+
+## Which painter
+
+`LoupeCapability.render` decides. Absent, the lens re-runs the instrument's own
+canvas layers through `lensCamera` — sharp at any factor, and `mode: 'pixel'`
+enlarges the presented pixels with smoothing off instead. Present, the
+instrument is handed a camera and draws itself again; a DOM loupe is always
+`vector`, since DOM has no framebuffer to enlarge.
+
+The canvas painter needs the stack's own pixels and layers, which is why
+`TrialLoupe` mounts *inside* `<CanvasStack>` for a drawing instrument and reads
+`CanvasStackContext`'s `surface`. A DOM instrument gets a
+`.lk-trial__loupe-host` wrapper from `Trial` and the lens tracks that.
+
+## Traps
+
+**jsdom cannot see magnification.** Everything assertable there is state — aim
+moved, factor clamped, mode switched, the lens raised and put away. That the
+lens shows the right region is a screenshot.
+
+**Do not dispose the model when React unmounts.** `dispose` is one-way, and
+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 has to be taken from pan/zoom by hand.** `usePanZoom` is a React
+handler on the same element, so the lens listens in the capture phase and stops
+propagation. See the loupe entry in `docs/TODO.md` for what replaces this.

package/src/loupe/CanvasLoupe.tsx

@@ -0,0 +1,83 @@
+import { useVisibleRaf } from '@weasel-js/core';
+import type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
+import { useEffect, useRef } from 'react';
+import type { CanvasStackSurface } from '../canvas/CanvasStackContext';
+import type { WorldFrame, WorldSpec } from '../canvas/worldSpec';
+import type { ViewTransform } from '../instrument/types';
+import { drawCanvasLens } from './canvasLens';
+
+/** Props for `<CanvasLoupe>`. */
+export interface CanvasLoupeProps {
+  aim: LoupePoint;
+  factor: number;
+  mode: LoupeMode;
+  diameter: number;
+  /** The stack being magnified: its layers, its pixels, and its measured box. */
+  surface: CanvasStackSurface;
+  view: ViewTransform;
+  frame: WorldFrame;
+  worldSpec?: WorldSpec;
+}
+
+/**
+ * Paints a lens over a `<CanvasStack>` by re-drawing the stack's layers through
+ * a zoomed camera — so the magnified content is as sharp as the original, at
+ * any factor. `pixel` mode enlarges what the stack presented instead.
+ */
+export function CanvasLoupe({
+  aim,
+  factor,
+  mode,
+  diameter,
+  surface,
+  view,
+  frame,
+  worldSpec,
+}: CanvasLoupeProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const dpr = surface.size.dpr;
+
+  // Whatever the stack redraws every frame, the lens has to redraw too — an
+  // instrument that animates from its own loop never re-renders this component.
+  const args = { aim, factor, mode, diameter, dpr, view, frame, worldSpec, surface };
+  const argsRef = useRef(args);
+  argsRef.current = args;
+
+  const loop = useVisibleRaf(
+    () => {
+      loop.request();
+      const canvas = canvasRef.current;
+      const ctx = canvas?.getContext('2d');
+      const canvases = argsRef.current.surface.canvases.current;
+      if (!ctx || !canvases) return;
+      const a = argsRef.current;
+      drawCanvasLens(ctx, {
+        aim: a.aim,
+        factor: a.factor,
+        diameter: a.diameter,
+        dpr: a.dpr,
+        mode: a.mode,
+        outer: a.view,
+        outerFrame: a.frame,
+        worldSpec: a.worldSpec,
+        layers: a.surface.layers,
+        canvases,
+      });
+    },
+    { target: canvasRef },
+  );
+
+  useEffect(() => {
+    loop.request();
+    return () => loop.cancel();
+  }, [loop]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      className="lk-loupe__canvas"
+      width={Math.max(1, Math.round(diameter * dpr))}
+      height={Math.max(1, Math.round(diameter * dpr))}
+    />
+  );
+}

package/src/loupe/DomLoupe.tsx

@@ -0,0 +1,62 @@
+import type { LoupeMode, LoupePoint } from '@weasel-js/loupe';
+import type { CSSProperties } from 'react';
+import { zoomAt } from '../canvas/camera';
+import type { ViewportSize, WorldFrame } from '../canvas/worldSpec';
+import type { ViewTransform } from '../instrument/types';
+import type { LoupeRenderArgs } from './types';
+
+/** Props for `<DomLoupe>`. */
+export interface DomLoupeProps {
+  aim: LoupePoint;
+  factor: number;
+  mode: LoupeMode;
+  diameter: number;
+  /** The host the instrument draws into, which the stage reproduces. */
+  size: ViewportSize;
+  /** The trial's own camera. */
+  view: ViewTransform;
+  frame?: WorldFrame;
+  state: unknown;
+  config: unknown;
+  render: (args: LoupeRenderArgs) => React.ReactNode;
+}
+
+/**
+ * Paints a lens over DOM content by asking the instrument to draw itself again
+ * at a magnified camera.
+ *
+ * The stage is a full copy of the host, so the instrument's own layout still
+ * holds; the camera is composed about the aimed point, which keeps that point
+ * where it already was, and the stage is then slid by `diameter / 2 - aim` to
+ * bring it to the middle of the lens.
+ */
+export function DomLoupe({
+  aim,
+  factor,
+  mode,
+  diameter,
+  size,
+  view,
+  frame,
+  state,
+  config,
+  render,
+}: DomLoupeProps) {
+  const style: CSSProperties = {
+    width: `${size.width}px`,
+    height: `${size.height}px`,
+    transform: `translate(${diameter / 2 - aim.x}px, ${diameter / 2 - aim.y}px)`,
+  };
+  return (
+    <div className="lk-loupe__stage" style={style}>
+      {render({
+        state,
+        config,
+        view: zoomAt(view, factor, aim, { frame }),
+        factor,
+        mode,
+        size,
+      })}
+    </div>
+  );
+}

package/src/loupe/Loupe.less

@@ -0,0 +1,38 @@
+.lk-loupe {
+  position: absolute;
+  top: 0;
+  left: 0;
+  border-radius: 50%;
+  overflow: hidden;
+  // Nothing under the lens stops working while it is up: the pan, the wheel and
+  // any overlay of the instrument's own keep receiving the pointer.
+  pointer-events: none;
+  border: var(--wzl-border-w) solid var(--wzl-border-raised);
+  box-shadow: 0 2px 8px var(--wzl-shadow);
+  // A painter's ground shows through wherever it draws nothing, and a vector
+  // lens leaves the gaps between marks transparent. This is the trial's own
+  // ground, for the part of a DOM lens its stage does not reach.
+  background: var(--wzl-surface-raised);
+}
+
+// `.lk-canvas-stack__overlay > *` turns pointer events back on for an
+// instrument's own overlay; the lens is the one child that must stay inert.
+.lk-canvas-stack__overlay > .lk-loupe {
+  pointer-events: none;
+}
+
+.lk-loupe__canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  // The stack's own ground, so the lens reads as a window onto it rather than
+  // as a panel sitting over it.
+  background: var(--wzl-surface-sunken);
+}
+
+.lk-loupe__stage {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: 0 0;
+}

package/src/loupe/LoupeBubble.tsx

@@ -0,0 +1,32 @@
+import type { LoupePoint } from '@weasel-js/loupe';
+import type { CSSProperties, ReactNode, RefObject } from 'react';
+
+/** Props for `<LoupeBubble>`. */
+export interface LoupeBubbleProps {
+  /** Where the lens is aimed, in its container's own pixels. */
+  aim: LoupePoint;
+  diameter: number;
+  hostRef?: RefObject<HTMLDivElement | null>;
+  children: ReactNode;
+}
+
+/**
+ * The lens itself: a circle centred on the aimed point, clipping whatever a
+ * painter draws into it.
+ *
+ * It takes no pointer events, so the pan, the wheel and anything underneath
+ * keep working while it is up — and it is `aria-hidden`, since it magnifies
+ * content already on the page rather than adding any.
+ */
+export function LoupeBubble({ aim, diameter, hostRef, children }: LoupeBubbleProps) {
+  const style: CSSProperties = {
+    width: `${diameter}px`,
+    height: `${diameter}px`,
+    transform: `translate(${aim.x - diameter / 2}px, ${aim.y - diameter / 2}px)`,
+  };
+  return (
+    <div ref={hostRef} className="lk-loupe" style={style} aria-hidden="true">
+      {children}
+    </div>
+  );
+}

package/src/loupe/TrialLoupe.tsx

@@ -0,0 +1,93 @@
+import { type RefObject, useContext, useMemo } from 'react';
+import { CanvasStackContext } from '../canvas/CanvasStackContext';
+import type { WorldSpec } from '../canvas/worldSpec';
+import type { ViewTransform } from '../instrument/types';
+import { CanvasLoupe } from './CanvasLoupe';
+import { sampleStack } from './canvasLens';
+import { DomLoupe } from './DomLoupe';
+import { LoupeBubble } from './LoupeBubble';
+import type { ResolvedLoupe } from './types';
+import { useHostSize } from './useHostSize';
+import { useLoupe } from './useLoupe';
+
+/** Props for `<TrialLoupe>`. */
+export interface TrialLoupeProps {
+  capability: ResolvedLoupe;
+  /** Whether the trial's loupe is turned on. Hold-to-peek shows it anyway. */
+  enabled: boolean;
+  state: unknown;
+  config: unknown;
+  /** The trial's own camera. */
+  view: ViewTransform;
+  worldSpec?: WorldSpec;
+  /** The element the lens tracks. A loupe mounted inside a `<CanvasStack>`
+   *  takes the stack's own element instead, and this goes unused. */
+  hostRef?: RefObject<HTMLElement | null>;
+}
+
+/** Stable stand-in, so a loupe with nothing to track does not re-bind its
+ *  listeners on every render. */
+const NO_HOST: RefObject<HTMLElement | null> = { current: null };
+
+/**
+ * A trial's loupe, painted by whichever painter suits its content: the canvas
+ * stack it is mounted inside, or the instrument's own `render` at a magnified
+ * camera.
+ */
+export function TrialLoupe({
+  capability,
+  enabled,
+  state,
+  config,
+  view,
+  worldSpec,
+  hostRef,
+}: TrialLoupeProps) {
+  const stack = useContext(CanvasStackContext);
+  const surface = capability.render ? undefined : stack?.surface;
+  const host = surface?.element ?? hostRef ?? NO_HOST;
+
+  const sample = useMemo(() => {
+    if (!surface) return undefined;
+    return (p: { x: number; y: number }): string | null => {
+      const canvases = surface.canvases.current;
+      return canvases ? sampleStack(surface.layers, canvases, p, surface.size.dpr) : null;
+    };
+  }, [surface]);
+
+  const loupe = useLoupe({ capability, hostRef: host, enabled, sample });
+  const measured = useHostSize(host);
+  const size = surface?.size ?? measured;
+
+  if (!loupe.visible) return null;
+
+  return (
+    <LoupeBubble aim={loupe.aim} diameter={capability.diameter}>
+      {capability.render ? (
+        <DomLoupe
+          aim={loupe.aim}
+          factor={loupe.factor}
+          mode={loupe.mode}
+          diameter={capability.diameter}
+          size={size}
+          view={view}
+          frame={stack?.frame}
+          state={state}
+          config={config}
+          render={capability.render}
+        />
+      ) : surface && stack ? (
+        <CanvasLoupe
+          aim={loupe.aim}
+          factor={loupe.factor}
+          mode={loupe.mode}
+          diameter={capability.diameter}
+          surface={surface}
+          view={stack.view}
+          frame={stack.frame}
+          worldSpec={worldSpec}
+        />
+      ) : null}
+    </LoupeBubble>
+  );
+}