@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/vendor/audits/perf-gate.mjs

@@ -0,0 +1,759 @@
+#!/usr/bin/env node
+// perf-gate.mjs — the BLOCKING frame-time gate. Runs the built world in a real GPU browser,
+// plays it, and passes or fails on how long a frame took.
+//
+//   helix world perf-gate --url http://localhost:4173/?perf=1 [--seconds 20]
+//                      [--width 1440] [--height 900] [--dpr 2] [--angle metal|gl|d3d11]
+//                      [--label "night-market build 5"] [--dist dist]
+//                      [--json qa/perf-gate.json] [--no-resize-probe] [--quiet]
+//
+// WHY THIS EXISTS. QA measured frame rate for a long time and printed it as an informational
+// line. Night Market shipped at 25.5 ms p50 / 92.7 ms p95 with 26% of frames over 33 ms —
+// every gate we had passed it, because a world can run at 10 fps and still have good
+// triangle counts, a small bundle and motivated lights. Frame time is the outcome; everything
+// else on this page is a cause. It blocks now.
+//
+// MEASUREMENT DISCIPLINE, or the numbers lie:
+//   · A REAL GPU. Headless Chromium falls back to SwiftShader unless you force ANGLE, and a
+//     software rasteriser makes every number here meaningless. This script reads the unmasked
+//     renderer string and FAILS on a software renderer rather than reporting its numbers.
+//   · gl.finish() ONCE PER FRAME. WebGL draw calls are asynchronous: without a sync the CPU
+//     queues frames ahead of the GPU and requestAnimationFrame deltas measure JS cost, not the
+//     frame. Skyward read 562 fps without it. The finish() in the sampler blocks on the
+//     previous frame's GPU work, so dt is end-to-end.
+//   · vsync off. Otherwise every healthy world reports exactly the refresh rate and you cannot
+//     see headroom disappear until it is already gone.
+//   · The renderer string is printed next to the result. A frame time without the GPU that
+//     produced it is not interpretable, and it is how you notice the flags stopped working.
+//
+// WHAT IT COUNTS, and why not from the app. Draw calls, triangles, render passes, drawing-buffer
+// pixels and decoded texture bytes are counted by wrapping the WebGL context itself, so they are
+// ground truth on ANY published bundle — including one built before the `?perf=1` handle existed.
+// The light census comes from `__helixPerf.lights()` when the world ships the handle (per-light
+// names, shadow flags, map sizes), and otherwise from the light-array sizes three.js compiled
+// into its own fragment shader. Both are the running renderer. Neither is a regex over source.
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { join, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Measuring a frame requires driving a real browser. Resolve Playwright from the world first
+// so a project-level browser install is honored, then fall back to the CLI package itself.
+async function loadChromium(explicit) {
+  const roots = [explicit, process.cwd(), join(process.cwd(), 'qa', 'harness'), dirname(new URL(import.meta.url).pathname)]
+    .filter(Boolean);
+  const tried = [];
+  for (const root of roots) {
+    for (const pkg of ['playwright', 'playwright-core']) {
+      try {
+        const req = createRequire(join(root, 'package.json'));
+        // playwright is CommonJS; depending on the entry point Node may or may not surface
+        // `chromium` as a named export, so take it from the namespace or from default.
+        const mod = await import(pathToFileURL(req.resolve(pkg)).href);
+        const chromium = mod.chromium ?? mod.default?.chromium;
+        if (chromium) return chromium;
+        tried.push(`${pkg} @ ${root} (no chromium export)`);
+      } catch { tried.push(`${pkg} @ ${root}`); }
+    }
+  }
+  console.error(
+    'perf-gate: could not load playwright. Install it in the world project:\n' +
+    '  npm i -D playwright && npx playwright install chromium\n' +
+    `(looked for: ${tried.join(', ')}; --playwright <dir> overrides the search root)`,
+  );
+  process.exit(2);
+}
+
+const argv = process.argv.slice(2);
+const arg = (n, d) => { const i = argv.indexOf(`--${n}`); return i === -1 ? d : argv[i + 1]; };
+const has = (n) => argv.includes(`--${n}`);
+
+const URL_ = arg('url');
+const SECONDS = Number(arg('seconds', '20'));
+const WIDTH = Number(arg('width', '1440'));
+const HEIGHT = Number(arg('height', '900'));
+const DPR = Number(arg('dpr', '2'));
+const ANGLE = arg('angle', process.platform === 'darwin' ? 'metal' : 'gl');
+const LABEL = arg('label', URL_ ?? '');
+const DIST = arg('dist', 'dist');
+const JSON_OUT = arg('json');
+
+if (!URL_) {
+  console.error('perf-gate: --url is required — the preview URL of the BUILT world, or the play URL `helix publish` returned');
+  process.exit(2);
+}
+
+// ── THE LIMITS ──────────────────────────────────────────────────────────────────────
+// Every number here was measured on Night Market's material set, M1 Pro / ANGLE Metal,
+// 2880x1800 drawing buffer. The full curve and the ablation ladder that produced it are in
+// references/perf-budgets.md. Where a limit is NOT a frame-time lever, its message says so —
+// otherwise someone deletes texture resolution expecting milliseconds back.
+const LIMITS = {
+  frameP50Ms: 1000 / 60,          // sustained 60 fps median
+  frameP95Ms: 1000 / 30,          // never worse than 30 fps at p95
+  punctualWarn: 6,                // point + spot COMBINED
+  punctualFail: 12,               // the knee is between 12 and 16; 8 is the design target
+  shadowDirectional: 1,
+  shadowPoint: 0,                 // a shadow-casting point light renders the scene SIX times
+  shadowSpot: 1,
+  shadowMapPx: 2048,              // MEMORY limit. 512 vs 1024 measured as noise.
+  bufferPixels: 2.6e6,            // drawing-buffer pixels; the single largest lever (69%)
+  drawCalls: 300,                 // CPU submission guard for machines weaker than this one
+  triangles: 500_000,             // ditto
+  textureBytes: 256 * 1024 * 1024, // UNVALIDATED — warns, never blocks. See the message.
+};
+
+const results = [];
+const fail = (id, m) => results.push({ level: 'FAIL', id, message: m });
+const warn = (id, m) => results.push({ level: 'WARN', id, message: m });
+const info = (id, m) => results.push({ level: 'INFO', id, message: m });
+
+// A gate that ran and found nothing reads exactly like a gate that never ran. Count them apart.
+const UNMEASURED = new Set(['census.unmeasured', 'shadowmap.unmeasured', 'resize.no-response']);
+
+// ── the in-page instrument ──────────────────────────────────────────────────────────
+// Installed before any app script in every frame. Passed as a function, so nothing here is
+// double-escaped string soup.
+function instrumentInit() {
+  const P = {
+    frames: [], lights: null, programs: 0, passSizes: Object.create(null),
+    sampling: false, errors: [],
+  };
+  window.__perfGate = P;
+
+  let calls = 0, tris = 0, offCalls = 0, offTris = 0, passes = 0, offPasses = 0;
+
+  const origGetContext = HTMLCanvasElement.prototype.getContext;
+  HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+    const gl = origGetContext.call(this, type, attrs);
+    if (gl && (type === 'webgl2' || type === 'webgl') && !gl.__perfGated) {
+      gl.__perfGated = true;
+      P.canvas = this;
+      P.glType = type;
+      try {
+        const dbg = gl.getExtension('WEBGL_debug_renderer_info');
+        P.renderer = dbg ? gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER);
+        P.vendor = dbg ? gl.getParameter(dbg.UNMASKED_VENDOR_WEBGL) : gl.getParameter(gl.VENDOR);
+      } catch (e) { P.errors.push(String(e)); }
+      instrument(gl);
+    }
+    return gl;
+  };
+
+  function bppFor(gl, internalformat, type) {
+    const G = gl;
+    const m = {
+      [G.RGBA]: 4, [G.RGB]: 4, [G.LUMINANCE_ALPHA]: 2, [G.LUMINANCE]: 1, [G.ALPHA]: 1,
+      [G.RGBA8]: 4, [G.SRGB8_ALPHA8]: 4, [G.RGB8]: 4, [G.SRGB8]: 4,
+      [G.R8]: 1, [G.RG8]: 2, [G.R16F]: 2, [G.RG16F]: 4, [G.RGBA16F]: 8, [G.RGB16F]: 8,
+      [G.R32F]: 4, [G.RG32F]: 8, [G.RGBA32F]: 16, [G.RGB32F]: 16,
+      [G.R11F_G11F_B10F]: 4, [G.RGB9_E5]: 4, [G.RGB10_A2]: 4,
+      [G.DEPTH_COMPONENT16]: 2, [G.DEPTH_COMPONENT24]: 4, [G.DEPTH_COMPONENT32F]: 4,
+      [G.DEPTH24_STENCIL8]: 4, [G.DEPTH32F_STENCIL8]: 8,
+    };
+    if (m[internalformat] !== undefined) return m[internalformat];
+    if (type === G.FLOAT) return 16;
+    if (type === G.HALF_FLOAT || type === 0x8D61) return 8;
+    return 4;
+  }
+
+  function instrument(gl) {
+    const texState = new Map();
+    const bound = Object.create(null);
+    let curFB = null;
+    let curVP = [0, 0, 0, 0];
+    let lastKey = null;
+
+    // The viewport ORIGIN is part of the key: three renders all six faces of a point-light cube
+    // shadow into one atlas FBO, changing only x/y. Keying on w/h alone collapses 6 passes to 1,
+    // which is exactly the cost this gate is trying to see.
+    const key = () => (curFB ? 'fbo' : 'screen') + ':' + curVP[2] + 'x' + curVP[3] + '@' + curVP[0] + ',' + curVP[1];
+    const wrap = (name, fn) => { const o = gl[name]; if (o) gl[name] = fn(o.bind(gl)); };
+
+    wrap('bindFramebuffer', (o) => function (target, fb) { curFB = fb; return o(target, fb); });
+    wrap('viewport', (o) => function (x, y, w, h) { curVP = [x, y, w, h]; return o(x, y, w, h); });
+    wrap('bindTexture', (o) => function (target, tex) { bound[target] = tex; return o(target, tex); });
+
+    const onDraw = (mode, count, instances) => {
+      const k = key();
+      if (k !== lastKey) {
+        lastKey = k;
+        passes += 1;
+        if (curFB) offPasses += 1;
+        P.passSizes[k] = (P.passSizes[k] || 0) + 1;
+      }
+      const n = instances || 1;
+      let t = 0;
+      if (mode === gl.TRIANGLES) t = (count / 3) * n;
+      else if (mode === gl.TRIANGLE_STRIP || mode === gl.TRIANGLE_FAN) t = Math.max(0, count - 2) * n;
+      calls += 1; tris += t;
+      if (curFB) { offCalls += 1; offTris += t; }
+    };
+
+    wrap('drawElements', (o) => function (mode, count, type, off) { onDraw(mode, count, 1); return o(mode, count, type, off); });
+    wrap('drawArrays', (o) => function (mode, first, count) { onDraw(mode, count, 1); return o(mode, first, count); });
+    wrap('drawElementsInstanced', (o) => function (mode, count, type, off, ic) { onDraw(mode, count, ic); return o(mode, count, type, off, ic); });
+    wrap('drawArraysInstanced', (o) => function (mode, first, count, ic) { onDraw(mode, count, ic); return o(mode, first, count, ic); });
+    wrap('drawRangeElements', (o) => function (mode, s, e, count, type, off) { onDraw(mode, count, 1); return o(mode, s, e, count, type, off); });
+
+    const texTargetKey = (t) => (t >= 0x8515 && t <= 0x851A ? gl.TEXTURE_CUBE_MAP : t);
+    const rec = (target, level, bytes, w, h) => {
+      const tex = bound[texTargetKey(target)];
+      if (!tex) return;
+      let st = texState.get(tex);
+      if (!st) { st = { base: 0, extra: 0, mips: false, w: 0, h: 0 }; texState.set(tex, st); }
+      if (level === 0) { st.base += bytes; st.w = Math.max(st.w, w); st.h = Math.max(st.h, h); }
+      else st.extra += bytes;
+    };
+
+    wrap('texImage2D', (o) => function (target, level, internalformat, a, b, c, d, e, f) {
+      let w = 0, h = 0;
+      if (arguments.length >= 9 || typeof c === 'number') { w = a; h = b; }
+      else {
+        const src = arguments.length === 6 ? (f ?? c) : c;
+        const s = src || {};
+        w = s.width || s.videoWidth || s.naturalWidth || 0;
+        h = s.height || s.videoHeight || s.naturalHeight || 0;
+      }
+      const type = arguments.length >= 9 ? e : b;
+      rec(target, level, w * h * bppFor(gl, internalformat, type), w, h);
+      return o.apply(gl, arguments);
+    });
+    wrap('texStorage2D', (o) => function (target, levels, internalformat, w, h) {
+      const bpp = bppFor(gl, internalformat, 0);
+      let bytes = 0, ww = w, hh = h;
+      for (let i = 0; i < levels; i += 1) { bytes += ww * hh * bpp; ww = Math.max(1, ww >> 1); hh = Math.max(1, hh >> 1); }
+      rec(target, 0, bytes * (target === gl.TEXTURE_CUBE_MAP ? 6 : 1), w, h);
+      return o.apply(gl, arguments);
+    });
+    wrap('compressedTexImage2D', (o) => function (target, level, internalformat, w, h, border, data) {
+      const n = data && data.byteLength ? data.byteLength : (typeof data === 'number' ? data : 0);
+      rec(target, level, n, w, h);
+      return o.apply(gl, arguments);
+    });
+    // Without this the total counts every texture ever allocated, including ones three has
+    // already thrown away on a resize — which reads as a memory regression that is not real.
+    wrap('deleteTexture', (o) => function (tex) { if (tex) texState.delete(tex); return o.apply(gl, arguments); });
+    wrap('generateMipmap', (o) => function (target) {
+      const st = texState.get(bound[texTargetKey(target)]);
+      if (st) st.mips = true;
+      return o.apply(gl, arguments);
+    });
+
+    // three substitutes the light counts textually into the shader (no #define survives), so
+    // read the array sizes off the uniform declarations. `*ShadowMap[N]` is exactly the number
+    // of shadow-CASTING lights of that type — the renderer's own count, not ours.
+    wrap('shaderSource', (o) => function (sh, src) {
+      if (typeof src === 'string' && src.indexOf('pointLights[') >= 0) {
+        P.programs += 1;
+        const g = (decl) => {
+          const m = src.match(new RegExp(decl + '\\[\\s*(\\d+)\\s*\\]'));
+          return m ? Number(m[1]) : 0;
+        };
+        const l = {
+          dir: g('directionalLights'), point: g('pointLights'), spot: g('spotLights'),
+          hemi: g('hemisphereLights'), rectArea: g('rectAreaLights'),
+          dirShadow: g('directionalShadowMap'), pointShadow: g('pointShadowMap'), spotShadow: g('spotShadowMap'),
+        };
+        if (!P.lights || (l.point + l.dir + l.spot) > (P.lights.point + P.lights.dir + P.lights.spot)) P.lights = l;
+      }
+      return o.apply(gl, arguments);
+    });
+
+    P._gl = gl;
+    P._collectTex = () => {
+      let total = 0;
+      for (const st of texState.values()) {
+        let b = st.base + st.extra;
+        if (st.mips) b = Math.round((st.base * 4) / 3) + st.extra;
+        total += b;
+      }
+      return { total, count: texState.size };
+    };
+  }
+
+  let last = performance.now();
+  let prev = { calls: 0, tris: 0, passes: 0, offCalls: 0, offTris: 0, offPasses: 0 };
+  const tick = () => {
+    requestAnimationFrame(tick);
+    // THE LINE THAT MAKES THE NUMBER REAL. Blocks on the previous frame's GPU work, so dt is
+    // end-to-end frame time rather than how long the JS took to queue it.
+    if (P._gl) { try { P._gl.finish(); } catch (e) { /* context lost */ } }
+    const now = performance.now();
+    const dt = now - last;
+    last = now;
+    if (P.sampling) {
+      P.frames.push({
+        dt,
+        calls: calls - prev.calls, tris: tris - prev.tris,
+        passes: passes - prev.passes, offCalls: offCalls - prev.offCalls,
+        offTris: offTris - prev.offTris, offPasses: offPasses - prev.offPasses,
+      });
+    }
+    prev = { calls, tris, passes, offCalls, offTris, offPasses };
+  };
+  requestAnimationFrame(tick);
+
+  P.start = () => { P.frames.length = 0; P.sampling = true; };
+  P.stop = () => { P.sampling = false; };
+}
+
+const pct = (a, p) => {
+  if (!a.length) return 0;
+  const s = [...a].sort((x, y) => x - y);
+  return s[Math.min(s.length - 1, Math.floor(p * s.length))];
+};
+const mb = (n) => +(n / 1048576).toFixed(1);
+
+// ── run ─────────────────────────────────────────────────────────────────────────────
+const chromium = await loadChromium(arg('playwright'));
+const browser = await chromium.launch({
+  headless: true,
+  args: [
+    `--use-angle=${ANGLE}`, '--enable-gpu', '--ignore-gpu-blocklist',
+    '--disable-gpu-vsync', '--disable-frame-rate-limit',
+    '--autoplay-policy=no-user-gesture-required', '--mute-audio',
+    '--window-position=-4000,-4000',   // never steal the human's focus
+  ],
+});
+const measurement = await (async () => {
+try {
+const ctx = await browser.newContext({
+  viewport: { width: WIDTH, height: HEIGHT },
+  deviceScaleFactor: DPR,
+  ignoreHTTPSErrors: true,
+});
+await ctx.addInitScript(instrumentInit);
+const page = await ctx.newPage();
+const consoleErrors = [];
+page.on('console', (m) => { if (m.type() === 'error') consoleErrors.push(m.text().slice(0, 200)); });
+
+const tNav = Date.now();
+try {
+  await page.goto(URL_, { waitUntil: 'domcontentloaded', timeout: 90000 });
+} catch (err) {
+  // A dead preview server is the single most common way this is run wrong. Report it as a
+  // gate failure with the URL in it, not as an unhandled Playwright stack trace.
+  fail('boot.unreachable', `${URL_} did not load: ${String(err).split('\n')[0]}. Is the preview server still up? Start it and run the gate in the same shell — a server started in a previous step is often already gone.`);
+  await browser.close();
+  report(null);
+}
+
+// A published world runs inside an iframe under the player shell. Find the frame that is
+// actually rendering rather than assuming it is the top one.
+async function findFrame() {
+  let lastState = null;
+  for (let i = 0; i < 90; i += 1) {
+    for (const f of page.frames()) {
+      try {
+        const st = await f.evaluate(() => ({
+          has: !!window.__perfGate,
+          r: window.__perfGate?.renderer || null,
+          progs: window.__perfGate?.programs || 0,
+          canvases: document.querySelectorAll('canvas').length,
+        }));
+        lastState = st;
+        if (st.has && st.r && st.canvases > 0 && st.progs > 0) return f;
+      } catch { /* frame navigated mid-evaluate */ }
+    }
+    await page.waitForTimeout(1000);
+  }
+  return null;
+}
+const frame = await findFrame();
+const msToFirstRender = Date.now() - tNav;
+
+if (!frame) {
+  fail('boot.no-render', `no rendering WebGL frame appeared at ${URL_} within 90 s — nothing was measured`);
+  await browser.close();
+  report(null);
+}
+
+const rendererString = await frame.evaluate(() => window.__perfGate.renderer ?? '(unknown)');
+const vendorString = await frame.evaluate(() => window.__perfGate.vendor ?? '(unknown)');
+info('gpu.renderer', `${rendererString} / ${vendorString} · ANGLE backend requested: ${ANGLE}`);
+
+// A software rasteriser makes every frame number below meaningless. Refuse loudly rather than
+// reporting numbers that describe a CPU pretending to be a GPU.
+if (/swiftshader|llvmpipe|software|basic render/i.test(rendererString)) {
+  fail(
+    'gpu.software-rasteriser',
+    `the page is rendering on "${rendererString}" — a software rasteriser. Every frame time this script could report would be a measurement of the CPU, not the world. Fix the ANGLE flags (--angle=metal on macOS, --angle=gl elsewhere) and re-run; do NOT report these numbers.`,
+  );
+  await browser.close();
+  report(null);
+}
+
+// Let assets finish streaming and shaders compile before the window opens.
+await page.waitForTimeout(6000);
+try { await page.mouse.click(WIDTH / 2, HEIGHT / 2); } catch { /* no canvas to focus */ }
+await page.waitForTimeout(500);
+
+// PLAY IT. Short forward bursts plus a continuous yaw sweep, so the sample averages over every
+// view direction instead of one lucky angle — a world measured facing the skybox is a world
+// that has not been measured. Bursts rather than a held key so a first-person climber does not
+// simply walk off the level and profile an empty view.
+await frame.evaluate(() => window.__perfGate.start());
+const t0 = Date.now();
+let held = false;
+let mx = WIDTH / 2;
+await page.mouse.move(mx, HEIGHT / 2);
+await page.mouse.down();          // attachPointer(dragLook) — the view only turns while held
+while (Date.now() - t0 < SECONDS * 1000) {
+  const el = Date.now() - t0;
+  const wantHeld = Math.floor(el / 500) % 2 === 0;
+  if (wantHeld !== held) { held = wantHeld; await page.keyboard[held ? 'down' : 'up']('w'); }
+  mx += 26;
+  if (mx > WIDTH - 60) { await page.mouse.up(); mx = 60; await page.mouse.move(mx, HEIGHT / 2); await page.mouse.down(); }
+  await page.mouse.move(mx, HEIGHT / 2 + Math.sin(el / 2600) * 300, { steps: 2 });
+  await page.waitForTimeout(60);
+}
+await page.mouse.up();
+if (held) await page.keyboard.up('w');
+await frame.evaluate(() => window.__perfGate.stop());
+
+const out = await frame.evaluate(() => {
+  const P = window.__perfGate;
+  const H = window.__helixPerf;
+  return {
+    frames: P.frames,
+    shaderLights: P.lights,
+    passSizes: P.passSizes,
+    tex: P._collectTex ? P._collectTex() : { total: 0, count: 0 },
+    canvas: P.canvas ? { w: P.canvas.width, h: P.canvas.height, cw: P.canvas.clientWidth, ch: P.canvas.clientHeight } : null,
+    dpr: window.devicePixelRatio,
+    // The scene census, from the world's own `?perf=1` handle when it ships one.
+    census: H && typeof H.lights === 'function' ? H.lights() : null,
+    handleInfo: H && typeof H.info === 'function' ? H.info() : null,
+    pixelRatio: H?.renderer?.getPixelRatio ? H.renderer.getPixelRatio() : null,
+  };
+});
+
+// A fixed DPR cap and a derived pixel budget are indistinguishable at one window size, and the
+// difference is the whole point: a fixed cap silently becomes a cliff on a bigger window. Grow
+// the window and read the drawing buffer again.
+let resizeProbe = null;
+if (!has('no-resize-probe')) {
+  await page.setViewportSize({ width: 1920, height: 1200 });
+  await page.waitForTimeout(2500);
+  resizeProbe = await frame.evaluate(() => {
+    const P = window.__perfGate;
+    const H = window.__helixPerf;
+    return {
+      w: P.canvas?.width ?? 0,
+      h: P.canvas?.height ?? 0,
+      innerWidth: window.innerWidth,
+      innerHeight: window.innerHeight,
+      pixelRatio: H?.renderer?.getPixelRatio ? H.renderer.getPixelRatio() : null,
+    };
+  });
+}
+
+return {
+  consoleErrors,
+  msToFirstRender,
+  out,
+  rendererString,
+  resizeProbe,
+  vendorString,
+};
+} finally {
+  await browser.close();
+}
+})();
+const {
+  consoleErrors,
+  msToFirstRender,
+  out,
+  rendererString,
+  resizeProbe,
+  vendorString,
+} = measurement;
+
+// ── reduce ──────────────────────────────────────────────────────────────────────────
+const fr = out.frames.filter((x) => x.dt > 0 && x.dt < 2000);
+const warm = fr.slice(Math.floor(fr.length * 0.15));   // drop the shader-compile tail
+const dts = warm.map((x) => x.dt);
+const avg = (k) => (warm.length ? warm.reduce((a, x) => a + x[k], 0) / warm.length : 0);
+
+if (warm.length < 60) {
+  fail('sample.too-few', `only ${warm.length} usable frame samples over ${SECONDS} s — the world may not be animating. Nothing below is trustworthy.`);
+}
+
+const p50 = pct(dts, 0.5);
+const p95 = pct(dts, 0.95);
+const p99 = pct(dts, 0.99);
+const over33 = dts.filter((d) => d > 33.3).length;
+const over167 = dts.filter((d) => d > 16.7).length;
+const calls = avg('calls');
+const tris = avg('tris');
+const offPasses = avg('offPasses');
+const bufferPixels = out.canvas ? out.canvas.w * out.canvas.h : 0;
+
+// ── G-perf 1: frame time. The gate. ─────────────────────────────────────────────────
+info(
+  'frame.scenario',
+  `${WIDTH}x${HEIGHT} CSS @ DPR ${DPR} → ${out.canvas ? `${out.canvas.w}x${out.canvas.h}` : '?'} drawing buffer · ${SECONDS} s of play · ${warm.length} samples · ${msToFirstRender} ms to first render`,
+);
+info(
+  'frame.times',
+  `p50 ${p50.toFixed(2)} ms (${(1000 / p50).toFixed(1)} fps) · p95 ${p95.toFixed(2)} ms (${(1000 / p95).toFixed(1)} fps) · p99 ${p99.toFixed(2)} ms · max ${Math.max(...dts).toFixed(1)} ms · over 33 ms: ${over33}/${dts.length} (${((over33 / dts.length) * 100).toFixed(1)}%) · over 16.7 ms: ${over167}/${dts.length}`,
+);
+if (p50 > LIMITS.frameP50Ms) {
+  fail('frame.p50', `median frame is ${p50.toFixed(1)} ms (${(1000 / p50).toFixed(1)} fps); the gate is ${LIMITS.frameP50Ms.toFixed(1)} ms (60 fps sustained). This is the outcome gate — a world that fails here is slow no matter how good its triangle count is.`);
+} else {
+  info('frame.p50', `${p50.toFixed(2)} ms median — 60 fps sustained (gate ${LIMITS.frameP50Ms.toFixed(1)} ms)`);
+}
+if (p95 > LIMITS.frameP95Ms) {
+  fail('frame.p95', `p95 frame is ${p95.toFixed(1)} ms (${(1000 / p95).toFixed(1)} fps); the gate is ${LIMITS.frameP95Ms.toFixed(1)} ms (30 fps). A good median with a bad p95 is a world that stutters exactly when the player turns to look at something.`);
+} else {
+  info('frame.p95', `${p95.toFixed(2)} ms at p95 — never below 30 fps (gate ${LIMITS.frameP95Ms.toFixed(1)} ms)`);
+}
+
+// ── G-perf 2: the light census, from the running scene ──────────────────────────────
+// TWO independent readings of the same fact, and neither is a regex over source:
+//   · the compiled fragment shader — three substitutes the light-array sizes into its own GLSL,
+//     so `pointLights[N]` IS the number of lights evaluated per lit pixel. This is the cost.
+//   · the `?perf=1` scene census — walks the live scene graph and names each light, which is
+//     what turns "12 lights" into "which twelve".
+// The gate keys on the shader when it has one; the census supplies the per-light detail, the
+// shadow-caster breakdown and the map sizes. A disagreement between them is reported, not
+// averaged away — it usually means a light is in the scene but not visible.
+let punctual = null;
+let casters = null;
+let censusSource = null;
+let mapSizes = [];
+let scenePunctual = null;
+
+if (out.census) {
+  const rows = out.census;
+  const of = (t) => rows.filter((r) => r.type === t);
+  scenePunctual = of('PointLight').length + of('SpotLight').length;
+  casters = {
+    directional: of('DirectionalLight').filter((r) => r.castShadow).length,
+    point: of('PointLight').filter((r) => r.castShadow).length,
+    spot: of('SpotLight').filter((r) => r.castShadow).length,
+  };
+  mapSizes = rows.filter((r) => r.castShadow && r.mapSize).map((r) => ({ name: `${r.type} "${r.name}"`, w: r.mapSize[0], h: r.mapSize[1] }));
+  const byType = {};
+  for (const r of rows) byType[r.type] = (byType[r.type] ?? 0) + 1;
+  info('census.scene', `${Object.entries(byType).map(([t, n]) => `${t}x${n}`).join(' · ')} — counted by walking the LIVE scene graph via ?perf=1, not by grepping source`);
+  const declaredPasses = rows.reduce((a, r) => a + (r.passesPerFrame ?? 0), 0);
+  info('census.shadow-passes', `${declaredPasses} shadow pass(es)/frame declared by the census · ${offPasses.toFixed(2)} offscreen pass(es)/frame measured at the GL level`);
+}
+
+if (out.shaderLights) {
+  const l = out.shaderLights;
+  censusSource = 'compiled fragment shader';
+  punctual = l.point + l.spot;
+  if (!casters) casters = { directional: l.dirShadow, point: l.pointShadow, spot: l.spotShadow };
+  info(
+    'census.shader',
+    `${l.dir} directional + ${l.point} point + ${l.spot} spot + ${l.hemi} hemisphere${l.rectArea ? ` + ${l.rectArea} rectArea` : ''} — read out of the light arrays three.js compiled into its own fragment shader. This is the number evaluated for every lit pixel.`,
+  );
+  if (scenePunctual != null && scenePunctual !== punctual) {
+    info('census.disagreement', `the scene graph holds ${scenePunctual} punctual light(s) but the shader compiled ${punctual}. A light that is not visible, or is parented outside the rendered scene, is in the census and not in the shader. The gate uses the shader count, because that is what costs.`);
+  }
+  if (!mapSizes.length) {
+    // Shadow-map SIZE is the one thing only the handle can tell us. It is tempting to infer it
+    // from the offscreen pass viewports, and that inference is wrong: the largest offscreen
+    // viewport in a typical world is the main render target, not a shadow map, so the guess
+    // fails a correct world on its own screen resolution. A proxy that confident and that wrong
+    // is exactly what this gate replaced. Report the sizes as context and call the gate
+    // unmeasured.
+    const dims = [...new Set(Object.keys(out.passSizes ?? {})
+      .filter((k) => k.startsWith('fbo:'))
+      .map((k) => /fbo:(\d+)x(\d+)/.exec(k))
+      .filter(Boolean)
+      .map((m) => `${m[1]}x${m[2]}`))];
+    warn(
+      'shadowmap.unmeasured',
+      `shadow-map size was NOT measured: it needs the ?perf=1 handle, which this bundle does not ship. Offscreen render passes observed at ${dims.join(', ') || '(none)'} — that list mixes shadow maps with the main render target and any other target, so no size gate can be read off it.`,
+    );
+  }
+} else if (scenePunctual != null) {
+  censusSource = '?perf=1 scene census';
+  punctual = scenePunctual;
+  warn('census.no-shader', 'no lit three.js shader was compiled during the run, so the per-pixel light count could not be read from the renderer. Falling back to the scene census, which counts lights that may not be visible.');
+} else {
+  fail(
+    'census.unmeasured',
+    'no light census: the world exposes no `?perf=1` handle AND no three.js lit shader was compiled. The punctual-light and shadow-caster gates measured NOTHING — that is a failure, not a pass. Ship the perf handle (references/perf-handle.md).',
+  );
+}
+
+if (punctual !== null) {
+  if (punctual > LIMITS.punctualFail) {
+    fail(
+      'lights.punctual',
+      `${punctual} punctual lights (point + spot) in the live scene; the ceiling is ${LIMITS.punctualFail}. three.js has NO light culling — every light is evaluated for every lit pixel, and the cost goes vertical between 12 and 16 lights: ~0.45 ms per light at 8, ~0.75 ms at 12, 6.1 ms at 20, 9.6 ms at 24. The 21st light costs 13x the 4th. Design target is 8. The fix is not "delete lanterns" — it is a fixed light pool plus instanced additive ground decals; see references/perf-budgets.md.`,
+    );
+  } else if (punctual > LIMITS.punctualWarn) {
+    warn(
+      'lights.punctual',
+      `${punctual} punctual lights (point + spot); design target is ${LIMITS.punctualWarn}-8, hard ceiling ${LIMITS.punctualFail}. You are inside the linear part of the curve but spending the headroom that covers GPUs weaker than the one this was measured on.`,
+    );
+  } else {
+    info('lights.punctual', `${punctual} punctual light(s) (point + spot) — within the ${LIMITS.punctualWarn} design target [${censusSource}]`);
+  }
+}
+
+if (casters) {
+  info('lights.shadow-casters', `${casters.directional} directional · ${casters.point} point · ${casters.spot} spot cast shadows [${censusSource}]`);
+  if (casters.point > LIMITS.shadowPoint) {
+    fail(
+      'shadow.point-caster',
+      `${casters.point} shadow-casting POINT light(s). three renders the whole scene SIX times per frame for each one, one per cube face — on Skyward a single brazier flame was 85 of 141 draw calls and 233k of 424k triangles for a shadow no player could read. Allowed: ${LIMITS.shadowPoint}.`,
+    );
+  }
+  if (casters.spot > LIMITS.shadowSpot) {
+    fail('shadow.spot-caster', `${casters.spot} shadow-casting spot lights; allowed ${LIMITS.shadowSpot}.`);
+  }
+  if (casters.directional > LIMITS.shadowDirectional) {
+    fail('shadow.directional-caster', `${casters.directional} shadow-casting directional lights; allowed ${LIMITS.shadowDirectional}. One key light carries the shape read.`);
+  }
+}
+
+// Shadow map size — a MEMORY limit. Stated as such so nobody shrinks it expecting frames.
+const worstMap = mapSizes.reduce((a, r) => (Math.max(r.w, r.h) > Math.max(a?.w ?? 0, a?.h ?? 0) ? r : a), null);
+if (worstMap) {
+  const d = Math.max(worstMap.w, worstMap.h);
+  const detail = mapSizes.map((r) => `${r.name} ${r.w}x${r.h}`).join(' · ');
+  if (d > LIMITS.shadowMapPx) {
+    fail('shadow.map-size', `largest shadow map is ${worstMap.w}x${worstMap.h} (limit ${LIMITS.shadowMapPx}). THIS IS A MEMORY LIMIT, NOT A TIME LIMIT — 512 vs 1024 measured as noise on the frame. Shrinking it returns megabytes, not milliseconds. ${detail}`);
+  } else if (d > 1024) {
+    info('shadow.map-size', `largest shadow map ${worstMap.w}x${worstMap.h} — under the ${LIMITS.shadowMapPx} memory limit; 1024 is the recommended size. Not a frame-time lever: 512 vs 1024 measured as noise. ${detail}`);
+  } else {
+    info('shadow.map-size', `largest shadow map ${worstMap.w}x${worstMap.h} — at or under the recommended 1024 (a MEMORY limit, not a time limit). ${detail}`);
+  }
+}
+
+// ── G-perf 3: resolution — the single largest lever ─────────────────────────────────
+info('resolution.buffer', `${bufferPixels.toLocaleString()} drawing-buffer pixels${out.pixelRatio ? ` at renderer pixel ratio ${out.pixelRatio}` : ''} (budget ${LIMITS.bufferPixels.toLocaleString()})`);
+if (bufferPixels > LIMITS.bufferPixels) {
+  fail(
+    'resolution.over-budget',
+    `${bufferPixels.toLocaleString()} drawing-buffer pixels exceeds the ${LIMITS.bufferPixels.toLocaleString()} budget. Resolution is a multiplier over every per-pixel cost in the world and was the largest single lever measured (69%). Pick the LARGEST pixel ratio (<=2, >=1) that keeps width*height*ratio^2 under budget — a derived ratio, never a fixed DPR cap.`,
+  );
+}
+if (resizeProbe) {
+  const grown = resizeProbe.w * resizeProbe.h;
+  const ratioNote = out.pixelRatio && resizeProbe.pixelRatio
+    ? ` (renderer pixel ratio ${out.pixelRatio.toFixed(3)} → ${resizeProbe.pixelRatio.toFixed(3)})`
+    : '';
+  if (resizeProbe.innerWidth === WIDTH) {
+    warn(
+      'resize.no-response',
+      `the page grew to 1920x1200 but the world still reports innerWidth ${resizeProbe.innerWidth} — it is running inside a shell iframe that did not grow with the page, so the fixed-cap check measured NOTHING. Run it against the local preview build, where the world owns the whole viewport.`,
+    );
+  } else if (grown > LIMITS.bufferPixels && bufferPixels <= LIMITS.bufferPixels) {
+    fail(
+      'resolution.fixed-cap',
+      `the drawing buffer is ${bufferPixels.toLocaleString()} px at 1440x900 (in budget) but ${grown.toLocaleString()} px at 1920x1200 (over the ${LIMITS.bufferPixels.toLocaleString()} budget)${ratioNote}. That is the signature of a FIXED DPR cap: it passes on the window you tested and falls off a cliff on a bigger one. Derive the ratio from the pixel budget instead.`,
+    );
+  } else if (grown > LIMITS.bufferPixels) {
+    info('resolution.grows', `at 1920x1200 the drawing buffer is ${grown.toLocaleString()} px — over budget, as it already is at 1440x900 (see resolution.over-budget above).`);
+  } else {
+    // A budget-derived ratio produces the SAME pixel count on any window at or above the budget:
+    // the ratio drops as the window grows. An unchanged buffer with a changed window is the
+    // signature of a correct derivation, not of an ignored resize — an earlier version of this
+    // check read it as "no response" and reported the right answer as unmeasured.
+    info(
+      'resolution.derived',
+      `window grown to 1920x1200 → ${resizeProbe.w}x${resizeProbe.h} = ${grown.toLocaleString()} drawing-buffer pixels, still within the ${LIMITS.bufferPixels.toLocaleString()} budget${ratioNote}. The ratio is derived from the budget, not capped at a constant.`,
+    );
+  }
+}
+
+// ── G-perf 4: CPU submission guards ─────────────────────────────────────────────────
+// DELIBERATELY GENEROUS, and not the thing that matters. Night Market measured 418 calls and
+// 778k triangles per frame COSTING NOTHING on this machine — freezing the shadow maps removed
+// 392 calls and 728k triangles and made it zero milliseconds faster. These guard CPU submission
+// cost on machines weaker than an M1 Pro. Do not go hunting draw calls to fix a frame time.
+info('submission.counters', `${calls.toFixed(1)} draw calls/frame · ${Math.round(tris).toLocaleString()} triangles/frame · ${offPasses.toFixed(2)} offscreen passes/frame`);
+if (calls > LIMITS.drawCalls) {
+  fail('submission.draw-calls', `${calls.toFixed(1)} draw calls/frame exceeds ${LIMITS.drawCalls}. This is a CPU-SUBMISSION guard for weaker machines, not a frame-time cause here: 418 calls/frame measured as costing nothing on an M1 Pro. Fix it by merging geometry or deleting shadow passes, and do not expect milliseconds back on this hardware.`);
+}
+if (tris > LIMITS.triangles) {
+  fail('submission.triangles', `${Math.round(tris).toLocaleString()} triangles/frame exceeds ${LIMITS.triangles.toLocaleString()}. Same category as draw calls: a guard for weaker GPUs. 778k triangles/frame measured as costing nothing here.`);
+}
+
+// ── G-perf 5: decoded texture memory — UNVALIDATED, and therefore NON-BLOCKING ──────
+// This is the one budget on this page that no measurement supports. Decoded texture bytes were
+// never observed to cost frame time on unified-memory Apple silicon; Skyward carries ~250 MB at
+// 526 fps. It is a memory-pressure precaution on a shared-memory machine, not a diagnosis.
+//
+// It warns rather than blocks, deliberately. A blocking gate on an unvalidated number teaches an
+// agent to delete texture resolution chasing frames it will not get — the same mistake as
+// "optimising" a shadow map, and the exact confusion between causes and outcomes that let two
+// worlds ship at 39 fps with every gate green. It becomes blocking the day someone measures
+// texture memory costing a frame, and not before.
+if (out.tex.total > LIMITS.textureBytes) {
+  warn(
+    'memory.textures',
+    `${mb(out.tex.total)} MB of decoded texture memory across ${out.tex.count} texture(s), over the ${mb(LIMITS.textureBytes)} MB budget. UNVALIDATED — this number is a precaution, not a measurement, so it warns and does not block: no run has shown decoded texture bytes costing frame time on unified memory. Treat it as "reduce the texture footprint on a 16 GB machine", NEVER as "this is why the world is slow". (It also moves ~18% run to run on the same bundle, which is another reason not to gate on it.)`,
+  );
+} else {
+  info('memory.textures', `${mb(out.tex.total)} MB decoded across ${out.tex.count} texture(s) — under the ${mb(LIMITS.textureBytes)} MB precaution (UNVALIDATED: never observed to cost frame time here)`);
+}
+
+if (consoleErrors.length) warn('console.errors', `${consoleErrors.length} console error(s) during the run — first: ${consoleErrors[0]}`);
+
+report({
+  label: LABEL,
+  url: URL_,
+  renderer: rendererString,
+  vendor: vendorString,
+  angle: ANGLE,
+  scenario: { width: WIDTH, height: HEIGHT, dpr: DPR, seconds: SECONDS, samples: warm.length },
+  msToFirstRender,
+  frame: {
+    p50, p95, p99, max: Math.max(...dts),
+    fps_p50: 1000 / p50, fps_p95: 1000 / p95,
+    over33, over167, total: dts.length,
+  },
+  lights: { punctual, scenePunctual, casters, source: censusSource, mapSizes, shader: out.shaderLights },
+  drawingBufferPixels: bufferPixels,
+  resizeProbe,
+  drawCalls: calls,
+  triangles: tris,
+  offscreenPasses: offPasses,
+  textureBytes: out.tex.total,
+  textureCount: out.tex.count,
+});
+
+// ── report ──────────────────────────────────────────────────────────────────────────
+function report(metrics) {
+  const failures = results.filter((r) => r.level === 'FAIL');
+  const unmeasured = results.filter((r) => UNMEASURED.has(r.id));
+
+  if (!has('quiet')) {
+    for (const r of results) console.log(`${r.level.padEnd(4)} ${r.id.padEnd(28)} ${r.message}`);
+    console.log('');
+    console.log(`perf-gate: ${LABEL}`);
+    console.log(`  GPU: ${metrics?.renderer ?? '(not reached)'}`);
+    const suffix = unmeasured.length ? ` (${unmeasured.length} gate(s) measured NOTHING: ${unmeasured.map((r) => r.id).join(', ')})` : '';
+    console.log(failures.length ? `  ${failures.length} BLOCKING failure(s)${suffix}` : `  pass${suffix}`);
+  }
+
+  if (JSON_OUT) {
+    // Bind the run to the exact bundle it measured, so live proof can refuse evidence from a
+    // different build.
+    let entrySha = null;
+    const entry = join(DIST, 'index.html');
+    if (existsSync(entry)) entrySha = createHash('sha256').update(readFileSync(entry)).digest('hex');
+    mkdirSync(dirname(JSON_OUT), { recursive: true });
+    writeFileSync(
+      JSON_OUT,
+      JSON.stringify({
+        tool: 'perf-gate', version: 1, measuredAt: new Date().toISOString(),
+        dist: DIST, entrySha256: entrySha,
+        failed: failures.length, unmeasured: unmeasured.map((r) => r.id),
+        limits: LIMITS, metrics, results,
+      }, null, 2),
+    );
+  }
+  process.exit(failures.length ? 1 : 0);
+}