feat: fix HeadlessClient connection + A/B benchmark PR #2 blob shadows

- Fix HeadlessClient: ignoreHTTPSErrors, CDP cert bypass, SwiftShader GL
- Patch fetch() to strip unsupported targetAddressSpace (Chrome PNA API)
- Add warmCert step for self-signed HTTPS certs
- Fix BaselineComparer: null-safe operations, nested JSON format support
- Add console log forwarding from headless browser for debugging
- A/B results: blob shadows add +1 draw call, +6.7% frame time, +0.9% triangles

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: web3dev1337

ai-memory/feature/perf-external-notes-verification-20260305-2249094/progress.md

@@ -23,3 +23,13 @@
 - [x] ConsoleReporter — rich client section (FPS, draw calls, triangles, entities, chunks, heap)
 - [x] Client thresholds — fps_min, fps_avg, draw_calls_max, triangles_max, frame_time_ms_max
 - [x] CLI — --with-client, --client-dev-url flags
+- [x] HeadlessClient fix — waitUntil 'load' instead of 'networkidle2' (game keeps persistent connections)
+- [x] BenchmarkRunner — graceful HeadlessClient error handling (try-catch around launch)
+- [x] Verified: client metrics pipeline — FPS avg=22.6, draw calls avg=11, triangles avg=22, JS heap avg=22.9MB (idle scene, no entities/chunks in headless)
+- [x] Fixed: HeadlessClient ignoreHTTPSErrors + CDP Security.setIgnoreCertificateErrors
+- [x] Fixed: Patched fetch() to strip unsupported targetAddressSpace (Chrome PNA API)
+- [x] Fixed: warmCert step to pre-accept self-signed HTTPS cert
+- [x] Fixed: Replaced --disable-gpu with --use-gl=swiftshader for WebGL rendering
+- [x] Fixed: BaselineComparer operations null-safety + loadBaseline nested format support
+- [x] A/B Benchmark PR #2 (blob shadows) — COMPLETED with real client metrics
+- [x] All pushed to origin

packages/perf-tools/perf-results/stress-baseline-no-shadows.json

@@ -0,0 +1,115 @@
+{
+  "timestamp": "2026-03-06T04:26:31.503Z",
+  "scenario": "stress-test",
+  "durationMs": 72899,
+  "baseline": {
+    "avgTickMs": 0.8349998947705856,
+    "maxTickMs": 12.012511000000814,
+    "p95TickMs": 2.072938316667266,
+    "p99TickMs": 4.238928266666274,
+    "ticksOverBudgetPct": 0,
+    "avgMemoryMb": 50.96484451293945,
+    "avgFps": 27.766666666666666,
+    "client": {
+      "avgFps": 27.766666666666666,
+      "minFps": 3,
+      "avgFrameTimeMs": 78.53666666746139,
+      "avgDrawCalls": 20.55,
+      "maxDrawCalls": 34,
+      "avgTriangles": 15433.466666666667,
+      "maxTriangles": 15947,
+      "avgGeometries": 18.983333333333334,
+      "avgEntities": 160,
+      "avgVisibleChunks": 6,
+      "avgUsedMemoryMb": 43.06479082107544
+    },
+    "operations": {
+      "entities_tick": {
+        "avgMs": 0.23867919862251075,
+        "p95Ms": 0.5874405166665383
+      },
+      "physics_step": {
+        "avgMs": 0.17312055879655402,
+        "p95Ms": 0.2684500000008484
+      },
+      "physics_cleanup": {
+        "avgMs": 0.007628609808494264,
+        "p95Ms": 0.007743966666870013
+      },
+      "simulation_step": {
+        "avgMs": 0.18813084050636156,
+        "p95Ms": 0.2958727833336828
+      },
+      "entities_emit_updates": {
+        "avgMs": 0.12927259610653663,
+        "p95Ms": 0.20604898333376695
+      },
+      "world_tick": {
+        "avgMs": 0.8291072575136396,
+        "p95Ms": 2.0896416499992787
+      },
+      "ticker_tick": {
+        "avgMs": 0.8990740486842234,
+        "p95Ms": 2.161601066666359
+      },
+      "serialize_packets": {
+        "avgMs": 0.05005582133096542,
+        "p95Ms": 0.06791426666650295
+      },
+      "send_packets": {
+        "avgMs": 0.2031820219195983,
+        "p95Ms": 0.3274495666664734
+      },
+      "send_all_packets": {
+        "avgMs": 0.4511723627023677,
+        "p95Ms": 0.9337175666661399
+      },
+      "network_synchronize_cleanup": {
+        "avgMs": 0.01083250275368758,
+        "p95Ms": 0.010753250000016123
+      },
+      "network_synchronize": {
+        "avgMs": 0.5143490774603025,
+        "p95Ms": 1.066514683332995
+      }
+    },
+    "network": {
+      "totalBytesSent": 5032278,
+      "totalBytesReceived": 381,
+      "maxConnectedPlayers": 3,
+      "avgBytesSentPerSecond": 74639.01842524527,
+      "maxBytesSentPerSecond": 112504.69959902228,
+      "avgBytesReceivedPerSecond": 5.6677308601674525,
+      "maxBytesReceivedPerSecond": 12.614810201718903,
+      "avgPacketsSentPerSecond": 82.37081361141468,
+      "maxPacketsSentPerSecond": 99.33494328345606,
+      "avgPacketsReceivedPerSecond": 1.7251234329295149,
+      "maxPacketsReceivedPerSecond": 3.881480062067355,
+      "avgSerializationMs": 0.04555379460987558,
+      "compressionCountTotal": 2
+    }
+  },
+  "phases": [
+    {
+      "name": "spawn-entities",
+      "durationMs": 283,
+      "collected": false
+    },
+    {
+      "name": "stabilize",
+      "durationMs": 2079,
+      "collected": false
+    },
+    {
+      "name": "measure",
+      "durationMs": 62049,
+      "collected": true
+    }
+  ],
+  "metrics": {
+    "tickReportCount": 0,
+    "spikeCount": 0,
+    "serverSnapshotCount": 60,
+    "clientSnapshotCount": 60
+  }
+}

packages/perf-tools/perf-results/stress-with-blob-shadows.json

@@ -0,0 +1,115 @@
+{
+  "timestamp": "2026-03-06T04:27:59.625Z",
+  "scenario": "stress-test",
+  "durationMs": 73358,
+  "baseline": {
+    "avgTickMs": 0.7359029286488398,
+    "maxTickMs": 13.290815000000293,
+    "p95TickMs": 1.829545699999653,
+    "p99TickMs": 3.758559049999955,
+    "ticksOverBudgetPct": 0,
+    "avgMemoryMb": 65.29272626241048,
+    "avgFps": 26.133333333333333,
+    "client": {
+      "avgFps": 26.133333333333333,
+      "minFps": 3,
+      "avgFrameTimeMs": 83.7683333337307,
+      "avgDrawCalls": 21.933333333333334,
+      "maxDrawCalls": 34,
+      "avgTriangles": 15564.7,
+      "maxTriangles": 16717,
+      "avgGeometries": 18.983333333333334,
+      "avgEntities": 160,
+      "avgVisibleChunks": 6,
+      "avgUsedMemoryMb": 42.87554248174032
+    },
+    "operations": {
+      "entities_tick": {
+        "avgMs": 0.23253740997715816,
+        "p95Ms": 0.6180427999991783
+      },
+      "physics_step": {
+        "avgMs": 0.17034304841306572,
+        "p95Ms": 0.28114455000083277
+      },
+      "physics_cleanup": {
+        "avgMs": 0.005363463158733647,
+        "p95Ms": 0.007633716666593197
+      },
+      "simulation_step": {
+        "avgMs": 0.18412275955659105,
+        "p95Ms": 0.31188256666694847
+      },
+      "entities_emit_updates": {
+        "avgMs": 0.13922205929656295,
+        "p95Ms": 0.22354569999891585
+      },
+      "world_tick": {
+        "avgMs": 0.7279635695853309,
+        "p95Ms": 1.7226242000005791
+      },
+      "ticker_tick": {
+        "avgMs": 0.7914679062679743,
+        "p95Ms": 1.8152888833331418
+      },
+      "serialize_packets": {
+        "avgMs": 0.04350473671018177,
+        "p95Ms": 0.06910131666694118
+      },
+      "send_packets": {
+        "avgMs": 0.2378755490273082,
+        "p95Ms": 0.3898857000008017
+      },
+      "send_all_packets": {
+        "avgMs": 0.25720112163234377,
+        "p95Ms": 0.42160113333417637
+      },
+      "network_synchronize_cleanup": {
+        "avgMs": 0.007394239075581019,
+        "p95Ms": 0.011449733333120094
+      },
+      "network_synchronize": {
+        "avgMs": 0.3093806637599563,
+        "p95Ms": 0.49408704999987096
+      }
+    },
+    "network": {
+      "totalBytesSent": 1968736,
+      "totalBytesReceived": 158,
+      "maxConnectedPlayers": 1,
+      "avgBytesSentPerSecond": 28946.035070796195,
+      "maxBytesSentPerSecond": 39833.57688983931,
+      "avgBytesReceivedPerSecond": 2.3142748083937827,
+      "maxBytesReceivedPerSecond": 6.7732385632630665,
+      "avgPacketsSentPerSecond": 31.198995516308436,
+      "maxPacketsSentPerSecond": 33.44922483163599,
+      "avgPacketsReceivedPerSecond": 0.7040805818582495,
+      "maxPacketsReceivedPerSecond": 1.9352110180751618,
+      "avgSerializationMs": 0.039125146425009125,
+      "compressionCountTotal": 0
+    }
+  },
+  "phases": [
+    {
+      "name": "spawn-entities",
+      "durationMs": 268,
+      "collected": false
+    },
+    {
+      "name": "stabilize",
+      "durationMs": 2045,
+      "collected": false
+    },
+    {
+      "name": "measure",
+      "durationMs": 62098,
+      "collected": true
+    }
+  ],
+  "metrics": {
+    "tickReportCount": 0,
+    "spikeCount": 0,
+    "serverSnapshotCount": 60,
+    "clientSnapshotCount": 60
+  }
+}

packages/perf-tools/src/runners/BaselineComparer.ts

@@ -97,10 +97,10 @@ export default class BaselineComparer {
       entries.push(this._compareMetric('net.avgSerializationMs', baseline.network.avgSerializationMs, current.network.avgSerializationMs));
     }
 
-    const allBaselineOps = new Set([...Object.keys(baseline.operations), ...Object.keys(current.operations)]);
+    const allBaselineOps = new Set([...Object.keys(baseline.operations ?? {}), ...Object.keys(current.operations ?? {})]);
 
     for (const op of allBaselineOps) {
-      if (baseline.operations[op] && current.operations[op]) {
+      if (baseline.operations?.[op] && current.operations?.[op]) {
         entries.push(this._compareMetric(`ops.${op}.avgMs`, baseline.operations[op].avgMs, current.operations[op].avgMs));
         entries.push(this._compareMetric(`ops.${op}.p95Ms`, baseline.operations[op].p95Ms, current.operations[op].p95Ms));
       }
@@ -123,8 +123,14 @@ export default class BaselineComparer {
 
   public static loadBaseline(filePath: string): BaselineResult {
     const content = fs.readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(content);
 
-    return JSON.parse(content) as BaselineResult;
+    // Support both raw baseline files and full report files (which have a .baseline field)
+    if (data.baseline && typeof data.baseline === 'object' && 'avgTickMs' in data.baseline) {
+      return data.baseline as BaselineResult;
+    }
+
+    return data as BaselineResult;
   }
 
   public static saveBaseline(filePath: string, baseline: BaselineResult): void {

packages/perf-tools/src/runners/BenchmarkRunner.ts

@@ -99,6 +99,10 @@ export default class BenchmarkRunner {
 
           await this._headlessClient.launch();
 
+          // Warm up the self-signed HTTPS cert by visiting the server URL first
+          this._log('[bench] Warming up server HTTPS cert in headless browser...');
+          await this._headlessClient.warmCert(this._options.clientUrl);
+
           // Navigate with ?join=<server host> and ?perf=1 (auto-appended by HeadlessClient)
           const serverUrl = new URL(this._options.clientUrl);
           const clientNavUrl = new URL(this._options.clientDevUrl);

packages/perf-tools/src/runners/HeadlessClient.ts

@@ -40,14 +40,18 @@ export default class HeadlessClient {
 
     this._browser = await puppeteer.default.launch({
       headless: this._options.headless ? 'new' : false,
+      ignoreHTTPSErrors: true,
       args: [
         '--no-sandbox',
         '--disable-setuid-sandbox',
-        '--disable-gpu',
         '--ignore-certificate-errors',
+        '--allow-insecure-localhost',
+        '--disable-web-security',
+        '--disable-features=PrivateNetworkAccessSendPreflights',
         '--enable-precise-memory-info',
         '--disable-notifications',
         '--autoplay-policy=no-user-gesture-required',
+        '--use-gl=swiftshader',
         `--window-size=${this._options.width},${this._options.height}`,
       ],
     });
@@ -64,11 +68,60 @@ export default class HeadlessClient {
       deviceScaleFactor: this._options.deviceScaleFactor,
     });
 
-    if (this._options.collectPerformance) {
-      const cdp = await page.createCDPSession();
+    // Forward browser console to Node stdout for debugging
+    page.on('console', (msg: any) => {
+      const type = msg.type();
+      const text = msg.text();
+
+      if (type === 'error' || type === 'warning') {
+        console.log(`[client:${type}] ${text}`);
+      }
+    });
+
+    page.on('pageerror', (err: any) => {
+      console.log(`[client:error] ${err.message ?? err}`);
+    });
+
+    const cdp = await page.createCDPSession();
 
+    // Bypass certificate errors via CDP (--ignore-certificate-errors doesn't work in headless: 'new')
+    await cdp.send('Security.setIgnoreCertificateErrors', { ignore: true });
+
+    if (this._options.collectPerformance) {
       await cdp.send('Performance.enable');
     }
+
+    // Patch fetch() to strip unsupported targetAddressSpace option
+    // (Chrome's Private Network Access API is not available in all Chrome versions)
+    await page.evaluateOnNewDocument(() => {
+      const originalFetch = window.fetch.bind(window);
+
+      (window as any).fetch = function(input: any, init?: any) {
+        if (init && 'targetAddressSpace' in init) {
+          const { targetAddressSpace: _, ...rest } = init;
+
+          return originalFetch(input, rest);
+        }
+
+        return originalFetch(input, init);
+      };
+    });
+  }
+
+  /**
+   * Visit the game server URL once to warm up the self-signed HTTPS cert
+   * in Chrome's cert cache. Without this, in-page fetch() to the server fails.
+   */
+  public async warmCert(serverUrl: string): Promise<void> {
+    const page = this._page as any;
+
+    if (!page) return;
+
+    try {
+      await page.goto(serverUrl, { waitUntil: 'load', timeout: 15000 });
+    } catch {
+      // Expected — self-signed cert page may fail but Chrome records the exception
+    }
   }
 
   public async navigate(url?: string): Promise<void> {