@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/packaged-runtime.ts

@@ -0,0 +1,108 @@
+/**
+ * Runtime detection of the PACKAGED editor server (`packages/editor/server/
+ * packaged.ts` — a `@volter/editor-core` npm package with NO monorepo checkout on
+ * disk) from editor CLIENT code. Needed because a react world's mount
+ * (`react-mount-runtime.ts`'s `resolveReactRootMountRuntime`) must resolve its
+ * `react`/`react-dom/client` from the
+ * PROJECT's own module graph ONLY under this runtime — see that function's
+ * doc comment, and `packaged.ts`'s header doc comment ("React-world OID
+ * authoring parity"), for the dual-React-instance bug this closes. Under
+ * dev, this must resolve `false` so the existing static-import path
+ * stays byte-unchanged (one shared Vite instance already collapses both
+ * react copies via `resolve.dedupe`).
+ *
+ * Reads the server's own `packaged` flag off `/__editor/project`'s response
+ * (computed server-side via `isMonorepoScaffoldRoot`, `server-utils.ts`)
+ * rather than probing a URL that only resolves in packaged mode: an
+ * unconditional dynamic `import()` probe would 404 (and log an
+ * unsuppressible browser console error) on EVERY react-world mount under
+ * dev — the exact reasoning `binding-resolver.ts`'s
+ * `loadProjectUIRegistry` doc comment already recorded for `hasUiRegistry`
+ * ("the client must not probe /@fs for it").
+ *
+ * A plain inline `fetch()`, not `editor-api.ts`'s `getCurrentServerProject`
+ * — same reasoning `loadProjectUIRegistry` documents: this module (via
+ * `binding-resolver.ts`) must stay importable by headless Node/vitest
+ * suites, and `editor-api.ts`'s module top level pulls in `./storage`.
+ *
+ * A HOST THAT SERVES NO `/__editor/project` is answered locally rather than by
+ * a doomed fetch: it is never the packaged runtime, because "packaged" names a
+ * Node host serving a project's own module graph, and a 404's console error is
+ * unsuppressible on every doorway of every mount. Same guard, same reason, as
+ * `ui-source/tier-source-write-backend.ts`'s `serverSourceWriteRoutes`.
+ *
+ * ## What is memoized, and what a FAILED probe does
+ *
+ * An ANSWER is memoized for the page — the runtime a server process runs
+ * under cannot change without a restart, so a settled answer is settled. A
+ * probe that never got an answer is NOT memoized, and does NOT resolve: it
+ * drops the memo and REJECTS, so the next caller asks again.
+ *
+ * Both halves were bought by one measured failure. A `.catch(() => false)`
+ * latch turned a single unreachable fetch — a mount landing in the window
+ * while the editor's `edit` command restarts its dev server, which it does on any
+ * server-file change — into a page where EVERY doorway
+ * (`three-ingest-runtime`, `canvas-entry-runtime`, `r3f-entry-runtime`,
+ * the two story runtimes, `binding-resolver`'s react
+ * mount) silently resolved the SHELL's namespace for the rest of the
+ * session. Under the packaged runtime that is the wrong graph, and the cost
+ * lands 10–15 seconds later as a mount failure whose message blames the
+ * GAME ("bundles its own (un-shared) copy of three") for a defect in this
+ * host — the exact mis-attribution `three-ingest-runtime.ts`'s own
+ * loud-throw comment already refuses to make for the sibling case.
+ *
+ * So "I don't know" is never spent as "dev". Every doorway reads this with
+ * `await isPackagedRuntime()` and does nothing else with the answer, so the
+ * rejection propagates to the mount site unchanged: nothing mounts on a
+ * guessed graph, the message names this host, and because the memo is
+ * dropped the remedy it states — retry the mount — is a real one rather
+ * than advice.
+ */
+
+import { editorServerJson } from '@volter/sdk/kit/editor-server-response';
+
+let cachedIsPackaged: Promise<boolean> | null = null;
+
+export function isPackagedRuntime(): Promise<boolean> {
+  if (!cachedIsPackaged) {
+    // The `fetch` call is INSIDE the chain so that a synchronous throw from it
+    // is a rejected probe like any other, rather than an exception thrown at
+    // whoever happened to ask first.
+    const probe: Promise<boolean> = Promise.resolve()
+      .then(() => fetch('/__editor/project'))
+      .then((res) =>
+        editorServerJson<{ project?: { packaged?: boolean } | null }>(
+          res,
+          '`/__editor/project` did not answer',
+        ),
+      )
+      .then((data) => Boolean(data.project?.packaged))
+      .catch((err: unknown) => {
+        if (cachedIsPackaged === probe) cachedIsPackaged = null;
+        throw new Error(
+          "This editor session's runtime is unknown — `/__editor/project` did not answer, so " +
+            'which module graph a world mounts in (this shell’s, or the project’s) cannot be ' +
+            'decided and nothing was mounted on a guess. This is a fault in the editor host, ' +
+            'not in the game. The answer is not latched: retry the mount (reopen the project) ' +
+            `and the question is asked again. (${err instanceof Error ? err.message : String(err)})`,
+          { cause: err },
+        );
+      });
+    cachedIsPackaged = probe;
+  }
+  return cachedIsPackaged;
+}
+
+/** Test-only: reset the memoized result between tests (mirrors
+ *  `setCachedProjectUIRegistry`'s test-seam shape). */
+export function resetPackagedRuntimeCacheForTest(): void {
+  cachedIsPackaged = null;
+}
+
+/** Test-only: pre-seed the probe's answer. jsdom has no `/__editor/project` to
+ *  ask (vitest's MODE is not `web`, so the browser short-circuit does not
+ *  apply), and the loud unknown-runtime refusal — correct in a live session —
+ *  is pure noise in a suite that mounts portable stories. */
+export function setPackagedRuntimeForTest(packaged: boolean): void {
+  cachedIsPackaged = Promise.resolve(packaged);
+}

package/src/kit/palettes/maya.palette.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 3,
+  "name": "Maya",
+  "theme": {
+    "id": "maya",
+    "color": {
+      "surface": {
+        "shell": "#2b2b2b",
+        "panel": "#444444",
+        "chrome": "#373737",
+        "raised": "#4b4b4b",
+        "inset": "#333333",
+        "overlay": "rgba(55,55,55,0.94)"
+      },
+      "boundary": {
+        "default": "#2b2b2b",
+        "strong": "#5a5a5a"
+      },
+      "content": {
+        "primary": "#cccccc",
+        "muted": "#a8a8a8",
+        "dim": "#858585",
+        "onAccent": "#ffffff",
+        "onBright": {
+          "primary": "#1c1c1c",
+          "muted": "rgba(28,28,28,0.82)",
+          "dim": "rgba(28,28,28,0.7)"
+        }
+      },
+      "accent": {
+        "default": "#5285a6",
+        "muted": "rgba(82,133,166,0.34)"
+      },
+      "semantic": {
+        "danger": "#d9534f",
+        "dangerMuted": "rgba(217,83,79,0.28)",
+        "dangerFaint": "rgba(217,83,79,0.12)",
+        "warning": "#e0a030",
+        "warningMuted": "rgba(224,160,48,0.28)",
+        "success": "#4fd85b",
+        "successMuted": "rgba(79,216,91,0.28)",
+        "dynamic": "#e6a6ff",
+        "dynamicMuted": "rgba(230,166,255,0.18)",
+        "instance": "#4fd85b"
+      },
+      "neutralOverlay": {
+        "hover": "rgba(255,255,255,0.07)",
+        "active": "rgba(255,255,255,0.12)"
+      },
+      "scrim": "rgba(0,0,0,0.55)"
+    },
+    "typography": {
+      "sans": "'Helvetica Neue', Arial, system-ui, sans-serif",
+      "mono": "Menlo, Consolas, monospace"
+    }
+  }
+}

package/src/kit/palettes/substance.palette.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 3,
+  "name": "Substance",
+  "theme": {
+    "id": "substance",
+    "color": {
+      "surface": {
+        "shell": "#1e1e1e",
+        "panel": "#252525",
+        "chrome": "#2a2a2a",
+        "raised": "#2d2d2d",
+        "inset": "#1a1a1a",
+        "overlay": "rgba(37,37,37,0.94)"
+      },
+      "boundary": {
+        "default": "#3a3a3a",
+        "strong": "#4a4a4a"
+      },
+      "content": {
+        "primary": "#d9d9d9",
+        "muted": "#a6a6a6",
+        "dim": "#7f7f7f",
+        "onAccent": "#ffffff",
+        "onBright": {
+          "primary": "#1e1e1e",
+          "muted": "rgba(30,30,30,0.82)",
+          "dim": "rgba(30,30,30,0.7)"
+        }
+      },
+      "accent": {
+        "default": "#4aa3df",
+        "muted": "rgba(74,163,223,0.3)"
+      },
+      "semantic": {
+        "danger": "#e5534b",
+        "dangerMuted": "rgba(229,83,75,0.28)",
+        "dangerFaint": "rgba(229,83,75,0.12)",
+        "warning": "#e3a52f",
+        "warningMuted": "rgba(227,165,47,0.28)",
+        "success": "#5cc27a",
+        "successMuted": "rgba(92,194,122,0.28)",
+        "dynamic": "#4aa3df",
+        "dynamicMuted": "rgba(74,163,223,0.18)",
+        "instance": "#e98b3a"
+      },
+      "neutralOverlay": {
+        "hover": "rgba(255,255,255,0.06)",
+        "active": "rgba(255,255,255,0.11)"
+      },
+      "scrim": "rgba(0,0,0,0.62)"
+    },
+    "typography": {
+      "sans": "'Source Sans 3', 'Segoe UI', system-ui, sans-serif",
+      "mono": "'Source Code Pro', Menlo, monospace"
+    }
+  }
+}

package/src/kit/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(`volter.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('volter.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/kit/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();
+}