@aura3d/engine 4.0.8 → 4.1.1

package/dist/debug/safety/blackFrame.js

@@ -0,0 +1,326 @@
+export const DEFAULT_HEAL_LADDER = [
+    { name: "no-aa", params: { aa: "0" } },
+    { name: "no-post", params: { post: "0" } },
+    { name: "aces-tone", params: { tm: "aces" } },
+    { name: "no-env", params: { env: "0" } },
+    { name: "no-shadow", params: { shadow: "0" } },
+    { name: "low-quality", params: { quality: "low", sky: "1" } }
+];
+export const DEFAULT_HEAL_STORAGE_KEY = "aura3d-safety-heal-stage";
+const BLACK_MAX_CHANNEL = 4;
+/** Nearest-neighbour probe grid: one texel per block, so thin bright features are not averaged away. */
+const PROBE_WIDTH = 48;
+const PROBE_HEIGHT = 32;
+/** "Nearly all" black: at most this fraction of grid samples may be lit (a few stray texels of a HUD drawn into the canvas). */
+const MAX_LIT_FRACTION = 0.002;
+const LOADING_SELECTOR = '#boot, .boot, #loading, #loader, #loading-screen, .loading, .loader, [data-loading="true"], [aria-busy="true"], [id*="loading" i], [class*="loading" i]';
+const HIDDEN_CLASSES = ["hidden", "done", "is-hidden", "loaded", "ready", "fade-out"];
+function safeStorage() {
+    try {
+        return globalThis.sessionStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Current rung (0 = full quality) from session storage, so a reload continues down the ladder. */
+export function healStage(storage = safeStorage(), ladder = DEFAULT_HEAL_LADDER, storageKey = DEFAULT_HEAL_STORAGE_KEY) {
+    const raw = Number(storage?.getItem(storageKey) ?? "0");
+    return Number.isInteger(raw) && raw >= 0 && raw <= ladder.length ? raw : 0;
+}
+/** Query parameters implied by rung `stage` (cumulative); callers merge them under the author's explicit parameters. */
+export function healParams(stage, ladder = DEFAULT_HEAL_LADDER) {
+    const merged = {};
+    for (const rung of ladder.slice(0, Math.max(0, stage)))
+        Object.assign(merged, rung.params);
+    return merged;
+}
+export function healRungName(stage, ladder = DEFAULT_HEAL_LADDER) {
+    return stage <= 0 ? "full" : ladder[Math.min(stage, ladder.length) - 1].name;
+}
+/** Statistics of a downscaled RGBA probe of the canvas. */
+export function analyseFrame(rgba, maxChannel = BLACK_MAX_CHANNEL) {
+    let samples = 0;
+    let lit = 0;
+    let max = 0;
+    let sum = 0;
+    for (let i = 0; i + 2 < rgba.length; i += 4) {
+        const r = rgba[i];
+        const g = rgba[i + 1];
+        const b = rgba[i + 2];
+        samples += 1;
+        sum += r + g + b;
+        const peak = Math.max(r, g, b);
+        if (peak > max)
+            max = peak;
+        if (peak > maxChannel)
+            lit += 1;
+    }
+    return { samples, lit, litFraction: samples === 0 ? 1 : lit / samples, max, mean: samples === 0 ? 0 : sum / (samples * 3) };
+}
+/**
+ * True when the sampled frame is black: every texel by default; pass a small `maxLitFraction` to tolerate a few stray lit
+ * texels (for example a HUD drawn into the same canvas). Empty input is never black.
+ */
+export function isBlackFrame(rgba, maxLitFraction = 0) {
+    if (rgba.length < 4)
+        return false;
+    return analyseFrame(rgba).litFraction <= maxLitFraction;
+}
+function elementVisible(element) {
+    const node = element;
+    if (node.hidden === true)
+        return false;
+    const classes = node.classList;
+    if (classes && HIDDEN_CLASSES.some((name) => classes.contains(name)))
+        return false;
+    if (typeof getComputedStyle === "function") {
+        try {
+            const style = getComputedStyle(node);
+            if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) < 0.02)
+                return false;
+        }
+        catch {
+            /* detached or stubbed element: treat as visible */
+        }
+    }
+    if (typeof node.getBoundingClientRect === "function") {
+        const box = node.getBoundingClientRect();
+        if (box.width <= 0 || box.height <= 0)
+            return false;
+    }
+    return true;
+}
+/** True while a visible loading overlay is on the page (`#boot`, `#loading`, `.loading`, `[aria-busy=true]` ...). */
+export function hasVisibleLoadingOverlay(root = typeof document === "undefined" ? undefined : document) {
+    if (!root || typeof root.querySelectorAll !== "function")
+        return false;
+    try {
+        return Array.from(root.querySelectorAll(LOADING_SELECTOR)).some(elementVisible);
+    }
+    catch {
+        return false;
+    }
+}
+/** Default readiness: document fully loaded, no asset fetches in flight, no visible loading overlay. */
+export function defaultIsReady() {
+    if (typeof document !== "undefined" && document.readyState && document.readyState !== "complete")
+        return false;
+    const inflight = globalThis.__aura3dInFlightByteFetches;
+    if (typeof inflight === "number" && inflight > 0)
+        return false;
+    return !hasVisibleLoadingOverlay();
+}
+/** Largest canvas big enough to be the world view, ignoring minimap/HUD/overlay canvases. */
+export function findWorldCanvas(root = typeof document === "undefined" ? undefined : document) {
+    if (!root || typeof root.querySelectorAll !== "function")
+        return null;
+    let best = null;
+    let area = 0;
+    for (const canvas of Array.from(root.querySelectorAll("canvas"))) {
+        const label = `${canvas.id ?? ""} ${canvas.className ?? ""}`;
+        if (/minimap|mini-map|hud|overlay|compass|radar|(^|[\s_-])ui([\s_-]|$)/i.test(label))
+            continue;
+        const a = canvas.width * canvas.height;
+        if (canvas.width >= 128 && canvas.height >= 96 && a > area) {
+            best = canvas;
+            area = a;
+        }
+    }
+    return best;
+}
+function defaultProbe() {
+    let ctx;
+    return (canvas) => {
+        if (ctx === undefined) {
+            const probe = document.createElement("canvas");
+            probe.width = PROBE_WIDTH;
+            probe.height = PROBE_HEIGHT;
+            ctx = probe.getContext("2d", { willReadFrequently: true });
+            if (ctx)
+                ctx.imageSmoothingEnabled = false;
+        }
+        if (!ctx)
+            return undefined;
+        ctx.drawImage(canvas, 0, 0, PROBE_WIDTH, PROBE_HEIGHT);
+        return ctx.getImageData(0, 0, PROBE_WIDTH, PROBE_HEIGHT).data;
+    };
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.floor(sorted.length / 2)];
+}
+export function createBlackFrameWatch(canvas, options) {
+    const ladder = options.ladder ?? DEFAULT_HEAL_LADDER;
+    const storageKey = options.storageKey ?? DEFAULT_HEAL_STORAGE_KEY;
+    const reasonKey = `${storageKey}:reason`;
+    const storage = options.storage ?? safeStorage();
+    const fast = options.fastFrames !== undefined;
+    const minFramesAfterReady = options.minFramesAfterReady ?? options.fastFrames ?? 30;
+    const sampleEvery = Math.max(1, options.sampleEvery ?? (fast ? 2 : 4));
+    const samplesNeeded = Math.max(2, options.samplesNeeded ?? (fast ? Math.ceil(options.fastFrames / 2) : 12));
+    const minBlackMs = options.minBlackMs ?? (fast ? 0 : 4000);
+    const blackFramesBudget = options.blackFramesBudget ?? (fast ? 0 : 40);
+    const stage = healStage(storage, ladder, storageKey);
+    const readProbe = options.readProbe ?? defaultProbe();
+    const log = options.log ?? ((code, message) => console.warn(`${code}: ${message}`));
+    const currentUrl = options.currentUrl ?? (() => location.href);
+    const navigate = options.navigate ?? ((url) => location.replace(url));
+    const now = options.now ?? (() => performance.now());
+    const isHidden = options.isHidden ?? (() => typeof document !== "undefined" && (document.hidden === true || document.visibilityState === "hidden"));
+    const appReady = options.isReady;
+    const previousReason = (() => {
+        try {
+            return storage?.getItem(reasonKey) ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    let calls = 0;
+    let readyAtCall = null;
+    let samples = 0;
+    let blackSamples = 0;
+    let consecutive = 0;
+    let litStreak = 0;
+    let healthy = false;
+    let blackSince = 0;
+    let escalated = false;
+    let lastStats;
+    let lastTime;
+    let reason = previousReason;
+    const deltas = [];
+    const skipped = { notReady: 0, noDrawCalls: 0, hidden: 0 };
+    if (stage > 0)
+        log("SAFETY_COMPAT_MODE", `rung ${stage} (${healRungName(stage, ladder)}) after a black frame was detected${previousReason ? `: ${previousReason}` : ""}`);
+    const resetStreak = () => {
+        consecutive = 0;
+        blackSince = 0;
+    };
+    return {
+        stage,
+        rung: healRungName(stage, ladder),
+        get escalated() {
+            return escalated;
+        },
+        observation() {
+            const t = lastTime ?? 0;
+            return {
+                calls,
+                readyAtCall,
+                framesSinceReady: readyAtCall === null ? 0 : calls - readyAtCall + 1,
+                samples,
+                blackSamples,
+                consecutiveBlack: consecutive,
+                healthy,
+                lastStats,
+                medianFrameMs: median(deltas),
+                blackMs: blackSince ? Math.max(0, t - blackSince) : 0,
+                skipped: { ...skipped },
+                escalated,
+                reason
+            };
+        },
+        sample() {
+            const t = now();
+            if (lastTime !== undefined && t >= lastTime) {
+                deltas.push(t - lastTime);
+                if (deltas.length > 31)
+                    deltas.shift();
+            }
+            lastTime = t;
+            calls += 1;
+            if (!options.enabled || escalated)
+                return;
+            if (isHidden()) {
+                skipped.hidden += 1;
+                resetStreak();
+                return;
+            }
+            let ready = (appReady ? appReady() : true) && defaultIsReady();
+            if (!ready) {
+                skipped.notReady += 1;
+                readyAtCall = null;
+                healthy = false;
+                litStreak = 0;
+                resetStreak();
+                return;
+            }
+            if (readyAtCall === null)
+                readyAtCall = calls;
+            ready = true;
+            const since = calls - readyAtCall + 1;
+            const every = healthy ? sampleEvery * 8 : sampleEvery;
+            if (since < minFramesAfterReady || since % every !== 0)
+                return;
+            const drawCalls = options.getDrawCalls?.();
+            if (drawCalls !== undefined && !(drawCalls > 0)) {
+                skipped.noDrawCalls += 1;
+                resetStreak();
+                return;
+            }
+            const target = typeof canvas === "function" ? canvas() : canvas;
+            if (!target)
+                return;
+            let stats;
+            try {
+                const data = readProbe(target);
+                if (!data)
+                    return;
+                stats = analyseFrame(data);
+            }
+            catch {
+                return;
+            }
+            lastStats = stats;
+            samples += 1;
+            const black = stats.samples > 0 && stats.litFraction <= MAX_LIT_FRACTION;
+            if (!black) {
+                litStreak += 1;
+                resetStreak();
+                if (litStreak >= 3)
+                    healthy = true;
+                return;
+            }
+            litStreak = 0;
+            blackSamples += 1;
+            consecutive += 1;
+            if (blackSince === 0)
+                blackSince = t;
+            const medianFrameMs = median(deltas);
+            const windowMs = Math.max(minBlackMs, medianFrameMs * blackFramesBudget);
+            if (consecutive < samplesNeeded || t - blackSince < windowMs || stage >= ladder.length)
+                return;
+            escalated = true;
+            reason = `black for ${consecutive} samples / ${Math.round(t - blackSince)} ms after ${since} ready frames (lit ${stats.lit}/${stats.samples}, max channel ${stats.max}, median frame ${Math.round(medianFrameMs)} ms, drawCalls ${drawCalls ?? "n/a"})`;
+            const href = currentUrl();
+            let next;
+            if (options.buildUrl) {
+                next = options.buildUrl(stage + 1, href);
+            }
+            else {
+                const url = new URL(href);
+                for (const [key, value] of Object.entries(healParams(stage + 1, ladder)))
+                    if (!url.searchParams.has(key))
+                        url.searchParams.set(key, value);
+                next = url.toString();
+            }
+            if (!next) {
+                escalated = false;
+                return;
+            }
+            try {
+                storage?.setItem(storageKey, String(stage + 1));
+                storage?.setItem(reasonKey, reason);
+            }
+            catch {
+                /* storage unavailable: the reload still happens, the rung just cannot continue */
+            }
+            log("SAFETY_BLACK_FRAME", `reloading at rung ${stage + 1} (${healRungName(stage + 1, ladder)}): ${reason}`);
+            navigate(next);
+        }
+    };
+}
+//# sourceMappingURL=blackFrame.js.map

package/dist/debug/safety/blackFrame.js.map

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

package/dist/debug/safety/diagnosticsPanel.d.ts

@@ -0,0 +1,70 @@
+/**
+ * On-screen GPU diagnostics panel: renderer string, WebGL limits and extensions, canvas size, WebGPU presence, engine
+ * draw calls, shader compile/link failures, WebGL context loss and the last console errors. Intended for real-device
+ * bug reports ("open the page with ?diag=1 and send a screenshot"). Nothing is installed until the function is called,
+ * and `dispose()` restores every patched browser prototype and console method.
+ */
+/** Subset of the engine's `diagnostics().shaderFailures` records the panel prints. */
+export interface ShaderFailureLike {
+    readonly code?: string;
+    readonly material?: string;
+    readonly stage?: string;
+    readonly message?: string;
+    readonly locations?: readonly {
+        readonly line?: number;
+        readonly authoredLine?: number;
+        readonly message?: string;
+        readonly window?: readonly {
+            readonly text?: string;
+            readonly error?: boolean;
+        }[];
+    }[];
+}
+export interface DiagnosticsAppLike {
+    /** `AuraApp.diagnostics()` shape; only these members are read. */
+    diagnostics?(): {
+        readonly backend?: unknown;
+        readonly drawCalls?: unknown;
+        readonly fps?: unknown;
+        readonly warnings?: readonly string[];
+        readonly errors?: readonly string[];
+        readonly shaderFailures?: readonly ShaderFailureLike[];
+    } | undefined;
+}
+export interface DiagnosticsPanelOptions {
+    readonly app?: DiagnosticsAppLike;
+    readonly title?: string;
+    readonly maxLines?: number;
+    /** Extra lines appended to the engine section (the safety net adds its rung and switches here). */
+    readonly extraLines?: () => readonly string[];
+    /** Update period in ms. */
+    readonly refreshMs?: number;
+}
+export interface DiagnosticsPanelHandle {
+    readonly lines: readonly string[];
+    refresh(): void;
+    dispose(): void;
+}
+export interface GpuProbe {
+    readonly renderer: string;
+    readonly limits: string;
+    readonly extensions: string;
+    readonly webgpu: boolean;
+    readonly dpr: number;
+}
+export declare function probeGpu(): GpuProbe | {
+    readonly error: string;
+};
+export declare function formatGpuProbe(probe: GpuProbe | {
+    readonly error: string;
+}): string;
+/** Pure formatter for the engine section so it can be unit tested without a browser. */
+export declare function formatEngineSection(app: DiagnosticsAppLike | undefined, canvases: ReadonlyArray<{
+    id?: string;
+    width: number;
+    height: number;
+    clientWidth: number;
+    clientHeight: number;
+}>): string;
+export declare function installDiagnosticsPanel(options?: DiagnosticsPanelOptions): DiagnosticsPanelHandle;
+//# sourceMappingURL=diagnosticsPanel.d.ts.map

package/dist/debug/safety/diagnosticsPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnosticsPanel.d.ts","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/diagnosticsPanel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE,EAAE,CAAA;KAAE,EAAE,CAAC;CAC1M;AAED,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,WAAW,CAAC,IAAI;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACtP;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mGAAmG;IACnG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAC9C,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAID,wBAAgB,QAAQ,IAAI,QAAQ,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAehE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGnF;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAsBnM;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CAsErG"}

package/dist/debug/safety/diagnosticsPanel.js

@@ -0,0 +1,123 @@
+const EXTENSIONS = ["EXT_color_buffer_float", "OES_texture_float_linear", "WEBGL_multi_draw", "EXT_disjoint_timer_query_webgl2"];
+export function probeGpu() {
+    try {
+        const gl = document.createElement("canvas").getContext("webgl2");
+        if (!gl)
+            return { error: "webgl2: unavailable" };
+        const info = gl.getExtension("WEBGL_debug_renderer_info");
+        return {
+            renderer: String(info ? gl.getParameter(info.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER)),
+            limits: `maxTex ${gl.getParameter(gl.MAX_TEXTURE_SIZE)} units ${gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS)} samples ${gl.getParameter(gl.MAX_SAMPLES)} fragUniforms ${gl.getParameter(gl.MAX_FRAGMENT_UNIFORM_VECTORS)} varyings ${gl.getParameter(gl.MAX_VARYING_VECTORS)}`,
+            extensions: EXTENSIONS.map((name) => `${name.replace(/^(EXT|OES|WEBGL)_/, "")}:${gl.getExtension(name) ? "y" : "n"}`).join(" "),
+            webgpu: "gpu" in navigator,
+            dpr: globalThis.devicePixelRatio ?? 1
+        };
+    }
+    catch (error) {
+        return { error: `webgl2 probe failed: ${String(error.message)}` };
+    }
+}
+export function formatGpuProbe(probe) {
+    if ("error" in probe)
+        return probe.error;
+    return `gpu: ${probe.renderer}\n${probe.limits}\n${probe.extensions} navigator.gpu:${probe.webgpu ? "y" : "n"} dpr ${probe.dpr}`;
+}
+/** Pure formatter for the engine section so it can be unit tested without a browser. */
+export function formatEngineSection(app, canvases) {
+    const parts = [];
+    try {
+        const report = app?.diagnostics?.();
+        if (report) {
+            if (report.backend !== undefined)
+                parts.push(`backend=${String(report.backend)}`);
+            if (report.drawCalls !== undefined)
+                parts.push(`drawCalls=${String(report.drawCalls)}`);
+            if (report.fps !== undefined)
+                parts.push(`fps=${Number(report.fps).toFixed(0)}`);
+            for (const warning of (report.warnings ?? []).slice(0, 3))
+                parts.push(`warn:${String(warning).slice(0, 80)}`);
+            for (const error of (report.errors ?? []).slice(0, 3))
+                parts.push(`error:${String(error).slice(0, 80)}`);
+            for (const failure of (report.shaderFailures ?? []).slice(0, 2)) {
+                const first = failure.locations?.[0];
+                const offending = first?.window?.find((row) => row.error)?.text?.trim();
+                const where = first ? ` ${failure.stage ?? ""} line ${first.line}${first.authoredLine !== undefined ? ` (source line ${first.authoredLine})` : ""}` : ` ${failure.stage ?? ""}`;
+                parts.push(`\nSHADER ${failure.code ?? "FAILED"} "${failure.material ?? "?"}"${where}: ${String(first?.message ?? failure.message ?? "").slice(0, 100)}${offending ? ` >> ${offending.slice(0, 100)}` : ""}`);
+            }
+        }
+    }
+    catch {
+        parts.push("diagnostics() threw");
+    }
+    const sizes = canvases.map((c) => `${c.id || "canvas"} ${c.width}x${c.height} (css ${c.clientWidth}x${c.clientHeight})`).join("; ");
+    return `engine: ${parts.join(" ") || "no diagnostics exposed"}\ncanvas: ${sizes}`;
+}
+export function installDiagnosticsPanel(options = {}) {
+    const lines = [];
+    const maxLines = options.maxLines ?? 14;
+    const restore = [];
+    const push = (line) => {
+        lines.push(line.slice(0, 220));
+        while (lines.length > maxLines)
+            lines.shift();
+    };
+    const originalError = console.error;
+    const originalWarn = console.warn;
+    console.error = (...args) => { push(`error: ${args.map(String).join(" ")}`); originalError.apply(console, args); };
+    console.warn = (...args) => { push(`warn: ${args.map(String).join(" ")}`); originalWarn.apply(console, args); };
+    restore.push(() => { console.error = originalError; console.warn = originalWarn; });
+    const onError = (event) => push(`uncaught: ${event.message}`);
+    const onRejection = (event) => push(`rejection: ${String(event.reason?.message ?? event.reason)}`);
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    restore.push(() => { window.removeEventListener("error", onError); window.removeEventListener("unhandledrejection", onRejection); });
+    const proto = globalThis.WebGL2RenderingContext?.prototype;
+    if (proto) {
+        const compile = proto.compileShader;
+        const link = proto.linkProgram;
+        proto.compileShader = function (shader) {
+            compile.call(this, shader);
+            if (!this.getShaderParameter(shader, this.COMPILE_STATUS))
+                push(`SHADER COMPILE FAILED: ${(this.getShaderInfoLog(shader) ?? "").replace(/\s+/g, " ")}`);
+        };
+        proto.linkProgram = function (program) {
+            link.call(this, program);
+            if (!this.getProgramParameter(program, this.LINK_STATUS))
+                push(`PROGRAM LINK FAILED: ${(this.getProgramInfoLog(program) ?? "").replace(/\s+/g, " ")}`);
+        };
+        restore.push(() => { proto.compileShader = compile; proto.linkProgram = link; });
+    }
+    const getContext = HTMLCanvasElement.prototype.getContext;
+    HTMLCanvasElement.prototype.getContext = function (...args) {
+        const context = getContext.apply(this, args);
+        if (context && !this.__auraSafetyWatched) {
+            this.__auraSafetyWatched = true;
+            this.addEventListener("webglcontextlost", () => push("WEBGL CONTEXT LOST"));
+        }
+        return context;
+    };
+    restore.push(() => { HTMLCanvasElement.prototype.getContext = getContext; });
+    const panel = document.createElement("pre");
+    panel.setAttribute("data-aura3d-safety-panel", "");
+    panel.style.cssText = "position:fixed;left:8px;top:8px;z-index:2147483001;max-width:min(720px,calc(100vw - 16px));margin:0;padding:6px 9px;border-radius:6px;background:rgba(0,0,0,.78);color:#9dffb0;font:400 11px/1.35 ui-monospace,Menlo,monospace;white-space:pre-wrap;pointer-events:none";
+    document.body.appendChild(panel);
+    restore.push(() => panel.remove());
+    const staticInfo = formatGpuProbe(probeGpu());
+    const refresh = () => {
+        const canvases = Array.from(document.querySelectorAll("canvas"));
+        const extra = options.extraLines?.() ?? [];
+        panel.textContent = `${options.title ?? "Aura3D diagnostics"}\n${staticInfo}\n${formatEngineSection(options.app, canvases)}${extra.length ? `\n${extra.join("\n")}` : ""}\n${lines.length ? lines.join("\n") : "no errors captured"}`;
+    };
+    refresh();
+    const timer = setInterval(refresh, options.refreshMs ?? 1000);
+    restore.push(() => clearInterval(timer));
+    return {
+        lines,
+        refresh,
+        dispose() {
+            for (const undo of restore.reverse())
+                undo();
+        }
+    };
+}
+//# sourceMappingURL=diagnosticsPanel.js.map

package/dist/debug/safety/diagnosticsPanel.js.map

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

package/dist/debug/safety/guard.d.ts

@@ -0,0 +1,51 @@
+import { createBlackFrameWatch, type BlackFrameWatch, type WatchObservation } from "./blackFrame.js";
+/**
+ * Black-frame guard for pages that run on the engine's `a3d-qr` URL flag list (the showcase games). It installs once,
+ * before the app starts drawing, wraps `requestAnimationFrame` so the world canvas is sampled right after each frame
+ * callback (same task, before the browser composites), and reloads one rung down when the canvas stays black. It is a
+ * thin shell around `createBlackFrameWatch`: readiness gating, black-versus-dark detection, once-per-load stepping and
+ * the recorded reason all live there.
+ *
+ * `?heal=0` disables it; an `a3d-qr` supplied in the URL by the author or player is never rewritten.
+ */
+export declare const QR_HEAL_LADDER: ReadonlyArray<{
+    readonly name: string;
+    readonly qr: string;
+}>;
+/** Rung currently applied (0 = full quality) from the stored value. */
+export declare function qrHealStage(raw: string | null | undefined): number;
+export declare const qrHealRungName: (stage: number) => string;
+/**
+ * URL for rung `stage`, or `null` when the ladder is exhausted or an author/player supplied their own `a3d-qr`.
+ * `ownsQr` is true when the `a3d-qr` already in the URL was written by an earlier rung of this guard.
+ */
+export declare function qrHealUrl(href: string, stage: number, ownsQr?: boolean): string | null;
+export interface HealGlobal {
+    rung: number;
+    name: string;
+    enabled: boolean;
+    /** Live view of what the watch has seen (frames, samples, last probe stats, skips) and why a reload happened. */
+    observation?: () => WatchObservation;
+}
+declare global {
+    interface Window {
+        __AURA3D_HEAL__?: HealGlobal;
+    }
+}
+export interface BlackFrameGuardOptions {
+    /** Defaults to true unless the URL has `heal=0`. */
+    readonly enabled?: boolean;
+    /** Tests only: shorter detection window. */
+    readonly fast?: boolean;
+    /** Extra readiness signal, for example the app's own `ready` flag. Combined with the built-in overlay/load/fetch checks. */
+    readonly isReady?: () => boolean;
+    /** Engine draw calls for the current frame; when given and not > 0 the frame is not judged. */
+    readonly getDrawCalls?: () => number | undefined;
+    /** Which canvas to judge. Defaults to the largest non-HUD canvas on the page. */
+    readonly canvas?: () => HTMLCanvasElement | null | undefined;
+    /** Test hooks forwarded to the watch (clock, probe, storage, navigation, logging). */
+    readonly watch?: Partial<Pick<Parameters<typeof createBlackFrameWatch>[1], "now" | "readProbe" | "storage" | "navigate" | "log" | "isHidden" | "currentUrl" | "minBlackMs" | "blackFramesBudget" | "minFramesAfterReady" | "sampleEvery" | "samplesNeeded">>;
+}
+/** Returns the watch (or undefined when disabled/unavailable) so callers and tests can read its observation. */
+export declare function installBlackFrameGuard(options?: BlackFrameGuardOptions): BlackFrameWatch | undefined;
+//# sourceMappingURL=guard.d.ts.map

package/dist/debug/safety/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAiC,KAAK,eAAe,EAAiB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnJ;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAIxF,CAAC;AAIF,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGlE;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAAuC,CAAC;AAEvF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,MAAM,GAAG,IAAI,CAMpF;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,iHAAiH;IACjH,WAAW,CAAC,EAAE,MAAM,gBAAgB,CAAC;CACtC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,eAAe,CAAC,EAAE,UAAU,CAAC;KAC9B;CACF;AAED,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,4HAA4H;IAC5H,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACjC,+FAA+F;IAC/F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACjD,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7D,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,aAAa,GAAG,eAAe,CAAC,CAAC,CAAC;CAC9P;AAED,gHAAgH;AAChH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,GAAG,SAAS,CAyBxG"}