Aura3D 4.1.1

Superseded. This version is deprecated. Upgrade to Aura3D 5.5.5; see the 4.x to 5.0 migration guide.

A patch release for the problems found by live verification of 4.1.0 and by the Apex Overdrive art pass. No API removals.

Fixes

• Fix: the black-frame self-heal no longer fires on healthy pages. Live verification of 4.1.0 showed it reloading Aura Slam while the loading overlay was still up and a slow CPU renderer had not drawn its first frame, and dark valid scenes could read as black. The watch now waits for readiness (loaded document, no visible loading overlay, no in-flight asset fetches, the app's own isReady), counts frames from that moment, samples a 48x32 nearest-neighbour grid instead of a blurred 16x16 copy, calls a frame black only when 0.2% or fewer of the samples are lit, and requires that to persist for 12 samples over at least max(4 s, 40 x the median frame time), so slow renderers wait longer. It steps down once per page load and records why (?diag=1, SAFETY_COMPAT_MODE). The showcase games and Drift & Deliver share this one implementation. installBlackFrameGuard (for pages driven by the a3d-qr flag ladder), QR_HEAL_LADDER, qrHealStage, qrHealRungName and qrHealUrl are now exported from @aura3d/debug. Docs: docs/api/safety-net.md.
• Fix: a custom shader that fails to compile or link no longer blanks the whole frame, and the failure is no longer silent. A duplicate GLSL variable in one material.custom sky shader threw out of the draw loop and took every other draw with it; only the black-frame self-heal noticed. Compile, link and (WebGPU) missing-WGSL failures now get the stable codes CUSTOM_SHADER_COMPILE_FAILED, CUSTOM_SHADER_LINK_FAILED and CUSTOM_SHADER_WGSL_MISSING, a once-per-material console.error with the driver log and the offending source lines (mapped back to your own GLSL line when possible), structured app.diagnostics().shaderFailures plus a summary in errors (so route health and check-deploy report error), and a line in the ?diag=1 panel. The failing item is skipped (flat magenta with ?diag=1 or renderer.shaderFailures: "magenta") while every other draw continues; strict mode (strict, A3D_QR_STRICT, renderer.materialStrictness: "strict", or renderer.shaderFailures: "throw") fails the frame with AuraRuntimeError("custom-shader-compile-failed") (recorded in diagnostics().errors by the async production renderer). effects.shaderPass compile failures are reported through the same record. A failed program is not recompiled every frame. Docs: docs/api/shader-diagnostics.md; @aura3d/rendering exports getShaderFailures, clearShaderFailures, setShaderFailureMode, formatShaderFailure, parseShaderLog.

Tooling and tests (not published packages)

• Test: public-example-boundary accepts url: new URL("./x.glb", import.meta.url) as a typed asset definition (the form the Apex Overdrive vehicles use, with a sha256 alongside), instead of flagging it as a raw model URL.
• Live verification of 4.1.0 (evidence/live-410/, tests/browser/live-index-games.spec.ts): software-WebGL2 smoke over the Crayon ports and the 15 index games, with hero frames and a results file. Two index games (Cross Hop, Iron Crown) looked near-black in that capture; the regression probe (tests/browser/pinregress.spec.ts, evidence/regress-fix/) showed both render fully at engine defaults, and the dark frames were the old guard escalating during a 95 MB and 38 MB asset load. That is what the guard fix above addresses.

Known issues

• The legacy post chain tone-maps and encodes on its own and bypasses OutputPass until PostGraph v2 migrates it, so frames with bloom or vignette on are about 25 to 40% darker and less saturated than with post off. This is an engine finding and is not patched in 4.1.1.
• Phase B (a blind model judge cannot tell a Crayon port from its original) is still not met: the judge still separates every port from its original (it picks the original in 73% to 100% of trials, except Splat Rush where it picked the port as the original in 83%, a reversed result, not a pass).
• Real-GPU confirmation is pending for several ports (Drift & Deliver, Silt & Signal, Last Train's full Enter, E, W path, HEATSINK and Last Train in an automated run); all automated checks ran on software WebGL2.