@vgai/engine 0.2.0 → 0.3.0

package/dist/audio/tone-offline-render.d.ts

@@ -0,0 +1,90 @@
+import { Offline } from 'tone';
+/**
+ * G2 — Integrate Tone with the Canonical Clock, OFFLINE-render half (spec
+ * §13 G2, and the G4/I6 seam it is deliberately shaped for). This module
+ * renders a Tone composition over an exact `[start, end)` time range to a
+ * real `AudioBuffer` via `Tone.Offline` — i.e. `OfflineAudioContext`, NOT a
+ * live real-time `AudioContext` — such that identical inputs produce
+ * bit-identical output samples on every call. This is what makes offline
+ * Tone audio safe to mux into a deterministically-rendered video (G4/I6):
+ * the video side already re-renders frame-by-frame from an exact clock
+ * position, and this is the audio side's equivalent — an exact re-render
+ * from an exact time range, not a live capture of whatever happened to play.
+ *
+ * ## Why this can't run in plain Node (documented, not assumed)
+ *
+ * `Tone.Offline` ultimately constructs a real `OfflineAudioContext`
+ * (via `standardized-audio-context`, Tone's own dependency). Node has no
+ * native Web Audio implementation, so `standardized-audio-context` throws
+ * `"Missing the native OfflineAudioContext constructor."` the moment
+ * `Tone.Offline(...)` is actually invoked — confirmed empirically against
+ * this repo's installed `tone@15.1.22` before writing this module (plain
+ * `import * as Tone from 'tone'` succeeds; calling `Tone.Offline(...)` in a
+ * Node process throws immediately). There is no lightweight polyfill in this
+ * repo's dependency tree, and installing a native Node Web Audio addon is
+ * out of scope for this unit (build-box constraints). The determinism proof
+ * for this module therefore runs in a REAL headless-Chromium page via
+ * Playwright — see `packages/engine/e2e/tests/tone-audio-g1-g2.spec.ts`
+ * — mirroring how I0 proved video-frame determinism. This module's own
+ * `packages/engine/test/audio/tone-offline-render.test.ts` covers everything
+ * that does NOT require a real `OfflineAudioContext` (range validation,
+ * synchronous pre-render cancellation) directly in Node.
+ *
+ * ## Composition contract
+ *
+ * `compose` is called by `Tone.Offline` itself, inside the offline context —
+ * build the SAME graph you would in real-time Tone code
+ * (`new Tone.Synth().toDestination()`, `context.transport.schedule(...)`,
+ * etc; see Tone's own `Offline` docs). Nothing about this wrapper changes
+ * Tone's native API surface — `compose`'s parameter is `Tone.Offline`'s own
+ * callback type, re-derived structurally (`Parameters<typeof Offline>[0]`)
+ * rather than duplicated, so this module can never drift from Tone's actual
+ * signature.
+ *
+ * ## Cancellation — cooperative, not a true mid-render abort
+ *
+ * The Web Audio spec gives `OfflineAudioContext` no `.close()`/cancel API
+ * once `startRendering()` is in flight, and neither does Tone. `signal`
+ * therefore provides COOPERATIVE cancellation only: if `signal` is already
+ * aborted before this function calls `Tone.Offline`, the render never
+ * starts at all (checked synchronously, before any `OfflineAudioContext` is
+ * created). If `signal` aborts WHILE a render is in flight, this function's
+ * returned promise rejects immediately with an `AbortError` — so a caller
+ * (e.g. a render-cancellation UI action) sees the render "stop" from its own
+ * perspective and never receives/uses the resulting buffer — even though
+ * the underlying browser-native render may keep running in the background
+ * until it would have finished anyway. This is an honest, documented
+ * limitation, not a gap: no browser API makes a stronger guarantee possible.
+ */
+/** Tone's own `Offline` callback signature, re-derived (not re-typed) so
+ *  this module can never drift from the real function it wraps. */
+export type ToneOfflineComposeFn = Parameters<typeof Offline>[0];
+export interface ToneOfflineRenderRequest {
+    /** Canonical/Theatre-time range start, in seconds. */
+    readonly start: number;
+    /** Canonical/Theatre-time range end, in seconds. Must be `> start`. */
+    readonly end: number;
+    /** Output sample rate. Default 44100 (CD-quality, FFmpeg's usual default). */
+    readonly sampleRate?: number;
+    /** Output channel count. Default 2 (stereo). */
+    readonly channels?: number;
+    /** Builds the Tone graph inside the offline context — Tone's native
+     *  `Offline` callback, unmodified. Receives local time `0` at `start`. */
+    readonly compose: ToneOfflineComposeFn;
+    /** Optional cooperative-cancellation signal — see module doc above. */
+    readonly signal?: AbortSignal;
+}
+export interface ToneOfflineRenderResult {
+    /** The rendered PCM, as a real (native) `AudioBuffer` — `.getChannelData(n)`
+     *  gives the Float32 samples for channel `n`, ready for a digest/RMS
+     *  computation or (eventually, G4/I6) FFmpeg muxing. */
+    readonly buffer: AudioBuffer;
+    readonly durationSeconds: number;
+    readonly sampleRate: number;
+    readonly channels: number;
+}
+/** Render `request.compose`'s Tone graph offline over `[start, end)`,
+ *  producing a deterministic `AudioBuffer`. See module doc for the
+ *  determinism/cancellation contract. */
+export declare function renderToneOffline(request: ToneOfflineRenderRequest): Promise<ToneOfflineRenderResult>;
+//# sourceMappingURL=tone-offline-render.d.ts.map

package/dist/audio/tone-offline-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tone-offline-render.d.ts","sourceRoot":"","sources":["../../src/audio/tone-offline-render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;mEACmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;8EAC0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC;;4DAEwD;IACxD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAKD;;yCAEyC;AACzC,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA4ClC"}

package/dist/audio/tone-offline-render.js

@@ -0,0 +1,56 @@
+import { Offline } from 'tone';
+const DEFAULT_SAMPLE_RATE = 44100;
+const DEFAULT_CHANNELS = 2;
+/** Render `request.compose`'s Tone graph offline over `[start, end)`,
+ *  producing a deterministic `AudioBuffer`. See module doc for the
+ *  determinism/cancellation contract. */
+export async function renderToneOffline(request) {
+    const { start, end, sampleRate = DEFAULT_SAMPLE_RATE, channels = DEFAULT_CHANNELS, compose, signal, } = request;
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+        throw new Error(`[tone-offline-render] invalid range [${start}, ${end}) — end must be a finite number > start`);
+    }
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+        throw new Error(`[tone-offline-render] sampleRate must be a finite number > 0, got ${sampleRate}`);
+    }
+    if (!Number.isInteger(channels) || channels <= 0) {
+        throw new Error(`[tone-offline-render] channels must be a positive integer, got ${channels}`);
+    }
+    // Cooperative cancellation, checked BEFORE ever constructing an
+    // OfflineAudioContext — an already-aborted signal must never start a
+    // render at all (see module doc).
+    if (signal?.aborted) {
+        throw createAbortError();
+    }
+    const durationSeconds = end - start;
+    const renderPromise = Offline(compose, durationSeconds, channels, sampleRate);
+    const toneBuffer = signal ? await raceAbort(renderPromise, signal) : await renderPromise;
+    const buffer = toneBuffer.get();
+    if (!buffer) {
+        throw new Error('[tone-offline-render] Tone.Offline resolved without a decoded AudioBuffer');
+    }
+    return {
+        buffer,
+        durationSeconds,
+        sampleRate: buffer.sampleRate,
+        channels: buffer.numberOfChannels,
+    };
+}
+function createAbortError() {
+    return new DOMException('[tone-offline-render] render canceled', 'AbortError');
+}
+/** Race `promise` against `signal` firing — resolves/rejects with whichever
+ *  happens first, without altering the underlying Web Audio render (see
+ *  module doc's "cooperative, not a true mid-render abort" section). */
+function raceAbort(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(createAbortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (err) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(err);
+        });
+    });
+}

package/dist/audio/wav-encode.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
+ * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
+ * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
+ * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
+ * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
+ * a browser render-mode page (`runtime/render-audio-control.ts`) and in
+ * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
+ * no Playwright needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+export interface PcmToWavInput {
+    /** One `Float32Array` per channel, each sample in `[-1, 1]` (values outside
+     *  that range are clamped, not thrown on — real synthesis can transiently
+     *  clip). All channels must have equal length. */
+    readonly channelData: readonly Float32Array[];
+    readonly sampleRate: number;
+}
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export declare function encodeWav16(input: PcmToWavInput): Uint8Array;
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export declare function pcmStats(channelData: readonly Float32Array[]): {
+    rms: number;
+    peak: number;
+};
+//# sourceMappingURL=wav-encode.d.ts.map

package/dist/audio/wav-encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav-encode.d.ts","sourceRoot":"","sources":["../../src/audio/wav-encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAeD;;;;sEAIsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAwD5D;AAED;;;2DAG2D;AAC3D,wBAAgB,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAa5F"}

package/dist/audio/wav-encode.js

@@ -0,0 +1,97 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
+ * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
+ * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
+ * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
+ * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
+ * a browser render-mode page (`runtime/render-audio-control.ts`) and in
+ * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
+ * no Playwright needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+const BYTES_PER_SAMPLE = 2; // 16-bit PCM
+const WAV_HEADER_BYTES = 44;
+function clamp(value, lo, hi) {
+    return Math.min(hi, Math.max(lo, value));
+}
+function writeAsciiString(view, offset, text) {
+    for (let i = 0; i < text.length; i++) {
+        view.setUint8(offset + i, text.charCodeAt(i));
+    }
+}
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export function encodeWav16(input) {
+    const { channelData, sampleRate } = input;
+    const numChannels = channelData.length;
+    if (numChannels === 0) {
+        throw new Error('[wav-encode] channelData must contain at least one channel');
+    }
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+        throw new Error(`[wav-encode] sampleRate must be a finite number > 0, got ${sampleRate}`);
+    }
+    const numFrames = channelData[0]?.length ?? 0;
+    for (let ch = 0; ch < numChannels; ch++) {
+        const len = channelData[ch]?.length ?? -1;
+        if (len !== numFrames) {
+            throw new Error(`[wav-encode] channel ${ch} has length ${len}, expected ${numFrames} (all channels must match)`);
+        }
+    }
+    const blockAlign = numChannels * BYTES_PER_SAMPLE;
+    const byteRate = sampleRate * blockAlign;
+    const dataSize = numFrames * blockAlign;
+    const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+    const view = new DataView(buffer);
+    // RIFF chunk descriptor
+    writeAsciiString(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAsciiString(view, 8, 'WAVE');
+    // fmt subchunk (PCM)
+    writeAsciiString(view, 12, 'fmt ');
+    view.setUint32(16, 16, true); // subchunk size for PCM
+    view.setUint16(20, 1, true); // audio format 1 = PCM
+    view.setUint16(22, numChannels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, BYTES_PER_SAMPLE * 8, true); // bits per sample
+    // data subchunk
+    writeAsciiString(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    let offset = WAV_HEADER_BYTES;
+    for (let i = 0; i < numFrames; i++) {
+        for (let ch = 0; ch < numChannels; ch++) {
+            const sample = clamp(channelData[ch]?.[i] ?? 0, -1, 1);
+            const intSample = Math.round(sample < 0 ? sample * 0x8000 : sample * 0x7fff);
+            view.setInt16(offset, intSample, true);
+            offset += BYTES_PER_SAMPLE;
+        }
+    }
+    return new Uint8Array(buffer);
+}
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export function pcmStats(channelData) {
+    let sumSquares = 0;
+    let peak = 0;
+    let count = 0;
+    for (const data of channelData) {
+        for (let i = 0; i < data.length; i++) {
+            const v = data[i] ?? 0;
+            sumSquares += v * v;
+            peak = Math.max(peak, Math.abs(v));
+            count++;
+        }
+    }
+    return { rms: count > 0 ? Math.sqrt(sumSquares / count) : 0, peak };
+}

package/dist/core/game-loop.d.ts

@@ -0,0 +1,21 @@
+import type { GameLoopConfig } from './types';
+/**
+ * Fixed-timestep game loop with accumulator pattern.
+ *
+ * Physics/logic run at a fixed rate (default 60 Hz) regardless of display
+ * frame rate. Rendering is deliberately fixed-rate too (decided — D1, see
+ * `docs/DECISIONS-PENDING.md`): `config.update(fixedDt)` runs once per
+ * consumed substep, and per the documented phase order (`PHASE_ORDER` in
+ * `core/types.ts`) the `render` phase executes as the last phase of that
+ * same call — there is no separate per-real-frame render step and no
+ * display-refresh interpolation. A frame whose accumulator produces zero
+ * substeps therefore calls `update` zero times and renders zero times; do
+ * not reintroduce a render call outside the substep loop below.
+ */
+export declare function createGameLoop(config: GameLoopConfig): {
+    start(): void;
+    stop(): void;
+    readonly isRunning: boolean;
+    timeScale: number;
+};
+//# sourceMappingURL=game-loop.d.ts.map

package/dist/core/game-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-loop.d.ts","sourceRoot":"","sources":["../../src/core/game-loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc;;;;eAkH5B,MAAM;EAc9B"}

package/dist/core/game-loop.js

@@ -0,0 +1,130 @@
+/**
+ * Fixed-timestep game loop with accumulator pattern.
+ *
+ * Physics/logic run at a fixed rate (default 60 Hz) regardless of display
+ * frame rate. Rendering is deliberately fixed-rate too (decided — D1, see
+ * `docs/DECISIONS-PENDING.md`): `config.update(fixedDt)` runs once per
+ * consumed substep, and per the documented phase order (`PHASE_ORDER` in
+ * `core/types.ts`) the `render` phase executes as the last phase of that
+ * same call — there is no separate per-real-frame render step and no
+ * display-refresh interpolation. A frame whose accumulator produces zero
+ * substeps therefore calls `update` zero times and renders zero times; do
+ * not reintroduce a render call outside the substep loop below.
+ */
+export function createGameLoop(config) {
+    const fixedDt = config.fixedTimestep ?? 1 / 60;
+    const maxSubSteps = config.maxSubSteps ?? 8;
+    // Also the accumulator's hard ceiling (see the spiral-of-death guard below).
+    const maxAccumulator = fixedDt * maxSubSteps;
+    // I2 (render-control runtime mode, see `GameLoopConfig.externalDrive`'s
+    // doc comment): in this mode `start()` below deliberately skips both the
+    // `requestAnimationFrame` arm AND the `visibilitychange` listener install —
+    // no wall-clock timing source ever exists for this loop instance, so
+    // `config.update` can only ever be invoked by an external driver calling
+    // into the render-control seam, never by this file's own `frame()`.
+    const externalDrive = config.externalDrive ?? false;
+    let accumulator = 0;
+    let lastTime = 0;
+    let running = false;
+    let rafId = 0;
+    let timeScale = 1.0;
+    // Idle throttle (T2.1): a hidden tab stops the loop outright; becoming
+    // visible again restarts it with the accumulator clock resynced to "now" —
+    // deliberately no catch-up burst for the wall-clock time spent hidden.
+    let hiddenPaused = false;
+    let visibilityListenerAttached = false;
+    function handleVisibilityChange() {
+        if (typeof document === 'undefined')
+            return;
+        if (document.hidden) {
+            if (running) {
+                running = false;
+                cancelAnimationFrame(rafId);
+                hiddenPaused = true;
+            }
+        }
+        else if (hiddenPaused) {
+            hiddenPaused = false;
+            running = true;
+            lastTime = performance.now();
+            accumulator = 0;
+            rafId = requestAnimationFrame(frame);
+        }
+    }
+    function frame(currentTime) {
+        if (!running)
+            return;
+        rafId = requestAnimationFrame(frame);
+        // Convert to seconds
+        const rawDt = (currentTime - lastTime) / 1000;
+        lastTime = currentTime;
+        // Clamp large frame gaps (e.g. a slow frame) before scaling by timeScale.
+        const dt = Math.min(rawDt, maxAccumulator) * timeScale;
+        accumulator += dt;
+        // Spiral-of-death guard: bound the accumulator regardless of timeScale
+        // (up to the clamped max of 8) or frame-gap size. Time that can't
+        // possibly be caught up on is dropped, never carried forward.
+        if (accumulator > maxAccumulator)
+            accumulator = maxAccumulator;
+        // Run fixed timestep updates (this is also where rendering happens —
+        // see the module doc comment above).
+        let steps = 0;
+        while (accumulator >= fixedDt && steps < maxSubSteps) {
+            config.update(fixedDt);
+            accumulator -= fixedDt;
+            steps++;
+        }
+    }
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            // A direct start() call can land while the loop is auto-hidden-paused
+            // (`hiddenPaused` true, `running` false, no rAF pending). Without this
+            // reset, a later visibilitychange-to-visible would see stale
+            // `hiddenPaused === true` and spawn a SECOND rAF chain on top of the
+            // one this call is about to start (doubled update()/render() overhead
+            // until the next stop() — no sim-speed effect, but wasted work).
+            hiddenPaused = false;
+            lastTime = performance.now();
+            accumulator = 0;
+            // External-drive mode (I2): never arm rAF and never install the
+            // visibilitychange auto-stop handler. `running` still flips `true`
+            // above (so `isRunning`/`stop()` behave normally for a caller that
+            // treats this loop as "started"), but nothing will ever call
+            // `frame()` — a headless/backgrounded capture page cannot have this
+            // loop silently killed by `document.hidden`, because there is no
+            // listener to fire in the first place.
+            if (externalDrive)
+                return;
+            rafId = requestAnimationFrame(frame);
+            if (!visibilityListenerAttached && typeof document !== 'undefined') {
+                document.addEventListener('visibilitychange', handleVisibilityChange);
+                visibilityListenerAttached = true;
+            }
+        },
+        stop() {
+            running = false;
+            hiddenPaused = false;
+            cancelAnimationFrame(rafId);
+            if (visibilityListenerAttached && typeof document !== 'undefined') {
+                document.removeEventListener('visibilitychange', handleVisibilityChange);
+                visibilityListenerAttached = false;
+            }
+        },
+        get isRunning() {
+            return running;
+        },
+        set timeScale(value) {
+            const clamped = Math.min(8, Math.max(0, value));
+            if (clamped !== value) {
+                console.warn(`[game-loop] timeScale ${value} is out of range [0, 8]; clamped to ${clamped}.`);
+            }
+            timeScale = clamped;
+        },
+        get timeScale() {
+            return timeScale;
+        },
+    };
+}

package/dist/core/system-runner.d.ts

@@ -0,0 +1,120 @@
+import { type SystemDef, type SystemFn, type SystemPhaseName } from './types';
+/**
+ * Ordered system execution by named phase.
+ *
+ * Systems are registered with a phase name. When `run(dt)` is called, all
+ * phases execute in `PHASE_ORDER` via `runPhase(phase, dt)`. Within a phase,
+ * `runPhase` executes three ordered buckets (GAME-ROOT-DESIGN.md §4, T7.1
+ * slice 2):
+ *
+ *   1. **engine** — everything `add()`/`register()`ed at or before the last
+ *      `markEngineBoundary()` call, or EVERYTHING if no boundary has ever
+ *      been marked (the world2d-silo case: it never calls
+ *      `markEngineBoundary`, so its systems are all "engine").
+ *   2. **componentTick** — the single per-phase slot set via
+ *      `setComponentTick(phase, fn)`. Component ticks are engine
+ *      infrastructure: they always run after every engine system and before
+ *      every game system in that phase, REGARDLESS of when
+ *      `setComponentTick` was called relative to other `add()` calls. This
+ *      is what makes "engine systems run before component ticks" a
+ *      structural guarantee rather than a registration-order convention
+ *      (see `component-manager.ts`, which registers its tick this way).
+ *   3. **game** — everything `add()`/`register()`ed AFTER the last
+ *      `markEngineBoundary()` call.
+ *
+ * Within each bucket, systems run in registration order.
+ */
+export declare function createSystemRunner(): {
+    /**
+     * Register a bare system function in a specific phase.
+     * Systems within the same phase run in the order they were added.
+     */
+    add(phase: SystemPhaseName, fn: SystemFn): void;
+    /**
+     * Remove a bare system function from a phase. Also drops it from the
+     * engine-membership set (if present) — the fix for the length-based
+     * bookkeeping bug: removing this has no effect on how any OTHER entry
+     * (before or after it) is classified, since classification is now
+     * per-function membership, not position.
+     */
+    remove(phase: SystemPhaseName, fn: SystemFn): void;
+    /**
+     * Register a lifecycle system. Adds its update to the correct phase.
+     * Call runInit() after all systems are registered to invoke init hooks.
+     */
+    register(system: SystemDef): void;
+    /**
+     * Unregister a lifecycle system. Removes its update and calls dispose.
+     */
+    unregister(system: SystemDef): void;
+    /**
+     * Register the ONE component-tick function for a phase (T7.1 slice 2).
+     * Component ticks are engine infrastructure, not a bare `add()`ed
+     * system: they always execute after every engine-bucket system and
+     * before every game-bucket system in that phase (see `runPhase`),
+     * they are never touched by `removeAllNonEngine()`, and they do not
+     * count toward `markEngineBoundary()`'s bookkeeping. Throws if a tick
+     * is already set for this phase — at most one component manager may
+     * own a phase's tick slot.
+     */
+    setComponentTick(phase: SystemPhaseName, fn: SystemFn): void;
+    /**
+     * Call init() on all registered lifecycle systems, in phase order.
+     * Call once after scene load, before the first game loop tick.
+     */
+    runInit(): void;
+    /**
+     * Call dispose() on all registered lifecycle systems and remove them.
+     */
+    runDispose(): void;
+    /**
+     * Run ONE phase's three ordered buckets — engine, componentTick, game
+     * (see the module doc comment). Each system call is isolated: a
+     * throwing system is loudly logged (never swallowed) but does not stop
+     * its siblings in the same bucket, a later bucket in this phase, or a
+     * later phase, from running this frame.
+     *
+     * Public — the Game root's frame executor (`runtime/game.ts`) calls this
+     * directly per (phase, world); `run(dt)` below is just a loop over it,
+     * preserved for the world2d silo and any direct caller.
+     */
+    runPhase(phase: SystemPhaseName, dt: number): void;
+    /**
+     * Run all phases in order, via `runPhase`.
+     */
+    run(dt: number): void;
+    /**
+     * Mark everything registered so far (via `add()`/`register()`, in every
+     * phase) as "engine" — infrastructure that must survive a warm restart.
+     * Call once, right after mount finishes wiring engine-level systems and
+     * BEFORE any game (`setup()`/scene load) registers its own. `hotReload`
+     * calls `removeAllNonEngine()` on every restart, which only ever removes
+     * what was added after this mark. Component-tick slots (`setComponentTick`)
+     * are unaffected — they are never part of this boundary.
+     */
+    markEngineBoundary(): void;
+    /**
+     * Bulk-remove every system registered after the last `markEngineBoundary()`
+     * call — both bare `add()`ed functions and lifecycle `register()`ed systems
+     * (the latter get `dispose()`d, mirroring `unregister()`). A no-op if no
+     * boundary has been marked. Idempotent: calling it again with nothing new
+     * registered since is a safe no-op. Component-tick slots are NEVER cleared
+     * by this — they are engine infrastructure, not game content.
+     *
+     * This is what makes a warm restart (`hotReload`) safe to call N times
+     * without accumulating duplicate systems/listeners — each restart's
+     * outgoing game systems are fully removed before the new one registers its
+     * own, while the engine systems (input/physics/render/the ComponentManager
+     * tick/...) registered before the boundary are never touched.
+     */
+    removeAllNonEngine(): void;
+    /**
+     * Total system-function count, optionally scoped to one phase. Includes
+     * component-tick slots (a set slot counts as 1 per phase it occupies).
+     * Test/introspection helper — used to assert a warm restart doesn't
+     * accumulate systems (see `removeAllNonEngine`).
+     */
+    count(phase?: SystemPhaseName): number;
+};
+export type SystemRunner = ReturnType<typeof createSystemRunner>;
+//# sourceMappingURL=system-runner.d.ts.map

package/dist/core/system-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-runner.d.ts","sourceRoot":"","sources":["../../src/core/system-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB;IAwC9B;;;OAGG;eACQ,eAAe,MAAM,QAAQ;IAQxC;;;;;;OAMG;kBACW,eAAe,MAAM,QAAQ;IAQ3C;;;OAGG;qBACc,SAAS;IAS1B;;OAEG;uBACgB,SAAS;IAa5B;;;;;;;;;OASG;4BACqB,eAAe,MAAM,QAAQ;IAYrD;;;OAGG;;IAUH;;OAEG;;IAaH;;;;;;;;;;OAUG;oBACa,eAAe,MAAM,MAAM;IA+B3C;;OAEG;YACK,MAAM;IAMd;;;;;;;;OAQG;;IAUH;;;;;;;;;;;;;OAaG;;IAsBH;;;;;OAKG;kBACW,eAAe,GAAG,MAAM;EAYzC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}