@volter/editor-game 0.5.65

package/src/profiler/ProfilerPanel.tsx

@@ -0,0 +1,53 @@
+import { type ProfilerViewId, profilerView } from '../host/components/utility-view-state';
+import { EditorTab, EditorTabList } from '@volter/editor-sdk/widgets';
+import { useSyncExternalStore } from 'react';
+import { FrameDebuggerPanel } from './FrameDebuggerPanel';
+import { PerformancePanel } from './PerformancePanel';
+
+/**
+ * The engine's instrument bench: frame cost over time (Profiler) and the
+ * single-frame draw-call capture (Frame). Both read the host's own render
+ * path, which is why they share one utility — the game's debug plane
+ * (providers/commands) is a different audience and lives in its own.
+ */
+
+const TABS: ReadonlyArray<{ id: ProfilerViewId; label: string }> = [
+  { id: 'profiler', label: 'Profiler' },
+  { id: 'frame', label: 'Frame' },
+];
+
+export function ProfilerPanel() {
+  useSyncExternalStore(profilerView.subscribe, profilerView.version, profilerView.version);
+  const active = profilerView.active();
+  return (
+    <div
+      data-testid="profiler-panel"
+      style={{
+        // §2.31: no root fill — the dock surface shows through.
+        flex: 1,
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'column',
+      }}
+    >
+      <EditorTabList aria-label="Profiler views">
+        {TABS.map((tab) => (
+          <EditorTab
+            key={tab.id}
+            selected={active === tab.id}
+            data-testid={`profiler-tab-${tab.id}`}
+            onClick={() => profilerView.select(tab.id)}
+          >
+            {tab.label}
+          </EditorTab>
+        ))}
+      </EditorTabList>
+      <div role="tabpanel" style={{ flex: 1, minHeight: 0, display: 'flex' }}>
+        {active === 'profiler' && <PerformancePanel />}
+        {/* W4b: the Frame debugger (single-frame draw-call capture over the
+            RenderDebugAdapter) renders its own honest no-adapter notice. */}
+        {active === 'frame' && <FrameDebuggerPanel />}
+      </div>
+    </div>
+  );
+}

package/src/profiler/frame-debugger-store.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared capture ring for the Frame debugger (W4b, F11). A single module store
+ * (the `utility-view-state.ts` idiom) so the TWO entry points that trigger a
+ * capture — the Game-tab `game-capture-frame` button and the Frame debugger
+ * panel's own `frame-capture-button` — append to and read from ONE bounded
+ * history. Without this, a capture fired from the Game tab would be lost to the
+ * panel it opens.
+ *
+ * HONESTY: `captureFrame` awaits the adapter's real capture, which REJECTS (it
+ * never fabricates) when no frame renders within the bounded timeout — a
+ * paused/stopped world. That rejection surfaces as `lastCaptureError`, shown
+ * verbatim in the panel. The ring is reset on adapter identity change (a new
+ * game mounted / play stopped) — captures from a prior session are stale.
+ */
+
+import { CaptureHistoryModel } from '../host/components/frame-debugger-model';
+import type { RenderDebugAdapter } from '@volter/editor-project/adapter';
+
+let history = new CaptureHistoryModel();
+let boundAdapter: RenderDebugAdapter | null = null;
+let capturing = false;
+let lastError: string | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeFrameDebugger(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Monotonic version — the `getSnapshot` for `useSyncExternalStore`. */
+export function frameDebuggerVersion(): number {
+  return version;
+}
+
+/** Reset the shared ring when the bound adapter identity changes (new mount /
+ *  play stopped). Idempotent for the same identity, so it is safe to call on
+ *  every render/tick. */
+export function syncFrameDebuggerAdapter(adapter: RenderDebugAdapter | null): void {
+  if (adapter === boundAdapter) return;
+  boundAdapter = adapter;
+  history = new CaptureHistoryModel();
+  lastError = null;
+  notify();
+}
+
+export function getCaptureHistory(): CaptureHistoryModel {
+  return history;
+}
+
+export function isCapturing(): boolean {
+  return capturing;
+}
+
+export function lastCaptureError(): string | null {
+  return lastError;
+}
+
+export function selectCapture(id: number): void {
+  history.select(id);
+  notify();
+}
+
+export function clearCaptures(): void {
+  history.clear();
+  lastError = null;
+  notify();
+}
+
+/**
+ * Capture one frame through the adapter and append it to the shared ring.
+ * Binds the adapter (resetting a stale ring) first. A rejection — the honest
+ * "no frame rendered" of a paused/stopped world — is recorded as
+ * `lastCaptureError`; nothing is fabricated. No-op while a capture is already
+ * in flight or when no adapter is present.
+ */
+export async function captureFrame(adapter: RenderDebugAdapter | null): Promise<void> {
+  if (!adapter || capturing) return;
+  syncFrameDebuggerAdapter(adapter);
+  capturing = true;
+  lastError = null;
+  notify();
+  try {
+    const capture = await adapter.captureFrame();
+    history.add(capture);
+  } catch (error) {
+    lastError = error instanceof Error ? error.message : String(error);
+  } finally {
+    capturing = false;
+    notify();
+  }
+}

package/src/profiler/main-thread-busy.ts

@@ -0,0 +1,90 @@
+/**
+ * Main-thread busy sampling for the Profiler's frame-budget accounting.
+ *
+ * The per-source profiler measures only its own loop's rAF callback. The
+ * frame budget also needs "how long did OTHER main-thread tasks run" — React
+ * commits, timers, observers — which the browser only attributes above the
+ * 50ms long-animation-frame threshold. Below it, the honest measurable is
+ * event-loop responsiveness: a self-rescheduling `setTimeout(0)` records the
+ * gap between wakeups. Chrome clamps nested zero timeouts to ~4ms, so the
+ * SMALLEST gap in a window is the scheduler's baseline and anything above it
+ * is time the thread was busy with someone else's work (including the
+ * measured loop itself — callers subtract the loop's own measured CPU).
+ *
+ * Honesty properties:
+ * - The baseline is measured per window, never assumed, so throttling changes
+ *   (background tab, battery saver) recalibrate instead of fabricating load.
+ * - Sustained saturation inflates every gap INCLUDING the minimum, so this
+ *   under-reports rather than over-reports busy time. It is a floor.
+ * - Cost: ~250 timer wakeups/s of a few µs each — an opt-in instrument that
+ *   runs only while the Profiler surface has it started, covered by the
+ *   panel's existing "profiling adds measurement overhead" warning.
+ */
+
+interface GapSample {
+  /** performance.now() at the wakeup that OBSERVED the gap (its end). */
+  readonly t: number;
+  readonly gapMs: number;
+}
+
+/**
+ * Pure aggregation (unit-tested): total blocked time across `gaps`, using the
+ * window's smallest gap as the scheduler baseline. Fewer than 4 samples is
+ * too little signal to call anything busy — returns 0, never a guess.
+ */
+export function busyMsFromGaps(gaps: readonly number[]): number {
+  if (gaps.length < 4) return 0;
+  let baseline = Number.POSITIVE_INFINITY;
+  for (const gap of gaps) baseline = Math.min(baseline, gap);
+  let busy = 0;
+  for (const gap of gaps) busy += Math.max(0, gap - baseline);
+  return busy;
+}
+
+const MAX_SAMPLES = 1200;
+
+export interface MainThreadBusySampler {
+  start(): void;
+  stop(): void;
+  /**
+   * Busy ms observed in [sinceMs, now], with the sample count so callers can
+   * report honest absence (`null` budget row) instead of a zero when the
+   * sampler has not covered the window.
+   */
+  busySince(sinceMs: number): { busyMs: number; sampleCount: number };
+}
+
+export function createMainThreadBusySampler(): MainThreadBusySampler {
+  const samples: GapSample[] = [];
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let last = 0;
+
+  const tick = (): void => {
+    const now = performance.now();
+    samples.push({ t: now, gapMs: now - last });
+    if (samples.length > MAX_SAMPLES) samples.splice(0, samples.length - MAX_SAMPLES);
+    last = now;
+    timer = setTimeout(tick, 0);
+  };
+
+  return {
+    start() {
+      if (timer !== null) return;
+      samples.length = 0;
+      last = performance.now();
+      timer = setTimeout(tick, 0);
+    },
+    stop() {
+      if (timer === null) return;
+      clearTimeout(timer);
+      timer = null;
+    },
+    busySince(sinceMs: number) {
+      const gaps: number[] = [];
+      for (const sample of samples) {
+        if (sample.t >= sinceMs) gaps.push(sample.gapMs);
+      }
+      return { busyMs: busyMsFromGaps(gaps), sampleCount: gaps.length };
+    },
+  };
+}