@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/audio/audio-introspection.ts

@@ -0,0 +1,290 @@
+/**
+ * W3c — first-party `AudioAdapter` INTROSPECTION over the engine's own audio
+ * stack (the engine is its own first adapter). `attachAudioIntrospection`
+ * augments the mute-only adapter `createAudioSystemAdapter` built with the
+ * optional read-only debugger capabilities the editor's Audio tab consumes:
+ *
+ *  - `graphSnapshot()` — the engine bus hierarchy (`setup-audio.ts`'s
+ *    music/sfx/voice → master → destination, plus the THREE listener tap)
+ *    and every Tone node a game routed through `connectToneBusToMasterGain`
+ *    (recorded at that seam — see `tone-context.ts`). Tone-INTERNAL wiring
+ *    (a game's private synth chains) is not visible from here and is not
+ *    fabricated; a game wanting richer graphs registers its own adapter.
+ *  - `transportState()` — Tone's real transport (`Tone.getTransport()`),
+ *    reported ONLY when the game bridged Tone onto this world's context
+ *    (`hasToneBridge`); otherwise an honest `null` ("no musical transport"),
+ *    and Tone's global context is never instantiated just by asking.
+ *  - `acquireMeters()` — per-bus linear-RMS levels via native `AnalyserNode`
+ *    taps (the "Tone.Meter or equivalent": analysers work identically
+ *    whether or not Tone is bridged, and disposal is a plain disconnect).
+ *    Returns `null` on a headless world (no real `createAnalyser`).
+ *  - `audioEvents()` — bounded seq-fenced ring fed by REAL observation
+ *    points only: Tone transport start/stop/pause emitter events (attached
+ *    lazily once a bridge exists), native context `statechange`, and the
+ *    adapter's own mute/unmute calls.
+ *
+ * SQ-4 boundary: this module is the READ-ONLY debugger seam. The full mixer
+ * (sends/effects/per-bus gain EDITING, FMOD-class adaptive-audio authoring)
+ * waits on SQ-4 and is deliberately absent here.
+ *
+ * Uses Tone directly (no wrapper). The EDITOR never imports this module or
+ * Tone — it consumes only `SystemAdapters.audio` (mirror of the networking
+ * rule). Wired by `vgai-scene-game-adapter.ts` via dynamic import so `tone`
+ * stays out of the mount-critical chunk, with the returned disposer called
+ * from `disposeGame` (no leaked transport listeners across mounts — the
+ * Tone transport is a singleton that outlives any one world).
+ */
+
+import * as Tone from 'tone';
+import type {
+  AudioAdapter,
+  AudioDebugEvent,
+  AudioGraphNode,
+  AudioMeterFrame,
+  AudioMeterHandle,
+  AudioTransportState,
+} from '../adapter/system-adapter';
+import type { AudioContext as GameAudio } from '../setup/setup-audio';
+import { getToneMasterGainRoutes, hasToneBridge } from './tone-context';
+
+/** Ring capacity — mirrors the debug-event ring's bounded-drop-oldest idiom. */
+const EVENT_RING_CAP = 200;
+
+function now(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+function ctorName(value: object): string {
+  const name = (value as { constructor?: { name?: string } }).constructor?.name;
+  return name && name !== 'Object' ? name : 'AudioNode';
+}
+
+/**
+ * Attach the W3c introspection capabilities to `adapter` (mutating it — the
+ * same object stays registered on `SystemAdapters.audio`) and return a
+ * disposer that detaches every listener and releases any meter handle still
+ * alive. Idempotent per adapter object is NOT required: call once per mount.
+ */
+export function attachAudioIntrospection(adapter: AudioAdapter, audio: GameAudio): () => void {
+  // --- event ring -----------------------------------------------------------
+  const ring: AudioDebugEvent[] = [];
+  let nextSeq = 1;
+  const record = (kind: AudioDebugEvent['kind'], detail?: string): void => {
+    const event: AudioDebugEvent = { seq: nextSeq++, time: now(), kind };
+    if (detail !== undefined) event.detail = detail;
+    ring.push(event);
+    if (ring.length > EVENT_RING_CAP) ring.splice(0, ring.length - EVENT_RING_CAP);
+  };
+
+  // The native context, when this world has a real one (headless worlds use
+  // a plain stand-in whose `listener.context` may be absent).
+  const nativeContext = (): (BaseAudioContext & Partial<AudioContext>) | null => {
+    const context = (audio.listener as { context?: BaseAudioContext } | undefined)?.context;
+    return context && typeof context.state === 'string'
+      ? (context as BaseAudioContext & Partial<AudioContext>)
+      : null;
+  };
+
+  /** Tone is CURRENTLY bridged onto this world's context. `hasToneBridge`
+   *  gates first so `Tone.getContext()` is only consulted when a Tone global
+   *  context already exists (never fabricating one — see tone-context.ts). */
+  const isBridged = (): boolean => {
+    const context = nativeContext();
+    if (!context || !hasToneBridge(context as AudioContext)) return false;
+    try {
+      return Tone.getContext().rawContext === context;
+    } catch {
+      return false; // no constructible Tone context in this environment (Node)
+    }
+  };
+
+  // --- mute/unmute events: wrap the adapter's OWN entry point ---------------
+  const baseSetMuted = adapter.setMuted.bind(adapter);
+  adapter.setMuted = (muted: boolean): void => {
+    baseSetMuted(muted);
+    record(muted ? 'mute' : 'unmute');
+  };
+
+  // --- context statechange --------------------------------------------------
+  const context = nativeContext();
+  const onStateChange = (): void => {
+    record('context-statechange', nativeContext()?.state ?? 'unknown');
+  };
+  if (context && typeof context.addEventListener === 'function') {
+    context.addEventListener('statechange', onStateChange);
+  }
+
+  // --- transport events (lazy: the game bridges Tone DURING its setup, after
+  //     this adapter is seeded — so hooks attach on the first capability read
+  //     that finds a live bridge) ------------------------------------------
+  let transportHooked = false;
+  const onTransportStart = (): void => record('transport-start');
+  const onTransportStop = (): void => record('transport-stop');
+  const onTransportPause = (): void => record('transport-pause');
+  const ensureTransportHooks = (): void => {
+    if (transportHooked || !isBridged()) return;
+    transportHooked = true;
+    const transport = Tone.getTransport();
+    transport.on('start', onTransportStart);
+    transport.on('stop', onTransportStop);
+    transport.on('pause', onTransportPause);
+    // A game typically bridges Tone and starts its transport DURING setup(),
+    // before anything polls this adapter — that start predates the listeners
+    // above. If the transport is already running at hook time, record that
+    // truthful observation (marked as such) so the log's first entry isn't a
+    // hole where the session's defining event happened.
+    if (transport.state === 'started') {
+      record('transport-start', 'already running when observed');
+    }
+  };
+
+  // --- capabilities ---------------------------------------------------------
+
+  adapter.graphSnapshot = (): AudioGraphNode[] => {
+    const nodes: AudioGraphNode[] = [];
+    const contextState = nativeContext()?.state;
+    const destination: AudioGraphNode = {
+      id: 'destination',
+      type: 'AudioDestinationNode',
+      label: 'Output',
+      outputs: [],
+    };
+    if (contextState !== undefined) destination.state = contextState;
+    nodes.push(destination);
+    nodes.push({
+      id: 'master',
+      type: ctorName(audio.masterGain),
+      label: 'Master',
+      outputs: ['destination'],
+    });
+    nodes.push({
+      id: 'bus-music',
+      type: ctorName(audio.buses.music),
+      label: 'Music bus',
+      outputs: ['master'],
+    });
+    nodes.push({
+      id: 'bus-sfx',
+      type: ctorName(audio.buses.sfx),
+      label: 'SFX bus',
+      outputs: ['master'],
+    });
+    nodes.push({
+      id: 'bus-voice',
+      type: ctorName(audio.buses.voice),
+      label: 'Voice bus',
+      outputs: ['master'],
+    });
+    if (audio.listener) {
+      nodes.push({
+        id: 'listener',
+        type: ctorName(audio.listener),
+        label: '3D listener (THREE)',
+        outputs: ['master'],
+      });
+    }
+    // Tone nodes routed into THIS world's master bus (seam-recorded; disposed
+    // nodes are pruned by the registry itself).
+    getToneMasterGainRoutes(audio.masterGain).forEach((toneNode, index) => {
+      nodes.push({
+        id: `tone-${index}`,
+        // Tone nodes carry their own class name (`'Gain'`, `'Volume'`…).
+        type: (toneNode as { name?: string }).name ?? ctorName(toneNode),
+        label: `Tone route ${index + 1}`,
+        outputs: ['master'],
+      });
+    });
+    return nodes;
+  };
+
+  adapter.transportState = (): AudioTransportState | null => {
+    ensureTransportHooks();
+    if (!isBridged()) return null; // honest: no musical transport in this world
+    const transport = Tone.getTransport();
+    return {
+      state: transport.state,
+      seconds: transport.seconds,
+      bpm: transport.bpm.value,
+      position: String(transport.position),
+    };
+  };
+
+  const liveMeterHandles = new Set<AudioMeterHandle>();
+  adapter.acquireMeters = (): AudioMeterHandle | null => {
+    const meterContext = nativeContext();
+    if (!meterContext || typeof meterContext.createAnalyser !== 'function') {
+      return null; // headless world — metering is impossible, and says so
+    }
+    const taps = (
+      [
+        ['master', 'Master', audio.masterGain],
+        ['bus-music', 'Music', audio.buses.music],
+        ['bus-sfx', 'SFX', audio.buses.sfx],
+        ['bus-voice', 'Voice', audio.buses.voice],
+      ] as const
+    ).map(([id, label, gain]) => {
+      const analyser = meterContext.createAnalyser();
+      analyser.fftSize = 1024;
+      gain.connect(analyser); // a TAP (analyser is a sink), not an insert
+      return { id, label, gain, analyser, buffer: new Float32Array(analyser.fftSize) };
+    });
+    let disposed = false;
+    const handle: AudioMeterHandle = {
+      read: (): AudioMeterFrame[] =>
+        taps.map(({ id, label, analyser, buffer }) => {
+          analyser.getFloatTimeDomainData(buffer);
+          let sum = 0;
+          for (let i = 0; i < buffer.length; i++) {
+            const sample = buffer[i] as number;
+            sum += sample * sample;
+          }
+          return { id, label, level: Math.sqrt(sum / buffer.length) };
+        }),
+      dispose: (): void => {
+        if (disposed) return;
+        disposed = true;
+        for (const tap of taps) {
+          try {
+            tap.gain.disconnect(tap.analyser);
+          } catch {
+            // already torn down with the context — nothing to release
+          }
+        }
+        liveMeterHandles.delete(handle);
+      },
+    };
+    liveMeterHandles.add(handle);
+    return handle;
+  };
+
+  adapter.audioEvents = (sinceSeq?: number): AudioDebugEvent[] => {
+    ensureTransportHooks();
+    return sinceSeq !== undefined ? ring.filter((e) => e.seq > sinceSeq) : [...ring];
+  };
+
+  // --- teardown -------------------------------------------------------------
+  return (): void => {
+    if (transportHooked) {
+      try {
+        const transport = Tone.getTransport();
+        transport.off('start', onTransportStart);
+        transport.off('stop', onTransportStop);
+        transport.off('pause', onTransportPause);
+      } catch {
+        // Tone context already closed — the listeners died with it
+      }
+      transportHooked = false;
+    }
+    if (context && typeof context.removeEventListener === 'function') {
+      context.removeEventListener('statechange', onStateChange);
+    }
+    // Safety net: a consumer should dispose its own handle, but Stop must
+    // never leak analyser taps regardless.
+    for (const handle of [...liveMeterHandles]) handle.dispose();
+    adapter.setMuted = baseSetMuted;
+    delete adapter.graphSnapshot;
+    delete adapter.transportState;
+    delete adapter.acquireMeters;
+    delete adapter.audioEvents;
+  };
+}

package/src/audio/tone-context.ts

@@ -95,12 +95,55 @@ export interface ToneAudioBridge {
  */
 export function bridgeToneToThreeAudio(context: AudioContext): ToneAudioBridge {
   Tone.setContext(context);
+  bridgedContexts.add(context);
   return {
     context,
     isBridged: () => Tone.getContext().rawContext === context,
   };
 }
 
+// --- W3c introspection bookkeeping (read-only debugger seam) ----------------
+//
+// The registries below record what already flows through THIS module's two
+// seams — nothing new is wrapped; Tone stays used through its own API. They
+// exist so the first-party `AudioAdapter` introspection
+// (`audio-introspection.ts`) can answer "is Tone bridged onto this world's
+// context?" and "which Tone nodes feed this world's master bus?" TRUTHFULLY,
+// without ever instantiating a Tone global context of its own (calling
+// `Tone.getContext()` on a page whose game never used Tone would fabricate
+// one just by asking).
+
+const bridgedContexts = new WeakSet<AudioContext>();
+
+/** `true` iff {@link bridgeToneToThreeAudio} has run for this exact native
+ *  context. A cheap pre-check: callers still confirm the bridge is CURRENT
+ *  via `Tone.getContext().rawContext === context` (a later re-bridge to a
+ *  different context leaves stale entries here) — but only after this
+ *  returns `true`, so the confirmation never forces Tone to create a
+ *  context that didn't already exist. */
+export function hasToneBridge(context: AudioContext): boolean {
+  return bridgedContexts.has(context);
+}
+
+interface ToneMasterRoute {
+  node: ToneAudioNode;
+  masterGain: GainNode;
+}
+
+const toneMasterRoutes: ToneMasterRoute[] = [];
+
+/** The still-alive Tone nodes routed into `masterGain` via
+ *  {@link connectToneBusToMasterGain}. Disposed nodes (Tone's own
+ *  `.disposed` flag) are pruned on every call, so a game that cleans up
+ *  after itself leaves nothing behind here. Filtered by `masterGain`
+ *  IDENTITY: one world's snapshot never shows another world's routes. */
+export function getToneMasterGainRoutes(masterGain: GainNode): ToneAudioNode[] {
+  for (let i = toneMasterRoutes.length - 1; i >= 0; i--) {
+    if (toneMasterRoutes[i]?.node.disposed) toneMasterRoutes.splice(i, 1);
+  }
+  return toneMasterRoutes.filter((r) => r.masterGain === masterGain).map((r) => r.node);
+}
+
 /**
  * Route a Tone output node (a bus, `Tone.getDestination()`, or any
  * `Tone.Gain` used as a submix) into the SAME `masterGain`
@@ -113,6 +156,9 @@ export function bridgeToneToThreeAudio(context: AudioContext): ToneAudioBridge {
  */
 export function connectToneBusToMasterGain(toneNode: ToneAudioNode, masterGain: GainNode): void {
   toneNode.connect(masterGain);
+  // W3c: record the route so the Audio debugger's graph snapshot can show it
+  // (see the introspection-bookkeeping section below).
+  toneMasterRoutes.push({ node: toneNode, masterGain });
 }
 
 /**

package/src/dev/chrome-trace.ts

@@ -0,0 +1,153 @@
+/**
+ * Chrome Trace Event Format exporter (W4b, F11 profiler → chrome://tracing /
+ * Perfetto). A PURE, deterministic function over recorded
+ * {@link PerformanceFrame}s — no clock reads, no randomness, no I/O — so the
+ * same frames always serialize to byte-identical output (asserted by the unit
+ * test).
+ *
+ * Format (https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU):
+ *  - `M` metadata events name the process and thread.
+ *  - One `X` (complete) event per frame — `ts` at the frame's absolute start,
+ *    `dur` the frame's CPU time — with nested `X` events per phase and per
+ *    system placed at their MEASURED `startMs` offsets inside the frame.
+ *  - One `C` (counter) event per frame carries the render draw/triangle
+ *    counters, so the trace viewer draws them as a graph track.
+ *
+ * All times are microseconds (the format's unit); our profiler measures ms, so
+ * every ms value is × 1000. Every event carries the full key set
+ * (`ph/ts/dur/pid/tid/name/cat`) for uniformity — metadata/counter events
+ * would normally omit `dur`, but a constant `dur: 0` is harmless to the viewer
+ * and lets a consumer read every event without per-`ph` branching.
+ */
+
+import type { PerformanceFrame } from './performance-profiler';
+
+export interface ChromeTraceEvent {
+  readonly name: string;
+  readonly cat: string;
+  readonly ph: 'X' | 'M' | 'C';
+  /** Timestamp, microseconds. */
+  readonly ts: number;
+  /** Duration, microseconds (0 for metadata/counter events). */
+  readonly dur: number;
+  readonly pid: number;
+  readonly tid: number;
+  readonly args?: Record<string, unknown>;
+}
+
+export interface ChromeTraceFile {
+  readonly traceEvents: readonly ChromeTraceEvent[];
+  readonly displayTimeUnit: 'ms';
+  readonly otherData: Record<string, unknown>;
+}
+
+export interface ChromeTraceOptions {
+  processName: string;
+  threadName: string;
+}
+
+const PID = 1;
+const TID = 1;
+const MS_TO_US = 1000;
+
+function ms(value: number): number {
+  return Math.round(value * MS_TO_US);
+}
+
+export function buildChromeTrace(
+  frames: readonly PerformanceFrame[],
+  options: ChromeTraceOptions,
+): ChromeTraceFile {
+  const events: ChromeTraceEvent[] = [];
+
+  // Metadata: name the process + thread the frames live on.
+  events.push({
+    name: 'process_name',
+    cat: '__metadata',
+    ph: 'M',
+    ts: 0,
+    dur: 0,
+    pid: PID,
+    tid: TID,
+    args: { name: options.processName },
+  });
+  events.push({
+    name: 'thread_name',
+    cat: '__metadata',
+    ph: 'M',
+    ts: 0,
+    dur: 0,
+    pid: PID,
+    tid: TID,
+    args: { name: options.threadName },
+  });
+
+  for (const frame of frames) {
+    // Absolute frame start (ms): timestamp is the frame's END, cpuMs its span.
+    const frameStartMs = frame.timestamp - frame.cpuMs;
+    const frameStartUs = ms(frameStartMs);
+
+    events.push({
+      name: `frame ${frame.id}`,
+      cat: 'frame',
+      ph: 'X',
+      ts: frameStartUs,
+      dur: ms(frame.cpuMs),
+      pid: PID,
+      tid: TID,
+      args: {
+        id: frame.id,
+        drawCalls: frame.render.drawCalls,
+        triangles: frame.render.triangles,
+      },
+    });
+
+    for (const phase of frame.phases) {
+      events.push({
+        name: phase.name,
+        cat: 'phase',
+        ph: 'X',
+        ts: ms(frameStartMs + (phase.startMs ?? 0)),
+        dur: ms(phase.ms),
+        pid: PID,
+        tid: TID,
+      });
+    }
+
+    for (const system of frame.systems) {
+      events.push({
+        name: system.name,
+        cat: 'system',
+        ph: 'X',
+        ts: ms(frameStartMs + system.startMs),
+        dur: ms(system.ms),
+        pid: PID,
+        tid: TID,
+        args: { phase: system.phase },
+      });
+    }
+
+    // Counter track: render draw/triangle counts at this frame's start.
+    events.push({
+      name: 'render',
+      cat: 'counter',
+      ph: 'C',
+      ts: frameStartUs,
+      dur: 0,
+      pid: PID,
+      tid: TID,
+      args: { drawCalls: frame.render.drawCalls, triangles: frame.render.triangles },
+    });
+  }
+
+  return {
+    traceEvents: events,
+    displayTimeUnit: 'ms',
+    otherData: {
+      version: 2,
+      processName: options.processName,
+      threadName: options.threadName,
+      frameCount: frames.length,
+    },
+  };
+}

package/src/dev/performance-profiler.ts

@@ -1,6 +1,40 @@
 export interface PerformanceTiming {
   readonly name: string;
   readonly ms: number;
+  /**
+   * Offset (ms) from THIS frame's start (`frameStart`) at which the timing
+   * began — a MEASURED value (e.g. a phase's `phaseStart - frameStart`), never
+   * synthesized. Present on per-frame phase timings (W4b, so a Chrome trace
+   * can place each phase span under its frame at the real offset). OMITTED on
+   * cross-frame aggregate rollups (`PerformanceSnapshot.phases`/`systems`/
+   * `components`), where no single start point exists — absent, never a
+   * fabricated 0.
+   */
+  readonly startMs?: number;
+}
+
+/**
+ * One MEASURED span within a frame (W4b) — a system or component invocation,
+ * with the phase it ran in and its measured start offset from `frameStart`.
+ * Distinct from {@link PerformanceTiming}: a span is a single timed
+ * invocation carrying `phase` + always-present `startMs` (the trace/flame
+ * unit), whereas a `PerformanceTiming` may be a cross-frame rollup.
+ */
+export interface PerformanceSpan {
+  readonly name: string;
+  readonly phase: string;
+  /** Measured offset (ms) from `frameStart` at which this span began. */
+  readonly startMs: number;
+  readonly ms: number;
+}
+
+/** Renderer counters accumulated over a frame (from `renderer.info`). */
+export interface PerformanceRenderStats {
+  readonly gpuMs: number | null;
+  readonly drawCalls: number;
+  readonly triangles: number;
+  readonly geometries: number;
+  readonly textures: number;
 }
 
 export interface PerformanceFrame {
@@ -9,6 +43,25 @@ export interface PerformanceFrame {
   readonly intervalMs: number;
   readonly cpuMs: number;
   readonly phases: readonly PerformanceTiming[];
+  /**
+   * Per-invocation system spans measured this frame (W4b). Ordered by
+   * `startMs` (execution order), NOT accumulated — a system that ran twice
+   * (two substeps) appears twice. Empty when the profiler saw no named
+   * systems this frame.
+   */
+  readonly systems: readonly PerformanceSpan[];
+  /**
+   * Per-invocation component spans measured this frame (W4b) — populated ONLY
+   * while `recording` (component timing is gated on recording, matching
+   * `beginComponent`/`endComponent`). Empty otherwise.
+   */
+  readonly components: readonly PerformanceSpan[];
+  /**
+   * Renderer counters reported during this frame (W4b) — a snapshot of the
+   * accumulated `reportRender` totals taken at `endFrame`. `gpuMs` is `null`
+   * when no GPU timer reported (headless/SwiftShader), never a fabricated 0.
+   */
+  readonly render: PerformanceRenderStats;
 }
 
 export interface PerformanceSnapshot {
@@ -43,9 +96,15 @@ function percentile(values: readonly number[], fraction: number): number {
 export function createPerformanceProfiler(initiallyEnabled = false) {
   const listeners = new Set<() => void>();
   const frames: PerformanceFrame[] = [];
-  const currentPhases = new Map<string, number>();
+  const currentPhases = new Map<string, { ms: number; startMs: number }>();
   const currentSystems = new Map<string, number>();
   const currentComponents = new Map<string, number>();
+  // Per-frame span logs (W4b) — cleared each beginFrame, snapshotted into the
+  // frame at endFrame. Distinct from the accumulate-by-name aggregate maps
+  // above (which back the cross-frame snapshot rollups): these preserve every
+  // individual invocation and its measured start offset, for the trace.
+  let frameSystems: PerformanceSpan[] = [];
+  let frameComponents: PerformanceSpan[] = [];
   let enabled = initiallyEnabled;
   let recording = false;
   let frameId = 0;
@@ -127,6 +186,8 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       currentPhases.clear();
       currentSystems.clear();
       currentComponents.clear();
+      frameSystems = [];
+      frameComponents = [];
       render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
       frameStart = now();
     },
@@ -137,7 +198,13 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
     endPhase(name: string) {
       if (!enabled) return;
       const elapsed = now() - phaseStart;
-      currentPhases.set(name, (currentPhases.get(name) ?? 0) + elapsed);
+      const existing = currentPhases.get(name);
+      // Accumulate ms across re-entries of the same phase, but keep the FIRST
+      // measured start offset (earliest entry) as the span's startMs.
+      currentPhases.set(name, {
+        ms: (existing?.ms ?? 0) + elapsed,
+        startMs: existing?.startMs ?? phaseStart - frameStart,
+      });
       if (recording)
         performance.measure(`vgai.phase.${name}`, { start: phaseStart, duration: elapsed });
     },
@@ -151,15 +218,28 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
         const end = now();
         const key = `${scope} / ${phase} / ${name}`;
         currentSystems.set(key, (currentSystems.get(key) ?? 0) + end - systemStart);
+        frameSystems.push({
+          name: key,
+          phase,
+          startMs: systemStart - frameStart,
+          ms: end - systemStart,
+        });
       },
     },
     beginComponent() {
       if (!recording) return;
       componentStart = now();
     },
-    endComponent(name: string) {
+    endComponent(name: string, phase = '') {
       if (!recording) return;
-      currentComponents.set(name, (currentComponents.get(name) ?? 0) + now() - componentStart);
+      const end = now();
+      currentComponents.set(name, (currentComponents.get(name) ?? 0) + end - componentStart);
+      frameComponents.push({
+        name,
+        phase,
+        startMs: componentStart - frameStart,
+        ms: end - componentStart,
+      });
     },
     reportRender(stats: {
       gpuMs: number | null;
@@ -187,7 +267,12 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
         timestamp,
         intervalMs,
         cpuMs: timestamp - frameStart,
-        phases: [...currentPhases].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+        phases: [...currentPhases]
+          .map(([name, { ms, startMs }]) => ({ name, ms, startMs }))
+          .sort((a, b) => b.ms - a.ms),
+        systems: frameSystems.slice(),
+        components: frameComponents.slice(),
+        render: { ...render },
       };
       frames.push(frame);
       if (frames.length > 600) frames.splice(0, frames.length - 600);
@@ -205,7 +290,9 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       return snapshot;
     },
     exportJSON() {
-      return JSON.stringify({ version: 1, capturedAt: new Date().toISOString(), frames }, null, 2);
+      // version 2 (W4b): frames now carry per-frame `systems`/`components`
+      // spans, per-frame `render` counters, and `startMs` on phase timings.
+      return JSON.stringify({ version: 2, capturedAt: new Date().toISOString(), frames }, null, 2);
     },
   };
 }