@rydr/game-sdk 1.16.0 → 1.17.0

package/dist/three/perf-marks.js

@@ -0,0 +1,86 @@
+/**
+ * perf-marks — lightweight timing instrumentation, shared so any rydr game's
+ * marks feed the same {@link PerfOverlay} panel.
+ *
+ * Toggle with `window.__PERF__ = true` (or `?perf=1`, handled by the overlay).
+ * When disabled every call is a cheap no-op, so it is safe to sprinkle through
+ * hot-path code.
+ *
+ * Usage:
+ * ```ts
+ *   perfMark('frame.update');    // start a region
+ *   … work …
+ *   perfMeasure('frame.update'); // end the region, record elapsed ms
+ *   window.__perfReport();       // { label: { avg, max, n } }
+ * ```
+ *
+ * Browser-only (uses `performance.now()` + `window`). Part of the optional
+ * `@rydr/game-sdk/three` entry point.
+ */
+const SAMPLES = 60;
+const marks = new Map();
+const histories = new Map();
+function enabled() {
+    return typeof window !== "undefined" && window.__PERF__ === true;
+}
+/** Start a timing region under `label`. No-op unless `window.__PERF__` is set. */
+export function perfMark(label) {
+    if (!enabled())
+        return;
+    marks.set(label, performance.now());
+}
+/**
+ * End the region opened by `perfMark(label)` and push the elapsed ms into a
+ * rolling ring buffer. No-op if no matching mark or perf is disabled.
+ */
+export function perfMeasure(label) {
+    if (!enabled())
+        return;
+    const start = marks.get(label);
+    if (start == null)
+        return;
+    const ms = performance.now() - start;
+    let hist = histories.get(label);
+    if (!hist) {
+        hist = [];
+        histories.set(label, hist);
+    }
+    hist.push(ms);
+    if (hist.length > SAMPLES)
+        hist.shift();
+}
+/** Snapshot every recorded label as `{ avg, max, n }`. null when perf is off. */
+export function perfReport() {
+    if (!enabled())
+        return null;
+    const out = {};
+    for (const [label, hist] of histories) {
+        if (!hist.length)
+            continue;
+        const avg = hist.reduce((a, b) => a + b, 0) / hist.length;
+        const max = Math.max(...hist);
+        out[label] = { avg: +avg.toFixed(2), max: +max.toFixed(2), n: hist.length };
+    }
+    return out;
+}
+/**
+ * Rolling average for a label, WITHOUT the `__PERF__` guard — the overlay reads
+ * these to render its phase breakdown regardless of global logging state.
+ */
+export function perfAvg(label) {
+    const hist = histories.get(label);
+    if (!hist || !hist.length)
+        return 0;
+    return hist.reduce((a, b) => a + b, 0) / hist.length;
+}
+/** Rolling peak for a label. Same no-guard rule as {@link perfAvg}. */
+export function perfPeak(label) {
+    const hist = histories.get(label);
+    if (!hist || !hist.length)
+        return 0;
+    return Math.max(...hist);
+}
+if (typeof window !== "undefined") {
+    window.__perfReport = perfReport;
+}
+//# sourceMappingURL=perf-marks.js.map

package/dist/three/perf-marks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-marks.js","sourceRoot":"","sources":["../../src/three/perf-marks.ts"],"names":[],"mappings":"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"}

package/dist/three/perf-overlay.d.ts

@@ -0,0 +1,104 @@
+/**
+ * perf-overlay — a shared, collapsible Three.js performance HUD for every rydr
+ * game. Shows FPS / CPU / GPU (via WebGL2 timer queries) / `renderer.info`, a
+ * `perfMark` phase breakdown, live entity counters, a copy-report button, and a
+ * generic draw-call audit. Default-off; zero cost when disabled.
+ *
+ * This is the SDK's first browser-UI module (the core protocol/client stay
+ * isomorphic). It is intentionally **self-contained**: it injects nothing
+ * global, depends on no CSS variables, and builds its own top-right overlay
+ * stack — so any Three.js game gets the panel by constructing it.
+ *
+ * Core is generic; each game extends it through a plain options object
+ * ({@link PerfOverlayOptions}) — `counters`, `phases`, `buttons`, `scene` — no
+ * formal capability interface (the surface is too small to warrant one).
+ *
+ * Enable: `?perf=1` on the page (or parent frame, for iframed games) or
+ * `window.__PERF__ = true`. Toggle the panel with the backtick key.
+ *
+ * Per-frame call order (mirrors a typical render loop):
+ * ```ts
+ *   perf.frameStart();
+ *   update();
+ *   perf.gpuBegin();  render();  perf.gpuEnd();
+ *   perf.frameEnd(dtSeconds);
+ * ```
+ */
+import type * as THREE from "three";
+/** Per-game extension surface — all optional. */
+export interface PerfOverlayOptions {
+    /** Scene to drive the generic "Audit draw calls" button. Omit to hide it. */
+    scene?: THREE.Object3D;
+    /** Live entity counts → rendered as panel rows (e.g. `{ enemies, projectiles }`). */
+    counters?: () => Record<string, number>;
+    /** `perfMark` labels to surface as an avg/max breakdown (e.g. `['update','render']`). */
+    phases?: string[];
+    /** Extra action buttons (e.g. a renderer-specific "Toggle bloom"). */
+    buttons?: PerfButtonSpec[];
+    /** Pixel offset of the overlay stack from the top-right corner. Default
+     *  `{ top: 8, right: 8 }`. Raise `right` to clear other top-right chrome
+     *  (e.g. a host hamburger menu). */
+    offset?: {
+        top?: number;
+        right?: number;
+    };
+}
+/** A custom panel button. */
+export interface PerfButtonSpec {
+    label: string;
+    /** CSS background tint; defaults to the neutral blue. */
+    color?: string;
+    onClick: () => void;
+}
+/**
+ * Bucket a scene's renderable objects (≈ draw calls) by top-level child, plus a
+ * material/geometry composition of the biggest bucket. Renderer-agnostic — the
+ * same audit the tower-defense game used, generalized over any `scene`.
+ */
+export declare function auditScene(scene: THREE.Object3D): string;
+/**
+ * The performance overlay. Construct once with the canvas host + renderer, drive
+ * it from the render loop, and pass game specifics via {@link PerfOverlayOptions}.
+ */
+export declare class PerfOverlay {
+    private readonly renderer;
+    private readonly opts;
+    private readonly gl;
+    private readonly ext;
+    private readonly fps;
+    private readonly frameMs;
+    private readonly cpuMs;
+    private readonly gpuMs;
+    private prevFrameTime;
+    private cpuStart;
+    private readonly gpuPool;
+    private readonly gpuPending;
+    private gpuCurrent;
+    private lastInfo;
+    private domTick;
+    private readonly DOM_INTERVAL;
+    private visible;
+    private readonly stack;
+    private readonly pill;
+    private readonly panel;
+    private readonly pre;
+    private readonly reportOut;
+    private readonly onKey;
+    constructor(host: HTMLElement, renderer: THREE.WebGLRenderer, opts?: PerfOverlayOptions);
+    frameStart(): void;
+    gpuBegin(): void;
+    gpuEnd(): void;
+    /** End of frame. `dt` is seconds since last frame (drives the DOM throttle). */
+    frameEnd(dt: number): void;
+    toggle(): void;
+    destroy(): void;
+    private applyVisibility;
+    private makeButton;
+    private buildButtons;
+    private dumpReport;
+    private initGpuExt;
+    private pollGpu;
+    private updatePill;
+    private updateDom;
+}
+//# sourceMappingURL=perf-overlay.d.ts.map

package/dist/three/perf-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-overlay.d.ts","sourceRoot":"","sources":["../../src/three/perf-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B;;wCAEoC;IACpC,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA6DD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CA6FxD;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiD;IACpE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;IAEnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IAEtC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAK;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,UAAU,CAA2B;IAE7C,OAAO,CAAC,QAAQ,CAAkF;IAElG,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;gBAEvC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,aAAa,EAAE,IAAI,GAAE,kBAAuB;IA2E3F,UAAU,IAAI,IAAI;IAWlB,QAAQ,IAAI,IAAI;IAShB,MAAM,IAAI,IAAI;IAQd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAsB1B,MAAM,IAAI,IAAI;IAMd,OAAO,IAAI,IAAI;IAgBf,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,YAAY;IAuBpB,OAAO,CAAC,UAAU;IA0BlB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,SAAS;CA6BlB"}

package/dist/three/perf-overlay.js

@@ -0,0 +1,446 @@
+/**
+ * perf-overlay — a shared, collapsible Three.js performance HUD for every rydr
+ * game. Shows FPS / CPU / GPU (via WebGL2 timer queries) / `renderer.info`, a
+ * `perfMark` phase breakdown, live entity counters, a copy-report button, and a
+ * generic draw-call audit. Default-off; zero cost when disabled.
+ *
+ * This is the SDK's first browser-UI module (the core protocol/client stay
+ * isomorphic). It is intentionally **self-contained**: it injects nothing
+ * global, depends on no CSS variables, and builds its own top-right overlay
+ * stack — so any Three.js game gets the panel by constructing it.
+ *
+ * Core is generic; each game extends it through a plain options object
+ * ({@link PerfOverlayOptions}) — `counters`, `phases`, `buttons`, `scene` — no
+ * formal capability interface (the surface is too small to warrant one).
+ *
+ * Enable: `?perf=1` on the page (or parent frame, for iframed games) or
+ * `window.__PERF__ = true`. Toggle the panel with the backtick key.
+ *
+ * Per-frame call order (mirrors a typical render loop):
+ * ```ts
+ *   perf.frameStart();
+ *   update();
+ *   perf.gpuBegin();  render();  perf.gpuEnd();
+ *   perf.frameEnd(dtSeconds);
+ * ```
+ */
+import { perfReport, perfAvg, perfPeak } from "./perf-marks.js";
+// ── Ring buffer (Float32) ──────────────────────────────────────
+class Ring {
+    buf;
+    i = 0;
+    n = 0;
+    constructor(len) {
+        this.buf = new Float32Array(len);
+    }
+    push(v) {
+        this.buf[this.i % this.buf.length] = v;
+        this.i++;
+        if (this.n < this.buf.length)
+            this.n++;
+    }
+    avg() {
+        if (!this.n)
+            return 0;
+        let s = 0;
+        for (let i = 0; i < this.n; i++)
+            s += this.buf[i];
+        return s / this.n;
+    }
+    max() {
+        if (!this.n)
+            return 0;
+        let m = 0;
+        for (let i = 0; i < this.n; i++)
+            if (this.buf[i] > m)
+                m = this.buf[i];
+        return m;
+    }
+    min() {
+        if (!this.n)
+            return 0;
+        let m = Infinity;
+        for (let i = 0; i < this.n; i++)
+            if (this.buf[i] < m)
+                m = this.buf[i];
+        return m === Infinity ? 0 : m;
+    }
+}
+// ── Formatting helpers ─────────────────────────────────────────
+const f1 = (v, w = 5) => v.toFixed(1).padStart(w);
+const f0 = (v, w = 4) => Math.round(v).toString().padStart(w);
+function kFmt(v, w = 6) {
+    if (v >= 10000)
+        return ((v / 1000).toFixed(0) + "k").padStart(w);
+    if (v >= 1000)
+        return ((v / 1000).toFixed(1) + "k").padStart(w);
+    return Math.round(v).toString().padStart(w);
+}
+const MONO = "11px/1.6 ui-monospace, 'SF Mono', Menlo, Consolas, monospace";
+/**
+ * Bucket a scene's renderable objects (≈ draw calls) by top-level child, plus a
+ * material/geometry composition of the biggest bucket. Renderer-agnostic — the
+ * same audit the tower-defense game used, generalized over any `scene`.
+ */
+export function auditScene(scene) {
+    const isRenderable = (o) => o.isMesh === true || o.isLine === true || o.isPoints === true || o.isSprite === true;
+    const buckets = [];
+    let total = 0;
+    for (const child of scene.children) {
+        let visible = 0;
+        let hidden = 0;
+        child.traverse((o) => {
+            if (!isRenderable(o))
+                return;
+            if (o.visible && child.visible)
+                visible++;
+            else
+                hidden++;
+        });
+        if (visible + hidden === 0)
+            continue;
+        total += visible;
+        buckets.push({ name: child.name || child.type || "unnamed", visible, hidden });
+    }
+    buckets.sort((a, b) => b.visible - a.visible);
+    const lines = buckets.map((b) => `${b.name.slice(0, 22).padEnd(22)} ${String(b.visible).padStart(5)} vis  ${String(b.hidden).padStart(5)} hidden`);
+    // Composition of the biggest bucket: unique geometries vs. materials, and the
+    // most-repeated geometry+material pair (merge-by-material vs. instancing cue).
+    const top = buckets[0];
+    let detail = "";
+    if (top) {
+        const topChild = scene.children.find((c) => (c.name || c.type || "unnamed") === top.name);
+        if (topChild) {
+            const geos = new Set();
+            const matInfo = new Map();
+            const pairCounts = new Map();
+            topChild.traverse((o) => {
+                const m = o;
+                if (!m.isMesh || !o.visible || !m.geometry)
+                    return;
+                geos.add(m.geometry.uuid);
+                const matList = Array.isArray(m.material) ? m.material : m.material ? [m.material] : [];
+                for (const mm of matList) {
+                    const entry = matInfo.get(mm.uuid);
+                    if (entry)
+                        entry.count++;
+                    else
+                        matInfo.set(mm.uuid, { mat: mm, count: 1 });
+                }
+                const pairKey = `${m.geometry.uuid}|${matList.map((mm) => mm.uuid).join("+")}`;
+                pairCounts.set(pairKey, (pairCounts.get(pairKey) ?? 0) + 1);
+            });
+            let maxRepeat = 0;
+            for (const n of pairCounts.values())
+                if (n > maxRepeat)
+                    maxRepeat = n;
+            const describe = (mat) => {
+                const color = mat.color ? "#" + mat.color.getHexString() : "—";
+                const maps = [];
+                if (mat.map)
+                    maps.push("map");
+                if (mat.normalMap)
+                    maps.push("normal");
+                if (mat.emissive && mat.emissiveMap)
+                    maps.push("emissiveMap");
+                if (mat.emissive && mat.emissive.getHex() !== 0)
+                    maps.push("emissive");
+                if (mat.transparent)
+                    maps.push("transparent");
+                const name = mat.name || "(unnamed)";
+                return `${name.slice(0, 18).padEnd(18)} ${(mat.type ?? "").replace("Material", "").slice(0, 10).padEnd(10)} ${color}  ${maps.join(",") || "flat"}`;
+            };
+            const matLines = [...matInfo.values()]
+                .sort((a, b) => b.count - a.count)
+                .map((e) => `   ${String(e.count).padStart(5)}×  ${describe(e.mat)}`);
+            detail =
+                `[${top.name}] composition:\n` +
+                    `  unique geometries: ${geos.size}\n` +
+                    `  unique materials:  ${matInfo.size}\n` +
+                    `  most-repeated geo+mat pair: ${maxRepeat}×\n` +
+                    `  materials (count × name / type / color / maps):\n` +
+                    matLines.join("\n") +
+                    `\n\n`;
+        }
+    }
+    return detail + `~${total} visible draw calls (scene.children = ${scene.children.length})\n` + lines.join("\n");
+}
+/**
+ * The performance overlay. Construct once with the canvas host + renderer, drive
+ * it from the render loop, and pass game specifics via {@link PerfOverlayOptions}.
+ */
+export class PerfOverlay {
+    renderer;
+    opts;
+    gl;
+    ext;
+    fps = new Ring(60);
+    frameMs = new Ring(60);
+    cpuMs = new Ring(60);
+    gpuMs = new Ring(30);
+    prevFrameTime = 0;
+    cpuStart = 0;
+    gpuPool = [];
+    gpuPending = [];
+    gpuCurrent = null;
+    lastInfo = { calls: 0, tris: 0, lines: 0, geos: 0, texs: 0, prgs: 0 };
+    domTick = 0;
+    DOM_INTERVAL = 1 / 8; // 8 Hz — 60 Hz numbers are unreadable
+    visible;
+    stack;
+    pill;
+    panel;
+    pre;
+    reportOut;
+    onKey;
+    constructor(host, renderer, opts = {}) {
+        this.renderer = renderer;
+        this.opts = opts;
+        this.gl = renderer.getContext();
+        this.ext = this.initGpuExt();
+        // Visibility: `?perf=1` on this frame OR the parent (games run iframed),
+        // or `window.__PERF__`. Showing the panel enables sampling.
+        let parentSearch = "";
+        try {
+            if (window.parent !== window)
+                parentSearch = window.parent.location.search;
+        }
+        catch {
+            /* cross-origin parent — ignore */
+        }
+        const urlFlag = new URLSearchParams(location.search).get("perf") === "1" ||
+            new URLSearchParams(parentSearch).get("perf") === "1";
+        this.visible = urlFlag || window.__PERF__ === true;
+        if (this.visible)
+            window.__PERF__ = true;
+        // ── Self-contained top-right overlay stack ──
+        const offTop = opts.offset?.top ?? 8;
+        const offRight = opts.offset?.right ?? 8;
+        this.stack = document.createElement("div");
+        this.stack.style.cssText = `
+      position: absolute; top: ${offTop}px; right: ${offRight}px; z-index: 99999;
+      display: flex; flex-direction: column; align-items: flex-end; gap: 6px;
+      pointer-events: none;`;
+        host.appendChild(this.stack);
+        this.pill = this.makeButton("PERF", "rgba(7,9,20,0.82)");
+        this.pill.addEventListener("click", () => this.toggle());
+        this.stack.appendChild(this.pill);
+        this.panel = document.createElement("div");
+        this.panel.style.cssText = `
+      background: rgba(7,9,20,0.90);
+      border: 1px solid rgba(255,255,255,0.12);
+      backdrop-filter: blur(10px); -webkit-backdrop-filter: blur(10px);
+      border-radius: 5px; padding: 8px 11px 7px;
+      pointer-events: auto; user-select: none;`;
+        this.stack.appendChild(this.panel);
+        const titleRow = document.createElement("div");
+        titleRow.style.cssText = "display:flex;align-items:center;justify-content:space-between;margin-bottom:4px;";
+        const titleText = document.createElement("span");
+        titleText.textContent = "PERF";
+        titleText.style.cssText = `font:600 9px/1.8 ${MONO};letter-spacing:0.12em;color:rgba(120,180,255,0.6);`;
+        const closeBtn = document.createElement("button");
+        closeBtn.textContent = "×";
+        closeBtn.style.cssText = `background:none;border:none;font:11px/1 ${MONO};color:rgba(255,255,255,0.35);cursor:pointer;padding:0 0 0 10px;pointer-events:auto;`;
+        closeBtn.addEventListener("click", () => this.toggle());
+        titleRow.append(titleText, closeBtn);
+        this.panel.appendChild(titleRow);
+        this.pre = document.createElement("pre");
+        this.pre.style.cssText = `margin:0;font:${MONO};color:rgba(220,230,255,0.85);white-space:pre;`;
+        this.panel.appendChild(this.pre);
+        this.buildButtons();
+        this.reportOut = document.createElement("pre");
+        this.reportOut.style.cssText = `margin:4px 0 0;font:10px/1.5 ${MONO};color:rgba(180,255,205,0.9);white-space:pre;max-height:240px;overflow:auto;`;
+        this.panel.appendChild(this.reportOut);
+        this.onKey = (e) => {
+            if (e.key === "`")
+                this.toggle();
+        };
+        document.addEventListener("keydown", this.onKey);
+        this.applyVisibility();
+    }
+    // ── Public per-frame API ─────────────────────────────────────
+    frameStart() {
+        const now = performance.now();
+        if (this.prevFrameTime) {
+            const frameMs = now - this.prevFrameTime;
+            this.frameMs.push(frameMs);
+            if (frameMs > 0)
+                this.fps.push(1000 / frameMs);
+        }
+        this.prevFrameTime = now;
+        this.cpuStart = now;
+    }
+    gpuBegin() {
+        if (!this.ext)
+            return;
+        const gl = this.gl;
+        const q = this.gpuPool.pop() ?? gl.createQuery();
+        if (!q)
+            return;
+        this.gpuCurrent = q;
+        gl.beginQuery(this.ext.TIME_ELAPSED_EXT, q);
+    }
+    gpuEnd() {
+        if (!this.ext || !this.gpuCurrent)
+            return;
+        const gl = this.gl;
+        gl.endQuery(this.ext.TIME_ELAPSED_EXT);
+        this.gpuPending.push(this.gpuCurrent);
+        this.gpuCurrent = null;
+    }
+    /** End of frame. `dt` is seconds since last frame (drives the DOM throttle). */
+    frameEnd(dt) {
+        this.cpuMs.push(performance.now() - this.cpuStart);
+        if (this.ext)
+            this.pollGpu();
+        const ri = this.renderer.info;
+        this.lastInfo = {
+            calls: ri.render.calls,
+            tris: ri.render.triangles,
+            lines: ri.render.lines,
+            geos: ri.memory.geometries,
+            texs: ri.memory.textures,
+            prgs: ri.programs?.length ?? 0,
+        };
+        this.domTick -= dt;
+        if (this.domTick <= 0) {
+            this.domTick = this.DOM_INTERVAL;
+            this.updatePill();
+            if (this.visible)
+                this.updateDom();
+        }
+    }
+    toggle() {
+        this.visible = !this.visible;
+        window.__PERF__ = this.visible;
+        this.applyVisibility();
+    }
+    destroy() {
+        document.removeEventListener("keydown", this.onKey);
+        this.stack.remove();
+        const gl = this.gl;
+        if (this.ext) {
+            for (const q of this.gpuPool)
+                gl.deleteQuery(q);
+            for (const q of this.gpuPending)
+                gl.deleteQuery(q);
+            if (this.gpuCurrent) {
+                gl.endQuery(this.ext.TIME_ELAPSED_EXT);
+                gl.deleteQuery(this.gpuCurrent);
+            }
+        }
+    }
+    // ── Internals ────────────────────────────────────────────────
+    applyVisibility() {
+        this.panel.style.display = this.visible ? "block" : "none";
+        this.pill.style.display = this.visible ? "none" : "block";
+    }
+    makeButton(label, bg) {
+        const b = document.createElement("button");
+        b.textContent = label;
+        b.style.cssText = `
+      margin: 6px 6px 0 0; padding: 4px 9px;
+      font: ${MONO}; color: rgba(225,235,255,0.95);
+      background: ${bg};
+      border: 1px solid rgba(255,255,255,0.18); border-radius: 4px;
+      cursor: pointer; pointer-events: auto; user-select: none;`;
+        return b;
+    }
+    buildButtons() {
+        const reportBtn = this.makeButton("Log perf report", "rgba(80,120,200,0.28)");
+        reportBtn.addEventListener("click", () => this.dumpReport(reportBtn));
+        this.panel.appendChild(reportBtn);
+        if (this.opts.scene) {
+            const scene = this.opts.scene;
+            const auditBtn = this.makeButton("Audit draw calls", "rgba(120,180,120,0.28)");
+            auditBtn.addEventListener("click", () => {
+                const text = auditScene(scene);
+                console.log("[perf] draw-call audit\n" + text);
+                this.reportOut.textContent = "✓ LOGGED IN CONSOLE\n\n" + text;
+            });
+            this.panel.appendChild(auditBtn);
+        }
+        for (const spec of this.opts.buttons ?? []) {
+            const btn = this.makeButton(spec.label, spec.color ?? "rgba(200,120,80,0.28)");
+            btn.addEventListener("click", spec.onClick);
+            this.panel.appendChild(btn);
+        }
+    }
+    dumpReport(btn) {
+        if (!window.__PERF__) {
+            window.__PERF__ = true;
+            this.reportOut.textContent = "Perf sampling enabled — run a few seconds, then click again.";
+            return;
+        }
+        const r = perfReport();
+        if (!r || !Object.keys(r).length) {
+            this.reportOut.textContent = "No samples yet — run a few seconds, then click again.";
+            return;
+        }
+        const text = Object.entries(r)
+            .sort((a, b) => b[1].avg - a[1].avg)
+            .map(([label, e]) => `${label.padEnd(16)} avg ${e.avg.toFixed(2).padStart(7)}ms  max ${e.max.toFixed(2).padStart(7)}ms  n${e.n}`)
+            .join("\n");
+        console.log("[perf] report\n" + text + "\n\n" + JSON.stringify(r, null, 2));
+        this.reportOut.textContent = "✓ LOGGED IN CONSOLE\n\n" + text;
+        btn.textContent = "Logged ✓";
+        setTimeout(() => {
+            btn.textContent = "Log perf report";
+        }, 1500);
+    }
+    initGpuExt() {
+        if (typeof WebGL2RenderingContext === "undefined")
+            return null;
+        if (!(this.gl instanceof WebGL2RenderingContext))
+            return null;
+        return this.gl.getExtension("EXT_disjoint_timer_query_webgl2");
+    }
+    pollGpu() {
+        const gl = this.gl;
+        const ext = this.ext;
+        const disjoint = gl.getParameter(ext.GPU_DISJOINT_EXT);
+        for (let i = this.gpuPending.length - 1; i >= 0; i--) {
+            const q = this.gpuPending[i];
+            if (!gl.getQueryParameter(q, gl.QUERY_RESULT_AVAILABLE))
+                continue;
+            if (!disjoint) {
+                const ns = gl.getQueryParameter(q, gl.QUERY_RESULT);
+                this.gpuMs.push(ns / 1_000_000);
+            }
+            this.gpuPool.push(q);
+            const last = this.gpuPending.length - 1;
+            if (i !== last)
+                this.gpuPending[i] = this.gpuPending[last];
+            this.gpuPending.pop();
+        }
+    }
+    updatePill() {
+        const gpuStr = this.ext ? `${this.gpuMs.avg().toFixed(1)}ms` : "n/a";
+        this.pill.textContent = `${Math.round(this.fps.avg())} fps • GPU ${gpuStr} • CPU ${this.cpuMs.avg().toFixed(1)}ms`;
+    }
+    updateDom() {
+        const { calls, tris, geos, texs, prgs } = this.lastInfo;
+        const gpuStr = this.ext ? `${f1(this.gpuMs.avg())}ms  ↑${f1(this.gpuMs.max())}ms` : "  n/a";
+        const rows = [
+            `FPS  ${f1(this.fps.avg())}  lo ${f0(this.fps.min(), 3)}      frame ${f1(this.frameMs.avg())}ms`,
+            `CPU  ${f1(this.cpuMs.avg())}ms  ↑${f1(this.cpuMs.max())}ms   GPU  ${gpuStr}`,
+        ];
+        for (const label of this.opts.phases ?? []) {
+            rows.push(`  ${label.padEnd(16)} ${f1(perfAvg(label))}ms  ↑${f1(perfPeak(label))}ms`);
+        }
+        rows.push("", `calls ${f0(calls, 4)}  tris ${kFmt(tris)}`, `geos  ${f0(geos, 4)}  tex ${f0(texs, 4)}  prgs ${f0(prgs, 3)}`);
+        const counters = this.opts.counters?.();
+        if (counters) {
+            rows.push("");
+            const entries = Object.entries(counters);
+            for (let i = 0; i < entries.length; i += 2) {
+                const a = entries[i];
+                const b = entries[i + 1];
+                const left = `${a[0].slice(0, 7).padEnd(7)} ${f0(a[1], 4)}`;
+                rows.push(b ? `${left}  ${b[0].slice(0, 7).padEnd(7)} ${f0(b[1], 4)}` : left);
+            }
+        }
+        this.pre.textContent = rows.join("\n");
+    }
+}
+//# sourceMappingURL=perf-overlay.js.map