@lagless/desync-diagnostics 0.0.48

package/src/lib/performance-profiler.spec.ts

@@ -0,0 +1,412 @@
+import { PerformanceProfiler } from './performance-profiler.js';
+import type { IECSSystem } from '@lagless/core';
+
+function createMockSystems(): IECSSystem[] {
+  return [
+    {
+      update(_tick: number) {
+        // Simulate ~0.1ms of work
+        const start = performance.now();
+        while (performance.now() - start < 0.1) { /* spin */ }
+      },
+      constructor: { name: 'PhysicsSystem' } as unknown as { name: string },
+    } as unknown as IECSSystem,
+    {
+      update(_tick: number) {
+        // Simulate ~0.05ms of work
+        const start = performance.now();
+        while (performance.now() - start < 0.05) { /* spin */ }
+      },
+      constructor: { name: 'MovementSystem' } as unknown as { name: string },
+    } as unknown as IECSSystem,
+  ];
+}
+
+/**
+ * Creates a mock runner that simulates the ECSSimulation tick loop.
+ * The simulate() method runs all systems, and saveSnapshot() is a no-op.
+ * addTickHandler() registers handlers called at the end of each tick.
+ */
+function createMockRunner(systems: IECSSystem[], opts?: { snapshotRate?: number }) {
+  const tickHandlers = new Set<(tick: number) => void>();
+  const snapshotRate = opts?.snapshotRate ?? 5;
+
+  const simulation = {
+    registeredSystems: systems as ReadonlyArray<IECSSystem>,
+    addTickHandler(handler: (tick: number) => void): () => void {
+      tickHandlers.add(handler);
+      return () => { tickHandlers.delete(handler); };
+    },
+    simulate(tick: number): void {
+      for (const sys of systems) {
+        sys.update(tick);
+      }
+    },
+    saveSnapshot(_tick: number): void {
+      // Simulate ~0.05ms of snapshot work
+      const start = performance.now();
+      while (performance.now() - start < 0.05) { /* spin */ }
+    },
+  };
+
+  /**
+   * Runs one full tick: simulate → extra work → conditionally saveSnapshot → tick handlers.
+   * Mirrors ECSSimulation.simulationTicks() loop body.
+   */
+  function runTick(tick: number): void {
+    (simulation as any).simulate(tick);
+    // Simulate non-system work (hash tracking, signals) ~0.02ms
+    const start = performance.now();
+    while (performance.now() - start < 0.02) { /* spin */ }
+    // Conditionally save snapshot
+    if (snapshotRate > 0 && tick % snapshotRate === 0) {
+      (simulation as any).saveSnapshot(tick);
+    }
+    // Call tick handlers
+    for (const handler of tickHandlers) handler(tick);
+  }
+
+  return {
+    Simulation: simulation,
+    runTick,
+  } as any;
+}
+
+describe('PerformanceProfiler', () => {
+  it('should attach and wrap system update methods', () => {
+    const systems = createMockSystems();
+    const originalUpdates = systems.map((s) => s.update);
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    // update methods should be wrapped (different references)
+    for (let i = 0; i < systems.length; i++) {
+      expect(systems[i].update).not.toBe(originalUpdates[i]);
+    }
+
+    profiler.dispose();
+  });
+
+  it('should detach and restore original update methods', () => {
+    const systems = createMockSystems();
+    const originalUpdates = systems.map((s) => s.update);
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+    profiler.detach();
+
+    for (let i = 0; i < systems.length; i++) {
+      expect(systems[i].update).toBe(originalUpdates[i]);
+    }
+
+    profiler.dispose();
+  });
+
+  it('should collect per-system timing stats', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    // Run full ticks through the mock tick loop
+    for (let tick = 1; tick <= 5; tick++) {
+      runner.runTick(tick);
+    }
+
+    const stats = profiler.getStats();
+    expect(stats.systems).toHaveLength(2);
+    expect(stats.systems[0].name).toBe('PhysicsSystem');
+    expect(stats.systems[1].name).toBe('MovementSystem');
+
+    // Each system should have positive timing values
+    for (const sys of stats.systems) {
+      expect(sys.latest).toBeGreaterThan(0);
+      expect(sys.min).toBeGreaterThan(0);
+      expect(sys.max).toBeGreaterThanOrEqual(sys.min);
+      expect(sys.avg).toBeGreaterThan(0);
+    }
+
+    profiler.dispose();
+  });
+
+  it('should compute aggregate tick time', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    for (let tick = 1; tick <= 3; tick++) {
+      runner.runTick(tick);
+    }
+
+    const stats = profiler.getStats();
+    // Tick time should be positive
+    expect(stats.tickTime.latest).toBeGreaterThan(0);
+    expect(stats.tickTime.avg).toBeGreaterThan(0);
+    expect(stats.tickTime.min).toBeGreaterThan(0);
+    expect(stats.tickTime.max).toBeGreaterThanOrEqual(stats.tickTime.min);
+
+    profiler.dispose();
+  });
+
+  it('should return zeroed stats when no ticks have run', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    const stats = profiler.getStats();
+    expect(stats.systems).toHaveLength(2);
+    for (const sys of stats.systems) {
+      expect(sys.latest).toBe(0);
+      expect(sys.min).toBe(0);
+      expect(sys.max).toBe(0);
+      expect(sys.avg).toBe(0);
+    }
+    expect(stats.tickTime.latest).toBe(0);
+
+    profiler.dispose();
+  });
+
+  it('should still call original update when wrapped', () => {
+    let callCount = 0;
+    const systems: IECSSystem[] = [
+      {
+        update() { callCount++; },
+        constructor: { name: 'TestSystem' } as unknown as { name: string },
+      } as unknown as IECSSystem,
+    ];
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+    systems[0].update(1);
+    systems[0].update(2);
+
+    expect(callCount).toBe(2);
+
+    profiler.dispose();
+  });
+
+  it('should handle rolling window correctly', () => {
+    let duration = 0.1;
+    const systems: IECSSystem[] = [
+      {
+        update() {
+          const start = performance.now();
+          while (performance.now() - start < duration) { /* spin */ }
+        },
+        constructor: { name: 'VaryingSystem' } as unknown as { name: string },
+      } as unknown as IECSSystem,
+    ];
+    const profiler = new PerformanceProfiler(8); // small window
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    // Run 8 ticks with 0.1ms duration
+    for (let i = 1; i <= 8; i++) {
+      runner.runTick(i);
+    }
+
+    const stats1 = profiler.getStats();
+    const avg1 = stats1.systems[0].avg;
+
+    // Run 8 more ticks with 0.3ms duration — old values should be overwritten
+    duration = 0.3;
+    for (let i = 9; i <= 16; i++) {
+      runner.runTick(i);
+    }
+
+    const stats2 = profiler.getStats();
+    // Average should now be higher since all window entries are ~0.3ms
+    expect(stats2.systems[0].avg).toBeGreaterThan(avg1);
+
+    profiler.dispose();
+  });
+
+  // --- NEW TESTS for tick time and snapshot time ---
+
+  it('should measure real total tick time greater than sum of system times', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems, { snapshotRate: 1 });
+
+    profiler.attach(runner);
+
+    // Run 10 ticks (with snapshot every tick to include snapshot overhead)
+    for (let tick = 1; tick <= 10; tick++) {
+      runner.runTick(tick);
+    }
+
+    const stats = profiler.getStats();
+    const systemSum = stats.systems.reduce((sum, s) => sum + s.avg, 0);
+
+    // Real tick time should be greater than system sum (includes non-system work + snapshot)
+    expect(stats.tickTime.avg).toBeGreaterThan(systemSum);
+
+    profiler.dispose();
+  });
+
+  it('should include snapshotTime in stats', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems, { snapshotRate: 1 });
+
+    profiler.attach(runner);
+
+    // Run ticks — snapshot happens every tick with snapshotRate=1
+    for (let tick = 1; tick <= 5; tick++) {
+      runner.runTick(tick);
+    }
+
+    const stats = profiler.getStats();
+    expect(stats.snapshotTime).toBeDefined();
+    expect(stats.snapshotTime.latest).toBeGreaterThan(0);
+    expect(stats.snapshotTime.min).toBeGreaterThan(0);
+    expect(stats.snapshotTime.max).toBeGreaterThanOrEqual(stats.snapshotTime.min);
+    expect(stats.snapshotTime.avg).toBeGreaterThan(0);
+
+    profiler.dispose();
+  });
+
+  it('should record snapshot time only when snapshot happens', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    // snapshotRate=5 means snapshot on tick 5, 10, 15, ...
+    const runner = createMockRunner(systems, { snapshotRate: 5 });
+
+    profiler.attach(runner);
+
+    // Run 4 ticks — no snapshot should happen
+    for (let tick = 1; tick <= 4; tick++) {
+      runner.runTick(tick);
+    }
+
+    let stats = profiler.getStats();
+    expect(stats.snapshotTime.latest).toBe(0);
+    expect(stats.snapshotTime.avg).toBe(0);
+
+    // Run tick 5 — snapshot should happen
+    runner.runTick(5);
+
+    stats = profiler.getStats();
+    expect(stats.snapshotTime.latest).toBeGreaterThan(0);
+    expect(stats.snapshotTime.avg).toBeGreaterThan(0);
+
+    profiler.dispose();
+  });
+
+  it('should detach and restore simulate() and saveSnapshot()', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    const originalSimulate = runner.Simulation.simulate;
+    const originalSaveSnapshot = runner.Simulation.saveSnapshot;
+
+    profiler.attach(runner);
+
+    // Methods should be monkey-patched
+    expect(runner.Simulation.simulate).not.toBe(originalSimulate);
+    expect(runner.Simulation.saveSnapshot).not.toBe(originalSaveSnapshot);
+
+    profiler.detach();
+
+    // Methods should be restored
+    expect(runner.Simulation.simulate).toBe(originalSimulate);
+    expect(runner.Simulation.saveSnapshot).toBe(originalSaveSnapshot);
+
+    profiler.dispose();
+  });
+
+  // --- overheadTime tests ---
+
+  it('should include overheadTime in stats reflecting non-system non-snapshot work', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    // snapshotRate=0 means no snapshots — overhead = tickTime - simulateTime
+    const runner = createMockRunner(systems, { snapshotRate: 0 });
+
+    profiler.attach(runner);
+
+    for (let tick = 1; tick <= 10; tick++) {
+      runner.runTick(tick);
+    }
+
+    const stats = profiler.getStats();
+    // The mock tick loop has ~0.02ms of non-system work between simulate and tick handlers
+    expect(stats.overheadTime).toBeDefined();
+    expect(stats.overheadTime.avg).toBeGreaterThan(0);
+    expect(stats.overheadTime.min).toBeGreaterThanOrEqual(0);
+    expect(stats.overheadTime.max).toBeGreaterThanOrEqual(stats.overheadTime.min);
+
+    profiler.dispose();
+  });
+
+  it('should return zeroed overheadTime when no ticks have run', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    const stats = profiler.getStats();
+    expect(stats.overheadTime.latest).toBe(0);
+    expect(stats.overheadTime.avg).toBe(0);
+
+    profiler.dispose();
+  });
+
+  it('should reset overheadTime state on detach', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    for (let tick = 1; tick <= 5; tick++) {
+      runner.runTick(tick);
+    }
+
+    profiler.detach();
+
+    const stats = profiler.getStats();
+    expect(stats.overheadTime.latest).toBe(0);
+    expect(stats.overheadTime.avg).toBe(0);
+
+    profiler.dispose();
+  });
+
+  it('should remove tick handler on detach', () => {
+    const systems = createMockSystems();
+    const profiler = new PerformanceProfiler();
+    const runner = createMockRunner(systems);
+
+    profiler.attach(runner);
+
+    // Run some ticks
+    for (let tick = 1; tick <= 3; tick++) {
+      runner.runTick(tick);
+    }
+
+    profiler.detach();
+
+    // Run more ticks — tick time should NOT accumulate
+    for (let tick = 4; tick <= 6; tick++) {
+      runner.runTick(tick);
+    }
+
+    // After detach, getStats should return zeroed (entries cleared)
+    const stats = profiler.getStats();
+    expect(stats.tickTime.latest).toBe(0);
+
+    profiler.dispose();
+  });
+});

package/src/lib/performance-profiler.ts

@@ -0,0 +1,245 @@
+import type { ECSRunner, ECSSimulation, IECSSystem } from '@lagless/core';
+
+export interface TimingStats {
+  latest: number;
+  min: number;
+  max: number;
+  avg: number;
+}
+
+export interface SystemTimingStats extends TimingStats {
+  name: string;
+}
+
+export interface PerformanceStats {
+  tickTime: TimingStats;
+  snapshotTime: TimingStats;
+  overheadTime: TimingStats;
+  systems: SystemTimingStats[];
+}
+
+interface SystemEntry {
+  name: string;
+  original: (tick: number) => void;
+  system: IECSSystem;
+  buffer: Float64Array;
+  writeIndex: number;
+  count: number;
+}
+
+/** Runtime shape of ECSSimulation with protected methods accessible via monkey-patching */
+interface SimulationRuntime {
+  simulate: (tick: number) => void;
+  saveSnapshot: (tick: number) => void;
+}
+
+const DEFAULT_WINDOW_SIZE = 600;
+const ZERO_TIMING: TimingStats = { latest: 0, min: 0, max: 0, avg: 0 };
+
+function computeBufferStats(buffer: Float64Array, writeIndex: number, count: number, windowSize: number): TimingStats {
+  if (count === 0) return { ...ZERO_TIMING };
+  let min = Infinity;
+  let max = -Infinity;
+  let sum = 0;
+  for (let i = 0; i < count; i++) {
+    const idx = (writeIndex - count + i + windowSize) % windowSize;
+    const v = buffer[idx];
+    if (v < min) min = v;
+    if (v > max) max = v;
+    sum += v;
+  }
+  const latestIdx = (writeIndex - 1 + windowSize) % windowSize;
+  return {
+    latest: buffer[latestIdx],
+    min,
+    max,
+    avg: sum / count,
+  };
+}
+
+export class PerformanceProfiler {
+  private readonly _windowSize: number;
+  private _entries: SystemEntry[] = [];
+  private _attached = false;
+
+  // Tick time ring buffer
+  private _tickTimeBuffer!: Float64Array;
+  private _tickTimeWriteIndex = 0;
+  private _tickTimeCount = 0;
+  private _tickStartTime = 0;
+
+  // Snapshot time ring buffer
+  private _snapshotTimeBuffer!: Float64Array;
+  private _snapshotTimeWriteIndex = 0;
+  private _snapshotTimeCount = 0;
+
+  // Overhead time ring buffer (tickTime - simulateElapsed - snapshotElapsed)
+  private _overheadTimeBuffer!: Float64Array;
+  private _overheadTimeWriteIndex = 0;
+  private _overheadTimeCount = 0;
+
+  // Per-tick elapsed tracking for overhead computation
+  private _lastSimulateElapsed = -1; // sentinel: -1 = no data yet (first-tick guard)
+  private _lastSnapshotElapsed = 0;
+
+  // Cleanup references
+  private _originalSimulate: ((tick: number) => void) | null = null;
+  private _originalSaveSnapshot: ((tick: number) => void) | null = null;
+  private _removeTickHandler: (() => void) | null = null;
+  private _simulation: ECSSimulation | null = null;
+
+  constructor(windowSize = DEFAULT_WINDOW_SIZE) {
+    this._windowSize = windowSize;
+  }
+
+  public attach(runner: ECSRunner): void {
+    if (this._attached) return;
+    this._attached = true;
+
+    const simulation = runner.Simulation;
+    this._simulation = simulation;
+    const sim = simulation as unknown as SimulationRuntime;
+    const systems = simulation.registeredSystems;
+    this._entries = [];
+
+    // Initialize ring buffers
+    this._tickTimeBuffer = new Float64Array(this._windowSize);
+    this._tickTimeWriteIndex = 0;
+    this._tickTimeCount = 0;
+    this._snapshotTimeBuffer = new Float64Array(this._windowSize);
+    this._snapshotTimeWriteIndex = 0;
+    this._snapshotTimeCount = 0;
+    this._overheadTimeBuffer = new Float64Array(this._windowSize);
+    this._overheadTimeWriteIndex = 0;
+    this._overheadTimeCount = 0;
+    this._lastSimulateElapsed = -1;
+    this._lastSnapshotElapsed = 0;
+
+    // Monkey-patch per-system update methods
+    for (const system of systems) {
+      const name = system.constructor.name;
+      const original = system.update;
+      const entry: SystemEntry = {
+        name,
+        original,
+        system,
+        buffer: new Float64Array(this._windowSize),
+        writeIndex: 0,
+        count: 0,
+      };
+      this._entries.push(entry);
+
+      system.update = (tick: number) => {
+        const start = performance.now();
+        original.call(system, tick);
+        const elapsed = performance.now() - start;
+        entry.buffer[entry.writeIndex % this._windowSize] = elapsed;
+        entry.writeIndex++;
+        entry.count = Math.min(entry.count + 1, this._windowSize);
+      };
+    }
+
+    // Monkey-patch simulate() to record tick start time
+    const originalSimulate = sim.simulate;
+    this._originalSimulate = originalSimulate;
+    sim.simulate = (tick: number) => {
+      this._lastSnapshotElapsed = 0; // Reset before saveSnapshot() might or might not run this tick
+      this._tickStartTime = performance.now();
+      originalSimulate.call(simulation, tick);
+      this._lastSimulateElapsed = performance.now() - this._tickStartTime;
+    };
+
+    // Monkey-patch saveSnapshot() to measure snapshot time
+    const originalSaveSnapshot = sim.saveSnapshot;
+    this._originalSaveSnapshot = originalSaveSnapshot;
+    sim.saveSnapshot = (tick: number) => {
+      const start = performance.now();
+      originalSaveSnapshot.call(simulation, tick);
+      const elapsed = performance.now() - start;
+      this._lastSnapshotElapsed = elapsed;
+      this._snapshotTimeBuffer[this._snapshotTimeWriteIndex % this._windowSize] = elapsed;
+      this._snapshotTimeWriteIndex++;
+      this._snapshotTimeCount = Math.min(this._snapshotTimeCount + 1, this._windowSize);
+    };
+
+    // Add tick handler to compute total tick time and overhead
+    this._removeTickHandler = simulation.addTickHandler(() => {
+      const elapsed = performance.now() - this._tickStartTime;
+      this._tickTimeBuffer[this._tickTimeWriteIndex % this._windowSize] = elapsed;
+      this._tickTimeWriteIndex++;
+      this._tickTimeCount = Math.min(this._tickTimeCount + 1, this._windowSize);
+
+      // Compute overhead: tickTime - simulateElapsed - snapshotElapsed
+      // Skip first tick after attach (sentinel: _lastSimulateElapsed === -1)
+      if (this._lastSimulateElapsed >= 0) {
+        const overhead = Math.max(0, elapsed - this._lastSimulateElapsed - this._lastSnapshotElapsed);
+        this._overheadTimeBuffer[this._overheadTimeWriteIndex % this._windowSize] = overhead;
+        this._overheadTimeWriteIndex++;
+        this._overheadTimeCount = Math.min(this._overheadTimeCount + 1, this._windowSize);
+      }
+    });
+  }
+
+  public detach(): void {
+    if (!this._attached) return;
+
+    // Restore per-system update methods
+    for (const entry of this._entries) {
+      entry.system.update = entry.original;
+    }
+    this._entries = [];
+
+    // Restore simulate() and saveSnapshot()
+    const sim = this._simulation as unknown as SimulationRuntime;
+    if (sim && this._originalSimulate) {
+      sim.simulate = this._originalSimulate;
+    }
+    if (sim && this._originalSaveSnapshot) {
+      sim.saveSnapshot = this._originalSaveSnapshot;
+    }
+
+    // Remove tick handler
+    if (this._removeTickHandler) {
+      this._removeTickHandler();
+      this._removeTickHandler = null;
+    }
+
+    this._originalSimulate = null;
+    this._originalSaveSnapshot = null;
+    this._simulation = null;
+    this._tickTimeWriteIndex = 0;
+    this._tickTimeCount = 0;
+    this._snapshotTimeWriteIndex = 0;
+    this._snapshotTimeCount = 0;
+    this._overheadTimeWriteIndex = 0;
+    this._overheadTimeCount = 0;
+    this._lastSimulateElapsed = -1;
+    this._lastSnapshotElapsed = 0;
+    this._attached = false;
+  }
+
+  public getStats(): PerformanceStats {
+    const systems: SystemTimingStats[] = this._entries.map((entry) => {
+      const stats = computeBufferStats(entry.buffer, entry.writeIndex, entry.count, this._windowSize);
+      return { name: entry.name, ...stats };
+    });
+
+    const tickTime = computeBufferStats(
+      this._tickTimeBuffer, this._tickTimeWriteIndex, this._tickTimeCount, this._windowSize,
+    );
+
+    const snapshotTime = computeBufferStats(
+      this._snapshotTimeBuffer, this._snapshotTimeWriteIndex, this._snapshotTimeCount, this._windowSize,
+    );
+
+    const overheadTime = computeBufferStats(
+      this._overheadTimeBuffer, this._overheadTimeWriteIndex, this._overheadTimeCount, this._windowSize,
+    );
+
+    return { tickTime, snapshotTime, overheadTime, systems };
+  }
+
+  public dispose(): void {
+    this.detach();
+  }
+}