@aura3d/debug 4.0.7 → 4.1.0

package/dist/index.d.ts

@@ -28,4 +28,6 @@ export { buildAxesHelper, buildBoundsHelper, buildCameraFrustumHelper, buildDire
 export type { AxesHelperOptions, BoundsHelperOptions, CameraFrustumHelperOptions, DebugColor, DebugVec3, DirectionalLightHelperOptions, GridHelperOptions, SkeletonHelperJoint } from "./SceneHelpers.js";
 export { ReportExporter } from "./ReportExporter.js";
 export type { DebugReport } from "./ReportExporter.js";
+export { DEFAULT_HEAL_LADDER, DEFAULT_HEAL_STORAGE_KEY, createBlackFrameWatch, formatEngineSection, formatGpuProbe, healParams, healRungName, healStage, installDiagnosticsPanel, installSafetyNet, isBlackFrame, probeGpu, resolveQualitySwitches } from "./safety/index.js";
+export type { BlackFrameWatch, BlackFrameWatchOptions, DiagnosticsAppLike, DiagnosticsPanelHandle, DiagnosticsPanelOptions, GpuProbe, HealRung, QualitySwitches, ResolveQualitySwitchesOptions, SafetyNet, SafetyNetOptions, SafetyReport, SafetySettings } from "./safety/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/debug/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACvF,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAClF,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACxF,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACtH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACjI,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,UAAU,EACV,SAAS,EACT,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/debug/src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -13,4 +13,5 @@ export { DebugOverlay } from "./DebugOverlay.js";
 export { DebugLineCanvasRenderer } from "./DebugLineCanvasRenderer.js";
 export { buildAxesHelper, buildBoundsHelper, buildCameraFrustumHelper, buildDirectionalLightHelper, buildGridHelper, buildSkeletonHelper } from "./SceneHelpers.js";
 export { ReportExporter } from "./ReportExporter.js";
+export { DEFAULT_HEAL_LADDER, DEFAULT_HEAL_STORAGE_KEY, createBlackFrameWatch, formatEngineSection, formatGpuProbe, healParams, healRungName, healStage, installDiagnosticsPanel, installSafetyNet, isBlackFrame, probeGpu, resolveQualitySwitches } from "./safety/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/debug/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAW3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/debug/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAW3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,sBAAsB,EACvB,MAAM,mBAAmB,CAAC"}

package/dist/safety/blackFrame.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Black-frame self-heal. Some GPU/driver combinations present a frame that is entirely black while the engine reports
+ * draw calls. When that persists the page reloads itself one rung down a compatibility ladder (each rung switches off
+ * one more optional stage) and records the rung, so a player still gets a picture and the diagnostics panel shows which
+ * rung fixed it. Opt-in only: nothing here runs unless `installSafetyNet` (or `createBlackFrameWatch`) is called.
+ */
+export interface HealRung {
+    readonly name: string;
+    readonly params: Readonly<Record<string, string>>;
+}
+export declare const DEFAULT_HEAL_LADDER: readonly HealRung[];
+export declare const DEFAULT_HEAL_STORAGE_KEY = "aura3d-safety-heal-stage";
+type StorageLike = Pick<Storage, "getItem" | "setItem">;
+/** Current rung (0 = full quality) from session storage, so a reload continues down the ladder. */
+export declare function healStage(storage?: Pick<Storage, "getItem"> | undefined, ladder?: readonly HealRung[], storageKey?: string): number;
+/** Query parameters implied by rung `stage` (cumulative); callers merge them under the author's explicit parameters. */
+export declare function healParams(stage: number, ladder?: readonly HealRung[]): Record<string, string>;
+export declare function healRungName(stage: number, ladder?: readonly HealRung[]): string;
+/** True when every sampled texel of a downscaled frame is (almost) black. */
+export declare function isBlackFrame(rgba: ArrayLike<number>): boolean;
+export interface BlackFrameWatchOptions {
+    readonly enabled: boolean;
+    readonly ladder?: readonly HealRung[];
+    readonly storageKey?: string;
+    /** Shortens the detection window (tests only); production uses 20 frames then 23 consecutive black samples. */
+    readonly fastFrames?: number;
+    /** Reads a downscaled RGBA probe of the canvas. Defaults to a 16x16 2D canvas copy. */
+    readonly readProbe?: (canvas: HTMLCanvasElement) => ArrayLike<number> | undefined;
+    readonly storage?: StorageLike;
+    readonly currentUrl?: () => string;
+    /** Navigates to the next rung. Defaults to `location.replace`. */
+    readonly navigate?: (url: string) => void;
+    readonly log?: (code: string, message: string) => void;
+}
+export interface BlackFrameWatch {
+    /** Call right after a frame was drawn, in the same task (before the browser composites it). */
+    sample(framesDrawn: number): void;
+    readonly stage: number;
+    readonly rung: string;
+    /** True once the watch decided to reload one rung down. */
+    readonly escalated: boolean;
+}
+export declare function createBlackFrameWatch(canvas: HTMLCanvasElement, options: BlackFrameWatchOptions): BlackFrameWatch;
+export {};
+//# sourceMappingURL=blackFrame.d.ts.map

package/dist/safety/blackFrame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blackFrame.d.ts","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/blackFrame.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,mBAAmB,EAAE,SAAS,QAAQ,EAOlD,CAAC;AAEF,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAKnE,KAAK,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAUxD,mGAAmG;AACnG,wBAAgB,SAAS,CACvB,OAAO,GAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,SAAyB,EAC7D,MAAM,GAAE,SAAS,QAAQ,EAAwB,EACjD,UAAU,GAAE,MAAiC,GAC5C,MAAM,CAGR;AAED,wHAAwH;AACxH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,QAAQ,EAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAInH;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,QAAQ,EAAwB,GAAG,MAAM,CAErG;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,OAAO,CAM7D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,+GAA+G;IAC/G,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAiBD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAwCjH"}

package/dist/safety/blackFrame.js

@@ -0,0 +1,109 @@
+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 DEFAULT_FRAMES_NEEDED = 45;
+const BLACK_MAX_CHANNEL = 4;
+const PROBE_SIZE = 16;
+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;
+}
+/** True when every sampled texel of a downscaled frame is (almost) black. */
+export function isBlackFrame(rgba) {
+    if (rgba.length < 4)
+        return false;
+    for (let i = 0; i + 2 < rgba.length; i += 4) {
+        if (rgba[i] > BLACK_MAX_CHANNEL || rgba[i + 1] > BLACK_MAX_CHANNEL || rgba[i + 2] > BLACK_MAX_CHANNEL)
+            return false;
+    }
+    return true;
+}
+function defaultProbe() {
+    let ctx;
+    return (canvas) => {
+        if (ctx === undefined) {
+            const probe = document.createElement("canvas");
+            probe.width = PROBE_SIZE;
+            probe.height = PROBE_SIZE;
+            ctx = probe.getContext("2d", { willReadFrequently: true });
+        }
+        if (!ctx)
+            return undefined;
+        ctx.drawImage(canvas, 0, 0, PROBE_SIZE, PROBE_SIZE);
+        return ctx.getImageData(0, 0, PROBE_SIZE, PROBE_SIZE).data;
+    };
+}
+export function createBlackFrameWatch(canvas, options) {
+    const ladder = options.ladder ?? DEFAULT_HEAL_LADDER;
+    const storageKey = options.storageKey ?? DEFAULT_HEAL_STORAGE_KEY;
+    const storage = options.storage ?? safeStorage();
+    const minFrames = options.fastFrames ?? 20;
+    const samplesNeeded = Math.max(2, Math.ceil((options.fastFrames ?? DEFAULT_FRAMES_NEEDED) / 2));
+    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));
+    let consecutive = 0;
+    let escalated = false;
+    if (stage > 0)
+        log("SAFETY_COMPAT_MODE", `rung ${stage} (${healRungName(stage, ladder)}) after a black frame was detected`);
+    return {
+        stage,
+        rung: healRungName(stage, ladder),
+        get escalated() {
+            return escalated;
+        },
+        sample(framesDrawn) {
+            if (!options.enabled || escalated || framesDrawn < minFrames || framesDrawn % 2 !== 0)
+                return;
+            let black;
+            try {
+                const data = readProbe(canvas);
+                if (!data)
+                    return;
+                black = isBlackFrame(data);
+            }
+            catch {
+                return;
+            }
+            consecutive = black ? consecutive + 1 : 0;
+            if (consecutive < samplesNeeded || stage >= ladder.length)
+                return;
+            escalated = true;
+            storage?.setItem(storageKey, String(stage + 1));
+            const url = new URL(currentUrl());
+            for (const [key, value] of Object.entries(healParams(stage + 1, ladder)))
+                if (!url.searchParams.has(key))
+                    url.searchParams.set(key, value);
+            log("SAFETY_BLACK_FRAME", `reloading at rung ${stage + 1} (${healRungName(stage + 1, ladder)})`);
+            navigate(url.toString());
+        }
+    };
+}
+//# sourceMappingURL=blackFrame.js.map

package/dist/safety/blackFrame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blackFrame.js","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/blackFrame.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,mBAAmB,GAAwB;IACtD,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;IACtC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAC1C,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE;IAC7C,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IACxC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;IAC9C,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;CAC9D,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;AACnE,MAAM,qBAAqB,GAAG,EAAE,CAAC;AACjC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAC5B,MAAM,UAAU,GAAG,EAAE,CAAC;AAItB,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,cAAc,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,SAAS,CACvB,UAAgD,WAAW,EAAE,EAC7D,SAA8B,mBAAmB,EACjD,aAAqB,wBAAwB;IAE7C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC;IACxD,OAAO,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,wHAAwH;AACxH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,SAA8B,mBAAmB;IACzF,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3F,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,SAA8B,mBAAmB;IAC3F,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAE,CAAC,IAAI,CAAC;AAChF,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,IAAuB;IAClD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,CAAC,CAAE,GAAG,iBAAiB,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,GAAG,iBAAiB,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,GAAG,iBAAiB;YAAE,OAAO,KAAK,CAAC;IACzH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AA0BD,SAAS,YAAY;IACnB,IAAI,GAAgD,CAAC;IACrD,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC/C,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC;YACzB,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC;YAC1B,GAAG,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;QACpD,OAAO,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC;IAC7D,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAyB,EAAE,OAA+B;IAC9F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,mBAAmB,CAAC;IACrD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,wBAAwB,CAAC;IAClE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,WAAW,EAAE,CAAC;IACjD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChG,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,YAAY,EAAE,CAAC;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9E,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,KAAK,GAAG,CAAC;QAAE,GAAG,CAAC,oBAAoB,EAAE,QAAQ,KAAK,KAAK,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,oCAAoC,CAAC,CAAC;IAC5H,OAAO;QACL,KAAK;QACL,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC;QACjC,IAAI,SAAS;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,CAAC,WAAmB;YACxB,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,SAAS,IAAI,WAAW,GAAG,SAAS,IAAI,WAAW,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO;YAC9F,IAAI,KAAc,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;gBAC/B,IAAI,CAAC,IAAI;oBAAE,OAAO;gBAClB,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;YACT,CAAC;YACD,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1C,IAAI,WAAW,GAAG,aAAa,IAAI,KAAK,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO;YAClE,SAAS,GAAG,IAAI,CAAC;YACjB,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;YAChD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;YAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC3I,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,KAAK,GAAG,CAAC,KAAK,YAAY,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YACjG,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/safety/diagnosticsPanel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+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[];
+    } | 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/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,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,CAAA;KAAE,GAAG,SAAS,CAAC;CAC9L;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,CAgBnM;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CAsErG"}

package/dist/safety/diagnosticsPanel.js

@@ -0,0 +1,117 @@
+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)}`);
+        }
+    }
+    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/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/safety/index.d.ts

@@ -0,0 +1,47 @@
+import { type BlackFrameWatchOptions, type HealRung } from "./blackFrame.js";
+import { type DiagnosticsAppLike } from "./diagnosticsPanel.js";
+import { type QualitySwitches } from "./switches.js";
+export * from "./blackFrame.js";
+export * from "./diagnosticsPanel.js";
+export * from "./switches.js";
+export interface SafetyNetOptions {
+    /** Must be true (or an options object) for anything to run: the safety net is never on by default. */
+    readonly safety: boolean | SafetySettings;
+    readonly canvas?: HTMLCanvasElement;
+    readonly app?: DiagnosticsAppLike;
+    /** Query string to read switches from; defaults to `location.search`. */
+    readonly search?: string | URLSearchParams;
+}
+export interface SafetySettings {
+    /** Reload one rung down when the canvas stays black. Default true; `?heal=0` still wins. */
+    readonly selfHeal?: boolean;
+    /** Show the diagnostics panel. Default: only when the URL has `?diag=1`. */
+    readonly panel?: boolean | "query";
+    readonly ladder?: readonly HealRung[];
+    readonly watch?: Pick<BlackFrameWatchOptions, "fastFrames" | "readProbe" | "storage" | "currentUrl" | "navigate" | "storageKey" | "log">;
+}
+export interface SafetyReport {
+    readonly enabled: boolean;
+    readonly stage: number;
+    readonly rung: string;
+    readonly escalated: boolean;
+    readonly switches: QualitySwitches;
+    readonly panel: boolean;
+}
+export interface SafetyNet {
+    /** Switches in force (explicit URL parameters, then the black-frame rung's parameters). */
+    readonly switches: QualitySwitches;
+    /** Call after every presented frame with the running frame count. */
+    sample(framesDrawn: number): void;
+    /** What the safety net did; also exposed as `globalThis.__AURA_SAFETY__` while installed. */
+    report(): SafetyReport;
+    dispose(): void;
+}
+/**
+ * Opt-in runtime safety net for real-device failures: quality URL switches, black-frame self-heal and the diagnostics panel.
+ * Returns an inert handle (switches still parsed) unless `safety` is truthy. Reports through stable console codes
+ * (`SAFETY_COMPAT_MODE`, `SAFETY_BLACK_FRAME`), `report()` and the panel; `AuraApp.diagnostics()` is a read-only snapshot,
+ * so the safety net does not write into it.
+ */
+export declare function installSafetyNet(options: SafetyNetOptions): SafetyNet;
+//# sourceMappingURL=index.d.ts.map

package/dist/safety/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6F,KAAK,sBAAsB,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACxK,OAAO,EAA2B,KAAK,kBAAkB,EAA+B,MAAM,uBAAuB,CAAC;AACtH,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE7E,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAE9B,MAAM,WAAW,gBAAgB;IAC/B,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;CAC5C;AAED,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,KAAK,CAAC,CAAC;CAC1I;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,qEAAqE;IACrE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,6FAA6F;IAC7F,MAAM,IAAI,YAAY,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA8CrE"}

package/dist/safety/index.js

@@ -0,0 +1,61 @@
+import { createBlackFrameWatch, DEFAULT_HEAL_LADDER, healRungName, healStage } from "./blackFrame.js";
+import { installDiagnosticsPanel } from "./diagnosticsPanel.js";
+import { resolveQualitySwitches } from "./switches.js";
+export * from "./blackFrame.js";
+export * from "./diagnosticsPanel.js";
+export * from "./switches.js";
+const NOOP_REPORT = (switches) => ({ enabled: false, stage: 0, rung: "full", escalated: false, switches, panel: false });
+/**
+ * Opt-in runtime safety net for real-device failures: quality URL switches, black-frame self-heal and the diagnostics panel.
+ * Returns an inert handle (switches still parsed) unless `safety` is truthy. Reports through stable console codes
+ * (`SAFETY_COMPAT_MODE`, `SAFETY_BLACK_FRAME`), `report()` and the panel; `AuraApp.diagnostics()` is a read-only snapshot,
+ * so the safety net does not write into it.
+ */
+export function installSafetyNet(options) {
+    const settings = typeof options.safety === "object" ? options.safety : {};
+    const enabled = options.safety !== false && options.safety !== undefined;
+    const ladder = settings.ladder ?? DEFAULT_HEAL_LADDER;
+    const stage = enabled ? healStage(settings.watch?.storage, ladder, settings.watch?.storageKey) : 0;
+    const switches = resolveQualitySwitches({ search: options.search, healStage: stage, ladder });
+    if (!enabled) {
+        return { switches, sample() { }, report: () => NOOP_REPORT(switches), dispose() { } };
+    }
+    let watch;
+    if (options.canvas && settings.selfHeal !== false) {
+        watch = createBlackFrameWatch(options.canvas, { enabled: switches.heal, ladder, ...settings.watch });
+    }
+    const showPanel = settings.panel === true || ((settings.panel === undefined || settings.panel === "query") && switches.diag);
+    const report = () => ({
+        enabled: true,
+        stage: watch?.stage ?? stage,
+        rung: watch?.rung ?? healRungName(stage, ladder),
+        escalated: watch?.escalated ?? false,
+        switches,
+        panel: showPanel
+    });
+    let panel;
+    if (showPanel && typeof document !== "undefined") {
+        panel = installDiagnosticsPanel({
+            ...(options.app ? { app: options.app } : {}),
+            title: "Aura3D safety net (?diag=1)",
+            extraLines: () => {
+                const r = report();
+                const off = ["post", "shadow", "env", "sky", "aa"].filter((key) => !switches[key]);
+                return [`safety: rung ${r.stage} (${r.rung})${r.escalated ? " reloading" : ""} off:[${off.join(",")}] quality:${switches.quality} tm:${switches.toneMapping} heal:${switches.heal ? "on" : "off"}`];
+            }
+        });
+    }
+    const g = globalThis;
+    g.__AURA_SAFETY__ = report;
+    return {
+        switches,
+        sample: (framesDrawn) => watch?.sample(framesDrawn),
+        report,
+        dispose() {
+            panel?.dispose();
+            if (g.__AURA_SAFETY__ === report)
+                delete g.__AURA_SAFETY__;
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/safety/index.js.map

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

package/dist/safety/switches.d.ts

@@ -0,0 +1,27 @@
+import { type HealRung } from "./blackFrame.js";
+/**
+ * Quality URL switches shared by every game: `?post=0 ?shadow=0 ?env=0 ?sky=0 ?aa=0 ?quality=low ?tm=aces ?heal=0 ?diag=1`.
+ * Parsing is pure; a game decides what each switch changes in its own options. Rung parameters from the black-frame
+ * ladder are merged UNDER explicit parameters, so an author's URL always wins.
+ */
+export interface QualitySwitches {
+    readonly post: boolean;
+    readonly shadow: boolean;
+    readonly env: boolean;
+    readonly sky: boolean;
+    readonly aa: boolean;
+    readonly heal: boolean;
+    readonly diag: boolean;
+    readonly quality: "default" | "low";
+    readonly toneMapping: "default" | "aces";
+    /** The merged query parameters actually used (explicit + ladder). */
+    readonly params: Readonly<Record<string, string>>;
+}
+export interface ResolveQualitySwitchesOptions {
+    readonly search?: string | URLSearchParams;
+    /** Black-frame ladder rung currently in force (0 = none). */
+    readonly healStage?: number;
+    readonly ladder?: readonly HealRung[];
+}
+export declare function resolveQualitySwitches(options?: ResolveQualitySwitchesOptions): QualitySwitches;
+//# sourceMappingURL=switches.d.ts.map

package/dist/safety/switches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"switches.d.ts","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/switches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEjF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,KAAK,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,GAAG,MAAM,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAC3C,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CACvC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,6BAAkC,GAAG,eAAe,CAmBnG"}

package/dist/safety/switches.js

@@ -0,0 +1,23 @@
+import { DEFAULT_HEAL_LADDER, healParams } from "./blackFrame.js";
+export function resolveQualitySwitches(options = {}) {
+    const raw = options.search ?? (typeof location === "undefined" ? "" : location.search);
+    const query = raw instanceof URLSearchParams ? new URLSearchParams(raw) : new URLSearchParams(raw);
+    for (const [key, value] of Object.entries(healParams(options.healStage ?? 0, options.ladder ?? DEFAULT_HEAL_LADDER))) {
+        if (!query.has(key))
+            query.set(key, value);
+    }
+    const off = (key) => query.get(key) !== "0";
+    return {
+        post: off("post"),
+        shadow: off("shadow"),
+        env: off("env"),
+        sky: off("sky"),
+        aa: off("aa"),
+        heal: off("heal"),
+        diag: query.get("diag") === "1",
+        quality: query.get("quality") === "low" ? "low" : "default",
+        toneMapping: query.get("tm") === "aces" ? "aces" : "default",
+        params: Object.fromEntries(query.entries())
+    };
+}
+//# sourceMappingURL=switches.js.map

package/dist/safety/switches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"switches.js","sourceRoot":"","sources":["../../../../../packages/debug/src/safety/switches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AA4BjF,MAAM,UAAU,sBAAsB,CAAC,UAAyC,EAAE;IAChF,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,GAAG,YAAY,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IACnG,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,IAAI,mBAAmB,CAAC,CAAC,EAAE,CAAC;QACrH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC;IAC7D,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QACjB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;QACrB,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC;QACf,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC;QACf,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC;QACb,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG;QAC/B,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;QAC3D,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QAC5D,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@aura3d/debug",
-  "version": "4.0.7",
+  "version": "4.1.0",
   "type": "module",
   "dependencies": {
-    "@aura3d/animation": "4.0.7",
-    "@aura3d/rendering": "4.0.7",
-    "@aura3d/physics": "4.0.7"
+    "@aura3d/animation": "4.1.0",
+    "@aura3d/physics": "4.1.0",
+    "@aura3d/rendering": "4.1.0"
   },
   "exports": {
     ".": {