@weasel-js/labkit 1.8.0 → 1.8.1

package/src/clock/trialClock.ts

@@ -0,0 +1,245 @@
+/**
+ * What an instrument declares to get a clock: how long a pass runs, how many
+ * passes, and how it opens. Shaped like a blits voice spec.
+ */
+export interface ClockCapability {
+  /** ms per pass. Omitted, the run never ends. */
+  duration?: number;
+  /** Passes: `true` endless, `false` one, `n` that many. Default `false`. */
+  loop?: boolean | number;
+  /** The rate it opens at; `0`, the default, opens paused. */
+  rate?: number;
+  /** `false` for an instrument whose state is built up by running, so time can
+   *  only move by running: no seek and no negative rate. Default `true`. */
+  seekable?: boolean;
+}
+
+/**
+ * A trial's time. A position (`elapsed`) moved by a signed `rate`, synced by
+ * the lab's frame loop once a frame. Named after blits' owner handle and
+ * `Ticked`, so a blits ticker can drive one and blits voices can play under it.
+ */
+export interface TrialClock {
+  /** ms the trial has played, rate applied, counted across passes. */
+  readonly elapsed: number;
+  /** Which pass `elapsed` falls in, 0 first; the last once the run is over. */
+  readonly pass: number;
+  /** How far through its pass, 0 to 1; 1 once the run is over. 0 with no duration. */
+  readonly phase: number;
+  /** Signed: 0 pauses and a negative rate plays backward. A write changes speed
+   *  at once and replaces any ramp. */
+  rate: number;
+  /** Passes, as `ClockCapability.loop`. */
+  loop: boolean | number;
+  /** Move `rate` to `to` linearly over `over` real ms; position stays continuous. */
+  ramp(to: number, over: number): void;
+  /** Move to `elapsed` ms from the start, clamped to the run. Never runs state
+   *  forward to meet it. Throws on a clock that is not seekable. */
+  seek(elapsed: number): void;
+  /** The frame loop reports the time, once a frame. */
+  sync(timestamp: number): void;
+  /** The time between now and the next sync does not count. */
+  rebase(): void;
+  /** Another frame would change nothing: paused, no ramp, nothing changed since
+   *  the last sync. */
+  readonly inert: boolean;
+  /** Called when a change needs frames again, once until the next sync. */
+  onWake(fn: () => void): () => void;
+  /** Called on a rate, seek or loop change, and when the run ends; never per frame. */
+  subscribe(fn: () => void): () => void;
+}
+
+/** A clock, and what labkit alone does with it. */
+export interface TrialClockHandle {
+  clock: TrialClock;
+  /** Back to 0 at the declared rate — the trial's Reset, allowed on a clock
+   *  that is not seekable. */
+  reset(): void;
+  /** Called after each sync that moved the clock or followed a change. */
+  onFrame(fn: (elapsed: number, pass: number) => void): () => void;
+}
+
+const passesOf = (loop: boolean | number): number =>
+  loop === true ? Number.POSITIVE_INFINITY : loop === false ? 1 : Math.max(1, loop);
+
+const checkRate = (rate: number, seekable: boolean): void => {
+  if (!Number.isFinite(rate)) throw new RangeError(`labkit: a clock's rate is finite, not ${rate}`);
+  if (rate < 0 && !seekable)
+    throw new RangeError('labkit: a clock that is not seekable cannot run backward');
+};
+
+/** A trial's clock, opened from its declaration and, for a trial reopened,
+ *  where it stood. */
+export function createTrialClock(
+  spec: ClockCapability,
+  start?: { elapsed: number; rate: number },
+): TrialClockHandle {
+  const duration = spec.duration ?? Number.POSITIVE_INFINITY;
+  const seekable = spec.seekable ?? true;
+  const openRate = spec.rate ?? 0;
+  checkRate(openRate, seekable);
+
+  let loop = spec.loop ?? false;
+  let span = duration * passesOf(loop);
+  let rate = start ? start.rate : openRate;
+  let elapsed = start ? Math.min(Math.max(0, start.elapsed), span) : 0;
+  let ramp: { to: number; left: number } | null = null;
+  let last = Number.NaN;
+  /** Changed since the last sync, so the next one is due even when paused. */
+  let changed = false;
+  /** Inert as of the last sync: the next one only records the time. */
+  let slept = false;
+  let wakeFired = false;
+  const wakes = new Set<() => void>();
+  const subs = new Set<() => void>();
+  const frames = new Set<(elapsed: number, pass: number) => void>();
+
+  const isInert = (): boolean => rate === 0 && ramp === null && !changed;
+  const notify = (): void => {
+    for (const fn of [...subs]) fn();
+  };
+  const change = (): void => {
+    changed = true;
+    if (wakeFired) return;
+    wakeFired = true;
+    for (const fn of [...wakes]) fn();
+  };
+  const passAt = (): number =>
+    duration > 0 && Number.isFinite(duration)
+      ? elapsed >= span
+        ? passesOf(loop) - 1
+        : Math.floor(elapsed / duration)
+      : 0;
+  const phaseAt = (): number =>
+    duration > 0 && Number.isFinite(duration)
+      ? elapsed >= span
+        ? 1
+        : (elapsed % duration) / duration
+      : 0;
+
+  /** ms of trial time over `dt` real ms, ramp included; settles the ramp. */
+  const advance = (dt: number): number => {
+    if (!ramp) return rate * dt;
+    if (dt >= ramp.left) {
+      const area = ((rate + ramp.to) / 2) * ramp.left + ramp.to * (dt - ramp.left);
+      rate = ramp.to;
+      ramp = null;
+      notify();
+      return area;
+    }
+    const next = rate + ((ramp.to - rate) * dt) / ramp.left;
+    const area = ((rate + next) / 2) * dt;
+    rate = next;
+    ramp.left -= dt;
+    return area;
+  };
+
+  const clock: TrialClock = {
+    get elapsed() {
+      return elapsed;
+    },
+    get pass() {
+      return passAt();
+    },
+    get phase() {
+      return phaseAt();
+    },
+    get rate() {
+      return rate;
+    },
+    set rate(next: number) {
+      checkRate(next, seekable);
+      rate = next;
+      ramp = null;
+      change();
+      notify();
+    },
+    get loop() {
+      return loop;
+    },
+    set loop(next: boolean | number) {
+      loop = next;
+      span = duration * passesOf(loop);
+      elapsed = Math.min(elapsed, span);
+      change();
+      notify();
+    },
+    ramp(to, over) {
+      checkRate(to, seekable);
+      if (!(over > 0)) {
+        clock.rate = to;
+        return;
+      }
+      ramp = { to, left: over };
+      change();
+      notify();
+    },
+    seek(target) {
+      if (!seekable) throw new Error('labkit: this clock is not seekable');
+      elapsed = Math.min(Math.max(0, target), span);
+      change();
+      notify();
+    },
+    sync(timestamp) {
+      const wasChanged = changed;
+      const before = elapsed;
+      if (!Number.isNaN(last) && !slept) {
+        elapsed += advance(Math.max(0, timestamp - last));
+        if (elapsed >= span && rate > 0) {
+          elapsed = span;
+          rate = 0;
+          ramp = null;
+          notify();
+        } else if (elapsed <= 0 && rate < 0) {
+          elapsed = 0;
+          rate = 0;
+          ramp = null;
+          notify();
+        }
+      }
+      last = timestamp;
+      changed = false;
+      wakeFired = false;
+      slept = isInert();
+      if (elapsed !== before || wasChanged) {
+        const pass = passAt();
+        for (const fn of [...frames]) fn(elapsed, pass);
+      }
+    },
+    rebase() {
+      last = Number.NaN;
+    },
+    get inert() {
+      return isInert();
+    },
+    onWake(fn) {
+      wakes.add(fn);
+      return () => {
+        wakes.delete(fn);
+      };
+    },
+    subscribe(fn) {
+      subs.add(fn);
+      return () => {
+        subs.delete(fn);
+      };
+    },
+  };
+
+  return {
+    clock,
+    reset() {
+      elapsed = 0;
+      rate = openRate;
+      ramp = null;
+      change();
+      notify();
+    },
+    onFrame(fn) {
+      frames.add(fn);
+      return () => {
+        frames.delete(fn);
+      };
+    },
+  };
+}

package/src/clock/useClockLoop.ts

@@ -0,0 +1,45 @@
+import { useVisibleRaf } from '@weasel-js/core';
+import { useEffect } from 'react';
+import type { ClockRegistry } from './clockRegistry';
+
+/**
+ * The lab's one frame loop for every trial clock: syncs each clock that is not
+ * inert, and sleeps once every clock is, until one wakes. Shaped like a blits
+ * `ticker`, so one could take its place.
+ */
+export function useClockLoop(registry: ClockRegistry): void {
+  const loop = useVisibleRaf(
+    (timestamp) => {
+      let live = false;
+      for (const { clock } of registry.all()) {
+        if (clock.inert) continue;
+        clock.sync(timestamp);
+        if (!clock.inert) live = true;
+      }
+      if (live) loop.request();
+    },
+    {
+      onResume: () => {
+        for (const { clock } of registry.all()) clock.rebase();
+      },
+    },
+  );
+
+  useEffect(() => {
+    let unwakes: (() => void)[] = [];
+    const attach = (): void => {
+      for (const off of unwakes) off();
+      unwakes = [];
+      for (const { clock } of registry.all()) {
+        unwakes.push(clock.onWake(() => loop.request()));
+        if (!clock.inert) loop.request();
+      }
+    };
+    attach();
+    const off = registry.subscribe(attach);
+    return () => {
+      off();
+      for (const unwake of unwakes) unwake();
+    };
+  }, [registry, loop]);
+}

package/src/config/resolve.test.ts

@@ -215,6 +215,18 @@ describe('resolveConfigSchema / nested groups', () => {
     expect(() => resolveConfigSchema(schema, [])).toThrow(/manual/);
   });
 
+  it('rejects a value leaf whose kind nothing can infer, naming it and the fix', () => {
+    const schema = f.schema({ grid: f.group({ when: f.value<number | null>(null) }) });
+    expect(() => resolveConfigSchema(schema, [])).toThrow(/grid\.when/);
+    expect(() => resolveConfigSchema(schema, [])).toThrow(/f\.custom/);
+  });
+
+  it('accepts a kindless value leaf once a lab rule supplies its kind', () => {
+    const rule: ConfigRule = (ctx) => (ctx.default === null ? { kind: 'number' } : null);
+    const schema = f.schema({ when: f.value<number | null>(null) });
+    expect(leafAt(resolveConfigSchema(schema, [rule]), 'when').kind).toBe('number');
+  });
+
   it('carries autoResolve, unpinned and manual onto the resolved leaf', () => {
     const r = resolveConfigSchema(
       f.schema({

package/src/config/resolve.ts

@@ -127,6 +127,11 @@ function resolveEntry(
     ...(entry.kind === null ? {} : { kind: entry.kind }),
   });
   const patch = applyRules(seed, { key, path, default: entry.default }, sink.chain);
+  if (patch.kind === undefined) {
+    throw new Error(
+      `[labkit] "${path}" is an f.value whose kind cannot be inferred from its default (${String(entry.default)}) — declare it with a typed builder, or f.custom(kind, default) for a value with no row`,
+    );
+  }
   const { autoResolve, unpinned, manual } = entry.options;
   return {
     ...patch,

package/src/controls/ControlMatrix.tsx

@@ -116,7 +116,7 @@ export function ControlMatrix({
     inheritHint ?? ((_: ControlMatrixColumn) => (fallback ? `from ${nameOf(fallback)}` : ''));
   const [open, setOpen] = useState<OpenCell | null>(null);
   const triggerRef = useRef<HTMLElement | null>(null);
-  const { anchor, portalProps } = useOverlayPortal();
+  const { anchor, portalProps, ready } = useOverlayPortal();
 
   const leafAt = (path: string): PrefLeaf | undefined => {
     const node = schemaNodeAtPath(schema.group, path);
@@ -195,59 +195,61 @@ export function ControlMatrix({
           ))}
         </tbody>
       </table>
-      <RACPopover
-        triggerRef={triggerRef}
-        isOpen={open !== null}
-        onOpenChange={(next) => {
-          if (!next) setOpen(null);
-        }}
-        placement="bottom"
-        className="lk-control-matrix__popover"
-        data-weasel-overlay=""
-        {...portalProps}
-      >
-        {open ? (
-          <RACDialog
-            className="lk-control-matrix__editor"
-            aria-label={`${nameOf(open.column)} ${open.label}`}
-          >
-            <PropertyList pack="one-up">
-              <Editor
-                open={open}
-                schema={schema}
-                config={config}
-                setConfig={setConfig}
-                close={() => setOpen(null)}
-              />
-            </PropertyList>
-            {clearable(open.leaf) ? (
-              <div className="lk-control-matrix__editor-actions">
-                <Button
-                  size="sm"
-                  variant="ghost"
-                  disabled={!valueAtPath(config, open.path) || auto.has(open.path)}
-                  onClick={() => setConfig(open.path, null)}
-                >
-                  Clear
-                </Button>
-              </div>
-            ) : null}
-            {open.first ? null : (
-              <div className="lk-control-matrix__editor-actions">
-                <Button
-                  size="sm"
-                  variant="ghost"
-                  disabled={auto.has(open.path)}
-                  tooltip={`Inherit ${hintFor(open.column)}`}
-                  onClick={() => setConfig(open.path, autoValue)}
-                >
-                  Inherit
-                </Button>
-              </div>
-            )}
-          </RACDialog>
-        ) : null}
-      </RACPopover>
+      {ready && (
+        <RACPopover
+          triggerRef={triggerRef}
+          isOpen={open !== null}
+          onOpenChange={(next) => {
+            if (!next) setOpen(null);
+          }}
+          placement="bottom"
+          className="lk-control-matrix__popover"
+          data-weasel-overlay=""
+          {...portalProps}
+        >
+          {open ? (
+            <RACDialog
+              className="lk-control-matrix__editor"
+              aria-label={`${nameOf(open.column)} ${open.label}`}
+            >
+              <PropertyList pack="one-up">
+                <Editor
+                  open={open}
+                  schema={schema}
+                  config={config}
+                  setConfig={setConfig}
+                  close={() => setOpen(null)}
+                />
+              </PropertyList>
+              {clearable(open.leaf) ? (
+                <div className="lk-control-matrix__editor-actions">
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    disabled={!valueAtPath(config, open.path) || auto.has(open.path)}
+                    onClick={() => setConfig(open.path, null)}
+                  >
+                    Clear
+                  </Button>
+                </div>
+              ) : null}
+              {open.first ? null : (
+                <div className="lk-control-matrix__editor-actions">
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    disabled={auto.has(open.path)}
+                    tooltip={`Inherit ${hintFor(open.column)}`}
+                    onClick={() => setConfig(open.path, autoValue)}
+                  >
+                    Inherit
+                  </Button>
+                </div>
+              )}
+            </RACDialog>
+          ) : null}
+        </RACPopover>
+      )}
     </div>
   );
 

package/src/index.ts

@@ -173,6 +173,7 @@ export {
   zoomAt,
 } from './canvas';
 export * from './chrome';
+export * from './clock';
 export { type Auto, auto, isAuto } from './config/auto';
 export { autoPathsOf, resolveAutoConfig } from './config/autoConfig';
 export {
@@ -274,6 +275,7 @@ export * from './job';
 export * from './lab';
 export type { LayerListItem, LayerListProps, LayerMove } from './layers';
 export { LayerList, moveLayers } from './layers';
+export * from './lightbox';
 export * from './primitives';
 export { SPECIMEN_SECTIONS, Specimen } from './specimen/Specimen';
 export {
@@ -311,7 +313,6 @@ export type {
   TrialInfo,
   TrialRecord,
   TrialStateHandle,
-  UndoStack,
 } from './state/types';
 export type { UndockedPanel, UndockedPanels } from './state/undock';
 export { dockPanel, panelKey, undockPanel } from './state/undock';
@@ -323,5 +324,5 @@ export * from './surface';
 export { interstellarTheme } from './theme/interstellar';
 export type { ToolCapability, TrialTool } from './tools/types';
 export * from './trial';
-export type { EventBus, EventListener } from './undo';
+export type { EventBus, EventListener, UndoStack } from './undo';
 export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo';

package/src/instrument/types.ts

@@ -3,6 +3,7 @@ import type { ReactNode } from 'react';
 import type { AnnotationsCapability } from '../annotations/types';
 import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
+import type { ClockCapability, TrialClock } from '../clock/trialClock';
 import type { ConfigPath, ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
@@ -41,6 +42,8 @@ export interface RenderContext<TS = unknown, TC = unknown> {
      * reading it works over either view.
      */
     pointer: PointerContextValue;
+    /** The trial's clock, present when the instrument declares `clock`. */
+    clock?: TrialClock;
   };
   emit: (event: string) => void;
   /** Present only when the instrument declares a `job`. */
@@ -54,7 +57,21 @@ export interface RenderContext<TS = unknown, TC = unknown> {
  *  set `ctx.lineWidth = 1 / zoom` to keep a hairline hairline. */
 export interface CanvasLayer<TS = unknown, TC = unknown> {
   id: string;
-  draw: (ctx: CanvasRenderingContext2D, args: { state: TS; config: TC; zoom: number }) => void;
+  /** Redraw every frame the trial's clock moves, not only when state, config
+   *  or the view change. For a layer that reads `elapsed`, `pass` or `phase`. */
+  timed?: boolean;
+  draw: (
+    ctx: CanvasRenderingContext2D,
+    args: {
+      state: TS;
+      config: TC;
+      zoom: number;
+      /** The trial clock's, as `TrialClock` has them; 0 with no clock. */
+      elapsed: number;
+      pass: number;
+      phase: number;
+    },
+  ) => void;
 }
 
 /** Declares that an instrument draws to a canvas: its layers, and where the
@@ -183,6 +200,9 @@ export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
   annotations?: AnnotationsCapability<TS, TC>;
   /** Chrome this instrument contributes beyond what its capabilities imply. */
   chrome?: TrialContribution[];
+  /** Gives the trial a clock: playback time that layers, renderers and chrome
+   *  read and drive. */
+  clock?: ClockCapability;
   /** Work too slow to do during a render. The runtime starts it, aborts it on
    *  unmount and on a `key` change, and renders progress into the trial. */
   job?: JobCapability<TS, TC, TItem>;

package/src/lab/Lab.chrome.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, it, vi } from 'vitest';
 import type { TrialContribution } from '../chrome/types';
@@ -32,6 +32,13 @@ describe('<Lab> chrome', () => {
     expect(screen.getByRole('button', { name: 'Export' })).toBeInTheDocument();
   });
 
+  it('puts the expand toggle in the trial title bar instead of the tile corner', async () => {
+    await renderSettled(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" />);
+    expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'Expand trial' }));
+    expect(document.querySelector('.lk-lightbox--expanded .lk-trial')).not.toBeNull();
+  });
+
   it('suppresses a built-in by id', async () => {
     await renderSettled(
       <Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['snapshot']} />,

package/src/lab/Lab.presentation.test.tsx

@@ -0,0 +1,113 @@
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { createMemoryAdapter } from '../state/adapters';
+import { labPrefix } from '../state/labRecords';
+import { Lab, type LabProps } from './Lab';
+import { LabContext, type LabContextValue } from './LabContext';
+import { type Presentation, usePresentation } from './presentation';
+
+const stub: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({ count: 0 }),
+  initialState: (config) => ({ value: (config as { count: number }).count }),
+  render: ({ state }) => <div data-testid="stub-content">{(state as { value: number }).value}</div>,
+};
+
+let presentation: Presentation | null = null;
+let lab: LabContextValue | null = null;
+function Capture() {
+  presentation = usePresentation();
+  return (
+    <LabContext.Consumer>
+      {(value) => {
+        lab = value;
+        return null;
+      }}
+    </LabContext.Consumer>
+  );
+}
+
+function mountLab(props: Partial<LabProps> = {}) {
+  return renderSettled(
+    <Lab {...({ instruments: [stub], defaultInstrument: 'Stub', ...props } as LabProps)}>
+      <Capture />
+    </Lab>,
+  );
+}
+
+const root = (container: HTMLElement) => container.querySelector('.lk-lab') as HTMLElement;
+const presented = (container: HTMLElement) =>
+  container.querySelectorAll<HTMLElement>('.lk-trial[data-lk-presented]');
+
+afterEach(() => {
+  presentation = null;
+  lab = null;
+  history.replaceState(null, '', '/');
+  vi.restoreAllMocks();
+});
+
+describe('<Lab present>', () => {
+  it('presents one trial opened on the seed', async () => {
+    const { container, getByTestId } = await mountLab({
+      present: true,
+      seed: { config: { count: 4 } },
+    });
+    expect(root(container).classList.contains('lk-lab--present')).toBe(true);
+    expect(presented(container)).toHaveLength(1);
+    expect(presented(container)[0]?.querySelector('.lk-trial__stage')).not.toBeNull();
+    expect(getByTestId('stub-content').textContent).toBe('4');
+    expect(presentation?.active).toBe(true);
+  });
+
+  it('presents from `?present` in the URL', async () => {
+    history.replaceState(null, '', '/?present');
+    const { container } = await mountLab();
+    expect(presented(container)).toHaveLength(1);
+  });
+
+  it('keeps a stored lab presenting under its own key', async () => {
+    const storage = createMemoryAdapter();
+    const { unmount } = await mountLab({ present: true, storageKey: 'lab', storage });
+    await waitFor(async () =>
+      expect((await storage.list(labPrefix('lab:present'))).length).toBeGreaterThan(0),
+    );
+    unmount();
+    expect(await storage.list(labPrefix('lab'))).toEqual([]);
+  });
+
+  it('does not leave on Escape, having nowhere to go back to', async () => {
+    const { container } = await mountLab({ present: true });
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(presented(container)).toHaveLength(1);
+  });
+
+  it('warns that a seed is ignored when the lab does not start presenting', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await mountLab({ seed: { config: { count: 4 } } });
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('`seed`'));
+  });
+});
+
+describe('usePresentation', () => {
+  it('presents the focused trial and returns on Escape', async () => {
+    const { container } = await mountLab();
+    await act(async () => lab?.addTrial('Stub', { config: { count: 2 } }));
+    await act(async () => lab?.focusTrial(lab.trials[1]?.id as string));
+    expect(presented(container)).toHaveLength(0);
+
+    await act(async () => presentation?.enter());
+    expect(presented(container)).toHaveLength(1);
+    expect(presented(container)[0]?.dataset.trialId).toBe(lab?.trials[1]?.id);
+
+    await act(async () => fireEvent.keyDown(document, { key: 'Escape' }));
+    expect(presented(container)).toHaveLength(0);
+    expect(root(container).classList.contains('lk-lab--present')).toBe(false);
+  });
+
+  it('throws outside <Lab>', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<Capture />)).toThrow(/inside <Lab>/);
+  });
+});