@aura3d/engine 3.0.0 → 4.0.0

package/dist/engine/agent-api/postBridge.js

@@ -0,0 +1,711 @@
+/**
+ * PRD-03 — C-13 engine bridge: submitted postprocess telemetry, the C-31
+ * `post`/`exposure` diagnostics sections, and the `AuraPostSurface` extension.
+ * One module because it is the lane-owned seam between the compiler bridge and
+ * the app surface.
+ *
+ * Diagnostics truthfulness (C-31): `compiler/postprocess.ts` records the exact
+ * `RendererPostProcessOptions` it hands the renderer on every mount. The
+ * sections read this store instead of `app.diagnostics()` — sections run
+ * *inside* `diagnostics()`, so calling back into it would recurse. Anything
+ * not measurable engine-side is `null`, never guessed. Recording never alters
+ * the submitted options and runs identically flag-off: the `post` section must
+ * report what the legacy chain executes today.
+ */
+import { createRendererPostprocessPlanDiagnostics, postGraphV2LastOutcome, postSkippedReasons, postStagesRan, postV2ModulesReady, postVelocityCoverage, volumetricLightDirection } from "../../rendering/index.js";
+import { registerPostPass, registeredPostPasses } from "../../rendering/contracts/index.js";
+import { AuraRuntimeError, groups } from "./index.js";
+import { expandPostPreset, presetCapabilityDegraded } from "./postPresets.js";
+/** Mirrors `postProductionBuild` in the renderer (§6.9 prod-skip rule). */
+function postProductionBuildBridge() {
+    const meta = import.meta;
+    if (meta.env?.PROD)
+        return true;
+    return globalThis
+        .process?.env?.NODE_ENV === "production";
+}
+let latest = null;
+/**
+ * Per-app binding (review P2): a module-global record is overwritten by
+ * whichever app compiles most recently, and the compile runs inside the
+ * app's async mount — after `ext.create` — so factory-time binding cannot
+ * attribute it. The compile's canvas is the one handle that reaches both
+ * sides: `createProductionRuntimePostprocess` records it, and
+ * `collectPostSection(app)`/`collectExposureSection(app)` resolve the record
+ * through `app.canvas`. Headless apps (no canvas) keep reading `latest`.
+ */
+const canvasRecords = new WeakMap();
+let sequence = 0;
+export function recordSubmittedPostprocess(options, context) {
+    sequence += 1;
+    latest = {
+        sequence,
+        atMs: Date.now(),
+        renderWidth: context.renderWidth,
+        renderHeight: context.renderHeight,
+        temporalRequested: context.temporalRequested,
+        options,
+        authored: context.authored
+    };
+    if (context.canvas)
+        canvasRecords.set(context.canvas, latest);
+}
+export function latestSubmittedPostprocess() {
+    return latest;
+}
+/** Test hook: clears the store between specs. */
+export function resetSubmittedPostprocess() {
+    latest = null;
+    sequence = 0;
+}
+let authoredContext = null;
+/**
+ * Per-app authored context — same async-mount scoping fix as `canvasRecords`
+ * (review P2): two apps created back-to-back both run `ext.create` before
+ * either async mount compiles, so a global context would hand the SECOND
+ * app's flags/options to the first app's compile. Keyed by `app.canvas`.
+ */
+const canvasAuthored = new WeakMap();
+/** Called by the `prd03.post` app extension once per `createAuraApp`. */
+export function recordAuthoredPostContext(ctx, app) {
+    const options = (ctx.options ?? {});
+    authoredContext = {
+        flags: { post: ctx.flags.on("A3D_QR_POST") },
+        output: options.output ?? options.renderer?.output,
+        qualityTier: authoredContext?.qualityTier ?? null,
+        compatPost3: options.compat?.post === "3.0"
+    };
+    if (app?.canvas)
+        canvasAuthored.set(app.canvas, authoredContext);
+}
+export function latestAuthoredPostContext() {
+    return authoredContext;
+}
+/** The context for the app that owns `canvas` — falls back to `latest`. */
+export function authoredPostContextFor(canvas) {
+    return (canvas ? canvasAuthored.get(canvas) : undefined) ?? authoredContext;
+}
+function recordPostQualityTier(tier, canvas) {
+    const target = (canvas ? canvasAuthored.get(canvas) : undefined) ?? authoredContext;
+    if (target) {
+        target.qualityTier = tier;
+    }
+    else {
+        authoredContext = { flags: { post: false }, output: undefined, qualityTier: tier, compatPost3: false };
+        if (canvas)
+            canvasAuthored.set(canvas, authoredContext);
+    }
+}
+/** Test hook: clears the authored context between specs. */
+export function resetAuthoredPostContext() {
+    authoredContext = null;
+}
+/** Depth-consuming legacy passes — mirrors `postprocessRequiresDepthTexture`. */
+function submittedNeedsDepthTexture(options) {
+    return Boolean((options.volumetricLight && !options.volumetricLight.depth) ||
+        (options.depthOfField && !options.depthOfField.depth) ||
+        (options.contactShadow && !options.contactShadow.depth) ||
+        (options.ssao && !options.ssao.depth) ||
+        (options.ssr && !options.ssr.depth));
+}
+function planForSubmitted(options, width, height) {
+    const targetFormat = options.targetFormat ?? "rgba8";
+    return createRendererPostprocessPlanDiagnostics(options, {
+        sourceTargetFormat: targetFormat,
+        targetFormat,
+        // The production WebGL2 device implements presentLdrPostprocess; a mounted
+        // forward target carries a depth texture exactly when the submitted chain
+        // consumes depth.
+        nativeLdrPostprocess: true,
+        rendererDepthAvailable: submittedNeedsDepthTexture(options),
+        width,
+        height
+    });
+}
+export function collectPostSection(app) {
+    const submitted = (app.canvas ? canvasRecords.get(app.canvas) : undefined) ?? latestSubmittedPostprocess();
+    const authoredContext = authoredPostContextFor(app.canvas ?? undefined);
+    // 03-S18c: report what the renderer executed, not what was authored.
+    // Registered C-13 passes run only when the v2 seam ran the stages
+    // (`postGraphV2LastOutcome() === "v2"`); otherwise the reason names the
+    // chain that served the frame (flag off, compat.post "3.0", a WebGPU
+    // backend, cpu-deterministic, unfusable passes, modules still loading, or
+    // `not-executed` when no postprocess frame reached the seam).
+    const customStatus = !authoredContext?.flags.post
+        ? "legacy-chain:A3D_QR_POST-off"
+        : authoredContext.compatPost3
+            ? "legacy-chain:compat.post-3.0"
+            : postGraphV2LastOutcome() ?? "not-executed";
+    const custom = registeredPostPasses().map((pass) => ({ id: pass.id, status: customStatus }));
+    const empty = {
+        present: false,
+        requestedPasses: [],
+        submittedPasses: [],
+        pixelBackedPasses: [],
+        droppedPasses: [],
+        missingInputs: [],
+        executionMode: null,
+        readbackPasses: [],
+        fusedLdr: false,
+        targetFormat: null,
+        temporalRequested: false,
+        velocityCoverage: null,
+        skipped: [],
+        warnings: []
+    };
+    const antiAlias = submitted?.authored.resolvedAntiAlias
+        ? {
+            ...submitted.authored.resolvedAntiAlias,
+            tier: authoredContext?.qualityTier ?? "high"
+        }
+        : null;
+    if (!submitted) {
+        return {
+            pipeline: "legacy",
+            ...empty,
+            antiAlias: null,
+            customPasses: custom,
+            source: "agent-api/postBridge.ts + RendererPostprocessPlanDiagnostics"
+        };
+    }
+    const plan = planForSubmitted(submitted.options, submitted.renderWidth, submitted.renderHeight);
+    return {
+        pipeline: submitted.authored.v2 ? "v2" : "legacy",
+        present: true,
+        requestedPasses: plan.requestedPassNames,
+        submittedPasses: plan.submittedPassNames,
+        pixelBackedPasses: plan.pixelBackedPassNames,
+        droppedPasses: plan.plannedVsActual.dropped,
+        missingInputs: plan.missingInputs,
+        executionMode: plan.executionMode,
+        readbackPasses: plan.readbackPassNames,
+        fusedLdr: plan.canFuseLdr,
+        targetFormat: plan.targetFormat,
+        temporalRequested: submitted.temporalRequested,
+        velocityCoverage: authoredContext?.flags.post ? postVelocityCoverage() : null,
+        antiAlias,
+        skipped: [
+            ...(antiAlias?.reason ? [`aa:${antiAlias.reason}`] : []),
+            ...plan.plannedVsActual.dropped,
+            // §6.3: the indirect-fraction feature is registered but the lane-01
+            // program generator is still the PR 0a stub — AO applies the
+            // `u_aoFallbackStrength` path until C-02 lands real.
+            ...(authoredContext?.flags.post && (submitted.authored.ambientOcclusion || submitted.authored.contactOcclusion)
+                ? ["AO_INDIRECT_FRACTION_PENDING"]
+                : []),
+            // §6.9: in production builds the non-GPU passes are skipped instead of
+            // throwing POSTPROCESS_PASS_NOT_GPU — record them here.
+            ...(postProductionBuildBridge() && authoredContext?.flags.post
+                ? plan.pixelBackedPassNames.map((name) => `POSTPROCESS_PASS_NOT_GPU:${name}`)
+                : []),
+            // §6.9: runtime record-and-skip reasons from the renderer / v2 drivers.
+            ...(authoredContext?.flags.post ? postSkippedReasons() : [])
+        ],
+        ...(authoredContext?.flags.post ? { stagesRan: postStagesRan() } : {}),
+        customPasses: custom,
+        warnings: [
+            ...plan.clarityWarnings,
+            // §7.1: flag-off unknown fields warn as `option-ignored`; deprecated
+            // fields + informational diagnostics keep their §7.1 names.
+            ...(submitted.authored.fieldDiagnostics ?? []).map((diagnostic) => diagnostic.code === "POST_FIELD_UNSUPPORTED" && !authoredContext?.flags.post
+                ? `option-ignored:${diagnostic.effect}.${diagnostic.field}`
+                : diagnostic.field
+                    ? `${diagnostic.code}:${diagnostic.effect}.${diagnostic.field}`
+                    : `${diagnostic.code}:${diagnostic.effect}`)
+        ],
+        source: "agent-api/postBridge.ts + RendererPostprocessPlanDiagnostics"
+    };
+}
+export function collectExposureSection(app) {
+    const submitted = (app.canvas ? canvasRecords.get(app.canvas) : undefined) ?? latestSubmittedPostprocess();
+    const authoredContext = authoredPostContextFor(app.canvas ?? undefined);
+    const toneMapping = submitted?.options.toneMapping;
+    const toneMappingOptions = typeof toneMapping === "object" && toneMapping !== null ? toneMapping : undefined;
+    return {
+        present: submitted !== null,
+        applied: toneMapping === false ? null : (toneMappingOptions?.exposure ?? (submitted ? 1 : null)),
+        operator: toneMapping === false ? "off" : (toneMappingOptions?.operator ?? (submitted ? "aces" : null)),
+        whitePoint: toneMappingOptions?.whitePoint ?? null,
+        inputColorSpace: toneMappingOptions?.inputColorSpace ?? null,
+        outputColorSpace: toneMappingOptions?.outputColorSpace ?? null,
+        authoredGradeExposure: submitted?.authored.colorGradeExposure ?? null,
+        outputExposureAuthored: typeof authoredContext?.output?.exposure === "number" ? authoredContext.output.exposure : null,
+        source: "agent-api/postBridge.ts"
+    };
+}
+/* ------------------------------------------------------------------------- */
+/* C-13 app surface                                                          */
+/* ------------------------------------------------------------------------- */
+let customPassSequence = 0;
+/** Space implied by the anchor a custom pass inserts at. */
+function spaceForAnchor(insertAt) {
+    return insertAt === "after-tonemap" ? "display" : "linear-hdr";
+}
+/**
+ * `AuraCustomPostPass` → `PostPassDescriptor`. Custom fragments are GPU-only by
+ * contract (`AuraCustomPostPass` carries fragment/uniforms, never a cpu run).
+ */
+function customPassToDescriptor(pass) {
+    customPassSequence += 1;
+    const uniforms = pass.uniforms;
+    return {
+        id: `prd03.custom.${pass.name || `pass-${customPassSequence}`}`,
+        owner: "prd03",
+        flag: "A3D_QR_POST",
+        space: spaceForAnchor(pass.insertAt),
+        insertAt: pass.insertAt,
+        inputs: pass.inputs ?? ["color"],
+        fragment: { glsl: pass.fragment.glsl, ...(pass.fragment.wgsl ? { wgsl: pass.fragment.wgsl } : {}) },
+        uniforms: uniforms ? () => uniforms : undefined,
+        enabled: () => true,
+        gpuOnly: true
+    };
+}
+/**
+ * The real `post` extension value. Flag-off it behaves exactly like
+ * `StubPostSurface` (addPostPass no-ops, the tier is only recorded); flag-on it
+ * additionally registers the descriptor into the C-13 pass registry, where the
+ * v2 graph picks it up. `setQualityTier` records either way — tier resolution
+ * against `AuraQualityTierSettings` lands with the graph.
+ */
+export class Prd03PostSurface {
+    flags;
+    canvas;
+    app;
+    requestedTier = null;
+    constructor(flags, canvas, app) {
+        this.flags = flags;
+        this.canvas = canvas;
+        this.app = app;
+    }
+    addPostPass(pass) {
+        if (!this.flags.on("A3D_QR_POST"))
+            return () => { };
+        return registerPostPass(customPassToDescriptor(pass));
+    }
+    setQualityTier(tier) {
+        this.requestedTier = tier;
+        // The compiler reads the shared context store when resolving tier AA (Phase 1).
+        recordPostQualityTier(tier, this.canvas);
+        // §6.8: delegate to the C-27 controller when lane 11 exposes `app.quality`;
+        // `quality.onChange` re-records below so the next compile/frame re-resolves
+        // the post tier. On this build's surface the recorded tier is the channel.
+        if (tier !== "auto") {
+            const quality = qualityControllerOf(this.app);
+            void quality?.set(tier);
+        }
+    }
+    /** Test/diagnostic accessor for the recorded tier. */
+    get qualityTier() {
+        return this.requestedTier;
+    }
+}
+/** C-27 duck-type: `app.quality` is lane 11's surface — read it if present. */
+function qualityControllerOf(app) {
+    const quality = app?.quality;
+    return quality && typeof quality.set === "function" && typeof quality.onChange === "function" ? quality : undefined;
+}
+/** C-38 factory: mounts `app.post` for prd03 with the app's resolved flags. */
+export function createPrd03PostSurface(app, ctx) {
+    // Record the C-38 `output` options so `compiler/postprocess.ts` can wire
+    // Phase-1 behaviour (exposure product, operator, tier AA) without reaching
+    // back into `createAuraApp` scope.
+    recordAuthoredPostContext(ctx, app);
+    // §6.8 re-resolution: a C-27 tier change re-records the authored tier so the
+    // next postpipeline resolve reads the new `QUALITY_TIERS` row.
+    qualityControllerOf(app)?.onChange((event) => recordPostQualityTier(event.to, app.canvas ?? undefined));
+    // Start the deferred v2 stage load at mount, not on the first frame, so the
+    // first frames after `app.ready()` run the real v2 chain (S1–S12 and C-13
+    // custom passes). A failed load is retried by the frame path.
+    if (ctx.flags.on("A3D_QR_POST"))
+        postV2ModulesReady().catch(() => undefined);
+    return new Prd03PostSurface(ctx.flags, app.canvas ?? undefined, app);
+}
+/* ------------------------------------------------------------------------- */
+/* Phase 2 — C-13 v2 bridge: field validation + v2 option assembly            */
+/* ------------------------------------------------------------------------- */
+/**
+ * Own keys allowed on every effect node regardless of `effect` — the node's
+ * shared bag fields (`AuraEffectNode`) plus the transform spec and the lane
+ * bookkeeping field `postAuthored` (CCR-03-3).
+ */
+export const POST_EFFECT_COMMON_FIELDS = [
+    "kind", "effect", "name", "id", "intensity", "enabled", "animation", "postAuthored", "postIntensity",
+    "position", "rotation", "scale", "lookAt", "rotationOrder", "quaternion"
+];
+/**
+ * §7.1 allowlist: v2-executed fields per post-relevant `effect` value. A field
+ * absent from the node's `postAuthored` list takes its v2 default; a field
+ * present but not in this list or `POST_EFFECT_DEPRECATED_FIELDS` throws
+ * `POST_FIELD_UNSUPPORTED` (flag on) before the first frame.
+ */
+export const POST_EFFECT_FIELDS = {
+    bloom: ["threshold", "knee", "scatter", "color", "clampLuminance"],
+    "ambient-occlusion": ["radius", "intensity", "falloff", "multiBounce"],
+    "contact-occlusion": ["radius", "intensity", "falloff", "multiBounce"],
+    "color-grade": ["exposure", "temperature", "tint", "contrast", "saturation", "vibrance",
+        "lift", "gamma", "gain", "shadows", "midtones", "highlights", "lut", "lutIntensity"],
+    "anti-alias": ["mode", "sharpness"],
+    vignette: ["intensity", "smoothness", "roundness", "color"],
+    "film-grain": ["intensity", "size", "luminanceResponse"],
+    "chromatic-aberration": ["intensity"],
+    // Lane-07 factories route through this bridge on the v2 chain (§6.9).
+    "volumetric-fog": ["density", "color", "volumetricQuality", "lightPosition", "heightFalloff", "heightReference"],
+    "depth-of-field": ["focusDistance", "fStop", "focalLength", "maxBlur"],
+    "motion-blur": ["shutter", "maxBlur", "samples", "tileSize", "timeScale"],
+    "screen-space-reflections": ["maxDistance", "intensity"],
+    outline: ["color", "width", "threshold"]
+};
+/**
+ * §7.1 deprecated fields — accepted with a `post-field-deprecated` diagnostic,
+ * mapped where the spec says so (bloom `radius` → `scatter`, `maxIntensity` /
+ * `antiBlowout` → `clampLuminance`; DOF `focus`/`aperture` convert with real
+ * near/far). Everything else is ignored.
+ */
+export const POST_EFFECT_DEPRECATED_FIELDS = {
+    bloom: ["quality", "softKnee", "shoulder", "maxIntensity", "antiBlowout", "radius"],
+    "ambient-occlusion": ["density", "color"],
+    "contact-occlusion": ["density", "color"],
+    "depth-of-field": ["focus", "aperture"]
+};
+function isAuthored(node, field) {
+    return node.postAuthored === undefined || node.postAuthored.includes(field);
+}
+/**
+ * Validates one effect node's own keys against the allowlists. Returns the
+ * diagnostics the caller either throws on (flag on, unknown fields) or warns
+ * with (flag off / deprecated). `undefined` for non-post effects — those are
+ * other lanes' to validate.
+ */
+export function validatePostEffectNode(node) {
+    const fields = POST_EFFECT_FIELDS[node.effect];
+    if (!fields)
+        return undefined;
+    const deprecated = POST_EFFECT_DEPRECATED_FIELDS[node.effect] ?? [];
+    const diagnostics = [];
+    // §7.1 applies to AUTHORED fields: `postAuthored` (CCR-03-3) lists the keys
+    // the caller actually wrote — factory-default own keys are excluded. Nodes
+    // built without the bridge marker fall back to validating every own key.
+    const keys = node.postAuthored ?? Object.keys(node);
+    for (const key of keys) {
+        if (POST_EFFECT_COMMON_FIELDS.includes(key) || fields.includes(key))
+            continue;
+        if (deprecated.includes(key)) {
+            diagnostics.push({
+                code: "post-field-deprecated",
+                effect: node.effect,
+                field: key,
+                message: `effects.${node.effect} field "${key}" is deprecated under the v2 post chain (§7.1 mapping).`
+            });
+            continue;
+        }
+        diagnostics.push({
+            code: "POST_FIELD_UNSUPPORTED",
+            effect: node.effect,
+            field: key,
+            message: `effects.${node.effect} field "${key}" has no v2 post-chain consumer (POST_FIELD_UNSUPPORTED).`
+        });
+    }
+    return diagnostics;
+}
+/* V2 option bags ---------------------------------------------------------- */
+const V2_BLOOM_DEFAULTS = { threshold: 1.0, knee: 0.25, intensity: 0.25, scatter: 0.7, clampLuminance: 64 };
+function numberField(node, field, fallback) {
+    const value = node[field];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function authoredNumber(node, field, fallback) {
+    return isAuthored(node, field) ? numberField(node, field, fallback) : fallback;
+}
+function rgbField(node, field, fallback) {
+    const value = node[field];
+    if (Array.isArray(value) && value.length >= 3) {
+        return { r: Number(value[0]), g: Number(value[1]), b: Number(value[2]) };
+    }
+    if (value && typeof value === "object" && "r" in value) {
+        const v = value;
+        return { r: Number(v.r), g: Number(v.g), b: Number(v.b) };
+    }
+    return fallback;
+}
+/**
+ * §6.6 v2 bloom mapping: authored fields win; fields absent from
+ * `postAuthored` take the v2 defaults (factory defaults are legacy). A
+ * threshold < 1 is honored as linear HDR and reported
+ * `BLOOM_THRESHOLD_BELOW_HDR_WHITE`. `radius` aliases `scatter`;
+ * `maxIntensity`/`antiBlowout` map to `clampLuminance`.
+ */
+export function mapBloomOptionsV2(node, mipLevels) {
+    const diagnostics = [];
+    const nodeFields = node;
+    const threshold = authoredNumber(node, "threshold", V2_BLOOM_DEFAULTS.threshold);
+    if (threshold < 1) {
+        diagnostics.push({
+            code: "BLOOM_THRESHOLD_BELOW_HDR_WHITE",
+            effect: "bloom",
+            field: "threshold",
+            message: `bloom threshold ${threshold} is below HDR white; honored as linear HDR (§6.6).`
+        });
+    }
+    const scatterAuthored = isAuthored(node, "scatter") ? numberField(node, "scatter", NaN) : NaN;
+    const radiusAlias = isAuthored(node, "radius") ? numberField(node, "radius", NaN) : NaN;
+    const maxIntensity = isAuthored(node, "maxIntensity") ? numberField(node, "maxIntensity", NaN) : NaN;
+    const antiBlowout = isAuthored(node, "antiBlowout") ? nodeFields.antiBlowout === true : false;
+    const clampLuminance = authoredNumber(node, "clampLuminance", Number.isFinite(maxIntensity) ? maxIntensity : antiBlowout ? V2_BLOOM_DEFAULTS.clampLuminance : V2_BLOOM_DEFAULTS.clampLuminance);
+    const tintAuthored = isAuthored(node, "color");
+    const tint = tintAuthored ? rgbField(node, "color", { r: 1, g: 1, b: 1 }) : { r: 1, g: 1, b: 1 };
+    return {
+        options: {
+            threshold: Math.min(64, Math.max(0, threshold)),
+            knee: Math.min(1, Math.max(0, authoredNumber(node, "knee", V2_BLOOM_DEFAULTS.knee))),
+            // `postIntensity` is the authored value before the legacy antiBlowout cap.
+            intensity: Math.min(4, Math.max(0, isAuthored(node, "intensity") && typeof node.postIntensity === "number" && Number.isFinite(node.postIntensity)
+                ? node.postIntensity
+                : authoredNumber(node, "intensity", V2_BLOOM_DEFAULTS.intensity))),
+            scatter: Math.min(1, Math.max(0, Number.isFinite(scatterAuthored) ? scatterAuthored : Number.isFinite(radiusAlias) ? radiusAlias : V2_BLOOM_DEFAULTS.scatter)),
+            tint: [tint.r, tint.g, tint.b],
+            clampLuminance,
+            mips: mipLevels
+        },
+        diagnostics
+    };
+}
+/**
+ * The v2 root post pipeline (C-13): assembles `PostPipelineOptions` from the
+ * snapshot's effect nodes + C-38 `output` + C-27 tier settings. Throws
+ * `AuraRuntimeError("POST_FIELD_UNSUPPORTED", ...)` on an unknown effect-node
+ * field — this runs inside the compile, so `app.ready()` rejects before the
+ * first frame instead of the error dying inside `diagnostics.errors`.
+ */
+export function createRootPostPipeline(snapshot, camera, output, tierSettings, lights = [], tierResolution) {
+    const nodes = groups.flatten(snapshot.nodes);
+    const diagnostics = [];
+    for (const node of nodes) {
+        if (node.kind !== "effect")
+            continue;
+        const nodeDiagnostics = validatePostEffectNode(node);
+        if (nodeDiagnostics)
+            diagnostics.push(...nodeDiagnostics);
+        const unsupported = nodeDiagnostics?.find((d) => d.code === "POST_FIELD_UNSUPPORTED");
+        if (unsupported) {
+            throw new AuraRuntimeError("POST_FIELD_UNSUPPORTED", unsupported.message);
+        }
+    }
+    // §6.8 (Phase 5): `output.preset` expands into `output` + effect nodes.
+    // Authored `output` fields win over the preset's; an authored effect node
+    // overrides the preset's same-effect node field by field. Presets naming
+    // agx/neutral render aces while C-05's operator selection is a stub.
+    const authoredEffectNodes = nodes.filter((node) => node.kind === "effect");
+    const expansion = expandPostPreset(output, authoredEffectNodes);
+    const effectiveOutput = expansion.output;
+    const effectNodes = expansion.nodes;
+    if (expansion.preset && presetCapabilityDegraded(expansion.preset, output?.toneMapping)) {
+        diagnostics.push({
+            code: "preset-capability-degraded",
+            effect: "output",
+            field: "preset",
+            message: `preset "${expansion.preset.id}" declares ${expansion.preset.output.toneMapping}; renders as "aces" until C-05's operator selection is real.`
+        });
+    }
+    const tierDisabled = (stage, reason) => {
+        diagnostics.push({
+            code: "post-tier-disabled",
+            effect: stage,
+            message: `${stage} is off on the ${tierResolution?.tier ?? "resolved"} post tier (${reason}).`
+        });
+    };
+    const effect = (kind) => effectNodes.find((node) => node.kind === "effect" && node.effect === kind);
+    const bloomNode = effect("bloom");
+    const gradeNode = effect("color-grade");
+    const vignetteNode = effect("vignette");
+    const grainNode = effect("film-grain");
+    const caNode = effect("chromatic-aberration");
+    const volumetricNode = effect("volumetric-fog");
+    const dofNode = effect("depth-of-field");
+    const mbNode = effect("motion-blur");
+    const ssrNode = effect("screen-space-reflections");
+    // §6.9/§8.4 (Phase 3): ambient-occlusion and contact-occlusion both target
+    // S2 GTAO, and the graph has one AO stage. `radius` is interpreted in
+    // metres flag-on; contactOcclusion is ambientOcclusion with a 0.2 m
+    // default radius.
+    //
+    // T0-29 (#979): six legacy games author both nodes (the post-v2 codemod
+    // merges them, §APIs). Throwing here failed the production mount, so with
+    // `post` on those routes drew 0 calls. The bridge now applies the codemod's
+    // merge at runtime: the ambient-occlusion node drives S2, the extra AO
+    // node is dropped and reported as `POST_DUPLICATE_STAGE` (a diagnostic, not
+    // a mount failure).
+    const aoNodes = effectNodes.filter((node) => node.kind === "effect" && (node.effect === "ambient-occlusion" || node.effect === "contact-occlusion"));
+    const aoNode = aoNodes.find((node) => node.effect === "ambient-occlusion") ?? aoNodes[0];
+    if (aoNodes.length > 1) {
+        diagnostics.push({
+            code: "POST_DUPLICATE_STAGE",
+            effect: "S2-gtao",
+            message: `POST_DUPLICATE_STAGE: ${aoNodes.length} AO effect nodes (${aoNodes.map((node) => node.effect).join(" + ")}) target stage S2-gtao; `
+                + `${aoNode.effect} drives it and the rest are dropped (run the post-v2 codemod to merge contactOcclusion).`
+        });
+    }
+    // §6.9: the god-ray light is the strongest DIRECTIONAL light in the
+    // compiled RenderSource — direction TOWARD the light for the S4 project.
+    const strongestDirectional = lights.reduce((best, light) => light.kind === "directional" && light.intensity > 0 && (!best || light.intensity > best.intensity) ? light : best, null);
+    const godRayLightDirection = strongestDirectional ? volumetricLightDirection(strongestDirectional) : null;
+    const bloom = bloomNode ? mapBloomOptionsV2(bloomNode, tierSettings.bloomMipLevels) : undefined;
+    if (bloom)
+        diagnostics.push(...bloom.diagnostics);
+    const exposure = (effectiveOutput?.exposure ?? 1) * authoredNumber(gradeNode ?? {}, "exposure", 1);
+    const toneMapping = effectiveOutput?.toneMapping ?? "aces";
+    // §6.8 tier gates (Phase 5): `resolvePostTier` decides which authored or
+    // preset-contributed stages the resolved tier can afford. Disabled stages
+    // drop their option bag and report `post-tier-disabled` so `post.skipped`
+    // shows the tier, not a missing node.
+    const aoEnabled = tierResolution === undefined || tierResolution.gtao.enabled;
+    if (aoNode && !aoEnabled)
+        tierDisabled("S2-gtao", "ambientOcclusion off in C-27");
+    const godRaysEnabled = tierResolution === undefined || tierResolution.godRays.enabled;
+    if (volumetricNode && !godRaysEnabled)
+        tierDisabled("S4-god-rays", "god rays off below Medium");
+    const dofEnabled = tierResolution === undefined || tierResolution.dof.enabled;
+    if (dofNode && !dofEnabled)
+        tierDisabled("S6-dof", "DOF off below High");
+    const mbEnabled = tierResolution === undefined || tierResolution.motionBlur.enabled;
+    if (mbNode && !mbEnabled)
+        tierDisabled("S7-motion-blur", "motion blur off below High");
+    const ssrEnabled = tierResolution === undefined || tierResolution.ssr.enabled;
+    if (ssrNode && !ssrEnabled)
+        tierDisabled("S3-ssr", "SSR off below High");
+    const grainEnabled = tierResolution === undefined || tierResolution.allowsFilmGrain;
+    if (grainNode && !grainEnabled)
+        tierDisabled("S12-film-grain", "grain off on Low");
+    const caEnabled = tierResolution === undefined || tierResolution.allowsChromaticAberration;
+    if (caNode && !caEnabled)
+        tierDisabled("S10-chromatic-aberration", "CA off on Low");
+    // S8 auto-exposure: authored `output.autoExposure` (CCR-03-2) gated by the
+    // C-27 tier row (off on Low; "if preset" otherwise).
+    const authoredAe = effectiveOutput?.autoExposure;
+    const aeRequested = authoredAe !== undefined && authoredAe !== false;
+    const aeEnabled = tierResolution === undefined || tierResolution.autoExposure;
+    if (aeRequested && !aeEnabled)
+        tierDisabled("S8-auto-exposure", "auto-exposure off on Low");
+    const options = {
+        antiAliasing: "off", // resolved by the caller through resolvePostAntiAlias
+        depthRange: {
+            near: camera?.near ?? 0.1,
+            far: camera?.far ?? 1000,
+            projection: camera?.mode === "orthographic" || camera?.mode === "isometric" ? "orthographic" : "perspective"
+        },
+        // The scale the post chain's input was rendered at, not the governor's
+        // floor: the renderer's postprocess forward target is full-size, so
+        // this is 1. Passing `minRenderScale` (0.5–0.75) made S5 run the §8.6
+        // TAAU upsample on a full-res frame (enlarging and re-filtering it: the
+        // prd03-taa 1-px line moved ~1 px and spread over five rows, promote run
+        // 38203056326) and armed the S12 RCAS sharpen on every frame.
+        renderScale: 1,
+        ...(bloom ? { bloom: bloom.options } : {}),
+        exposure,
+        toneMapping: toneMapping,
+        dither: effectiveOutput?.dither !== false,
+        backgroundPassthrough: effectiveOutput?.backgroundPassthrough === true,
+        ...(aoNode && aoEnabled ? {
+            ao: {
+                radius: aoNode.effect === "contact-occlusion"
+                    ? numberField(aoNode, "radius", 0.2)
+                    : numberField(aoNode, "radius", 0.35),
+                intensity: numberField(aoNode, "intensity", 1),
+                falloff: numberField(aoNode, "falloff", 1),
+                directions: (tierResolution?.gtao.enabled === true ? tierResolution.gtao.directions : 4),
+                steps: (tierResolution?.gtao.enabled === true ? tierResolution.gtao.steps : 4),
+                halfRes: tierResolution?.gtao.enabled === true ? tierResolution.gtao.halfRes : true,
+                temporal: tierResolution?.gtao.enabled === true ? tierResolution.gtao.temporal : true,
+                multiBounce: aoNode.multiBounce !== false,
+                fallbackStrength: 0.6
+            }
+        } : {}),
+        ...(volumetricNode && godRaysEnabled ? {
+            godRays: {
+                samples: (tierResolution?.godRays.enabled === true ? tierResolution.godRays.samples : 32),
+                decay: 0.94,
+                weight: numberField(volumetricNode, "intensity", 0.7),
+                density: numberField(volumetricNode, "density", 0.18),
+                intensity: numberField(volumetricNode, "intensity", 0.7),
+                color: rgbField(volumetricNode, "color", { r: 0.44, g: 0.52, b: 0.73 }),
+                lightWorld: Array.isArray(volumetricNode.lightPosition) ? volumetricNode.lightPosition.slice(0, 3) : undefined,
+                ...(godRayLightDirection ? { lightDirection: godRayLightDirection } : {})
+            }
+        } : {}),
+        ...(dofNode && dofEnabled ? {
+            dof: {
+                // §7.1: legacy `focus` fraction converts with real near/far; the new
+                // `focusDistance` field (metres) wins when authored.
+                focusDistance: isAuthored(dofNode, "focusDistance")
+                    ? numberField(dofNode, "focusDistance", 3)
+                    : (camera?.near ?? 0.1) + numberField(dofNode, "focus", 0.02) * ((camera?.far ?? 1000) - (camera?.near ?? 0.1)),
+                fStop: numberField(dofNode, "fStop", 2.8),
+                focalLengthMm: numberField(dofNode, "focalLength", 50),
+                maxBlurPx: numberField(dofNode, "maxBlur", 12),
+                halfRes: tierResolution?.dof.enabled === true ? tierResolution.dof.halfRes : true,
+                sensorHeightMm: 24
+            }
+        } : {}),
+        ...(mbNode && mbEnabled ? {
+            motionBlur: {
+                // §8.8: authored shutter × node timeScale (C-23's per-node scale;
+                // session-level timeScale lands via QR-03-12).
+                shutter: numberField(mbNode, "shutter", numberField(mbNode, "intensity", 0.5)) * numberField(mbNode, "timeScale", 1),
+                maxBlurPx: numberField(mbNode, "maxBlur", 32),
+                // §8.8: legal sets — samples 8|12|16; the tier sets the default taps.
+                samples: (() => {
+                    const tierDefault = tierResolution?.motionBlur.enabled === true ? tierResolution.motionBlur.samples : 12;
+                    const s = numberField(mbNode, "samples", tierDefault);
+                    return (s <= 8 ? 8 : s <= 12 ? 12 : 16);
+                })(),
+                tileSize: numberField(mbNode, "tileSize", 16) <= 16 ? 16 : 20
+            }
+        } : {}),
+        ...(ssrNode && ssrEnabled ? { ssr: { intensity: numberField(ssrNode, "intensity", 0.9), maxDistance: numberField(ssrNode, "maxDistance", 18) } } : {}),
+        ...(gradeNode ? {
+            grade: {
+                temperature: authoredNumber(gradeNode, "temperature", 0),
+                tint: authoredNumber(gradeNode, "tint", 0),
+                contrast: authoredNumber(gradeNode, "contrast", 1),
+                saturation: authoredNumber(gradeNode, "saturation", 1),
+                vibrance: authoredNumber(gradeNode, "vibrance", 0),
+                lift: rgbField(gradeNode, "lift", { r: 0, g: 0, b: 0 }),
+                gamma: rgbField(gradeNode, "gamma", { r: 1, g: 1, b: 1 }),
+                gain: rgbField(gradeNode, "gain", { r: 1, g: 1, b: 1 }),
+                shadows: rgbField(gradeNode, "shadows", { r: 1, g: 1, b: 1 }),
+                midtones: rgbField(gradeNode, "midtones", { r: 1, g: 1, b: 1 }),
+                highlights: rgbField(gradeNode, "highlights", { r: 1, g: 1, b: 1 }),
+                lutIntensity: authoredNumber(gradeNode, "lutIntensity", 1)
+            }
+        } : {}),
+        ...(gradeNode?.lut ? { lut: { source: gradeNode.lut, intensity: numberField(gradeNode, "lutIntensity", 1) } } : {}),
+        ...(vignetteNode ? {
+            vignette: {
+                intensity: numberField(vignetteNode, "intensity", 0.3),
+                smoothness: numberField(vignetteNode, "smoothness", 1),
+                roundness: numberField(vignetteNode, "roundness", 1),
+                color: rgbField(vignetteNode, "color", { r: 0, g: 0, b: 0 })
+            }
+        } : {}),
+        ...(grainNode && grainEnabled ? {
+            filmGrain: {
+                intensity: numberField(grainNode, "intensity", 0.05),
+                size: numberField(grainNode, "size", 1),
+                luminanceResponse: numberField(grainNode, "luminanceResponse", 1)
+            }
+        } : {}),
+        ...(caNode && caEnabled ? { chromaticAberration: { intensity: numberField(caNode, "intensity", 0.0015) } } : {}),
+        ...(aeRequested && aeEnabled ? {
+            autoExposure: {
+                minEv: authoredAe?.minEv ?? -4,
+                maxEv: authoredAe?.maxEv ?? 4,
+                speedUp: authoredAe?.speedUp ?? 3,
+                speedDown: authoredAe?.speedDown ?? 1,
+                meteringMask: authoredAe?.meteringMask ?? "center-weighted",
+                compensationEv: authoredAe?.compensationEv ?? 0
+            }
+        } : {})
+    };
+    return { options, diagnostics };
+}
+//# sourceMappingURL=postBridge.js.map