@volter/editor-core 0.5.57

package/src/performance-profiler.ts

@@ -0,0 +1,367 @@
+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;
+  /**
+   * How many top-level `renderer.render()` submissions the last presentation
+   * took (`renderer.info.render.frame`'s delta across one draw) — a composer
+   * chain, a shadow pass and a post stack each cost one. `null` (never a
+   * fabricated 0, same rule as `gpuMs`) when no reporter counted them: a
+   * reporter that omits `renderPasses` is saying it does not know, which is
+   * different from saying nothing was drawn.
+   */
+  readonly renderPasses: number | null;
+}
+
+export interface PerformanceFrame {
+  readonly id: number;
+  readonly timestamp: number;
+  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 {
+  readonly enabled: boolean;
+  readonly recording: boolean;
+  readonly fps: number;
+  readonly cpuMs: number;
+  readonly p95Ms: number;
+  readonly p99Ms: number;
+  readonly frames: readonly PerformanceFrame[];
+  readonly phases: readonly PerformanceTiming[];
+  readonly systems: readonly PerformanceTiming[];
+  readonly components: readonly PerformanceTiming[];
+  readonly render: PerformanceRenderStats;
+}
+
+const now = () => globalThis.performance?.now() ?? Date.now();
+
+function percentile(sorted: readonly number[], fraction: number): number {
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))] ?? 0;
+}
+
+/** Game-owned, bounded external store for browser-native performance diagnostics. */
+export function createPerformanceProfiler(initiallyEnabled = false) {
+  const listeners = new Set<() => void>();
+  const frames: PerformanceFrame[] = [];
+  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;
+  // The header's always-visible FPS sparkline needs frame INTERVALS without
+  // turning on the full profiler. Full profiling measures phases/systems,
+  // issues GPU timer queries at render sites, and intentionally warns about
+  // overhead; a glanceable heartbeat must not silently opt the user into all
+  // of that work. `telemetryEnabled` records only the frame envelope.
+  let telemetryEnabled = false;
+  let recording = false;
+  let frameId = 0;
+  let frameStart = 0;
+  let lastFrameStart = 0;
+  /**
+   * Phase start times, innermost last. A STACK rather than the single slot
+   * this used to be, because phases NEST: the three adapter brackets its CPU
+   * render submission as its own phase (`render.submit`,
+   * `dev/render-vitals.ts`) from inside the frame's enclosing `render` phase.
+   * With one slot the inner `beginPhase()` overwrote the outer's start, so the
+   * outer `endPhase('render')` measured only the tail after the inner phase —
+   * silently under-reporting the very phase the inner one was decomposing.
+   * Balanced callers are unaffected; `endPhase` with an empty stack falls back
+   * to `frameStart` rather than a stale start from a previous frame.
+   */
+  const phaseStack: number[] = [];
+  let systemStart = 0;
+  let componentStart = 0;
+  let render: PerformanceRenderStats = {
+    gpuMs: null,
+    drawCalls: 0,
+    triangles: 0,
+    geometries: 0,
+    textures: 0,
+    renderPasses: null,
+  };
+  let snapshot: PerformanceSnapshot = {
+    enabled,
+    recording,
+    fps: 0,
+    cpuMs: 0,
+    p95Ms: 0,
+    p99Ms: 0,
+    frames: [],
+    phases: [],
+    systems: [],
+    components: [],
+    render,
+  };
+
+  function publish(): void {
+    const latest = frames.at(-1);
+    // Frame-only subscribers need no percentile work. Keep this window stable
+    // so a retained snapshot's first percentile read still describes its frames.
+    const snapshotFrames = frames.slice();
+    let sortedIntervals: number[] | undefined;
+    const readPercentile = (fraction: number): number => {
+      sortedIntervals ??= snapshotFrames
+        .map((frame) => frame.intervalMs)
+        .filter((value) => value > 0)
+        .sort((a, b) => a - b);
+      return percentile(sortedIntervals, fraction);
+    };
+    snapshot = {
+      enabled,
+      recording,
+      fps: latest?.intervalMs ? 1000 / latest.intervalMs : 0,
+      cpuMs: latest?.cpuMs ?? 0,
+      get p95Ms() {
+        return readPercentile(0.95);
+      },
+      get p99Ms() {
+        return readPercentile(0.99);
+      },
+      frames: snapshotFrames,
+      phases: latest?.phases ?? [],
+      systems: [...currentSystems].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+      components: [...currentComponents]
+        .map(([name, ms]) => ({ name, ms }))
+        .sort((a, b) => b.ms - a.ms),
+      render,
+    };
+    for (const listener of listeners) listener();
+  }
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    set enabled(value: boolean) {
+      if (enabled === value) return;
+      enabled = value;
+      if (value && !telemetryEnabled) lastFrameStart = 0;
+      publish();
+    },
+    get telemetryEnabled() {
+      return telemetryEnabled;
+    },
+    set telemetryEnabled(value: boolean) {
+      if (telemetryEnabled === value) return;
+      const wasInactive = !enabled && !telemetryEnabled;
+      telemetryEnabled = value;
+      if (value && wasInactive) lastFrameStart = 0;
+      publish();
+    },
+    get recording() {
+      return recording;
+    },
+    startRecording() {
+      const wasInactive = !enabled && !telemetryEnabled;
+      enabled = true;
+      if (wasInactive) lastFrameStart = 0;
+      recording = true;
+      frames.length = 0;
+      publish();
+    },
+    stopRecording() {
+      recording = false;
+      publish();
+    },
+    clear() {
+      frames.length = 0;
+      publish();
+    },
+    beginFrame() {
+      if (!enabled && !telemetryEnabled) return;
+      currentPhases.clear();
+      currentSystems.clear();
+      currentComponents.clear();
+      frameSystems = [];
+      frameComponents = [];
+      // A frame that threw mid-phase leaves entries on the stack; a fresh
+      // frame starts from nothing rather than inheriting them.
+      phaseStack.length = 0;
+      render = {
+        gpuMs: null,
+        drawCalls: 0,
+        triangles: 0,
+        geometries: 0,
+        textures: 0,
+        renderPasses: null,
+      };
+      frameStart = now();
+    },
+    beginPhase() {
+      if (!enabled) return;
+      phaseStack.push(now());
+    },
+    endPhase(name: string) {
+      if (!enabled) return;
+      // See `phaseStack`: pop restores the ENCLOSING phase's own start, so a
+      // nested bracket measures itself without truncating its parent.
+      const phaseStart = phaseStack.pop() ?? frameStart;
+      const elapsed = now() - phaseStart;
+      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 });
+    },
+    systemObserver: {
+      beginSystem() {
+        if (!enabled) return;
+        systemStart = now();
+      },
+      endSystem(scope: string, phase: string, name: string) {
+        if (!enabled) return;
+        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, phase = '') {
+      if (!recording) return;
+      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;
+      drawCalls: number;
+      triangles: number;
+      geometries: number;
+      textures: number;
+      /** Omit when this reporter does not count passes — see
+       *  {@link PerformanceRenderStats.renderPasses}. */
+      renderPasses?: number;
+    }) {
+      if (!enabled) return;
+      render = {
+        gpuMs: stats.gpuMs ?? render.gpuMs,
+        drawCalls: render.drawCalls + stats.drawCalls,
+        triangles: render.triangles + stats.triangles,
+        geometries: render.geometries + stats.geometries,
+        textures: render.textures + stats.textures,
+        renderPasses:
+          stats.renderPasses === undefined
+            ? render.renderPasses
+            : (render.renderPasses ?? 0) + stats.renderPasses,
+      };
+    },
+    endFrame() {
+      if (!enabled && !telemetryEnabled) return;
+      const timestamp = now();
+      const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
+      lastFrameStart = frameStart;
+      const frame: PerformanceFrame = {
+        id: ++frameId,
+        timestamp,
+        intervalMs,
+        cpuMs: timestamp - frameStart,
+        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);
+      if (recording)
+        performance.measure('vgai.frame', { start: frameStart, duration: frame.cpuMs });
+      publish();
+    },
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    exportJSON() {
+      // 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);
+    },
+  };
+}
+
+export type PerformanceProfiler = ReturnType<typeof createPerformanceProfiler>;

package/src/performance-sources.ts

@@ -0,0 +1,69 @@
+import type { PerformanceProfiler } from './performance-profiler';
+
+export interface EditorPerformanceSource {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: 'scene' | 'source' | 'asset' | 'game';
+  readonly profiler: PerformanceProfiler;
+  /** Mount identity for a Game runtime source. Document identity stays
+   * `workspace:game`; this disambiguates the runtime inspected inside it. */
+  readonly instanceId?: string;
+}
+
+const sources = new Map<string, EditorPerformanceSource>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Register one real render loop as a profiler source. */
+export function registerPerformanceSource(source: EditorPerformanceSource): () => void {
+  sources.set(source.id, source);
+  notify();
+  return () => {
+    if (sources.get(source.id) !== source) return;
+    sources.delete(source.id);
+    notify();
+  };
+}
+
+export function performanceSourceForDocument(
+  documentId: string | null,
+): EditorPerformanceSource | null {
+  return documentId ? (sources.get(documentId) ?? null) : null;
+}
+
+/** Every registered render loop. The self-vitals checks
+ *  (`coverage/session-vitals.ts`) ask "did the thing that is running draw a
+ *  frame", which is a question about whichever loop exists, not about the
+ *  document the user happens to be looking at. */
+export function allPerformanceSources(): readonly EditorPerformanceSource[] {
+  return [...sources.values()];
+}
+
+export function performanceSourceForGameInstance(
+  instanceId: string | null,
+): EditorPerformanceSource | null {
+  if (instanceId === null) return null;
+  for (const source of sources.values()) {
+    if (source.kind === 'game' && source.instanceId === instanceId) return source;
+  }
+  return null;
+}
+
+export function subscribePerformanceSources(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function performanceSourcesVersion(): number {
+  return version;
+}
+
+export function __resetPerformanceSourcesForTest(): void {
+  sources.clear();
+  notify();
+}

package/src/play-boot-phase.ts

@@ -0,0 +1,145 @@
+/**
+ * WHAT PLAY WAS DOING WHEN IT STOPPED ANSWERING.
+ *
+ * ## The measurement this exists for
+ *
+ * 2026-08-20, `packages/editor/scripts/scale-harness` at N=20000 on the canvas
+ * lane. `vgai play` burned its whole 120s budget and was refused with
+ *
+ *     Command timed out — the tab is present (last heartbeat 0.8s ago) and
+ *     did not respond.
+ *
+ * then `screenshot` (15s) and `stop` (30s) were refused with the same sentence.
+ * Every one of those statements was TRUE and none of them was the answer: the
+ * heartbeat is a WORKER, so it kept beating at 0.4s while the page's main
+ * thread sat inside one 199.5-second synchronous block. Four consecutive runs,
+ * three silent timeouts each, against a session every reader called healthy.
+ *
+ * The defect the fix closed was a quadratic name derivation
+ * (`@vgai/game-runtime/pixi/authoring`). The defect THIS closes is that nothing anywhere
+ * could say which of play's eight steps the page was in — the relay knows only
+ * that it asked, the tab table knows only that the tab exists, and the page
+ * itself, being wedged, is the one party that cannot speak.
+ *
+ * ## The mechanism
+ *
+ * A phase is published BEFORE its work starts, on the control channel, as its
+ * own tiny message — never folded into the state snapshot, which is the
+ * expensive derivation a wedged page cannot produce and which is exactly the
+ * thing that goes silent. So the server always holds the phase the page was
+ * ENTERING when it went quiet, and the relay's refusal can name it.
+ *
+ * This module is the page's half and is deliberately pure apart from one
+ * injected reporter: the latch, the phase vocabulary, and the sentence are all
+ * unit-testable without a browser.
+ */
+
+/**
+ * The steps of a play boot, in the order `play-mode.ts` runs them.
+ *
+ * The vocabulary is shared with `play-boot-stall.ts`: the three network-shaped
+ * steps it already guards use the SAME wording here, so the hidden-tab stall
+ * message and a stuck-play refusal cannot describe the same step differently.
+ * The steps that guard does not wrap — the runtime mount and the authoring
+ * install, which must never be abandoned mid-flight — are the ones that had no
+ * name at all, and they are where the 199.5s block was measured.
+ */
+export const PLAY_BOOT_PHASES = [
+  'waiting for the editor to bind Play',
+  'waiting for the project bootstrap to settle',
+  'starting the play log session',
+  'opening the Game document',
+  'fetching the project manifest',
+  "resolving the project's root entries",
+  'mounting the runtime roots',
+  'installing play authoring for each root',
+  'binding the editor to the running game',
+] as const;
+
+export type PlayBootPhase = (typeof PLAY_BOOT_PHASES)[number];
+
+/** The page's standing answer to "what is play doing right now". */
+/** Any main-thread work the page announces before starting it: a play boot
+ *  step, or a document's `building src/models/x.ts`. */
+export type PagePhase = PlayBootPhase | `building ${string}`;
+
+export interface PlayBootPhaseState {
+  /** The phase being ENTERED, or `null` once the boot settled either way. */
+  readonly phase: PagePhase | null;
+  /** Epoch ms the page entered it (or left the last one). */
+  readonly at: number;
+  /** This play attempt's ordinal, so a stale report is recognizable as stale. */
+  readonly run: number;
+}
+
+let _state: PlayBootPhaseState = { phase: null, at: 0, run: 0 };
+let _report: ((state: PlayBootPhaseState) => void) | null = null;
+
+/**
+ * Install the upstream reporter. Wired once at editor boot; left unset in
+ * tests, where the latch is read directly.
+ */
+export function setPlayBootPhaseReporter(
+  report: ((state: PlayBootPhaseState) => void) | null,
+): void {
+  _report = report;
+}
+
+function publish(next: PlayBootPhaseState): void {
+  _state = next;
+  // A reporter that throws must never break a play boot — the phase is
+  // diagnostics, and diagnostics that can fail the thing they describe are
+  // worse than none.
+  try {
+    _report?.(next);
+  } catch {
+    /* the boot continues; the reader loses one phase line */
+  }
+}
+
+/** Begin a play attempt. Returns its run ordinal. */
+export function beginPlayBoot(now: number = Date.now()): number {
+  publish({ phase: null, at: now, run: _state.run + 1 });
+  return _state.run;
+}
+
+/** Enter one phase. Called BEFORE the phase's work, never after it. */
+export function markPlayBootPhase(phase: PlayBootPhase, now: number = Date.now()): void {
+  publish({ phase, at: now, run: _state.run });
+}
+
+/**
+ * The boot settled — started, failed, or was superseded. Clearing the phase is
+ * what makes a LATER stuck command ("stop", "screenshot") report honestly that
+ * play was not booting rather than blaming the last phase of a boot that
+ * finished minutes ago.
+ */
+export function endPlayBoot(now: number = Date.now()): void {
+  publish({ phase: null, at: now, run: _state.run });
+}
+
+/**
+ * Announce main-thread work that is NOT a play boot — a model document about
+ * to run a module's `build()` — so a command that times out while the page is
+ * inside it is refused by name ("the page is still inside building
+ * src/models/mushroom.ts") instead of "never answered". A blind session on a
+ * swapped box read the generic refusal as its own module hanging and bisected
+ * a parameter for five minutes (2026-09-06). Returns the end call; nested
+ * work is not tracked — the latest announcement stands until it ends.
+ */
+export function beginPageWork(label: `building ${string}`, now: number = Date.now()): () => void {
+  publish({ phase: label, at: now, run: _state.run });
+  return () => {
+    if (_state.phase === label) publish({ phase: null, at: Date.now(), run: _state.run });
+  };
+}
+
+export function currentPlayBootPhase(): PlayBootPhaseState {
+  return _state;
+}
+
+/** Test-only reset — drops the latch and the reporter. */
+export function __resetPlayBootPhaseForTest(): void {
+  _state = { phase: null, at: 0, run: 0 };
+  _report = null;
+}