@weasel-js/labkit 1.7.3 → 1.8.1

package/src/lab/LabLightbox.browser.test.tsx

@@ -0,0 +1,216 @@
+import '@weasel-js/theme/tokens.css';
+import 'windease/styles.css';
+import '../styles.less';
+import './LabLightbox.browser.test.less';
+import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { useEffect } from 'react';
+import { afterEach, beforeEach, expect, test } from 'vitest';
+import { page, userEvent } from 'vitest/browser';
+import { useAnnotations } from '../annotations/AnnotationsContext';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { toDeviceRect } from '../surface/deviceRect';
+import { useSurface, useSurfaceCanvas, useSurfaceTile, useTileId } from '../surface/useSurfaceTile';
+import { Lab } from './Lab';
+
+// Annotation marks are drawn into the lab's shared buffer and take input from
+// a box the lab mounts, neither inside the trial. Whether they come along when
+// the trial is expanded is stacking and hit-testing — a browser's to answer.
+
+afterEach(cleanup);
+beforeEach(async () => {
+  await page.viewport(1000, 700);
+});
+
+const CONTENT = { w: 200, h: 100 };
+const panes = new Map<string, { current: HTMLDivElement | null }>();
+const paneFor = (id: string) => {
+  let ref = panes.get(id);
+  if (!ref) {
+    ref = { current: null };
+    panes.set(id, ref);
+  }
+  return ref;
+};
+
+function Count() {
+  return <output data-testid="count">{useAnnotations().query().length}</output>;
+}
+
+/** Stands in for a 3D view: paints its rect green in the shared buffer
+ *  under the trials, through the surface, as a three.js tenant would. */
+function Solid() {
+  const attach = useSurfaceTile('solid');
+  const id = useTileId('solid');
+  const surface = useSurface();
+  const canvas = useSurfaceCanvas('under');
+  useEffect(
+    () =>
+      surface.registerPainter(id, (rect, frame) => {
+        const gl = canvas?.getContext('webgl2', { preserveDrawingBuffer: true });
+        if (!gl) return;
+        const v = toDeviceRect(rect, frame.size.height, frame.dpr);
+        const px = (n: number) => Math.round(n * frame.dpr);
+        gl.enable(gl.SCISSOR_TEST);
+        gl.scissor(px(v.x), px(v.y), px(v.w), px(v.h));
+        gl.clearColor(0, 1, 0, 1);
+        gl.clear(gl.COLOR_BUFFER_BIT);
+        gl.disable(gl.SCISSOR_TEST);
+      }),
+    [surface, id, canvas],
+  );
+  return <div className="lk-lightbox-lab-solid" ref={attach} />;
+}
+
+/** The under buffer's own pixel at a viewport point, read back from GL. */
+function underPixelAt(x: number, y: number): [number, number, number] {
+  const canvas = document.querySelector('.lk-lab__layer--under canvas') as HTMLCanvasElement;
+  const gl = canvas.getContext('webgl2') as WebGL2RenderingContext;
+  const box = canvas.getBoundingClientRect();
+  const dpr = canvas.width / box.width;
+  const out = new Uint8Array(4);
+  const gx = Math.round((x - box.left) * dpr);
+  const gy = Math.round(canvas.height - (y - box.top) * dpr);
+  gl.readPixels(gx, gy, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, out);
+  return [out[0] ?? 0, out[1] ?? 0, out[2] ?? 0];
+}
+
+const Marked = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Marked',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: (ctx) => (
+    <>
+      <div
+        className="lk-lightbox-lab-pane"
+        ref={(el) => {
+          paneFor(ctx.trial.id).current = el;
+        }}
+      />
+      <Solid />
+      <Count />
+    </>
+  ),
+  annotations: {
+    targets: (_s, _c, trial) => [{ id: 'pane', ref: paneFor(trial.id), content: CONTENT }],
+  },
+});
+
+/** A screenshot's pixels along a horizontal line, in viewport px: what the
+ *  compositor shows, top layer included. */
+async function rowAt(y: number, x0: number, x1: number): Promise<Array<[number, number, number]>> {
+  // With `save: false` the call resolves to the base64 string alone.
+  const base64 = (await page.screenshot({ base64: true, save: false })) as unknown as string;
+  const img = new Image();
+  img.src = `data:image/png;base64,${base64}`;
+  await img.decode();
+  const c = document.createElement('canvas');
+  c.width = img.width;
+  c.height = img.height;
+  const g = c.getContext('2d') as CanvasRenderingContext2D;
+  g.drawImage(img, 0, 0);
+  const scale = img.width / window.innerWidth;
+  const left = Math.round(x0 * scale);
+  const d = g.getImageData(left, Math.round(y * scale), Math.round((x1 - x0) * scale), 1).data;
+  const out: Array<[number, number, number]> = [];
+  for (let i = 0; i < d.length; i += 4) out.push([d[i] ?? 0, d[i + 1] ?? 0, d[i + 2] ?? 0]);
+  return out;
+}
+
+const BLUE = '0,0,255';
+
+/** Drags a rectangle across the middle of `box`, in viewport px, delivered
+ *  to whatever the browser hit-tests at the press. */
+async function drawRect(box: DOMRect): Promise<void> {
+  const x0 = box.left + box.width * 0.3;
+  const y0 = box.top + box.height * 0.3;
+  const x1 = box.left + box.width * 0.7;
+  const y1 = box.top + box.height * 0.7;
+  const target = document.elementFromPoint(x0, y0) as Element;
+  const fire = (type: string, x: number, y: number, buttons: number): void => {
+    target.dispatchEvent(
+      new PointerEvent(type, {
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+        pointerId: 1,
+        pointerType: 'mouse',
+        isPrimary: true,
+        button: 0,
+        buttons,
+        clientX: x,
+        clientY: y,
+      }),
+    );
+  };
+  fire('pointerdown', x0, y0, 1);
+  for (let i = 1; i <= 8; i++) {
+    fire('pointermove', x0 + ((x1 - x0) * i) / 8, y0 + ((y1 - y0) * i) / 8, 1);
+    await new Promise((r) => requestAnimationFrame(r));
+  }
+  fire('pointerup', x1, y1, 0);
+  await new Promise((r) => requestAnimationFrame(r));
+}
+
+test('an expanded trial keeps its marks over it and takes new ones', async () => {
+  render(
+    <div className="lk-lightbox-lab-host">
+      <Lab instruments={[Marked]} defaultInstrument="Marked" />
+    </div>,
+  );
+  await userEvent.click(await screen.findByRole('button', { name: 'Rectangle' }));
+  const pane = document.querySelector('.lk-lightbox-lab-pane') as HTMLElement;
+  await waitFor(() => expect(document.querySelector('.lk-annotate__input')).not.toBeNull());
+
+  await drawRect(pane.getBoundingClientRect());
+  await waitFor(() => expect(screen.getByTestId('count').textContent).toBe('1'));
+
+  await userEvent.click(screen.getByRole('button', { name: 'Expand trial' }));
+  const box = pane.closest('.lk-lightbox') as HTMLElement;
+  expect(box.matches(':popover-open')).toBe(true);
+  const big = pane.getBoundingClientRect();
+  expect(big.width).toBeGreaterThan(window.innerWidth * 0.5);
+
+  // The input box followed the pane into the top layer, and is what a press
+  // over the pane reaches.
+  const input = document.querySelector('.lk-annotate__input') as HTMLElement;
+  await waitFor(() => {
+    const r = input.getBoundingClientRect();
+    expect(r.left).toBeCloseTo(big.left, 0);
+    expect(r.width).toBeCloseTo(big.width, 0);
+  });
+  expect(document.elementFromPoint(big.left + big.width / 2, big.top + big.height / 2)).toBe(input);
+
+  // The first mark is drawn over the expanded pane: somewhere along the
+  // pane's middle row the rectangle's stroke crosses it, and the margins of
+  // that row, outside the mark, are still the pane's flat blue.
+  await waitFor(
+    async () => {
+      const row = await rowAt(big.top + big.height / 2, big.left + 2, big.right - 2);
+      expect(row[0]?.join()).toBe(BLUE);
+      expect(row.at(-1)?.join()).toBe(BLUE);
+      expect(row.filter((p) => p.join() !== BLUE).length).toBeGreaterThan(0);
+    },
+    { timeout: 5000 },
+  );
+
+  await drawRect(big);
+  await waitFor(() => expect(screen.getByTestId('count').textContent).toBe('2'));
+
+  // The under buffer was lifted below the trial and covers the window, and the
+  // tenant painted the expanded solid's rect there.
+  const under = document.querySelector('.lk-lab__layer--under') as HTMLElement;
+  expect(under.matches(':popover-open')).toBe(true);
+  expect(under.getBoundingClientRect().width).toBeCloseTo(window.innerWidth, 0);
+  const solid = (
+    document.querySelector('.lk-lightbox-lab-solid') as HTMLElement
+  ).getBoundingClientRect();
+  expect(solid.width).toBeGreaterThan(0);
+  await waitFor(() =>
+    expect(underPixelAt(solid.left + solid.width / 2, solid.top + solid.height / 2)).toEqual([
+      0, 255, 0,
+    ]),
+  );
+
+  await userEvent.keyboard('{Escape}');
+  expect(box.matches(':popover-open')).toBe(false);
+});

package/src/lab/LabShell.less

@@ -118,20 +118,27 @@
 // the pane can still hold a label or a control. Both sit under the viewport
 // chrome, whose z-overlay outranks them, and both are inert — every tile takes
 // input from its own box.
-.lk-lab__surface {
+// The shared surface's two layers, over the whole body and taking no input.
+// The over layer is also the box tile rects are measured against.
+.lk-lab__layer {
   position: absolute;
   inset: 0;
   pointer-events: none;
 }
 
-.lk-lab__surface--under {
+.lk-lab__layer--under {
   z-index: 0;
 }
 
-.lk-lab__surface--over {
+.lk-lab__layer--over {
   z-index: 1;
 }
 
+.lk-lab__surface {
+  position: absolute;
+  inset: 0;
+}
+
 .lk-shell-footer {
   border-top: 1px solid var(--wzl-border);
   padding: var(--wzl-space-xs) var(--wzl-space-md);

package/src/lab/LabSurface.tsx

@@ -0,0 +1,129 @@
+import { type ReactNode, useCallback, useInsertionEffect, useMemo, useRef, useState } from 'react';
+import { LightboxLayers } from '../lightbox/LightboxLayers';
+import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
+import { useSurfaceCanvas, useSurfaceOptional } from '../surface/useSurfaceTile';
+import { type SurfaceFrame, useTiledSurface } from '../surface/useTiledSurface';
+
+/** Props for `LabSurface`. */
+export interface LabSurfaceProps {
+  /** Receives the lab body, which the surface's layers cover. */
+  bodyRef: (el: HTMLDivElement | null) => void;
+  children: ReactNode;
+}
+
+/**
+ * The lab body and the one shared drawing surface its trials paint into.
+ *
+ * The two buffers sit in layers stacked around the trials, both taking no
+ * input — each tile takes it from its own box. A tile's marks annotate the
+ * instrument's DOM from over it; an opaque renderer sits under it, so the
+ * pane can still hold a label. Tile rects are measured against the over
+ * layer, which is also where a tile's own chrome on the surface (an
+ * annotation input box) mounts. The layers are declared to any lightbox
+ * inside, which lifts them around an expanded trial; while lifted they cover
+ * the window, the surface re-measures against that, and the buffers resize.
+ *
+ * A host that already owns a surface keeps it: a lab embedded in a larger
+ * shared-surface app must not open a second GL tenancy, and mounts no buffer
+ * or layer of its own.
+ */
+export function LabSurface({ bodyRef, children }: LabSurfaceProps) {
+  const outerSurface = useSurfaceOptional();
+  const outerOver = useSurfaceCanvas('over');
+  const outerUnder = useSurfaceCanvas('under');
+  const [ownOver, setOwnOver] = useState<HTMLCanvasElement | null>(null);
+  const [ownUnder, setOwnUnder] = useState<HTMLCanvasElement | null>(null);
+  const [underLayer, setUnderLayer] = useState<HTMLDivElement | null>(null);
+  const [overLayer, setOverLayer] = useState<HTMLDivElement | null>(null);
+  const ownOverRef = useRef<HTMLCanvasElement | null>(null);
+  const ownUnderRef = useRef<HTMLCanvasElement | null>(null);
+  const bufferRef = useRef({ w: 0, h: 0 });
+  const surfaceRef = useRef<ReturnType<typeof useTiledSurface> | null>(null);
+
+  // Sizing the buffer clears all of it, so every tile has to repaint — not
+  // only the one whose move triggered the measurement. Both buffers are sized
+  // together off one comparison: they are the same box, so a tenant of either
+  // is looking at the same rects, and one invalidateAll covers both.
+  const onFrame = useCallback((frame: SurfaceFrame) => {
+    const canvases = [ownUnderRef.current, ownOverRef.current].filter((c) => c !== null);
+    if (canvases.length === 0) return;
+    const w = Math.round(frame.size.width * frame.dpr);
+    const h = Math.round(frame.size.height * frame.dpr);
+    if (bufferRef.current.w !== w || bufferRef.current.h !== h) {
+      bufferRef.current = { w, h };
+      for (const c of canvases) {
+        c.width = w;
+        c.height = h;
+        c.style.width = `${frame.size.width}px`;
+        c.style.height = `${frame.size.height}px`;
+      }
+      surfaceRef.current?.invalidateAll();
+      return;
+    }
+    // A same-size re-tile does not go through here: assigning `width` its own
+    // value resizes nothing, so it clears nothing. The tenants clear, through
+    // `registerClear`.
+  }, []);
+
+  const ownSurface = useTiledSurface({ onFrame });
+  // Not `useLatest`: `onFrame` reads it, and is needed before the surface exists.
+  useInsertionEffect(() => {
+    surfaceRef.current = ownSurface;
+  }, [ownSurface]);
+
+  const attachOwnSurface = ownSurface.containerRef;
+  const overLayerRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      setOverLayer(el);
+      attachOwnSurface(el);
+    },
+    [attachOwnSurface],
+  );
+
+  const surface = outerSurface ?? ownSurface;
+  const canvases = useMemo(
+    () =>
+      outerSurface ? { over: outerOver, under: outerUnder } : { over: ownOver, under: ownUnder },
+    [outerSurface, outerOver, outerUnder, ownOver, ownUnder],
+  );
+  const below = useMemo(() => [underLayer], [underLayer]);
+  const above = useMemo(() => [overLayer], [overLayer]);
+
+  const body = (
+    <div className="lk-lab__body" ref={bodyRef}>
+      {outerSurface ? null : (
+        <div className="lk-lab__layer lk-lab__layer--under" ref={setUnderLayer}>
+          <canvas
+            className="lk-lab__surface"
+            ref={(el) => {
+              ownUnderRef.current = el;
+              setOwnUnder(el);
+            }}
+          />
+        </div>
+      )}
+      {children}
+      {outerSurface ? null : (
+        <div className="lk-lab__layer lk-lab__layer--over" ref={overLayerRef}>
+          <canvas
+            className="lk-lab__surface"
+            ref={(el) => {
+              ownOverRef.current = el;
+              setOwnOver(el);
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+
+  return (
+    <SurfaceContext.Provider value={surface}>
+      <SurfaceCanvasContext.Provider value={canvases}>
+        <LightboxLayers below={below} above={above}>
+          {body}
+        </LightboxLayers>
+      </SurfaceCanvasContext.Provider>
+    </SurfaceContext.Provider>
+  );
+}

package/src/lab/Workspace.stories.tsx

@@ -17,6 +17,8 @@ const Tile = ({ children }: { children: React.ReactNode }) => (
       borderRadius: 'var(--wzl-radius-md)',
       padding: 'var(--wzl-space-md)',
       minHeight: 120,
+      height: '100%',
+      boxSizing: 'border-box',
       display: 'grid',
       placeItems: 'center',
     }}
@@ -75,3 +77,19 @@ export const Resizable: Story = {
     </div>
   ),
 };
+
+/** Every tile has an expand button in its corner that shows it large over the
+ *  page. The tile is lifted into the browser's top layer rather than
+ *  remounted; Escape, the close button, or a click in the margin puts it back.
+ *  Tile 1 also opens on a double-click, through `expandOnDoubleClick`. */
+export const Lightbox: Story = {
+  render: () => (
+    <div style={{ height: 500 }}>
+      <Workspace ids={['a', 'b', 'c']} resizable expandOnDoubleClick={(id) => id === 'a'}>
+        <Tile>1</Tile>
+        <Tile>2</Tile>
+        <Tile>3</Tile>
+      </Workspace>
+    </div>
+  ),
+};

package/src/lab/Workspace.surface.test.tsx

@@ -10,11 +10,15 @@ function fakeHandle(): SurfaceHandle {
     invalidate: vi.fn(),
     invalidateAll: vi.fn(),
     invalidateRects: vi.fn(),
+    invalidateBox: vi.fn(),
     registerTile: vi.fn(),
     registerClear: vi.fn(() => () => {}),
     registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
     getContainer: vi.fn(() => null),
+    scope: vi.fn(),
+    inScope: vi.fn(() => true),
+    subscribeScope: vi.fn(() => () => {}),
   };
 }
 

package/src/lab/Workspace.test.tsx

@@ -1,4 +1,4 @@
-import { act, screen } from '@testing-library/react';
+import { act, fireEvent, screen } from '@testing-library/react';
 import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, test, vi } from 'vitest';
 import { useTrialDrag } from '../trial/TrialDragContext';
@@ -50,6 +50,42 @@ describe('Workspace', () => {
     expect(container.querySelector('[data-node="a"]')).toBeNull();
   });
 
+  test('opens a tile on double-click only where expandOnDoubleClick says so', async () => {
+    const { container } = await renderSettled(
+      <Workspace ids={['a', 'b']} viewport={VIEWPORT} expandOnDoubleClick={(id) => id === 'a'}>
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    const box = (id: string) => container.querySelector(`[data-node="${id}"] .lk-lightbox`);
+    expect(screen.getAllByRole('button', { name: 'Expand' })).toHaveLength(2);
+    fireEvent.doubleClick(screen.getByText('b'));
+    expect(box('b')).not.toHaveClass('lk-lightbox--expanded');
+    fireEvent.doubleClick(screen.getByText('a'));
+    expect(box('a')).toHaveClass('lk-lightbox--expanded');
+  });
+
+  test('lets a predicate take the lightbox off one tile', async () => {
+    await renderSettled(
+      <Workspace ids={['a', 'b']} viewport={VIEWPORT} lightbox={(id) => id !== 'b'}>
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    expect(screen.getAllByRole('button', { name: 'Expand' })).toHaveLength(1);
+  });
+
+  test('lightbox={false} leaves no tile expandable', async () => {
+    await renderSettled(
+      <Workspace viewport={VIEWPORT} lightbox={false} expandOnDoubleClick>
+        <div>a</div>
+      </Workspace>,
+    );
+    fireEvent.doubleClick(screen.getByText('a'));
+    expect(document.querySelector('.lk-lightbox--expanded')).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull();
+  });
+
   test('uses lk-workspace class', async () => {
     const { container } = await renderSettled(
       <Workspace viewport={VIEWPORT}>

package/src/lab/Workspace.tsx

@@ -17,6 +17,7 @@ import {
   StrategyRegistryProvider,
 } from 'windease/react';
 
+import { Lightbox } from '../lightbox/Lightbox';
 import { useSurfaceOptional } from '../surface/useSurfaceTile';
 import { TrialDragContext } from '../trial/TrialDragContext';
 import { usePanelHosts } from './panelHost';
@@ -66,6 +67,19 @@ export interface WorkspaceProps {
    *  floating zone above it. The body is portaled in by the trial that owns
    *  it, so all this renders is the frame and the host. */
   panels?: readonly PanelDescriptor[];
+  /**
+   * Whether a tile can open in a `<Lightbox>` — shown large over the page from
+   * the expand button in its corner — without being remounted. On by default;
+   * `false` turns it off for every tile, and a function decides per tile id.
+   */
+  lightbox?: boolean | ((id: string) => boolean);
+  /**
+   * Whether a double-click on a tile's content also opens its lightbox. Off by
+   * default, since most content has its own use for a double-click; give it
+   * to a tile whose content has none, such as an image, with a function of
+   * the tile id.
+   */
+  expandOnDoubleClick?: boolean | ((id: string) => boolean);
   /**
    * 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
@@ -149,6 +163,8 @@ export function Workspace({
   gap = 12,
   padding = 0,
   viewport,
+  lightbox = true,
+  expandOnDoubleClick = false,
 }: WorkspaceProps) {
   const items = Children.toArray(children);
   const tilePanels = useMemo(() => (panels ?? []).filter((p) => p.as === 'tile'), [panels]);
@@ -226,6 +242,9 @@ export function Workspace({
   );
 
   const chrome = useMemo<ChromeMap>(() => {
+    const lightboxFor = typeof lightbox === 'function' ? lightbox : () => lightbox;
+    const doubleClickFor =
+      typeof expandOnDoubleClick === 'function' ? expandOnDoubleClick : () => expandOnDoubleClick;
     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]),
@@ -237,17 +256,26 @@ export function Workspace({
         return <PanelFrame panel={panel} />;
       },
       [KIND]: ({ node }) => {
-        const content = byId.get(node.id) ?? null;
-        if (!reorderable) return content;
+        const id = String(node.id);
+        const tile = (
+          // `disabled` rather than leaving the wrapper out, so turning the
+          // lightbox off cannot remount the tile.
+          <Lightbox
+            className="lk-trial-tile"
+            disabled={!lightboxFor(id)}
+            expandOnDoubleClick={doubleClickFor(id)}
+          >
+            {byId.get(node.id) ?? null}
+          </Lightbox>
+        );
+        if (!reorderable) return tile;
         return (
           // No grip strip: the trial's own title bar is the drag surface.
-          <TrialDragContext.Provider value={{ nodeId: node.id }}>
-            <div className="lk-trial-tile">{content}</div>
-          </TrialDragContext.Provider>
+          <TrialDragContext.Provider value={{ nodeId: node.id }}>{tile}</TrialDragContext.Provider>
         );
       },
     };
-  }, [nodeIds, items, reorderable, tilePanels]);
+  }, [nodeIds, items, reorderable, tilePanels, lightbox, expandOnDoubleClick]);
 
   const floatingLayer =
     floatPanels.length === 0 ? null : (

package/src/lab/index.ts

@@ -12,5 +12,7 @@ export { LabShell } from './LabShell';
 export type { LabPage, LabSwitcherProps } from './LabSwitcher';
 export { currentPage, LabSwitcher } from './LabSwitcher';
 export { LabZoom } from './LabZoom';
+export type { PresentationSeed } from './openLab';
+export { type Presentation, usePresentation } from './presentation';
 export type { PanelDescriptor, TrialLayout, WorkspaceProps } from './Workspace';
 export { Workspace } from './Workspace';

package/src/lab/nebula.ts

@@ -0,0 +1,30 @@
+import { type ColorList, colorAt, colorCount, resolveTheme, type Theme } from '@weasel-js/theme';
+
+// Fixed spread of nebula blob positions / sizes / fall-off stops. Colors
+// supplied via the `nebula` prop are slotted into these slots in order;
+// callers passing more than 5 wrap around (intentional — keeps the look
+// readable and bounded).
+const NEBULA_SLOTS = [
+  { cx: '18%', cy: '30%', sx: '60%', sy: '80%', stop: '70%' },
+  { cx: '78%', cy: '70%', sx: '55%', sy: '90%', stop: '65%' },
+  { cx: '50%', cy: '50%', sx: '50%', sy: '70%', stop: '75%' },
+  { cx: '12%', cy: '82%', sx: '50%', sy: '70%', stop: '70%' },
+  { cx: '85%', cy: '18%', sx: '55%', sy: '80%', stop: '70%' },
+] as const;
+
+export function buildNebula(
+  list: ColorList,
+  theme: Theme,
+  mode: 'light' | 'dark',
+  density: string,
+): string {
+  const ctx = { theme, resolved: resolveTheme(theme, { mode, density }) };
+  const n = colorCount(list, ctx) ?? NEBULA_SLOTS.length;
+  const colors = Array.from({ length: n }, (_, i) => colorAt(list, i, ctx));
+  const blobs = colors.map((c, i) => {
+    const p = NEBULA_SLOTS[i % NEBULA_SLOTS.length];
+    return `radial-gradient(ellipse ${p.sx} ${p.sy} at ${p.cx} ${p.cy}, color-mix(in srgb, ${c} 22%, transparent), transparent ${p.stop})`;
+  });
+  blobs.push('radial-gradient(ellipse at center, #0a0a18 0%, #02020a 100%)');
+  return blobs.join(', ');
+}

package/src/lab/openLab.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import type { Instrument, InstrumentList } from '../instrument/types';
+import { createMemoryAdapter } from '../state/adapters';
+import { openStoredLab, openUnstoredLab, presentStorageKey } from './openLab';
+
+const counter: Instrument<{ count: number }, { n: number }> = {
+  name: 'Counter',
+  defaultConfig: () => ({ n: 1 }),
+  initialState: (config) => ({ count: config.n * 10 }),
+  render: () => null,
+};
+const other: Instrument<{ k: string }, { k: string }> = {
+  name: 'Other',
+  defaultConfig: () => ({ k: 'a' }),
+  initialState: (config) => ({ k: config.k }),
+  render: () => null,
+};
+const instruments = [counter, other] as unknown as InstrumentList;
+const base = { instruments, defaultInstrument: 'Counter' };
+
+describe('presentStorageKey', () => {
+  it('keeps a presented lab apart from the full one', () => {
+    expect(presentStorageKey('rosee')).toBe('rosee:present');
+  });
+});
+
+describe('opening a presented lab', () => {
+  it('opens one trial on the seed', () => {
+    const { store } = openUnstoredLab(base, {
+      instrument: 'Other',
+      config: { k: 'b' },
+    });
+    const trials = store.getState().trials;
+    expect(trials).toHaveLength(1);
+    expect(trials[0]).toMatchObject({
+      instrumentName: 'Other',
+      config: { k: 'b' },
+      state: { k: 'b' },
+    });
+  });
+
+  it('takes a seeded state and view over the ones the config would give', () => {
+    const { store } = openUnstoredLab(base, { config: { n: 2 }, state: { count: 7 }, view: 'v' });
+    expect(store.getState().trials[0]).toMatchObject({
+      instrumentName: 'Counter',
+      config: { n: 2 },
+      state: { count: 7 },
+      view: 'v',
+    });
+  });
+
+  it("keeps a returning visitor's trial while the seed is unchanged", async () => {
+    const storage = createMemoryAdapter();
+    const seed = { config: { n: 2 } };
+    const first = await openStoredLab(base, 'lab', storage, seed);
+    const id = first.store.getState().trials[0]?.id;
+    first.store.getState().updateTrialState(id as string, { count: 99 });
+    await first.close();
+
+    const second = await openStoredLab(base, 'lab', storage, { config: { n: 2 } });
+    expect(second.store.getState().trials).toHaveLength(1);
+    expect(second.store.getState().trials[0]).toMatchObject({ id, state: { count: 99 } });
+    await second.close();
+  });
+
+  it('reopens the trial on a seed that changed', async () => {
+    const storage = createMemoryAdapter();
+    const first = await openStoredLab(base, 'lab', storage, { config: { n: 2 } });
+    await first.close();
+
+    const second = await openStoredLab(base, 'lab', storage, { config: { n: 3 } });
+    const trials = second.store.getState().trials;
+    expect(trials).toHaveLength(1);
+    expect(trials[0]).toMatchObject({ config: { n: 3 }, state: { count: 30 } });
+    await second.close();
+
+    const third = await openStoredLab(base, 'lab', storage, { config: { n: 3 } });
+    expect(third.store.getState().trials[0]?.id).toBe(trials[0]?.id);
+    await third.close();
+  });
+});