@jgengine/shell 0.31.0 → 0.33.0

package/dist/audio/hapticsRoute.js

@@ -0,0 +1,59 @@
+function browserPads() {
+    return typeof navigator === "undefined" || navigator.getGamepads === undefined ? [] : navigator.getGamepads();
+}
+function hasVibratingPad(pads) {
+    for (let index = 0; index < pads.length; index += 1) {
+        const pad = pads[index];
+        if (pad !== null && pad !== undefined && pad.connected && pad.vibrationActuator != null)
+            return true;
+    }
+    return false;
+}
+function browserVibrate() {
+    if (typeof navigator === "undefined" || navigator.vibrate === undefined)
+        return null;
+    return (ms) => {
+        navigator.vibrate(ms);
+    };
+}
+function browserEvents() {
+    return typeof window === "undefined" ? null : window;
+}
+/**
+ * One pulse in, whichever motor the player has: a connected gamepad takes it through the haptic
+ * channels the gamepad loop already drives, and a phone with no pad falls back to
+ * `navigator.vibrate`. Pad presence is cached and refreshed on connection events, so a hit never
+ * asks the browser for its pad list. Reduced motion does not silence this: see `eventFeedback`.
+ *
+ * @capability haptics-route send a feedback pulse to the gamepad when one is connected, else to the phone's vibration motor
+ */
+export function createHapticsRoute(pad, options = {}) {
+    const readPads = options.gamepads ?? browserPads;
+    const vibrate = options.vibrate === undefined ? browserVibrate() : options.vibrate;
+    const events = options.events === undefined ? browserEvents() : options.events;
+    let padPresent = hasVibratingPad(readPads());
+    const refresh = () => {
+        padPresent = hasVibratingPad(readPads());
+    };
+    const readPerPulse = events === null;
+    events?.addEventListener("gamepadconnected", refresh);
+    events?.addEventListener("gamepaddisconnected", refresh);
+    return {
+        deliver(pulse) {
+            if (readPerPulse)
+                refresh();
+            if (padPresent) {
+                pad(pulse);
+                return "gamepad";
+            }
+            if (vibrate === null || Math.max(0, pulse.ms) === 0)
+                return "none";
+            vibrate(Math.round(pulse.ms));
+            return "vibration";
+        },
+        dispose() {
+            events?.removeEventListener("gamepadconnected", refresh);
+            events?.removeEventListener("gamepaddisconnected", refresh);
+        },
+    };
+}

package/dist/audio/loopParams.js

@@ -54,18 +54,28 @@ const MAX_LISTENER_SPEED = 400;
  */
 export function stepListenerVelocity(track, position, dt) {
     const last = track.last;
-    track.last = { x: position.x, y: position.y, z: position.z };
-    if (last === null || !(dt > 0))
+    if (last === null) {
+        track.last = { x: position.x, y: position.y, z: position.z };
         return track.velocity;
-    const vx = (position.x - last.x) / dt;
-    const vy = (position.y - last.y) / dt;
-    const vz = (position.z - last.z) / dt;
-    if (Math.hypot(vx, vy, vz) > MAX_LISTENER_SPEED) {
-        track.velocity = { x: 0, y: 0, z: 0 };
+    }
+    const dx = position.x - last.x;
+    const dy = position.y - last.y;
+    const dz = position.z - last.z;
+    last.x = position.x;
+    last.y = position.y;
+    last.z = position.z;
+    if (!(dt > 0))
         return track.velocity;
+    const v = track.velocity;
+    if (Math.hypot(dx, dy, dz) / dt > MAX_LISTENER_SPEED) {
+        v.x = 0;
+        v.y = 0;
+        v.z = 0;
+        return v;
     }
     const blend = 1 - Math.exp(-dt / 0.05);
-    const v = track.velocity;
-    track.velocity = { x: v.x + (vx - v.x) * blend, y: v.y + (vy - v.y) * blend, z: v.z + (vz - v.z) * blend };
-    return track.velocity;
+    v.x += (dx / dt - v.x) * blend;
+    v.y += (dy / dt - v.y) * blend;
+    v.z += (dz / dt - v.z) * blend;
+    return v;
 }

package/dist/audio/playableAudio.d.ts

@@ -1,6 +1,6 @@
 import type { AudioBusDef, SoundDef } from "@jgengine/core/audio/audioFalloff";
 import type { PlayableGame } from "../registry.js";
-/** A playable's sound catalog and buses with the default UI cues merged in. @internal */
+/** A playable's sound catalog and buses with the default UI and gameplay feedback cues merged in. @internal */
 export interface ResolvedPlayableAudio {
     sounds: Record<string, SoundDef>;
     buses: Record<string, AudioBusDef> | undefined;

package/dist/audio/playableAudio.js

@@ -1,10 +1,12 @@
+import { withFeedbackCueSounds } from "@jgengine/core/audio/feedbackCues";
 import { withUiCueSounds } from "@jgengine/core/audio/uiCues";
 const cache = new WeakMap();
 /** Resolve once per playable so the engine, the volume bridge and the settings rows share one bus list. @internal */
 export function resolvePlayableAudio(playable) {
     let resolved = cache.get(playable);
     if (resolved === undefined) {
-        resolved = withUiCueSounds(playable.audio?.sounds, playable.audio?.buses, playable.audio?.uiCues);
+        const ui = withUiCueSounds(playable.audio?.sounds, playable.audio?.buses, playable.audio?.uiCues);
+        resolved = withFeedbackCueSounds(ui.sounds, ui.buses, playable.audio?.feedbackCues);
         cache.set(playable, resolved);
     }
     return resolved;

package/dist/devtools/FrameTelemetry.d.ts

@@ -1,4 +1,4 @@
-import type { PerfQuality } from "@jgengine/core/devtools/devtools";
+import { type PerfQuality } from "@jgengine/core/devtools/devtools";
 /**
  * Mounts the in-page frame sampler for the live 3D scene: it wraps this renderer's
  * context for GPU-object counts, reads renderer and scene numbers on demand, and

package/dist/devtools/FrameTelemetry.js

@@ -1,5 +1,6 @@
 import { useEffect } from "react";
 import { useThree } from "@react-three/fiber";
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { readUrlParam } from "@jgengine/core/devtools/urlFlags";
 import { attachGlCounters, installFrameTelemetry, probeReportRoute, reportGameId, TELEMETRY_FLAG, } from "./frameSampler.js";
 /**
@@ -35,12 +36,13 @@ export function FrameTelemetry({ game, quality }) {
                 quality: () => quality,
                 viewport: () => `${window.innerWidth}x${window.innerHeight}`,
                 gpu: () => readGpuLabel(gl.getContext()),
-                render: () => ({
+                render: () => devtools.render.latest() ?? {
+                    // Falling back to the live counter is a mid-frame read: it holds the passes drawn so far.
                     drawCalls: gl.info.render.calls,
                     triangles: gl.info.render.triangles,
                     geometries: gl.info.memory.geometries,
                     textures: gl.info.memory.textures,
-                }),
+                },
                 scene: () => scene,
                 gl: () => counters,
                 residentPrograms: () => gl.info.programs?.length ?? null,

package/dist/devtools/agentBridge.js

@@ -1,5 +1,6 @@
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
+import { canvasCover } from "@jgengine/react/canvasCover";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
 import { buildFullReport, buildLeanReport, summarizeLeanReport } from "./devtoolsReports.js";
@@ -125,6 +126,7 @@ function panelLayoutSnapshot(placement, extras) {
 export function installAgentBridge(options) {
     const { playable, devtoolsEnabled, isDevtoolsOpen, setDevtoolsOpen } = options;
     const getContext = options.getContext ?? (() => null);
+    let coverRelease = null;
     const handle = (request) => {
         const method = typeof request?.method === "string" ? request.method : "";
         switch (method) {
@@ -317,6 +319,15 @@ export function installAgentBridge(options) {
                 }
                 return { ok: false, error: `no HUD panel "${id}" — canvas_state lists ids` };
             }
+            case "canvas_cover": {
+                if (request.covered === true) {
+                    coverRelease ??= canvasCover.hold();
+                    return { ok: true, covered: true, holders: canvasCover.holders() };
+                }
+                coverRelease?.();
+                coverRelease = null;
+                return { ok: true, covered: canvasCover.covered(), holders: canvasCover.holders() };
+            }
             case "canvas_list_panel_types":
                 return {
                     ok: true,
@@ -368,6 +379,8 @@ export function installAgentBridge(options) {
     };
     window.__jgengineAgent = { handle };
     return () => {
+        coverRelease?.();
+        coverRelease = null;
         if (window.__jgengineAgent?.handle === handle)
             delete window.__jgengineAgent;
     };

package/dist/devtools/frameSampler.js

@@ -110,6 +110,10 @@ export function buildFrameReport(inputs) {
         frame: scaled,
         render: {
             draws: inputs.render?.drawCalls ?? null,
+            // Only the CDP harness wraps the draw calls and samples a whole frame; this sampler reads
+            // whatever the renderer probe last recorded, so it cannot state a percentile.
+            drawsFrame: null,
+            drawsFrames: 0,
             triangles: inputs.render?.triangles ?? null,
             geometries: inputs.render?.geometries ?? null,
             textures: inputs.render?.textures ?? null,

package/dist/drivers/CanvasCoverFrameloop.d.ts

@@ -0,0 +1,13 @@
+/** The frameloop the shell asked for; the cover only ever overrides it with `"never"`. */
+type CanvasFrameloop = "always" | "demand" | "never";
+/**
+ * Stops R3F's loop while a surface covers the canvas: the world, its shadow passes and postfx
+ * stop drawing, and the last drawn frame stays on the canvas under the surface. Input, audio and
+ * the DOM HUD live outside the loop and keep running. Lifting the cover restores the loop, which
+ * draws the untouched scene again.
+ * @internal
+ */
+export declare function CanvasCoverFrameloop({ authored }: {
+    authored: CanvasFrameloop;
+}): null;
+export {};

package/dist/drivers/CanvasCoverFrameloop.js

@@ -0,0 +1,22 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+import { useCanvasCovered } from "@jgengine/react/canvasCover";
+/**
+ * Stops R3F's loop while a surface covers the canvas: the world, its shadow passes and postfx
+ * stop drawing, and the last drawn frame stays on the canvas under the surface. Input, audio and
+ * the DOM HUD live outside the loop and keep running. Lifting the cover restores the loop, which
+ * draws the untouched scene again.
+ * @internal
+ */
+export function CanvasCoverFrameloop({ authored }) {
+    const covered = useCanvasCovered();
+    const frameloop = useThree((state) => state.frameloop);
+    const setFrameloop = useThree((state) => state.setFrameloop);
+    useEffect(() => {
+        const wanted = covered ? "never" : authored;
+        if (frameloop === wanted)
+            return;
+        setFrameloop(wanted);
+    }, [covered, authored, frameloop, setFrameloop]);
+    return null;
+}

package/dist/drivers/FrameRateLimiter.d.ts

@@ -1,7 +1,8 @@
 /**
  * Drives the Canvas at a capped frame rate. Mount only with `frameloop="never"`: it runs its
  * own requestAnimationFrame loop and advances R3F on the refreshes `paceFrame` admits, so
- * simulation, useFrame and rendering all run at the cap with correct deltas.
+ * simulation, useFrame and rendering all run at the cap with correct deltas. Under a canvas
+ * cover it advances nothing, so a covered canvas draws no frames even at a cap.
  * @internal shell-internal; driven by the player's frame-rate limit setting.
  */
 export declare function FrameRateLimiter({ fps }: {

package/dist/drivers/FrameRateLimiter.js

@@ -1,17 +1,20 @@
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
 import { paceFrame } from "@jgengine/core/settings/frameRateLimit";
+import { useCanvasCovered } from "@jgengine/react/canvasCover";
 /**
  * Drives the Canvas at a capped frame rate. Mount only with `frameloop="never"`: it runs its
  * own requestAnimationFrame loop and advances R3F on the refreshes `paceFrame` admits, so
- * simulation, useFrame and rendering all run at the cap with correct deltas.
+ * simulation, useFrame and rendering all run at the cap with correct deltas. Under a canvas
+ * cover it advances nothing, so a covered canvas draws no frames even at a cap.
  * @internal shell-internal; driven by the player's frame-rate limit setting.
  */
 export function FrameRateLimiter({ fps }) {
+    const covered = useCanvasCovered();
     const advance = useThree((state) => state.advance);
     const get = useThree((state) => state.get);
     useEffect(() => {
-        if (fps <= 0)
+        if (fps <= 0 || covered)
             return;
         // R3F's "never" mode reads the timestamp as seconds on its own clock; continue that clock.
         const base = get().clock.elapsedTime;
@@ -34,6 +37,6 @@ export function FrameRateLimiter({ fps }) {
             // Hand the clock back to R3F's own loop in milliseconds so its next delta is one frame.
             get().clock.oldTime = performance.now();
         };
-    }, [fps, advance, get]);
+    }, [fps, advance, get, covered]);
     return null;
 }

package/dist/postfx/PostProcessing.d.ts

@@ -1,9 +1,62 @@
+import * as THREE from "three";
 import { EffectComposer, type ShaderPass } from "three-stdlib";
-import { type AoConfig, type PostProcessingConfig } from "@jgengine/core/render/postProcessing";
+import { type AoConfig, type BloomConfig, type DofConfig, type GradeConfig, type PostProcessingConfig, type StylizeConfig } from "@jgengine/core/render/postProcessing";
+import { type AutoExposureConfig } from "@jgengine/core/render/colorPipeline";
 import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+/**
+ * GTAO renders the scene with an `overrideMaterial` normal/depth prepass when it has no GBuffer,
+ * which stamps transparent overlay quads (additive VFX sprites, telegraphs, debug gizmos) into the
+ * AO buffers as opaque squares — the AO composite then multiplies them toward black. Hide marked
+ * overlay subtrees for the whole pass: the beauty buffer it composites over was already rendered
+ * with them in. A chain whose AO reads the beauty pass's own depth buffer draws no prepass, so
+ * nothing is stamped and the cached hide list is empty.
+ */
+/**
+ * GTAO's own `_overrideVisibility` walks the whole scene to hide points and lines before its normal
+ * render. `renderShadowlessPrepass` already hides the same set from a cached list, so that walk is
+ * skipped here; three only fills its cache with objects it hid, so leaving it empty restores nothing.
+ * The hooks are optional: a three version without them leaves the walk in place.
+ * @internal
+ */
+export type GtaoVisibilityHooks = {
+    _overrideVisibility?: () => void;
+    _restoreVisibility?: () => void;
+};
+/** Point three's GTAO pass at the prepass that already hid its points and lines. @internal */
+export declare function skipGtaoVisibilityWalk(pass: object): boolean;
+/** A post chain stage that costs its own draws; the plan names the ones a chain actually builds. @internal */
+export type PostfxStage = "ao" | "bloom" | "dof" | "smaa" | "exposure" | "stylize" | "grade";
+/** What one chain will build, resolved from the game's config, the tier and the player's toggles. @internal */
+export interface PostfxStagePlan {
+    /** MSAA samples on the composer's beauty target: 2 unless AA is off or MSAA-only. */
+    samples: number;
+    ao: AoConfig | null;
+    aoSamples: number;
+    /**
+     * Where AO's depth and normals come from. `"beauty"` reads the composer's own depth buffer, so the
+     * stage draws nothing; `"prepass"` renders the scene again for a normal buffer, which is only
+     * needed when the beauty target is multisampled and its depth cannot be sampled.
+     *
+     * The prepass was the whole price of the stage: 537 extra draws and 2.6-2.9 ms/frame in Harbor
+     * Heat, 2,105 extra draws in Drift Foundry (1600x900, RTX 3070). The beauty target is therefore
+     * single-sampled whenever AO reads it, so an `aa: "smaa"` chain keeps SMAA's edge resolve without
+     * the extra MSAA one; `aa: "msaa"` has no other antialiasing and keeps the prepass.
+     */
+    aoGbuffer: "beauty" | "prepass";
+    bloom: BloomConfig | null;
+    dof: DofConfig | null;
+    smaa: boolean;
+    autoExposure: AutoExposureConfig | null;
+    stylize: StylizeConfig | null;
+    grade: GradeConfig | null;
+    /** The authored exposure the meter corrects around. */
+    exposure: number;
+}
 interface BuiltGraph {
     composer: EffectComposer;
     grade: ShaderPass | null;
+    /** Stages this chain actually built, in pass order. A stage absent here costs no draw. */
+    stages: readonly PostfxStage[];
 }
 /**
  * Rounds an adapted exposure to 1/32 of a stop. Without it the sky's display-colour cache (which keys
@@ -17,6 +70,28 @@ export declare function disposeGraph(built: BuiltGraph): void;
 export declare function syncSize(built: BuiltGraph, width: number, height: number, pixelRatio: number): void;
 /** AO the chain runs: authored config, {@link DEFAULT_AO} when unset, null when off or the tier skips it. @internal */
 export declare function resolveAoStage(ao: PostProcessingConfig["ao"], tierAllowsAo: boolean): AoConfig | null;
+/** The stages one chain asks for, before any pass is built. Pure data. @internal */
+export declare function planPostStages(config: PostProcessingConfig, quality?: GraphicsQuality, stages?: {
+    ao: boolean;
+    bloom: boolean;
+    dof: boolean;
+    smaa: boolean;
+}): PostfxStagePlan;
+/** The stage toggles a settings surface may offer; each is a pass a chain can either build or skip. @internal */
+export type PostfxToggleStage = "ao" | "bloom" | "dof" | "smaa";
+/**
+ * The toggle stages a chain built from `config` can contain on its most permissive tier, with the
+ * player's own toggles ignored. A row for any other stage switches a pass the chain never builds, so
+ * nothing the player picks reaches the screen.
+ * @internal
+ */
+export declare function availablePostfxStages(config: PostProcessingConfig): readonly PostfxToggleStage[];
+/**
+ * Build the composer for a plan. A stage the plan left out adds no pass, so it draws nothing and
+ * allocates no render target.
+ * @internal
+ */
+export declare function buildPostGraph(gl: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, plan: PostfxStagePlan, width: number, height: number): BuiltGraph;
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
@@ -25,7 +100,8 @@ export declare function resolveAoStage(ao: PostProcessingConfig["ao"], tierAllow
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes
  * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
- * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages. A stage
+ * that is off adds no pass at all, so it costs no draw and allocates no target.
  */
 export declare function PostProcessing({ config, quality, stages }: {
     config: PostProcessingConfig;

package/dist/postfx/PostProcessing.js

@@ -6,23 +6,39 @@ import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
-import { DEFAULT_AO } from "@jgengine/core/render/postProcessing";
-import { adaptExposure, DEFAULT_AUTO_EXPOSURE, exposureForKey, keyLuminanceFromSamples } from "@jgengine/core/render/colorPipeline";
+import { DEFAULT_AO, } from "@jgengine/core/render/postProcessing";
+import { adaptExposure, DEFAULT_AUTO_EXPOSURE, exposureForKey, keyLuminanceFromSamples, } from "@jgengine/core/render/colorPipeline";
 import { ExposureMeterPass } from "./autoExposure.js";
 import { createGradePass } from "./gradeShader.js";
+import { releasePostfxOverlayTracking } from "./postfxOverlay.js";
 import { StylizePass } from "./stylizePass.js";
 import { renderShadowlessPrepass } from "./shadowPrepass.js";
-/**
- * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
- * transparent overlay quads (additive VFX sprites, telegraphs, debug gizmos) into the AO
- * buffers as opaque squares — the AO composite then multiplies them toward black. Hide
- * marked overlay subtrees for the whole pass: the beauty buffer it composites over was
- * already rendered with them in.
- */
+/** Point three's GTAO pass at the prepass that already hid its points and lines. @internal */
+export function skipGtaoVisibilityWalk(pass) {
+    const hooks = pass;
+    if (typeof hooks._overrideVisibility !== "function" || typeof hooks._restoreVisibility !== "function")
+        return false;
+    const restore = hooks._restoreVisibility;
+    hooks._overrideVisibility = () => { };
+    hooks._restoreVisibility = () => {
+        // three's restore only touches its own cache, which stays empty while the walk is skipped.
+        restore.call(pass);
+    };
+    return true;
+}
 class OverlayAwareGTAOPass extends GTAOPass {
     hiddenOverlays = [];
+    constructor(scene, camera, width, height) {
+        super(scene, camera, width, height);
+        skipGtaoVisibilityWalk(this);
+    }
     render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
-        renderShadowlessPrepass(renderer, this.scene, this.hiddenOverlays, () => super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive));
+        const rendersGbuffer = this._renderGBuffer !== false;
+        if (!rendersGbuffer) {
+            super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+            return;
+        }
+        renderShadowlessPrepass(renderer, this.scene, this.hiddenOverlays, () => super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive), true);
     }
 }
 /** DOF's depth prepass has the same `overrideMaterial` overlay-stamping problem as GTAO. */
@@ -65,6 +81,125 @@ export function resolveAoStage(ao, tierAllowsAo) {
         return null;
     return ao ?? DEFAULT_AO;
 }
+/** The stages one chain asks for, before any pass is built. Pure data. @internal */
+export function planPostStages(config, quality = "high", stages) {
+    const aa = config.aa === undefined ? "smaa" : config.aa;
+    const tierStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
+    const ao = resolveAoStage(config.ao, tierStages.ao);
+    const authoredDof = tierStages.dof && config.dof !== undefined && config.dof !== false ? config.dof : null;
+    const bloom = tierStages.bloom && config.bloom !== false ? (config.bloom ?? {}) : null;
+    const smaa = tierStages.smaa && aa === "smaa";
+    return {
+        samples: aa === false ? 0 : 2,
+        ao,
+        aoSamples: quality === "ultra" ? 16 : quality === "high" ? 12 : 8,
+        aoGbuffer: smaa || aa === false ? "beauty" : "prepass",
+        bloom,
+        dof: authoredDof === null ? null : { ...authoredDof, aperture: authoredDof.aperture ?? (quality === "high" ? 0.00025 : 0.00012) },
+        smaa,
+        autoExposure: config.autoExposure === false ? null : { ...DEFAULT_AUTO_EXPOSURE, ...(config.autoExposure ?? {}) },
+        stylize: config.stylize !== undefined && config.stylize !== false ? config.stylize : null,
+        grade: config.grade !== false ? (config.grade ?? {}) : null,
+        exposure: config.exposure ?? 1,
+    };
+}
+/**
+ * The toggle stages a chain built from `config` can contain on its most permissive tier, with the
+ * player's own toggles ignored. A row for any other stage switches a pass the chain never builds, so
+ * nothing the player picks reaches the screen.
+ * @internal
+ */
+export function availablePostfxStages(config) {
+    const plan = planPostStages(config, "high", { ao: true, bloom: true, dof: true, smaa: true });
+    const stages = [];
+    if (plan.ao !== null)
+        stages.push("ao");
+    if (plan.bloom !== null)
+        stages.push("bloom");
+    if (plan.dof !== null)
+        stages.push("dof");
+    if (plan.smaa)
+        stages.push("smaa");
+    return stages;
+}
+/**
+ * Build the composer for a plan. A stage the plan left out adds no pass, so it draws nothing and
+ * allocates no render target.
+ * @internal
+ */
+export function buildPostGraph(gl, scene, camera, plan, width, height) {
+    const beautyDepth = plan.ao !== null && plan.aoGbuffer === "beauty" ? new THREE.DepthTexture(width, height) : null;
+    const target = new THREE.WebGLRenderTarget(width, height, {
+        type: THREE.HalfFloatType,
+        samples: beautyDepth === null ? plan.samples : 0,
+        ...(beautyDepth === null ? {} : { depthTexture: beautyDepth }),
+    });
+    const composer = new EffectComposer(gl, target);
+    const built = [];
+    composer.addPass(new RenderPass(scene, camera));
+    if (plan.ao !== null) {
+        const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
+        if (beautyDepth !== null)
+            ao.setGBuffer(beautyDepth);
+        ao.blendIntensity = plan.ao.blend ?? 1;
+        ao.updateGtaoMaterial({
+            radius: plan.ao.radius ?? 1.8,
+            distanceExponent: 1,
+            thickness: plan.ao.distanceFalloff ?? 3.6,
+            scale: plan.ao.intensity ?? 2.4,
+            samples: plan.aoSamples,
+        });
+        composer.addPass(ao);
+        built.push("ao");
+    }
+    if (plan.bloom !== null) {
+        composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), plan.bloom.strength ?? 0.32, plan.bloom.radius ?? 0.55, plan.bloom.threshold ?? 0.85));
+        built.push("bloom");
+    }
+    if (plan.dof !== null) {
+        const dof = new OverlayAwareBokehPass(scene, camera, {
+            focus: plan.dof.focus ?? 18,
+            aperture: plan.dof.aperture ?? 0.00025,
+            maxblur: plan.dof.maxBlur ?? 0.01,
+        });
+        composer.addPass(dof);
+        built.push("dof");
+    }
+    // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
+    if (plan.smaa) {
+        composer.addPass(new SMAAPass());
+        built.push("smaa");
+    }
+    // Clamped auto-exposure meters the pre-tone-map buffer, so the meter sits before OutputPass and
+    // hands the adaptation to the renderer's exposure — the one value the sky swatches also read.
+    const authoredExposure = plan.exposure;
+    if (plan.autoExposure !== null) {
+        const autoExposure = plan.autoExposure;
+        let current = authoredExposure;
+        let sampled = false;
+        composer.addPass(new ExposureMeterPass((samples, seconds) => {
+            const target = authoredExposure * exposureForKey(keyLuminanceFromSamples(samples), autoExposure);
+            // The first sample lands on its own target; fading in from the authored exposure would
+            // open every load on a visible exposure slideshow.
+            current = sampled ? adaptExposure(current, target, seconds, autoExposure.adaptationSeconds) : target;
+            sampled = true;
+            gl.toneMappingExposure = quantizeExposure(current);
+        }));
+        built.push("exposure");
+    }
+    composer.addPass(new OutputPass());
+    if (plan.stylize !== null) {
+        composer.addPass(new StylizePass(scene, camera, plan.stylize));
+        built.push("stylize");
+    }
+    let grade = null;
+    if (plan.grade !== null) {
+        grade = createGradePass(plan.grade);
+        composer.addPass(grade);
+        built.push("grade");
+    }
+    return { composer, grade, stages: built };
+}
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
@@ -73,7 +208,8 @@ export function resolveAoStage(ao, tierAllowsAo) {
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes
  * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
- * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages. A stage
+ * that is off adds no pass at all, so it costs no draw and allocates no target.
  */
 export function PostProcessing({ config, quality = "high", stages }) {
     const gl = useThree((s) => s.gl);
@@ -84,75 +220,12 @@ export function PostProcessing({ config, quality = "high", stages }) {
     useEffect(() => {
         const width = Math.max(1, size.width);
         const height = Math.max(1, size.height);
-        const aa = config.aa === undefined ? "smaa" : config.aa;
-        const msaaSamples = aa === false ? 0 : 2;
-        const target = new THREE.WebGLRenderTarget(width, height, {
-            type: THREE.HalfFloatType,
-            samples: msaaSamples,
-        });
-        const composer = new EffectComposer(gl, target);
-        composer.addPass(new RenderPass(scene, camera));
-        const resolvedStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
-        const aoStage = resolveAoStage(config.ao, resolvedStages.ao);
-        if (aoStage !== null) {
-            const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
-            ao.blendIntensity = aoStage.blend ?? 1;
-            ao.updateGtaoMaterial({
-                radius: aoStage.radius ?? 1.8,
-                distanceExponent: 1,
-                thickness: aoStage.distanceFalloff ?? 3.6,
-                scale: aoStage.intensity ?? 2.4,
-                samples: quality === "ultra" ? 16 : quality === "high" ? 12 : 8,
-            });
-            composer.addPass(ao);
-        }
-        if (resolvedStages.bloom && config.bloom !== false) {
-            const b = config.bloom ?? {};
-            composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
-        }
-        if (resolvedStages.dof && config.dof !== undefined && config.dof !== false) {
-            const d = config.dof;
-            const dof = new OverlayAwareBokehPass(scene, camera, {
-                focus: d.focus ?? 18,
-                aperture: d.aperture ?? (quality === "high" ? 0.00025 : 0.00012),
-                maxblur: d.maxBlur ?? 0.01,
-            });
-            composer.addPass(dof);
-        }
-        // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
-        if (resolvedStages.smaa && aa === "smaa") {
-            composer.addPass(new SMAAPass());
-        }
-        // Clamped auto-exposure meters the pre-tone-map buffer, so the meter sits before OutputPass and
-        // hands the adaptation to the renderer's exposure — the one value the sky swatches also read.
-        const autoExposure = config.autoExposure === false ? null : { ...DEFAULT_AUTO_EXPOSURE, ...(config.autoExposure ?? {}) };
-        const authoredExposure = config.exposure ?? 1;
-        if (autoExposure !== null) {
-            let current = authoredExposure;
-            let sampled = false;
-            composer.addPass(new ExposureMeterPass((samples, seconds) => {
-                const target = authoredExposure * exposureForKey(keyLuminanceFromSamples(samples), autoExposure);
-                // The first sample lands on its own target; fading in from the authored exposure would
-                // open every load on a visible exposure slideshow.
-                current = sampled ? adaptExposure(current, target, seconds, autoExposure.adaptationSeconds) : target;
-                sampled = true;
-                gl.toneMappingExposure = quantizeExposure(current);
-            }));
-        }
-        composer.addPass(new OutputPass());
-        if (config.stylize !== undefined && config.stylize !== false) {
-            composer.addPass(new StylizePass(scene, camera, config.stylize));
-        }
-        let grade = null;
-        if (config.grade !== false) {
-            grade = createGradePass(config.grade ?? {});
-            composer.addPass(grade);
-        }
-        const graph = { composer, grade };
+        const graph = buildPostGraph(gl, scene, camera, planPostStages(config, quality, stages), width, height);
         syncSize(graph, width, height, gl.getPixelRatio());
         builtRef.current = graph;
         return () => {
             disposeGraph(graph);
+            releasePostfxOverlayTracking(scene);
             builtRef.current = null;
         };
     }, [gl, scene, camera, config, quality, stages]);