@weasel-js/labkit 1.7.3 → 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/builder.ts

@@ -1,4 +1,4 @@
-import type { Display } from '@weasel-js/quantity';
+import type { Display, InfinityText } from '@weasel-js/quantity';
 import type { PrefLeaf, PrefNumberUnit } from '@weasel-js/ui';
 import { type Auto, isAuto } from './auto';
 import type {
@@ -159,6 +159,16 @@ export class NumberNode extends BaseNode<number> {
     return this.ann({ unit });
   }
 
+  /**
+   * Make the top of the range mean infinity: the slider's `max` stop stores
+   * `Infinity` and reads `word` — `.range(0, 5000).endless('never')`. A value
+   * of `Infinity` sits at that stop. `at: 'min'` puts it at the bottom
+   * instead, as `-Infinity`; `'both'` does both.
+   */
+  endless(word?: InfinityText, at: 'min' | 'max' | 'both' = 'max'): this {
+    return this.ann(word === undefined ? { endless: at } : { endless: at, infinity: word });
+  }
+
   /** Force a slider even without both bounds. */
   slider(): this {
     return this.ann({ control: 'slider' });

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/config/types.ts

@@ -1,4 +1,4 @@
-import type { Display } from '@weasel-js/quantity';
+import type { Display, InfinityText } from '@weasel-js/quantity';
 import type { PrefGroup, PrefLeaf, PrefNumberUnit, PrefRenderer } from '@weasel-js/ui';
 import type { ReactNode } from 'react';
 
@@ -36,6 +36,10 @@ export interface Annotations {
   /** Display-unit conversion for a number stored in a canonical unit — the
    *  value, its bounds and its step all convert at the control's edge. */
   unit?: PrefNumberUnit;
+  /** Which end of a number's slider stands for infinity. */
+  endless?: 'min' | 'max' | 'both';
+  /** The word a number's infinity shows as — `'never'`. Default `∞`. */
+  infinity?: InfinityText;
   /** A color leaf's value carries alpha (`#rrggbbaa`) and its row edits it. */
   alpha?: boolean;
   control?: string;

package/src/controls/ControlMatrix.test.tsx

@@ -158,6 +158,16 @@ describe('<ControlMatrix>', () => {
     expect(setConfig).toHaveBeenCalledWith('looks.window.glow', 0.75);
   });
 
+  it('lists an enum cell’s options in its popover, with no dropdown inside, and closes on a choice', () => {
+    const { setConfig } = setup();
+    fireEvent.click(cell('Window Shading'));
+    const dialog = screen.getByRole('dialog', { name: 'Window Shading' });
+    expect(within(dialog).queryByRole('button', { name: /Shading/ })).toBeNull();
+    fireEvent.click(within(dialog).getByRole('radio', { name: 'Soft' }));
+    expect(setConfig).toHaveBeenCalledWith('looks.window.shading', 'soft');
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
   it('unpins from the popover with Inherit, disabled while already inherited', () => {
     const { setConfig, unmount } = setup();
     fireEvent.click(cell('Window Glow'));

package/src/controls/ControlMatrix.tsx

@@ -5,6 +5,7 @@ import {
   isPrefLeaf,
   type PrefLeaf,
   type PropertyControlProps,
+  PropertyField,
   PropertyHelp,
   PropertyList,
   PropertyPanel,
@@ -115,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);
@@ -194,63 +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">
-              <ControlRow
-                path={open.path}
-                leaf={open.leaf}
-                resolved={schema}
-                config={config}
-                shown={config}
-                setConfig={setConfig}
-                pack="one-up"
-                auto={NO_AUTO}
-                setRowAuto={noop}
-              />
-            </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>
   );
 
@@ -262,6 +261,59 @@ export function ControlMatrix({
   );
 }
 
+/**
+ * The control a cell opens. An enum lists its options outright, as radios: the
+ * panel's dropdown would be a second popup opened from inside this one.
+ * Choosing one is the whole edit, so it closes the popover.
+ */
+function Editor({
+  open,
+  schema,
+  config,
+  setConfig,
+  close,
+}: {
+  open: OpenCell;
+  schema: ResolvedConfig;
+  config: Record<string, unknown>;
+  setConfig: (path: string, value: unknown) => void;
+  close: () => void;
+}) {
+  const { path, leaf } = open;
+  const field = isBuiltinToolPref(leaf)
+    ? prefFieldProps(leaf, {
+        value: valueAtPath(config, path) ?? leaf.default,
+        setValue: (next) => setConfig(path, next),
+      })
+    : null;
+  if (field?.kind === 'enum') {
+    return (
+      <PropertyField
+        {...field}
+        label={leaf.name}
+        control="radio"
+        onChange={(next: Parameters<typeof field.onChange>[0]) => {
+          field.onChange(next);
+          close();
+        }}
+      />
+    );
+  }
+  return (
+    <ControlRow
+      path={path}
+      leaf={leaf}
+      resolved={schema}
+      config={config}
+      shown={config}
+      setConfig={setConfig}
+      pack="one-up"
+      auto={NO_AUTO}
+      setRowAuto={noop}
+    />
+  );
+}
+
 function ColumnHeader({
   column,
   onClick,

package/src/controls/ControlPanel.test.tsx

@@ -1188,3 +1188,33 @@ describe('<ControlPanel> resettable group', () => {
     ]);
   });
 });
+
+describe('<ControlPanel> endless number', () => {
+  it('reads its word at the top of the range and writes Infinity there', () => {
+    const schema = resolveConfigSchema(
+      f.schema({ cut: f.number(Infinity).range(0, 5000).step(50).suffix('ms').endless('never') }),
+      [],
+    );
+    const setConfig = vi.fn();
+    function Harness() {
+      const [config, setState] = useState<Record<string, unknown>>({ cut: Infinity });
+      return (
+        <ControlPanel
+          schema={schema}
+          config={config}
+          setConfig={(key: string, value: unknown) => {
+            setConfig(key, value);
+            setState((c) => ({ ...c, [key]: value }));
+          }}
+        />
+      );
+    }
+    render(<Harness />);
+    expect(screen.getByRole('spinbutton')).toHaveValue('never');
+    expect(screen.queryByText('ms')).toBeNull();
+    fireEvent.change(screen.getByRole('slider'), { target: { value: '4950' } });
+    expect(setConfig).toHaveBeenLastCalledWith('cut', 4950);
+    fireEvent.change(screen.getByRole('slider'), { target: { value: '5000' } });
+    expect(setConfig).toHaveBeenLastCalledWith('cut', Infinity);
+  });
+});

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';