@weasel-js/labkit 1.8.0 → 1.8.1

package/src/clock/clock.integration.test.tsx

@@ -0,0 +1,95 @@
+import { act, fireEvent, screen } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
+import { describe, expect, it } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+import { useLabContext } from '../lab/LabContext';
+import { useLabStore } from '../state/context';
+import { useTrialClock } from './hooks';
+
+function Readout({ label }: { label: string }) {
+  const clock = useTrialClock();
+  return <output aria-label={label}>{clock ? `${clock.elapsed}@${clock.rate}` : 'none'}</output>;
+}
+
+function Persisted({ trialId }: { trialId: string }) {
+  const clock = useLabStore().trials.find((t) => t.id === trialId)?.clock;
+  return (
+    <output aria-label="persisted">{clock ? `${clock.elapsed}@${clock.rate}` : 'none'}</output>
+  );
+}
+
+function ResetButton({ trialId }: { trialId: string }) {
+  const lab = useLabContext();
+  return (
+    <button type="button" onClick={() => lab.resetTrial(trialId)}>
+      reset trial
+    </button>
+  );
+}
+
+const timed: Instrument = {
+  name: 'Timed',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  clock: { duration: 1000 },
+  render: (ctx) => (
+    <>
+      <button type="button" onClick={() => ctx.trial.clock?.seek(500)}>
+        seek
+      </button>
+      <button
+        type="button"
+        onClick={() => {
+          if (ctx.trial.clock) ctx.trial.clock.rate = 2;
+        }}
+      >
+        fast
+      </button>
+      <Readout label="inside" />
+      <Persisted trialId={ctx.trial.id} />
+      <ResetButton trialId={ctx.trial.id} />
+    </>
+  ),
+};
+
+describe('a trial clock in a mounted lab', () => {
+  it('reaches the instrument, the trial, the lab, the record and Reset', async () => {
+    await renderSettled(
+      <Lab title="T" instruments={[timed]} defaultInstrument="Timed">
+        <Readout label="outside" />
+      </Lab>,
+    );
+    expect(screen.getByLabelText('inside')).toHaveTextContent('0@0');
+    expect(screen.getByLabelText('outside')).toHaveTextContent('0@0');
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'seek' }));
+    });
+    expect(screen.getByLabelText('inside')).toHaveTextContent('500@0');
+    expect(screen.getByLabelText('outside')).toHaveTextContent('500@0');
+    expect(screen.getByLabelText('persisted')).toHaveTextContent('500@0');
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'fast' }));
+    });
+    expect(screen.getByLabelText('persisted')).toHaveTextContent('500@2');
+
+    await act(async () => {
+      fireEvent.click(screen.getByRole('button', { name: 'reset trial' }));
+    });
+    expect(screen.getByLabelText('inside')).toHaveTextContent('0@0');
+    expect(screen.getByLabelText('persisted')).toHaveTextContent('0@0');
+  });
+
+  it('gives an instrument without a clock none', async () => {
+    const plain: Instrument = {
+      ...timed,
+      name: 'Plain',
+      clock: undefined,
+      render: () => <Readout label="inside" />,
+    };
+    await renderSettled(<Lab title="T" instruments={[plain]} defaultInstrument="Plain" />);
+    expect(screen.getByLabelText('inside')).toHaveTextContent('none');
+  });
+});

package/src/clock/clockRegistry.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createClockRegistry } from './clockRegistry';
+import { createTrialClock } from './trialClock';
+
+describe('createClockRegistry', () => {
+  it('publishes a clock under its trial id until released', () => {
+    const registry = createClockRegistry();
+    const handle = createTrialClock({});
+    const release = registry.register('t1', handle);
+    expect(registry.get('t1')).toBe(handle);
+    expect([...registry.all()]).toEqual([handle]);
+    release();
+    expect(registry.get('t1')).toBeNull();
+  });
+
+  it('notifies on register and release', () => {
+    const registry = createClockRegistry();
+    const listener = vi.fn();
+    registry.subscribe(listener);
+    registry.register('t1', createTrialClock({}))();
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  it('leaves a newer registration alone when a stale release runs', () => {
+    const registry = createClockRegistry();
+    const first = createTrialClock({});
+    const second = createTrialClock({});
+    const releaseFirst = registry.register('t1', first);
+    registry.register('t1', second);
+    releaseFirst();
+    expect(registry.get('t1')).toBe(second);
+  });
+});

package/src/clock/clockRegistry.ts

@@ -0,0 +1,46 @@
+import { createContext } from 'react';
+import type { TrialClockHandle } from './trialClock';
+
+/** A lab's trial clocks, by trial id. A trial has at most one. */
+export interface ClockRegistry {
+  /** Publish `handle` under `trialId` and return its release. */
+  register(trialId: string, handle: TrialClockHandle): () => void;
+  get(trialId: string): TrialClockHandle | null;
+  all(): Iterable<TrialClockHandle>;
+  /** Fires after any register or release. Shaped for `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+}
+
+/** An empty in-memory `ClockRegistry`. */
+export function createClockRegistry(): ClockRegistry {
+  const handles = new Map<string, TrialClockHandle>();
+  const listeners = new Set<() => void>();
+  const notify = (): void => {
+    for (const l of [...listeners]) l();
+  };
+  return {
+    register(trialId, handle) {
+      handles.set(trialId, handle);
+      notify();
+      return () => {
+        if (handles.get(trialId) !== handle) return;
+        handles.delete(trialId);
+        notify();
+      };
+    },
+    get: (trialId) => handles.get(trialId) ?? null,
+    all: () => handles.values(),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** The registry a lab keeps its trials' clocks in. */
+export const ClockRegistryContext = createContext<ClockRegistry | null>(null);
+
+/** The clock of the trial a component renders inside, when it declares one. */
+export const TrialClockContext = createContext<TrialClockHandle | null>(null);

package/src/clock/hooks.ts

@@ -0,0 +1,44 @@
+import { useLatest } from '@weasel-js/core';
+import { useContext, useEffect, useReducer, useSyncExternalStore } from 'react';
+import { LabContext } from '../lab/LabContext';
+import { ClockRegistryContext, TrialClockContext } from './clockRegistry';
+import type { TrialClock } from './trialClock';
+
+const NO_SUBSCRIBE = () => () => {};
+
+/**
+ * A trial's clock: `trialId`'s, else the one of the trial this renders inside,
+ * else the lab's focused trial's. `null` when that trial declares no clock.
+ * Re-renders on rate, seek and loop changes, never per frame — read `elapsed`
+ * per frame through {@link useClockFrame}.
+ */
+export function useTrialClock(trialId?: string): TrialClock | null {
+  const registry = useContext(ClockRegistryContext);
+  const own = useContext(TrialClockContext);
+  const lab = useContext(LabContext);
+  useSyncExternalStore(registry?.subscribe ?? NO_SUBSCRIBE, () => (registry ? resolve() : own));
+  function resolve() {
+    if (trialId !== undefined) return registry?.get(trialId) ?? null;
+    if (own) return own;
+    const focused = lab?.focusedTrialId;
+    return focused ? (registry?.get(focused) ?? null) : null;
+  }
+  const clock = resolve()?.clock ?? null;
+  const [, bump] = useReducer((n: number) => n + 1, 0);
+  useEffect(() => clock?.subscribe(bump), [clock]);
+  return clock;
+}
+
+/**
+ * Run `fn` after each frame the clock of the trial this renders inside moves,
+ * with its `elapsed` and `pass`, outside React's render — for a renderer that
+ * draws imperatively, or text that changes every frame written into a ref.
+ */
+export function useClockFrame(fn: (elapsed: number, pass: number) => void): void {
+  const handle = useContext(TrialClockContext);
+  const latest = useLatest(fn);
+  useEffect(
+    () => handle?.onFrame((elapsed, pass) => latest.current(elapsed, pass)),
+    [handle, latest],
+  );
+}

package/src/clock/index.ts

@@ -0,0 +1,2 @@
+export { useClockFrame, useTrialClock } from './hooks';
+export type { ClockCapability, TrialClock } from './trialClock';

package/src/clock/trialClock.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTrialClock } from './trialClock';
+
+/** A clock already synced once at t=0, so the next sync advances it. */
+function started(...args: Parameters<typeof createTrialClock>) {
+  const c = createTrialClock(...args);
+  c.clock.sync(0);
+  return c;
+}
+
+describe('createTrialClock', () => {
+  it('opens paused at 0, and inert', () => {
+    const { clock } = createTrialClock({});
+    expect(clock.elapsed).toBe(0);
+    expect(clock.rate).toBe(0);
+    expect(clock.inert).toBe(true);
+  });
+
+  it('opens at the declared rate', () => {
+    const { clock } = createTrialClock({ rate: 2 });
+    expect(clock.rate).toBe(2);
+    expect(clock.inert).toBe(false);
+  });
+
+  it('advances by rate times real time', () => {
+    const { clock } = started({ rate: 2 });
+    clock.sync(100);
+    expect(clock.elapsed).toBe(200);
+  });
+
+  it('records the time on its first sync without advancing', () => {
+    const { clock } = createTrialClock({ rate: 1 });
+    clock.sync(5000);
+    expect(clock.elapsed).toBe(0);
+    clock.sync(5016);
+    expect(clock.elapsed).toBe(16);
+  });
+
+  it('plays backward at a negative rate', () => {
+    const { clock } = started({ rate: -1 }, { elapsed: 500, rate: -1 });
+    clock.sync(200);
+    expect(clock.elapsed).toBe(300);
+  });
+
+  it('does not charge a sleep to the clock when it wakes', () => {
+    const { clock } = started({ rate: 1 });
+    clock.sync(10);
+    expect(clock.elapsed).toBe(10);
+    clock.rate = 0;
+    clock.sync(20);
+    expect(clock.inert).toBe(true);
+    clock.rate = 1;
+    clock.sync(100_000);
+    expect(clock.elapsed).toBe(10);
+    clock.sync(100_016);
+    expect(clock.elapsed).toBe(26);
+  });
+
+  it('drops the time between a rebase and the next sync', () => {
+    const { clock } = started({ rate: 1 });
+    clock.sync(100);
+    clock.rebase();
+    clock.sync(60_000);
+    expect(clock.elapsed).toBe(100);
+    clock.sync(60_010);
+    expect(clock.elapsed).toBe(110);
+  });
+
+  describe('ends', () => {
+    it('holds at the end of a run and pauses', () => {
+      const listener = vi.fn();
+      const { clock } = started({ duration: 1000, rate: 1 });
+      clock.subscribe(listener);
+      clock.sync(1500);
+      expect(clock.elapsed).toBe(1000);
+      expect(clock.rate).toBe(0);
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it('holds at 0 playing backward and pauses', () => {
+      const { clock } = started({ duration: 1000 }, { elapsed: 100, rate: -1 });
+      clock.sync(500);
+      expect(clock.elapsed).toBe(0);
+      expect(clock.rate).toBe(0);
+    });
+
+    it('never ends with no duration', () => {
+      const { clock } = started({ rate: 1 });
+      clock.sync(1e9);
+      expect(clock.elapsed).toBe(1e9);
+      expect(clock.rate).toBe(1);
+    });
+
+    it('runs n passes when loop is n, counting them', () => {
+      const { clock } = started({ duration: 100, loop: 3, rate: 1 });
+      clock.sync(250);
+      expect(clock.pass).toBe(2);
+      expect(clock.phase).toBeCloseTo(0.5);
+      clock.sync(400);
+      expect(clock.elapsed).toBe(300);
+      expect(clock.pass).toBe(2);
+      expect(clock.phase).toBe(1);
+      expect(clock.rate).toBe(0);
+    });
+
+    it('loops forever on loop: true, the phase wrapping both ways', () => {
+      const { clock } = started({ duration: 100, loop: true, rate: 1 });
+      clock.sync(1050);
+      expect(clock.pass).toBe(10);
+      expect(clock.phase).toBeCloseTo(0.5);
+      clock.rate = -1;
+      clock.sync(1050);
+      clock.sync(1150);
+      expect(clock.pass).toBe(9);
+      expect(clock.phase).toBeCloseTo(0.5);
+    });
+
+    it('plays once by default', () => {
+      const { clock } = started({ duration: 100, rate: 1 });
+      clock.sync(150);
+      expect(clock.elapsed).toBe(100);
+    });
+  });
+
+  describe('seek', () => {
+    it('is absolute, across passes', () => {
+      const { clock } = createTrialClock({ duration: 100, loop: true });
+      clock.seek(250);
+      expect(clock.elapsed).toBe(250);
+      expect(clock.pass).toBe(2);
+    });
+
+    it('clamps to the run', () => {
+      const { clock } = createTrialClock({ duration: 100, loop: 2 });
+      clock.seek(-5);
+      expect(clock.elapsed).toBe(0);
+      clock.seek(999);
+      expect(clock.elapsed).toBe(200);
+    });
+
+    it('wakes a paused clock for one frame', () => {
+      const wake = vi.fn();
+      const { clock } = started({});
+      clock.onWake(wake);
+      clock.seek(50);
+      expect(wake).toHaveBeenCalledTimes(1);
+      expect(clock.inert).toBe(false);
+      clock.sync(16);
+      expect(clock.inert).toBe(true);
+    });
+  });
+
+  describe('seekable: false', () => {
+    it('throws on any seek', () => {
+      const { clock } = createTrialClock({ seekable: false });
+      expect(() => clock.seek(0)).toThrow();
+      expect(() => clock.seek(10)).toThrow();
+    });
+
+    it('throws on a negative rate, set or ramped', () => {
+      const { clock } = createTrialClock({ seekable: false });
+      expect(() => {
+        clock.rate = -1;
+      }).toThrow();
+      expect(() => clock.ramp(-1, 100)).toThrow();
+    });
+
+    it('still resets to 0 at its declared rate', () => {
+      const c = started({ seekable: false, rate: 1 });
+      c.clock.sync(500);
+      c.clock.rate = 3;
+      c.reset();
+      expect(c.clock.elapsed).toBe(0);
+      expect(c.clock.rate).toBe(1);
+    });
+  });
+
+  describe('ramp', () => {
+    it('moves rate linearly and integrates position', () => {
+      const { clock } = started({ rate: 0 });
+      clock.ramp(2, 100);
+      clock.sync(10); // woken: records the time
+      clock.sync(110);
+      expect(clock.rate).toBe(2);
+      expect(clock.elapsed).toBeCloseTo(100);
+      clock.sync(160);
+      expect(clock.elapsed).toBeCloseTo(200);
+    });
+
+    it('finishes mid-frame and runs on at the new rate', () => {
+      const { clock } = started({ rate: 1 });
+      clock.ramp(3, 100);
+      clock.sync(200);
+      expect(clock.rate).toBe(3);
+      expect(clock.elapsed).toBeCloseTo(200 + 300);
+    });
+
+    it('is replaced by a rate write', () => {
+      const { clock } = started({ rate: 1 });
+      clock.ramp(5, 1000);
+      clock.rate = 0;
+      clock.sync(500);
+      expect(clock.elapsed).toBe(0);
+    });
+  });
+
+  describe('notifications', () => {
+    it('subscribe fires on rate, seek and loop changes, not per frame', () => {
+      const listener = vi.fn();
+      const { clock } = started({ rate: 1, duration: 1000 });
+      clock.subscribe(listener);
+      clock.sync(16);
+      clock.sync(32);
+      expect(listener).not.toHaveBeenCalled();
+      clock.rate = 2;
+      clock.seek(10);
+      clock.loop = true;
+      expect(listener).toHaveBeenCalledTimes(3);
+    });
+
+    it('onWake fires once until the next sync', () => {
+      const wake = vi.fn();
+      const { clock } = started({});
+      clock.onWake(wake);
+      clock.rate = 1;
+      clock.rate = 2;
+      expect(wake).toHaveBeenCalledTimes(1);
+      clock.sync(16);
+      clock.rate = 0;
+      expect(wake).toHaveBeenCalledTimes(2);
+    });
+
+    it('onFrame fires after a sync that moved the clock, with elapsed and pass', () => {
+      const frame = vi.fn();
+      const c = started({ rate: 1, duration: 100, loop: true });
+      c.onFrame(frame);
+      c.clock.sync(150);
+      expect(frame).toHaveBeenCalledWith(150, 1);
+      c.clock.rate = 0;
+      c.clock.sync(160);
+      frame.mockClear();
+      c.clock.sync(170);
+      expect(frame).not.toHaveBeenCalled();
+    });
+
+    it('onFrame fires once after a seek, though paused', () => {
+      const frame = vi.fn();
+      const c = started({});
+      c.onFrame(frame);
+      c.clock.seek(40);
+      c.clock.sync(16);
+      expect(frame).toHaveBeenCalledWith(40, 0);
+    });
+  });
+
+  it('rejects a rate that is not a finite number', () => {
+    const { clock } = createTrialClock({});
+    expect(() => {
+      clock.rate = Number.NaN;
+    }).toThrow();
+    expect(() => {
+      clock.rate = Number.POSITIVE_INFINITY;
+    }).toThrow();
+  });
+});