entangled-worlds-orbiters-shared 1.1.0 → 1.2.1

package/dist/clock/ClockBackend.d.ts

@@ -0,0 +1,44 @@
+/** A cancel handle from `armAt`; returns true iff it cancelled an armed-but-unoccurred event. */
+export type CancelHandle = () => boolean;
+/**
+ * The neutral backend contract the Transport depends on. No Tone/AudioContext type leaks through the
+ * transport's public surface (design doc §0 D1).
+ */
+export interface ClockBackend {
+    /** Current audio time in seconds. */
+    nowSec(): number;
+    /** Arm an audio event at a precise future audio time. Returns a cancel handle. */
+    armAt(audioTimeSec: number, payload: unknown): CancelHandle;
+}
+interface ArmedRecord {
+    audioTimeSec: number;
+    payload: unknown;
+    armedAtNowSec: number;
+    cancelled: boolean;
+    occurred: boolean;
+}
+/**
+ * Headless, fully deterministic backend. Time only moves when the test advances it (no wall-clock
+ * flakiness). Records arms + occurrences for assertions, and actually OCCURS armed events when virtual
+ * time passes their target — so tests can prove cancellation, not just callback invocation.
+ */
+export declare class VirtualClockBackend implements ClockBackend {
+    private _now;
+    readonly armed: ArmedRecord[];
+    readonly occurrences: Array<{
+        audioTimeSec: number;
+        payload: unknown;
+    }>;
+    constructor(startSec?: number);
+    nowSec(): number;
+    /** Arm an audio event at a precise future audio time. Returns a cancel handle (true if it cancelled). */
+    armAt(audioTimeSec: number, payload: unknown): CancelHandle;
+    /** Advance virtual audio time. Marks armed events occurred (for cancellation assertions only — the
+     *  Transport, not the backend, fires them). A cancelled event never occurs. */
+    advance(dtSec: number, jitterSec?: number): number;
+    /** Events armed at least `leadSec` before their target (proof of look-ahead). */
+    armedAheadBy(leadSec: number): ArmedRecord[];
+    /** Count of events that actually occurred (not cancelled) — the audible truth. */
+    get occurredCount(): number;
+}
+export {};

package/dist/clock/ClockBackend.js

@@ -0,0 +1,70 @@
+// ClockBackend — the neutral audio-anchored time source the transport depends on.
+//
+// The shared package depends ONLY on this interface. Production injects an AudioContext/Tone-backed
+// implementation; headless tests inject a VirtualClockBackend. No Tone/AudioContext type ever leaks
+// through the transport's public surface (design doc §0 D1).
+//
+// The contract distinguishes ARMING from OCCURRENCE:
+//   - `armAt(audioTimeSec, payload)` schedules an audio event AHEAD and returns a CANCEL handle. This
+//     is the ONLY thing a real backend must do — wire `node.start(audioTimeSec)` here. The backend is
+//     pure audio I/O; it does NOT drive the transport's event lifecycle.
+//   - the TRANSPORT self-detects occurrence in its tick (when its audio clock passes `armedTarget`)
+//     and runs the per-event fire/reset itself — so a real backend never needs a JS timer to call back.
+//   - cancelling before occurrence prevents the sound (pause/seek/rate/loop change cancels armed-but-
+//     unplayed audio). Cancelling after occurrence is a no-op.
+/**
+ * Headless, fully deterministic backend. Time only moves when the test advances it (no wall-clock
+ * flakiness). Records arms + occurrences for assertions, and actually OCCURS armed events when virtual
+ * time passes their target — so tests can prove cancellation, not just callback invocation.
+ */
+export class VirtualClockBackend {
+    _now;
+    armed;
+    occurrences;
+    constructor(startSec = 0) {
+        this._now = startSec;
+        this.armed = [];
+        this.occurrences = [];
+    }
+    nowSec() {
+        return this._now;
+    }
+    /** Arm an audio event at a precise future audio time. Returns a cancel handle (true if it cancelled). */
+    armAt(audioTimeSec, payload) {
+        const rec = {
+            audioTimeSec,
+            payload,
+            armedAtNowSec: this._now,
+            cancelled: false,
+            occurred: false,
+        };
+        this.armed.push(rec);
+        return () => {
+            if (rec.occurred || rec.cancelled)
+                return false;
+            rec.cancelled = true;
+            return true;
+        };
+    }
+    /** Advance virtual audio time. Marks armed events occurred (for cancellation assertions only — the
+     *  Transport, not the backend, fires them). A cancelled event never occurs. */
+    advance(dtSec, jitterSec = 0) {
+        const step = Math.max(0, dtSec + jitterSec);
+        this._now += step;
+        for (const r of this.armed) {
+            if (!r.cancelled && !r.occurred && r.audioTimeSec <= this._now + 1e-12) {
+                r.occurred = true;
+                this.occurrences.push(r);
+            }
+        }
+        return this._now;
+    }
+    /** Events armed at least `leadSec` before their target (proof of look-ahead). */
+    armedAheadBy(leadSec) {
+        return this.armed.filter((a) => a.audioTimeSec - a.armedAtNowSec >= leadSec - 1e-9);
+    }
+    /** Count of events that actually occurred (not cancelled) — the audible truth. */
+    get occurredCount() {
+        return this.occurrences.length;
+    }
+}

package/dist/clock/Transport.d.ts

@@ -0,0 +1,85 @@
+import type { ClockBackend } from './ClockBackend.js';
+export interface LoopSec {
+    startSec: number;
+    endSec: number;
+}
+export type PlayState = 'playing' | 'paused';
+/** The event handed to `schedule`. `fire` runs at occurrence with (audioTimeSec, atSec). */
+export interface EventSpec {
+    atSec: number;
+    fire: (audioTimeSec: number, atSec: number) => void;
+    payload?: unknown;
+}
+export interface TransportSnapshot {
+    playState: PlayState;
+    positionSec: number;
+    rate: number;
+    loop: LoopSec | null;
+}
+export interface AnchoredState {
+    playState: PlayState;
+    positionSec: number;
+    rate?: number;
+    anchorAudioSec?: number;
+    loop?: LoopSec | null;
+}
+export interface ScheduleStateMeta {
+    term?: number;
+    seq?: number;
+    onApply?: (() => void) | null;
+}
+/** Structural shape of a musical projection — typed here so `./clock` never imports `./clock/musical`. */
+export interface MusicalProjectionLike {
+    musicalAt(positionSec: number): unknown;
+}
+export interface TransportOptions {
+    lookaheadSec?: number;
+}
+export declare class Transport {
+    backend: ClockBackend;
+    lookaheadSec: number;
+    private _playing;
+    private _rate;
+    private _anchorBackend;
+    private _anchorPos;
+    private _events;
+    private _nextId;
+    private _frameReaders;
+    private _loop;
+    private _projection;
+    private _pending;
+    constructor(backend: ClockBackend, opts?: TransportOptions);
+    positionSec(): number;
+    private _reanchor;
+    play(): void;
+    pause(): void;
+    seekSec(sec: number): void;
+    setRate(rate: number): void;
+    get rate(): number;
+    get playing(): boolean;
+    setLoopSec(loop: LoopSec | null): void;
+    get loopEnabled(): boolean;
+    schedule(spec: EventSpec): number;
+    unschedule(id: number): void;
+    onTick(cb: (positionSec: number) => void): () => void;
+    /** Cancel armed-but-unoccurred audio and clear arm state (does NOT replay already-fired events). */
+    private _cancelArmed;
+    /** Re-open fired events so they can occur again — only after a POSITION/topology change (seek/loop). */
+    private _reopenEvents;
+    private _eventLoops;
+    /** Transport-seconds distance to an event's NEXT occurrence from `pos` (null = won't occur). */
+    private _nextDist;
+    setProjection(projection: MusicalProjectionLike | null): void;
+    musicalPosition(): unknown;
+    applyAnchoredState(s: AnchoredState): void;
+    /** Arm an anchored state (with optional control) to apply when audio time reaches `atAudioSec`. */
+    scheduleStateChange(atAudioSec: number, state: AnchoredState, meta?: ScheduleStateMeta): void;
+    /** Drop pending changes older than a freshly-applied (term,seq) — supersession (Codex fix #4). */
+    dropPendingOlderThan(term: number, seq: number): void;
+    private _drainPending;
+    tick(): void;
+    /** Fire armed events whose audio time has arrived, and reset them for re-arm (loop) / mark done. */
+    private _detectOccurrences;
+    private _maybeWrapLoop;
+    snapshot(): TransportSnapshot;
+}

package/dist/clock/Transport.js

@@ -0,0 +1,268 @@
+// Transport — the seconds-first clock + look-ahead scheduler (design doc §0 D1/D3, §2).
+//
+// Canonical position is SECONDS, derived from the injected ClockBackend's audio time. The musical
+// grid is an OPTIONAL projection (setProjection); with none, the transport is a pure time machine.
+//
+// Scheduling discipline (rewritten after Codex review):
+//   - Events are ARMED ahead of their deadline via backend.armAt -> they OCCUR at the precise audio
+//     time. An armed event is cancelable; any disruption (pause/seek/rate/loop change) cancels armed-
+//     but-unoccurred events so stale audio never plays, then re-arms from the new position.
+//   - The look-ahead window is scaled by rate (audio-time, not transport-time).
+//   - Looping is handled by computing each event's NEXT occurrence distance (wrapping across the loop
+//     boundary), so events just after loopStart are armed during the pre-wrap look-ahead.
+const EPS = 1e-9;
+export class Transport {
+    backend;
+    lookaheadSec;
+    _playing;
+    _rate;
+    _anchorBackend;
+    _anchorPos;
+    _events;
+    _nextId;
+    _frameReaders;
+    _loop;
+    _projection;
+    _pending;
+    constructor(backend, opts = {}) {
+        this.backend = backend;
+        this.lookaheadSec = opts.lookaheadSec ?? 0.1;
+        this._playing = false;
+        this._rate = 1;
+        this._anchorBackend = backend.nowSec();
+        this._anchorPos = 0;
+        this._events = new Map();
+        this._nextId = 1;
+        this._frameReaders = new Set();
+        this._loop = null;
+        this._projection = null;
+        this._pending = [];
+    }
+    // ---- position (seconds is canonical) ------------------------------------------------
+    positionSec() {
+        if (!this._playing)
+            return this._anchorPos;
+        return this._anchorPos + (this.backend.nowSec() - this._anchorBackend) * this._rate;
+    }
+    _reanchor(atPos = this.positionSec()) {
+        this._anchorPos = atPos;
+        this._anchorBackend = this.backend.nowSec();
+    }
+    // ---- transport ops ------------------------------------------------------------------
+    play() {
+        if (this._playing)
+            return;
+        this._reanchor(this._anchorPos);
+        this._playing = true;
+    }
+    pause() {
+        if (!this._playing)
+            return;
+        this._anchorPos = this.positionSec();
+        this._playing = false;
+        this._cancelArmed(); // armed future audio must not sound during pause; re-armed on resume
+    }
+    seekSec(sec) {
+        this._reanchor(Math.max(0, sec));
+        this._cancelArmed();
+        this._reopenEvents(); // a seek MOVES position -> fired events may replay
+    }
+    setRate(rate) {
+        if (rate <= 0)
+            throw new Error('rate must be > 0');
+        this._reanchor();
+        this._rate = rate;
+        this._cancelArmed(); // window/audio-time changed -> re-arm pending events (NOT replay fired ones)
+    }
+    get rate() {
+        return this._rate;
+    }
+    get playing() {
+        return this._playing;
+    }
+    setLoopSec(loop) {
+        this._loop = loop ? { startSec: loop.startSec, endSec: loop.endSec } : null;
+        this._cancelArmed();
+        this._reopenEvents(); // loop topology changed -> events may re-enter/leave the loop window
+    }
+    get loopEnabled() {
+        return this._loop != null;
+    }
+    // ---- scheduling ---------------------------------------------------------------------
+    schedule(spec) {
+        const id = this._nextId++;
+        this._events.set(id, {
+            atSec: spec.atSec,
+            fire: spec.fire,
+            payload: spec.payload ?? null,
+            armedTarget: null,
+            handle: null,
+            done: false,
+            lastOccurredTarget: null,
+        });
+        return id;
+    }
+    unschedule(id) {
+        const ev = this._events.get(id);
+        if (ev && ev.handle)
+            ev.handle();
+        this._events.delete(id);
+    }
+    onTick(cb) {
+        this._frameReaders.add(cb);
+        return () => this._frameReaders.delete(cb);
+    }
+    /** Cancel armed-but-unoccurred audio and clear arm state (does NOT replay already-fired events). */
+    _cancelArmed() {
+        // An event whose audio time has ALREADY passed has sounded (osc.start fired) — settle its fire()
+        // before we cancel, else a pause/seek/rate/loop change right after the beat would drop the visual
+        // flash / lifecycle for a sound the listener already heard (Codex review).
+        this._detectOccurrences(this.backend.nowSec());
+        for (const ev of this._events.values()) {
+            if (ev.handle)
+                ev.handle();
+            ev.handle = null;
+            ev.armedTarget = null;
+        }
+    }
+    /** Re-open fired events so they can occur again — only after a POSITION/topology change (seek/loop). */
+    _reopenEvents() {
+        for (const ev of this._events.values()) {
+            ev.done = false;
+            ev.lastOccurredTarget = null;
+        }
+    }
+    _eventLoops(ev) {
+        if (!this._loop)
+            return false;
+        const { startSec, endSec } = this._loop;
+        return ev.atSec >= startSec - EPS && ev.atSec < endSec - EPS;
+    }
+    /** Transport-seconds distance to an event's NEXT occurrence from `pos` (null = won't occur). */
+    _nextDist(ev, pos) {
+        if (this._loop) {
+            const { startSec, endSec } = this._loop;
+            const len = endSec - startSec;
+            if (len > 0 && ev.atSec >= startSec - EPS && ev.atSec < endSec - EPS) {
+                let d = ev.atSec - pos;
+                if (d < -EPS)
+                    d += len; // wrapped into the next pass
+                return d;
+            }
+        }
+        const d = ev.atSec - pos;
+        return d >= -EPS ? d : null; // non-loop: a passed event won't fire again until a seek
+    }
+    // ---- optional musical overlay -------------------------------------------------------
+    setProjection(projection) {
+        this._projection = projection;
+    }
+    musicalPosition() {
+        return this._projection ? this._projection.musicalAt(this.positionSec()) : null;
+    }
+    // ---- sync apply (Inc 3) -------------------------------------------------------------
+    applyAnchoredState(s) {
+        this._playing = s.playState === 'playing';
+        if (s.rate != null)
+            this._rate = s.rate;
+        this._anchorPos = s.positionSec;
+        this._anchorBackend = s.anchorAudioSec ?? this.backend.nowSec();
+        if (s.loop !== undefined)
+            this._loop = s.loop ? { ...s.loop } : null;
+        this._cancelArmed();
+        this._reopenEvents(); // anchored apply repositions the timeline -> events re-evaluate
+    }
+    /** Arm an anchored state (with optional control) to apply when audio time reaches `atAudioSec`. */
+    scheduleStateChange(atAudioSec, state, meta = {}) {
+        this._pending.push({
+            atAudioSec,
+            state,
+            term: meta.term ?? 0,
+            seq: meta.seq ?? 0,
+            onApply: meta.onApply ?? null,
+        });
+        this._pending.sort((a, b) => a.atAudioSec - b.atAudioSec);
+    }
+    /** Drop pending changes older than a freshly-applied (term,seq) — supersession (Codex fix #4). */
+    dropPendingOlderThan(term, seq) {
+        this._pending = this._pending.filter((p) => !(p.term < term || (p.term === term && p.seq < seq)));
+    }
+    _drainPending() {
+        const now = this.backend.nowSec();
+        while (this._pending.length && this._pending[0].atAudioSec <= now + EPS) {
+            const p = this._pending.shift();
+            this.applyAnchoredState({ ...p.state, anchorAudioSec: p.state.anchorAudioSec ?? now });
+            if (p.onApply)
+                p.onApply(); // control rides WITH the state, applied atomically here (fix #5)
+        }
+    }
+    // ---- the pump -----------------------------------------------------------------------
+    tick() {
+        this._drainPending();
+        if (this._playing) {
+            const now = this.backend.nowSec();
+            this._detectOccurrences(now); // fire events whose audio time has passed (Transport owns this)
+            this._maybeWrapLoop();
+            const pos = this.positionSec();
+            for (const ev of this._events.values()) {
+                if (ev.done || ev.armedTarget != null)
+                    continue;
+                const d = this._nextDist(ev, pos);
+                if (d == null)
+                    continue;
+                const audioDist = d / this._rate; // look-ahead is in AUDIO time (rate-scaled)
+                if (audioDist <= this.lookaheadSec + EPS) {
+                    const audioTime = now + audioDist;
+                    // a loop event at/near the boundary must not re-arm for the instant it just fired.
+                    // The dedupe window must stay below half a loop period, else ultra-short loops starve.
+                    const period = this._loop ? (this._loop.endSec - this._loop.startSec) / this._rate : Infinity;
+                    const dedupeEps = Math.min(1e-6, 0.4 * period);
+                    if (ev.lastOccurredTarget != null && audioTime <= ev.lastOccurredTarget + dedupeEps)
+                        continue;
+                    ev.armedTarget = audioTime;
+                    // armed AHEAD: a real backend schedules node.start(audioTime) here, using `data` for the sound.
+                    ev.handle = this.backend.armAt(audioTime, { atSec: ev.atSec, data: ev.payload });
+                }
+            }
+        }
+        const p = this.positionSec();
+        for (const r of this._frameReaders)
+            r(p);
+    }
+    /** Fire armed events whose audio time has arrived, and reset them for re-arm (loop) / mark done. */
+    _detectOccurrences(now) {
+        for (const ev of this._events.values()) {
+            if (ev.armedTarget == null || now < ev.armedTarget - EPS)
+                continue;
+            const at = ev.armedTarget;
+            ev.armedTarget = null;
+            ev.handle = null; // the scheduled audio already plays at `at`; nothing to cancel
+            ev.lastOccurredTarget = at;
+            if (!this._eventLoops(ev))
+                ev.done = true; // non-loop fires once; loop re-arms next pass
+            ev.fire(at, ev.atSec);
+        }
+    }
+    _maybeWrapLoop() {
+        if (!this._loop)
+            return;
+        const { startSec, endSec } = this._loop;
+        const len = endSec - startSec;
+        if (len <= 0)
+            return;
+        const pos = this.positionSec();
+        if (pos < endSec - EPS)
+            return;
+        const overshoot = (pos - startSec) % len;
+        this._reanchor(startSec + overshoot); // armed events keep their absolute audio times across the wrap
+    }
+    // ---- snapshot -----------------------------------------------------------------------
+    snapshot() {
+        return {
+            playState: this._playing ? 'playing' : 'paused',
+            positionSec: this.positionSec(),
+            rate: this._rate,
+            loop: this._loop ? { ...this._loop } : null,
+        };
+    }
+}

package/dist/clock/curves.d.ts

@@ -0,0 +1,84 @@
+/** Easing function: maps a normalized fraction in [0,1] to an eased fraction. */
+export type EaseFn = (x: number) => number;
+export declare const Ease: {
+    linear: EaseFn;
+    smooth: EaseFn;
+};
+/** A single curve keyframe: a time key `t` (seconds or beats) and its value. */
+export interface Keyframe {
+    t: number;
+    value: number;
+}
+export type TimeMode = 'absolute-seconds' | 'beat-locked';
+/**
+ * Structural shape of a musical projection — typed here so `./clock/curves` never imports
+ * `./clock/musical`. A beat-locked curve only needs seconds <-> beats conversion.
+ */
+export interface ProjectionLike {
+    secondsToBeats(positionSec: number): number;
+}
+export interface CurveTrackSpec {
+    keyframes: Keyframe[];
+    timeMode?: TimeMode;
+    projection?: ProjectionLike | null;
+    ease?: EaseFn;
+    outputIntent?: unknown;
+}
+export declare class CurveTrack {
+    keyframes: Keyframe[];
+    timeMode: TimeMode;
+    projection: ProjectionLike | null;
+    ease: EaseFn;
+    outputIntent: unknown;
+    constructor(spec: CurveTrackSpec);
+    /** The track's own time key for a given clock position. */
+    _key(positionSec: number): number;
+    sample(positionSec: number): number;
+}
+/**
+ * Structural shape of the transport a GestureRecorder/Orchestrator subscribes to — typed here so
+ * `./clock/curves` never imports `./clock/musical`. Mirrors the subset of `./Transport.js` used.
+ */
+export interface TransportLike {
+    positionSec(): number;
+    onTick(cb: (positionSec: number) => void): () => void;
+    schedule(spec: {
+        atSec: number;
+        fire: (audioTimeSec: number, atSec: number) => void;
+    }): number;
+}
+export interface GestureRecorderOptions {
+    timeMode?: TimeMode;
+    projection?: ProjectionLike | null;
+}
+/**
+ * GestureRecorder — captures live input samples stamped with the transport position, producing a
+ * CurveTrack. Free gestures stamp seconds; musical gestures stamp beats (so they tempo-rebase).
+ * (design doc §4a: today gestures are applied live & never recorded against musical time.)
+ */
+export declare class GestureRecorder {
+    transport: TransportLike;
+    timeMode: TimeMode;
+    projection: ProjectionLike | null;
+    keyframes: Keyframe[];
+    constructor(transport: TransportLike, { timeMode, projection }?: GestureRecorderOptions);
+    /** Stamp a value at the current transport position. */
+    capture(value: number): void;
+    toTrack(ease?: EaseFn): CurveTrack;
+}
+/**
+ * Orchestrator — the thin layer that subscribes every domain to ONE transport (design doc §5):
+ *   - audio: schedule(atSec, fire) -> armed ahead with precise audio time
+ *   - visuals: onTick -> sample curves at the current position each frame (one shared reader)
+ */
+export declare class Orchestrator {
+    transport: TransportLike;
+    curves: Map<string, CurveTrack>;
+    lastValues: Map<string, number>;
+    private _off;
+    constructor(transport: TransportLike);
+    addCurve(id: string, track: CurveTrack): void;
+    scheduleAudio(atSec: number, fire: (audioTimeSec: number, atSec: number) => void): number;
+    _readFrame(positionSec: number): void;
+    dispose(): void;
+}

package/dist/clock/curves.js

@@ -0,0 +1,115 @@
+// CurveTrack — a time-addressable curve the orchestrator samples by position (design doc §0 D3, §4/§5).
+//
+// Two kinds, one interface:
+//   - 'absolute-seconds' : keyframes are { t: seconds, value }  (free gestures, non-metric)
+//   - 'beat-locked'      : keyframes are { t: beats,   value }  (musical; needs a projection)
+// A beat-locked curve REFLOWS automatically when tempo changes — a peak authored "at beat 3" lands on
+// beat 3 at any tempo. This is what lets recorded gestures and authored anime-style curves share the
+// musical timeline. `sample(positionSec)` is pure: position in, value out — no internal timer.
+export const Ease = {
+    linear: (x) => x,
+    smooth: (x) => x * x * (3 - 2 * x), // smoothstep
+};
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+export class CurveTrack {
+    keyframes;
+    timeMode;
+    projection;
+    ease;
+    outputIntent;
+    constructor(spec) {
+        this.keyframes = spec.keyframes.slice().sort((a, b) => a.t - b.t);
+        this.timeMode = spec.timeMode ?? 'absolute-seconds';
+        this.projection = spec.projection ?? null;
+        this.ease = spec.ease ?? Ease.linear;
+        this.outputIntent = spec.outputIntent ?? null;
+        if (this.timeMode === 'beat-locked' && !this.projection) {
+            throw new Error('beat-locked CurveTrack needs a MusicalProjection');
+        }
+    }
+    /** The track's own time key for a given clock position. */
+    _key(positionSec) {
+        return this.timeMode === 'beat-locked' ? this.projection.secondsToBeats(positionSec) : positionSec;
+    }
+    sample(positionSec) {
+        const k = this._key(positionSec);
+        const kf = this.keyframes;
+        if (k <= kf[0].t)
+            return kf[0].value;
+        if (k >= kf[kf.length - 1].t)
+            return kf[kf.length - 1].value;
+        let i = 0;
+        while (i < kf.length - 1 && kf[i + 1].t <= k)
+            i++;
+        const a = kf[i];
+        const b = kf[i + 1];
+        const frac = (k - a.t) / (b.t - a.t);
+        return lerp(a.value, b.value, this.ease(frac));
+    }
+}
+/**
+ * GestureRecorder — captures live input samples stamped with the transport position, producing a
+ * CurveTrack. Free gestures stamp seconds; musical gestures stamp beats (so they tempo-rebase).
+ * (design doc §4a: today gestures are applied live & never recorded against musical time.)
+ */
+export class GestureRecorder {
+    transport;
+    timeMode;
+    projection;
+    keyframes;
+    constructor(transport, { timeMode = 'absolute-seconds', projection = null } = {}) {
+        this.transport = transport;
+        this.timeMode = timeMode;
+        // `_projection` is the transport's private musical overlay (read defensively — it is an
+        // implementation detail not part of the public TransportLike contract).
+        const carried = transport._projection;
+        this.projection = projection ?? carried ?? null;
+        // Fail fast: a beat-locked gesture must have a projection to stamp beats, else capture() would
+        // crash later with a cryptic null error (Codex review). Invalid config only — valid paths unchanged.
+        if (this.timeMode === 'beat-locked' && !this.projection) {
+            throw new Error('[GestureRecorder] timeMode "beat-locked" requires a projection (none provided or carried by the transport).');
+        }
+        this.keyframes = [];
+    }
+    /** Stamp a value at the current transport position. */
+    capture(value) {
+        const pos = this.transport.positionSec();
+        const t = this.timeMode === 'beat-locked' ? this.projection.secondsToBeats(pos) : pos;
+        this.keyframes.push({ t, value });
+    }
+    toTrack(ease) {
+        return new CurveTrack({ keyframes: this.keyframes, timeMode: this.timeMode, projection: this.projection, ease });
+    }
+}
+/**
+ * Orchestrator — the thin layer that subscribes every domain to ONE transport (design doc §5):
+ *   - audio: schedule(atSec, fire) -> armed ahead with precise audio time
+ *   - visuals: onTick -> sample curves at the current position each frame (one shared reader)
+ */
+export class Orchestrator {
+    transport;
+    curves;
+    lastValues;
+    _off;
+    constructor(transport) {
+        this.transport = transport;
+        this.curves = new Map();
+        this._off = transport.onTick((positionSec) => this._readFrame(positionSec));
+        this.lastValues = new Map();
+    }
+    addCurve(id, track) {
+        this.curves.set(id, track);
+    }
+    scheduleAudio(atSec, fire) {
+        return this.transport.schedule({ atSec, fire });
+    }
+    _readFrame(positionSec) {
+        for (const [id, track] of this.curves)
+            this.lastValues.set(id, track.sample(positionSec));
+    }
+    dispose() {
+        this._off();
+    }
+}

package/dist/clock/index.d.ts

@@ -0,0 +1,4 @@
+export { Transport } from './Transport.js';
+export type { LoopSec, PlayState, EventSpec, TransportSnapshot, AnchoredState, ScheduleStateMeta, MusicalProjectionLike, TransportOptions, } from './Transport.js';
+export { VirtualClockBackend } from './ClockBackend.js';
+export type { ClockBackend, CancelHandle } from './ClockBackend.js';

package/dist/clock/index.js

@@ -0,0 +1,4 @@
+// ./clock — the headless, framework-free time core: the seconds-first Transport + look-ahead
+// scheduler and the neutral ClockBackend contract. No three, no react, no sync/musical/curves.
+export { Transport } from './Transport.js';
+export { VirtualClockBackend } from './ClockBackend.js';