@aura3d/engine 4.3.7 → 4.6.0

package/dist/engine/agent-api/app/parentFit.js

@@ -1,8 +1,8 @@
 const EPSILON = 0.5;
-export function createParentFit(canvas) {
-    const own = canvas.getBoundingClientRect();
-    const mountedWidth = parseFloat(canvas.style.width) || own.width || canvas.clientWidth;
-    const mountedHeight = parseFloat(canvas.style.height) || own.height || canvas.clientHeight;
+export function createParentFit(canvas, own) {
+    const mountedRect = canvas.getBoundingClientRect();
+    const mountedWidth = parseFloat(canvas.style.width) || mountedRect.width || canvas.clientWidth;
+    const mountedHeight = parseFloat(canvas.style.height) || mountedRect.height || canvas.clientHeight;
     let contentWidth = false;
     let contentHeight = false;
     let lastParentWidth = 0;
@@ -12,20 +12,24 @@ export function createParentFit(canvas) {
             const parentRect = canvas.parentElement?.getBoundingClientRect();
             lastParentWidth = parentRect?.width ?? 0;
             lastParentHeight = parentRect?.height ?? 0;
-            const cssWidth = contentWidth && mountedWidth > 0 ? mountedWidth : lastParentWidth || canvas.clientWidth || fallbackWidth;
-            const cssHeight = contentHeight && mountedHeight > 0 ? mountedHeight : lastParentHeight || canvas.clientHeight || fallbackHeight;
-            return { cssWidth, cssHeight };
+            const ownBox = own && (own.width || own.height) ? own.box() : undefined;
+            const ownWidth = Boolean(own?.width && ownBox && ownBox.width > 0);
+            const ownHeight = Boolean(own?.height && ownBox && ownBox.height > 0);
+            const cssWidth = ownWidth ? ownBox.width : contentWidth && mountedWidth > 0 ? mountedWidth : lastParentWidth || canvas.clientWidth || fallbackWidth;
+            const cssHeight = ownHeight ? ownBox.height : contentHeight && mountedHeight > 0 ? mountedHeight : lastParentHeight || canvas.clientHeight || fallbackHeight;
+            return { cssWidth, cssHeight, ownWidth, ownHeight };
         },
         settle() {
             const parentRect = canvas.parentElement?.getBoundingClientRect();
             if (!parentRect)
                 return false;
             let frozen = false;
-            if (!contentWidth && Math.abs(parentRect.width - lastParentWidth) > EPSILON) {
+            // Axes sized by the page's CSS do not follow the parent, so they cannot feed back into it.
+            if (!own?.width && !contentWidth && Math.abs(parentRect.width - lastParentWidth) > EPSILON) {
                 contentWidth = true;
                 frozen = true;
             }
-            if (!contentHeight && Math.abs(parentRect.height - lastParentHeight) > EPSILON) {
+            if (!own?.height && !contentHeight && Math.abs(parentRect.height - lastParentHeight) > EPSILON) {
                 contentHeight = true;
                 frozen = true;
             }

package/dist/engine/agent-api/app/parentFit.js.map

@@ -1 +1 @@
-{"version":3,"file":"parentFit.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/app/parentFit.ts"],"names":[],"mappings":"AAqBA,MAAM,OAAO,GAAG,GAAG,CAAC;AAEpB,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;IAC3C,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,IAAI,MAAM,CAAC,WAAW,CAAC;IACvF,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC;IAC3F,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,OAAO;QACL,OAAO,CAAC,aAAa,EAAE,cAAc;YACnC,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,qBAAqB,EAAE,CAAC;YACjE,eAAe,GAAG,UAAU,EAAE,KAAK,IAAI,CAAC,CAAC;YACzC,gBAAgB,GAAG,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,YAAY,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,IAAI,MAAM,CAAC,WAAW,IAAI,aAAa,CAAC;YAC1H,MAAM,SAAS,GAAG,aAAa,IAAI,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,IAAI,MAAM,CAAC,YAAY,IAAI,cAAc,CAAC;YACjI,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QACjC,CAAC;QACD,MAAM;YACJ,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,qBAAqB,EAAE,CAAC;YACjE,IAAI,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC9B,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,eAAe,CAAC,GAAG,OAAO,EAAE,CAAC;gBAAC,YAAY,GAAG,IAAI,CAAC;gBAAC,MAAM,GAAG,IAAI,CAAC;YAAC,CAAC;YACpH,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EAAE,CAAC;gBAAC,aAAa,GAAG,IAAI,CAAC;gBAAC,MAAM,GAAG,IAAI,CAAC;YAAC,CAAC;YACxH,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"parentFit.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/app/parentFit.ts"],"names":[],"mappings":"AAmCA,MAAM,OAAO,GAAG,GAAG,CAAC;AAEpB,MAAM,UAAU,eAAe,CAAC,MAAuB,EAAE,GAAe;IACtE,MAAM,WAAW,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;IACnD,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,KAAK,IAAI,MAAM,CAAC,WAAW,CAAC;IAC/F,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC;IACnG,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,OAAO;QACL,OAAO,CAAC,aAAa,EAAE,cAAc;YACnC,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,qBAAqB,EAAE,CAAC;YACjE,eAAe,GAAG,UAAU,EAAE,KAAK,IAAI,CAAC,CAAC;YACzC,gBAAgB,GAAG,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC;YAC3C,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,KAAK,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACnE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,MAAM,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACtE,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAO,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,IAAI,MAAM,CAAC,WAAW,IAAI,aAAa,CAAC;YACrJ,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,MAAO,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,IAAI,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,IAAI,MAAM,CAAC,YAAY,IAAI,cAAc,CAAC;YAC9J,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QACtD,CAAC;QACD,MAAM;YACJ,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,qBAAqB,EAAE,CAAC;YACjE,IAAI,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC9B,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,2FAA2F;YAC3F,IAAI,CAAC,GAAG,EAAE,KAAK,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,eAAe,CAAC,GAAG,OAAO,EAAE,CAAC;gBAAC,YAAY,GAAG,IAAI,CAAC;gBAAC,MAAM,GAAG,IAAI,CAAC;YAAC,CAAC;YACnI,IAAI,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EAAE,CAAC;gBAAC,aAAa,GAAG,IAAI,CAAC;gBAAC,MAAM,GAAG,IAAI,CAAC;YAAC,CAAC;YACxI,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/agent-api/app/renderPath.d.ts

@@ -0,0 +1,86 @@
+import { type AuraQualityMode, type BloomFusionConfig, type DirectPathItemLike, type RenderPathDecision } from "../../../rendering/index.js";
+import type { AuraBloomFusion, QrFlags } from "../../../rendering/contracts/index.js";
+import type { AuraCreateAppOptions, AuraSceneSnapshot } from "../nodes/types.js";
+/** What `app.diagnostics().renderPath` reports. */
+export interface AuraRenderPathReport {
+    readonly path: RenderPathDecision["path"];
+    readonly quality: AuraQualityMode;
+    readonly reason: string;
+    /**
+     * Bloom pass fusion mode that applies to this mount. `"off"` whenever no fused bloom pass can be issued: quality `production` or
+     * `safe-basic`, the direct path (no post chain), the legacy LDR route (not HDR, so the pyramid never fuses), or a scene with no
+     * bloom effect. Otherwise the selected mode. The pyramid itself additionally needs a five-mip-or-fewer plan, which depends on the
+     * canvas size and is only known at render time.
+     */
+    readonly bloomFusion: AuraBloomFusion | "off";
+}
+/** Fusion is allowed only under quality `auto` or `cinematic`; the mount (`applyRenderPathToCanvas`) and the report both use this. */
+export declare function bloomFusionAllowed(quality: AuraQualityMode): boolean;
+export interface AppRenderPath {
+    readonly report: AuraRenderPathReport;
+    /** Flags to hand the renderer; the app's own flags unchanged on the HDR path. */
+    readonly flags: QrFlags;
+    /**
+     * True when this mount chose the direct path over the HDR one: the source then carries no
+     * postprocess at all (no default tone-mapping chain), so the forward pass renders straight into
+     * the canvas framebuffer and encodes in-shader.
+     */
+    readonly direct: boolean;
+    /**
+     * Warnings for `diagnostics().warnings`: ignored URL switches (RP-04, `QUALITY_URL_IGNORED:`) and what `safe-basic` does not
+     * render (RP-06, `SAFE_BASIC_DROPS:`).
+     */
+    readonly warnings: readonly string[];
+}
+/** Record (per canvas, per mount) that the direct path was chosen; read by the render-input and clear-colour code. */
+export declare function setDirectRenderPath(canvas: object, direct: boolean): void;
+/** Record (per canvas, per mount) that look-neutral bloom pass fusion is allowed: quality `auto` or `cinematic`, never `production`. */
+export declare function setFusedBloomPasses(canvas: object, enabled: boolean): void;
+export declare function isFusedBloomPasses(canvas: object | undefined): boolean;
+/** Record this mount's route on the canvas: whether it is direct, and whether bloom pass fusion is allowed (one predicate: `bloomFusionAllowed`). */
+export declare function applyRenderPathToCanvas(canvas: object, renderPath: Pick<AppRenderPath, "direct" | "report">): void;
+/** The device fields the fused bloom pyramid reads. */
+export interface BloomFusionDevice {
+    bloomFusedPasses?: boolean;
+    bloomFusion?: BloomFusionConfig;
+}
+/**
+ * Configure a freshly created render device for this canvas's route: fused bloom passes plus the selected mode when the mount
+ * allowed fusion (`auto` / `cinematic`), nothing at all otherwise so `production` keeps the original pass sequence.
+ */
+export declare function configureBloomFusionDevice(device: BloomFusionDevice, canvas: object | undefined, rendererOptions: AuraCreateAppOptions["renderer"]): void;
+export declare function isDirectRenderPath(canvas: object | undefined): boolean;
+/** Add a reason that keeps `canvas` off the direct path; returns a release function (reference counted per reason). */
+export declare function vetoDirectPath(canvas: object, reason: string): () => void;
+export declare function directPathVetoReasons(canvas: object | undefined): string[];
+/** RP-01: decoded-material blockers of a mounted scene's GLB actors (their render items at the default placement). */
+export declare function decodedModelDirectPathBlockers(actors: readonly {
+    readonly actor: {
+        collectRenderItems(): readonly DirectPathItemLike[];
+    };
+}[]): string[];
+/** Called by the mount once its GLBs are decoded (direct path only); read once by the frame loop through {@link takeDecodedDirectPathBlockers}. */
+export declare function recordDecodedDirectPathBlockers(canvas: object, blockers: readonly string[]): void;
+export declare function takeDecodedDirectPathBlockers(canvas: object): readonly string[];
+/** Reasons this scene needs the HDR target. Conservative: anything not known to render identically on the direct path is listed. */
+export declare function renderPathBlockers(snapshot: AuraSceneSnapshot, options: AuraCreateAppOptions): string[];
+/**
+ * The node-level part of {@link renderPathBlockers}: effects other than fog, node kinds the direct path does not draw, HDRI
+ * environments, and custom, transmissive or transparent materials (authored, from the asset manifest, or overrides). Also used for
+ * nodes added at runtime (RP-03).
+ */
+export declare function nodeDirectPathBlockers(nodes: AuraSceneSnapshot["nodes"]): string[];
+export interface ResolveAppRenderPathContext {
+    /** URL query to read the debug switches from; defaults to `location.search`. */
+    readonly search?: string | null;
+    /** Reasons found after mount that keep this canvas off the direct path (see {@link vetoDirectPath}). */
+    readonly extraBlockers?: readonly string[];
+}
+export declare function resolveAppRenderPath(snapshot: AuraSceneSnapshot, options: AuraCreateAppOptions, flags: QrFlags, context?: ResolveAppRenderPathContext): AppRenderPath;
+/**
+ * Whether the WebGL drawing buffer must survive presentation: capture and
+ * evidence runs read the canvas after the frame was presented. An explicit
+ * `preserveDrawingBuffer` option wins; otherwise `?capture=1` / `?qa=1`.
+ */
+export declare function wantsPreservedDrawingBuffer(options: Pick<AuraCreateAppOptions, "preserveDrawingBuffer">, search?: string | null): boolean;
+//# sourceMappingURL=renderPath.d.ts.map

package/dist/engine/agent-api/app/renderPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderPath.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/app/renderPath.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/app/renderPath.js

@@ -0,0 +1,269 @@
+// beat-three.js L-P1: pick the render path for one mount (direct canvas MSAA vs HDR multisampled target).
+import { directPathItemBlockers, isQualityMode, qrCoreOutputOn, resolveBloomFusionConfig, resolveRenderPath, withDirectPath } from "../../../rendering/index.js";
+import { groups } from "../nodes/groups.js";
+import { ignoreInvalidUrlValue, parseBloomFusionOption } from "./rendererOptions.js";
+/** Fusion is allowed only under quality `auto` or `cinematic`; the mount (`applyRenderPathToCanvas`) and the report both use this. */
+export function bloomFusionAllowed(quality) {
+    return quality === "auto" || quality === "cinematic";
+}
+/**
+ * The bloom fusion mode to report. The pyramid fuses only on the HDR route (`hdr-msaa`) and only when the scene has a bloom
+ * effect (the only source of a bloom pass), so every other combination reports `"off"`. The option is validated first so a
+ * typo throws whatever the quality.
+ */
+function reportedBloomFusion(quality, path, legacyLdrRoute, snapshot, options, search, policy) {
+    const mode = parseBloomFusionOption(options.renderer, search, policy);
+    if (!bloomFusionAllowed(quality) || path !== "hdr-msaa" || legacyLdrRoute)
+        return "off";
+    const hasBloom = groups.flatten(snapshot.nodes).some((node) => node.kind === "effect" && node.effect === "bloom");
+    return hasBloom ? mode : "off";
+}
+const directPathCanvases = new WeakSet();
+/** Record (per canvas, per mount) that the direct path was chosen; read by the render-input and clear-colour code. */
+export function setDirectRenderPath(canvas, direct) {
+    if (direct)
+        directPathCanvases.add(canvas);
+    else
+        directPathCanvases.delete(canvas);
+}
+const fusedBloomCanvases = new WeakSet();
+/** Record (per canvas, per mount) that look-neutral bloom pass fusion is allowed: quality `auto` or `cinematic`, never `production`. */
+export function setFusedBloomPasses(canvas, enabled) {
+    if (enabled)
+        fusedBloomCanvases.add(canvas);
+    else
+        fusedBloomCanvases.delete(canvas);
+}
+export function isFusedBloomPasses(canvas) {
+    return canvas !== undefined && fusedBloomCanvases.has(canvas);
+}
+/** Record this mount's route on the canvas: whether it is direct, and whether bloom pass fusion is allowed (one predicate: `bloomFusionAllowed`). */
+export function applyRenderPathToCanvas(canvas, renderPath) {
+    setDirectRenderPath(canvas, renderPath.direct);
+    setFusedBloomPasses(canvas, bloomFusionAllowed(renderPath.report.quality));
+}
+/**
+ * Configure a freshly created render device for this canvas's route: fused bloom passes plus the selected mode when the mount
+ * allowed fusion (`auto` / `cinematic`), nothing at all otherwise so `production` keeps the original pass sequence.
+ */
+export function configureBloomFusionDevice(device, canvas, rendererOptions) {
+    if (!isFusedBloomPasses(canvas))
+        return;
+    device.bloomFusedPasses = true;
+    device.bloomFusion = resolveBloomFusionConfig(parseBloomFusionOption(rendererOptions));
+}
+export function isDirectRenderPath(canvas) {
+    return canvas !== undefined && directPathCanvases.has(canvas);
+}
+/*
+ * RP-01 / RP-03: reasons, found after the path was chosen, why this canvas must leave the direct path. The direct-path decision
+ * reads the authored snapshot, so it cannot see a GLB's own BLEND or transmission materials (known only once decoded) or a custom
+ * post pass registered after mount. Each mount on the canvas reads these as extra blockers, so the re-mount takes the HDR target.
+ */
+const directPathVetoes = new WeakMap();
+/** Add a reason that keeps `canvas` off the direct path; returns a release function (reference counted per reason). */
+export function vetoDirectPath(canvas, reason) {
+    let reasons = directPathVetoes.get(canvas);
+    if (!reasons)
+        directPathVetoes.set(canvas, (reasons = new Map()));
+    reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const count = (reasons.get(reason) ?? 1) - 1;
+        if (count > 0)
+            reasons.set(reason, count);
+        else
+            reasons.delete(reason);
+    };
+}
+export function directPathVetoReasons(canvas) {
+    return canvas === undefined ? [] : [...(directPathVetoes.get(canvas)?.keys() ?? [])];
+}
+/** RP-01: decoded-material blockers of a mounted scene's GLB actors (their render items at the default placement). */
+export function decodedModelDirectPathBlockers(actors) {
+    if (actors.length === 0)
+        return [];
+    const items = [];
+    for (const entry of actors) {
+        try {
+            items.push(...entry.actor.collectRenderItems());
+        }
+        catch {
+            // An actor that cannot collect here is not evidence either way; the frame loop reports its own errors.
+        }
+    }
+    return directPathItemBlockers(items);
+}
+const decodedBlockers = new WeakMap();
+/** Called by the mount once its GLBs are decoded (direct path only); read once by the frame loop through {@link takeDecodedDirectPathBlockers}. */
+export function recordDecodedDirectPathBlockers(canvas, blockers) {
+    if (blockers.length > 0)
+        decodedBlockers.set(canvas, blockers);
+    else
+        decodedBlockers.delete(canvas);
+}
+export function takeDecodedDirectPathBlockers(canvas) {
+    const blockers = decodedBlockers.get(canvas) ?? [];
+    decodedBlockers.delete(canvas);
+    return blockers;
+}
+/** Effects the forward pass draws itself; every other effect is a post pass or a frame contributor that reads the HDR target. */
+const FORWARD_ONLY_EFFECTS = new Set(["fog"]);
+const DIRECT_SAFE_NODE_KINDS = new Set(["model", "primitive", "group", "light", "environment", "interaction", "label"]);
+/** Reasons this scene needs the HDR target. Conservative: anything not known to render identically on the direct path is listed. */
+export function renderPathBlockers(snapshot, options) {
+    const blockers = [];
+    if (options.output !== undefined || options.renderer?.output !== undefined)
+        blockers.push("output options (tone mapping, exposure, dithering) are authored");
+    if (options.renderer?.backend !== undefined && options.renderer.backend !== "webgl2")
+        blockers.push(`backend ${String(options.renderer.backend)}`);
+    if (typeof location !== "undefined" && /[?&](aura3d-tonemap|tm|aura3d-exp|exp)=/.test(location.search))
+        blockers.push("URL tone-mapping or exposure override");
+    if (snapshot.backgroundToneMapped === false)
+        blockers.push("background opts out of tone mapping");
+    // RP-02: the background-image shader encodes with its own ACES fit (Narkowicz), not the r185 curve the direct path's forward
+    // shader uses, so on the direct path the backdrop and the scene would be tone-mapped differently (linear 0.18 grey: 141 vs 127).
+    if (snapshot.backgroundImage !== undefined)
+        blockers.push("background image");
+    for (const reason of nodeDirectPathBlockers(snapshot.nodes))
+        blockers.push(reason);
+    return blockers;
+}
+/**
+ * The node-level part of {@link renderPathBlockers}: effects other than fog, node kinds the direct path does not draw, HDRI
+ * environments, and custom, transmissive or transparent materials (authored, from the asset manifest, or overrides). Also used for
+ * nodes added at runtime (RP-03).
+ */
+export function nodeDirectPathBlockers(nodes) {
+    const blockers = [];
+    const seen = new Set();
+    const note = (message) => {
+        if (seen.has(message))
+            return;
+        seen.add(message);
+        blockers.push(message);
+    };
+    for (const node of groups.flatten(nodes)) {
+        if (node.kind === "effect") {
+            if (!FORWARD_ONLY_EFFECTS.has(node.effect))
+                note(`effect "${node.effect}"`);
+            continue;
+        }
+        if (!DIRECT_SAFE_NODE_KINDS.has(node.kind)) {
+            note(`${node.kind} node`);
+            continue;
+        }
+        // A visible HDRI background is encoded by the environment-background shader's own (different) filmic curve.
+        if (node.kind === "environment" && node.environment === "hdri")
+            note("hdri environment");
+        if (node.kind !== "model" && node.kind !== "primitive")
+            continue;
+        if (node.kind === "model")
+            for (const reason of modelAssetBlockers(node))
+                note(reason);
+        const material = node.material;
+        if (!material)
+            continue;
+        if (material.kind !== undefined)
+            note(`${material.kind} material`);
+        if (material.shader !== undefined)
+            note(`shader material "${material.shader}"`);
+        if (typeof material.transmission === "number" && material.transmission > 0)
+            note("transmission material");
+        // Blending happens after the in-shader encode on the direct path (display space) but before it on the HDR path (linear).
+        if (material.alphaMode === "blend" || material.blend !== undefined || (typeof material.opacity === "number" && material.opacity < 1))
+            note("transparent material");
+    }
+    return blockers;
+}
+/**
+ * RP-01: material facts the asset manifest records for a typed GLB (`metadata.materialMetadata`, written by `aura3d assets add`
+ * and `assets typegen`), plus `materialOverrides` opacity. A BLEND or partly transparent material blends after the in-shader encode
+ * on the direct path. Transmission is not in the manifest; the mount catches it after decode (`decodedModelDirectPathBlockers`).
+ */
+function modelAssetBlockers(node) {
+    const reasons = [];
+    const facts = node.asset?.metadata?.materialMetadata;
+    if (Array.isArray(facts)) {
+        const transparent = facts.some((fact) => fact !== null && typeof fact === "object"
+            // glTF ignores base-colour alpha on OPAQUE and MASK materials, so opacity counts only when no alpha mode was recorded.
+            && (typeof fact.alphaMode === "string" ? fact.alphaMode.toUpperCase() === "BLEND" : typeof fact.opacity === "number" && fact.opacity < 1));
+        if (transparent)
+            reasons.push("model asset has a transparent (BLEND) material");
+    }
+    if (node.materialOverrides?.some((override) => typeof override.opacity === "number" && override.opacity < 1))
+        reasons.push("transparent material override");
+    return reasons;
+}
+function requestedQuality(options, search, policy) {
+    let fromOptions;
+    if (options.quality !== undefined) {
+        if (!isQualityMode(options.quality)) {
+            throw new Error(`QUALITY_OPTION_INVALID:quality=${String(options.quality)} (expected auto|production|safe-basic|cinematic)`);
+        }
+        fromOptions = options.quality;
+    }
+    // `?aura3d-render=<mode>` wins over the option (like `?aura3d-quality=`): compare a page's two render paths without a rebuild.
+    // RP-04: a typo there warns and keeps the code option (strict apps still throw).
+    const fromUrl = search ? new URLSearchParams(search).get("aura3d-render") : null;
+    if (fromUrl !== null) {
+        if (isQualityMode(fromUrl))
+            return fromUrl;
+        ignoreInvalidUrlValue(`?aura3d-render=${fromUrl} (expected auto|production|safe-basic|cinematic); using "${fromOptions ?? "auto"}"`, policy);
+    }
+    // `renderer.qualityProfile` is a deprecated pixel-ratio/draw-budget preset, not a pipeline request.
+    return fromOptions;
+}
+export function resolveAppRenderPath(snapshot, options, flags, context = {}) {
+    const search = context.search !== undefined ? context.search : typeof location !== "undefined" ? location.search : null;
+    const warnings = [];
+    const policy = { strict: options.strict ?? flags.on("A3D_QR_STRICT"), warnings };
+    const quality = requestedQuality(options, search, policy) ?? "auto";
+    if (!qrCoreOutputOn(flags)) {
+        const explicit = flags.values.A3D_QR_CORE_OUTPUT !== undefined;
+        return {
+            report: { path: "direct", quality, reason: explicit ? "A3D_QR_CORE_OUTPUT is off: legacy LDR route" : "A3D_QR_CORE is off: legacy LDR route (its own post chain is kept)", bloomFusion: reportedBloomFusion(quality, "direct", true, snapshot, options, search, policy) },
+            flags,
+            direct: false,
+            warnings
+        };
+    }
+    if (flags.values.A3D_QR_CORE_OUTPUT !== undefined) {
+        return { report: { path: "hdr-msaa", quality, reason: "A3D_QR_CORE_OUTPUT is set explicitly", bloomFusion: reportedBloomFusion(quality, "hdr-msaa", false, snapshot, options, search, policy) }, flags, direct: false, warnings };
+    }
+    // RP-06: blockers are computed for safe-basic too, so what it does not render is named instead of dropped silently.
+    const blockers = quality === "auto" || quality === "safe-basic"
+        ? [...new Set([...renderPathBlockers(snapshot, options), ...(context.extraBlockers ?? [])])]
+        : [];
+    const decision = resolveRenderPath({ quality, blockers });
+    if (quality === "safe-basic" && blockers.length > 0) {
+        warnings.push(`SAFE_BASIC_DROPS: quality "safe-basic" renders on the direct path, which has no post chain or HDR target, so these are not rendered: ${blockers.join("; ")}. Use quality "auto" or "production" to keep them.`);
+    }
+    return {
+        report: { path: decision.path, quality: decision.quality, reason: decision.reason, bloomFusion: reportedBloomFusion(decision.quality, decision.path, false, snapshot, options, search, policy) },
+        flags: decision.path === "direct" ? withDirectPath(flags) : flags,
+        direct: decision.path === "direct",
+        warnings
+    };
+}
+/**
+ * Whether the WebGL drawing buffer must survive presentation: capture and
+ * evidence runs read the canvas after the frame was presented. An explicit
+ * `preserveDrawingBuffer` option wins; otherwise `?capture=1` / `?qa=1`.
+ */
+export function wantsPreservedDrawingBuffer(options, search = typeof location !== "undefined" ? location.search : null) {
+    if (typeof options.preserveDrawingBuffer === "boolean")
+        return options.preserveDrawingBuffer;
+    if (!search)
+        return false;
+    const params = new URLSearchParams(search);
+    const on = (key) => {
+        const raw = params.get(key);
+        return raw !== null && raw !== "0" && raw.toLowerCase() !== "false";
+    };
+    return on("capture") || on("qa");
+}
+//# sourceMappingURL=renderPath.js.map

package/dist/engine/agent-api/app/renderPath.js.map

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

package/dist/engine/agent-api/app/rendererOptions.d.ts

@@ -1,4 +1,5 @@
 import type { AuraCreateAppRendererOptions, AuraRendererQualityPreset, AuraRendererQualityProfile, AuraRendererQualityProfileId } from "../nodes/types.js";
+import { type AuraBloomFusion } from "../../../rendering/contracts/index.js";
 /**
  * PRD 11 Phase 1 freeze (§6.2): thrown when a caller requests the frozen
  * `experimental-webgpu` quality profile. The union member stays for CCR
@@ -41,5 +42,34 @@ export declare function resetRendererOptionDeprecationsForTests(): void;
  */
 export declare function parseQualityRendererOptions(renderer: AuraCreateAppRendererOptions | undefined, search?: string | null, root?: {
     readonly performanceQuality?: unknown;
-}): ParsedQualityRendererOptions;
+}, urlPolicy?: Pick<UrlOptionPolicy, "strict">): ParsedQualityRendererOptions;
+/** How URL-sourced debug switches behave on an invalid value (RP-04). */
+export interface UrlOptionPolicy {
+    /** Throw on an invalid URL value, like an invalid code option. Default false: warn and fall back. */
+    readonly strict?: boolean;
+    /** Receives one `QUALITY_URL_IGNORED:` message per ignored URL value. */
+    readonly warnings?: string[];
+    /** Also `console.warn` the message (once per message). Default true; false when the caller prints `warnings` itself. */
+    readonly console?: boolean;
+}
+/**
+ * RP-04: a typo in a debug URL switch (`?aura3d-render=`, `?aura3d-bloom-fusion=`, `?aura3d-quality=`, `?aura3d-adaptive=`) used to
+ * throw inside the mount, so every game showed its "needs WebGL 2" error screen. URL values are a tester's switch, not code: warn
+ * once (console and `diagnostics().warnings`) and keep the code option or default. Strict apps keep the throw.
+ */
+export declare function ignoreInvalidUrlValue(message: string, policy: UrlOptionPolicy | undefined): void;
+/**
+ * Bloom pass-fusion mode (PRD beat-threejs-2 contract 2.1): `renderer.bloomFusion` (`"separable"` default | `"fused-2d"`),
+ * overridden by `?aura3d-bloom-fusion=`. An invalid code option throws so a typo never silently runs the default; an invalid URL
+ * value warns and falls back to the code option (RP-04) unless `policy.strict`. The mode only takes effect under
+ * `quality: "auto"` / `"cinematic"`; `production` never fuses.
+ */
+export declare function parseBloomFusionOption(renderer: Pick<AuraCreateAppRendererOptions, "bloomFusion"> | undefined, search?: string | null, policy?: UrlOptionPolicy): AuraBloomFusion;
+/**
+ * Top-tennis C11 (engine part): `renderer.quality` diagnostics, reported in `diagnostics().warnings` (not the console, since the
+ * string form is valid). A tier-name string is a fixed tier: every device, phones included, mounts at that tier, which a reader
+ * of `renderer: { quality: "high" }` easily takes for a no-op or for "best available". An unknown name used to mount at "high"
+ * with no message while the quality lane is off.
+ */
+export declare function rendererQualityWarnings(renderer: Pick<AuraCreateAppRendererOptions, "quality"> | undefined): string[];
 //# sourceMappingURL=rendererOptions.d.ts.map

package/dist/engine/agent-api/app/rendererOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rendererOptions.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/app/rendererOptions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAE3J;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAElC,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,GAAG,YAAY,EAAE,yBAAyB,CAAC,CAqB5G,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,4BAA4B,EAAE,0BAA0B,CAAC,CA6D9G,CAAC;AAEF,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,4BAA4B,GAAG,SAAS,GAAG,0BAA0B,CAOtH;AAED,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,4BAA4B,GAAG,SAAS,GAAG,QAAQ,CAAC,4BAA4B,CAAC,GAAG;IAC7I,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;CAC9C,CAYA;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7E;AAQD,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,KAAK,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,KAAK,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAiBD,kFAAkF;AAClF,wBAAgB,uCAAuC,IAAI,IAAI,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,4BAA4B,GAAG,SAAS,EAClD,MAAM,GAAE,MAAM,GAAG,IAA+D,EAChF,IAAI,GAAE;IAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAO,GACnD,4BAA4B,CA4D9B"}
+{"version":3,"file":"rendererOptions.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/app/rendererOptions.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/app/rendererOptions.js

@@ -1,4 +1,5 @@
 // PR 0b-1 carve-out (CONTRACTS.md §3.2) — verbatim move from agent-api/index.ts; 0 changed logic lines.
+import { DEFAULT_BLOOM_FUSION_MODE, isBloomFusion } from "../../../rendering/contracts/index.js";
 /**
  * PRD 11 Phase 1 freeze (§6.2): thrown when a caller requests the frozen
  * `experimental-webgpu` quality profile. The union member stays for CCR
@@ -140,6 +141,7 @@ function deprecation(id, message, out) {
 /** Test seam: forget which one-time deprecation warnings were already emitted. */
 export function resetRendererOptionDeprecationsForTests() {
     warnedDeprecations.clear();
+    warnedUrlValues.clear();
 }
 /**
  * Parse `renderer.quality` (tier string or `{ tier, overrides }`),
@@ -149,7 +151,7 @@ export function resetRendererOptionDeprecationsForTests() {
  * `source: "url"`). `qualityProfile` and root `performanceQuality` stay
  * accepted and emit a one-time deprecation warning pointing at `quality`.
  */
-export function parseQualityRendererOptions(renderer, search = typeof location !== "undefined" ? location.search : null, root = {}) {
+export function parseQualityRendererOptions(renderer, search = typeof location !== "undefined" ? location.search : null, root = {}, urlPolicy) {
     const warnings = [];
     const quality = renderer?.quality;
     let requested;
@@ -185,16 +187,24 @@ export function parseQualityRendererOptions(renderer, search = typeof location !
         const params = new URLSearchParams(search);
         const urlTier = params.get("aura3d-quality");
         if (urlTier !== null) {
-            requested = parseTier(urlTier, "?aura3d-quality");
-            requestedSource = "url";
+            // RP-04: a URL typo warns and keeps the code option (strict apps still throw).
+            if (urlTier === "auto" || QUALITY_TIER_NAMES.includes(urlTier)) {
+                requested = urlTier;
+                requestedSource = "url";
+            }
+            else {
+                ignoreInvalidUrlValue(`?aura3d-quality=${urlTier} (expected low|medium|high|ultra|auto); using "${requested}"`, { strict: urlPolicy?.strict, warnings, console: false });
+            }
         }
         const urlAdaptive = params.get("aura3d-adaptive");
         if (urlAdaptive !== null) {
-            if (urlAdaptive !== "0" && urlAdaptive !== "1") {
-                throw new Error(`QUALITY_OPTION_INVALID:?aura3d-adaptive=${urlAdaptive} (expected 0|1)`);
+            if (urlAdaptive === "0" || urlAdaptive === "1") {
+                adaptive = urlAdaptive === "1";
+                adaptiveSource = "url";
+            }
+            else {
+                ignoreInvalidUrlValue(`?aura3d-adaptive=${urlAdaptive} (expected 0|1); using ${adaptive ? "1" : "0"}`, { strict: urlPolicy?.strict, warnings, console: false });
             }
-            adaptive = urlAdaptive === "1";
-            adaptiveSource = "url";
         }
     }
     if (renderer?.qualityProfile !== undefined) {
@@ -205,4 +215,61 @@ export function parseQualityRendererOptions(renderer, search = typeof location !
     }
     return { requested, requestedSource, overrides, adaptive, adaptiveSource, targetFrameRate, batching, warnings };
 }
+const warnedUrlValues = new Set();
+/**
+ * RP-04: a typo in a debug URL switch (`?aura3d-render=`, `?aura3d-bloom-fusion=`, `?aura3d-quality=`, `?aura3d-adaptive=`) used to
+ * throw inside the mount, so every game showed its "needs WebGL 2" error screen. URL values are a tester's switch, not code: warn
+ * once (console and `diagnostics().warnings`) and keep the code option or default. Strict apps keep the throw.
+ */
+export function ignoreInvalidUrlValue(message, policy) {
+    if (policy?.strict)
+        throw new Error(`QUALITY_OPTION_INVALID:${message}`);
+    const warning = `QUALITY_URL_IGNORED: ${message}`;
+    policy?.warnings?.push(warning);
+    if (policy?.console !== false && !warnedUrlValues.has(warning)) {
+        warnedUrlValues.add(warning);
+        if (typeof console !== "undefined")
+            console.warn(`[aura3d] ${warning}`);
+    }
+}
+/**
+ * Bloom pass-fusion mode (PRD beat-threejs-2 contract 2.1): `renderer.bloomFusion` (`"separable"` default | `"fused-2d"`),
+ * overridden by `?aura3d-bloom-fusion=`. An invalid code option throws so a typo never silently runs the default; an invalid URL
+ * value warns and falls back to the code option (RP-04) unless `policy.strict`. The mode only takes effect under
+ * `quality: "auto"` / `"cinematic"`; `production` never fuses.
+ */
+export function parseBloomFusionOption(renderer, search = typeof location !== "undefined" ? location.search : null, policy) {
+    const mode = renderer?.bloomFusion ?? DEFAULT_BLOOM_FUSION_MODE;
+    if (!isBloomFusion(mode))
+        throw new Error(`QUALITY_OPTION_INVALID:renderer.bloomFusion=${String(mode)} (expected separable|fused-2d)`);
+    if (search) {
+        const fromUrl = new URLSearchParams(search).get("aura3d-bloom-fusion");
+        if (fromUrl !== null) {
+            if (isBloomFusion(fromUrl))
+                return fromUrl;
+            ignoreInvalidUrlValue(`?aura3d-bloom-fusion=${fromUrl} (expected separable|fused-2d); using "${mode}"`, policy);
+        }
+    }
+    return mode;
+}
+/**
+ * Top-tennis C11 (engine part): `renderer.quality` diagnostics, reported in `diagnostics().warnings` (not the console, since the
+ * string form is valid). A tier-name string is a fixed tier: every device, phones included, mounts at that tier, which a reader
+ * of `renderer: { quality: "high" }` easily takes for a no-op or for "best available". An unknown name used to mount at "high"
+ * with no message while the quality lane is off.
+ */
+export function rendererQualityWarnings(renderer) {
+    const quality = renderer?.quality;
+    if (quality === undefined || quality === "auto")
+        return [];
+    const tier = typeof quality === "string" ? quality : quality !== null && typeof quality === "object" ? quality.tier : quality;
+    if (tier === undefined || tier === "auto")
+        return [];
+    if (typeof tier !== "string" || !QUALITY_TIER_NAMES.includes(tier)) {
+        return [`RENDERER_QUALITY_INVALID: renderer.quality${typeof quality === "object" ? ".tier" : ""}=${String(tier)} is not a tier (expected low|medium|high|ultra|auto); the mount uses "high".`];
+    }
+    if (typeof quality !== "string")
+        return [];
+    return [`RENDERER_QUALITY_STRING: renderer.quality "${tier}" is a fixed tier, so every device, phones included, mounts at "${tier}" (pixel-ratio cap, shadow and post settings). Use "auto" or { tier: "auto" } to let the tier follow the device where the quality lane (A3D_QR_TIERS) is on.`];
+}
 //# sourceMappingURL=rendererOptions.js.map