@jgengine/shell 0.32.0 → 0.34.0

package/dist/audio/emitterTracking.js

@@ -0,0 +1,153 @@
+/**
+ * Track one sound map's positional loops.
+ *
+ * Membership is reconciled only when `sources.ids()` returns a new array, and each frame then reads
+ * just the tracked emitters — so a game with hundreds of props and a handful of sounding ones pays
+ * for the handful, and a still frame allocates nothing. An emitter that gains a sounding key through
+ * a rename is picked up on the next membership change, not per frame; catalog ids never change, and a
+ * spawned entity already carries the name its sound map is keyed by.
+ * @internal
+ */
+export function createEmitterTracker(options) {
+    const entries = [];
+    const byId = new Map();
+    const pose = { key: "", position: [0, 0, 0] };
+    const target = { x: 0, y: 0, z: 0 };
+    let soundsRef;
+    let idsRef = null;
+    let reconcileNext = false;
+    function stopEntry(entry) {
+        entry.handle?.stop();
+        entry.handle = null;
+    }
+    function removeAt(index) {
+        const entry = entries[index];
+        stopEntry(entry);
+        byId.delete(entry.id);
+        const last = entries.pop();
+        if (index < entries.length) {
+            entries[index] = last;
+            last.index = index;
+        }
+    }
+    function clear() {
+        for (let index = 0; index < entries.length; index += 1)
+            stopEntry(entries[index]);
+        entries.length = 0;
+        byId.clear();
+    }
+    function playAt(sound, x, y, z) {
+        target.x = x;
+        target.y = y;
+        target.z = z;
+        return options.play(sound, target);
+    }
+    function start(id, key, sound) {
+        const position = pose.position;
+        const entry = {
+            id,
+            key,
+            sound,
+            handle: playAt(sound, position[0], position[1], position[2]),
+            index: entries.length,
+            x: position[0],
+            y: position[1],
+            z: position[2],
+        };
+        entries.push(entry);
+        byId.set(id, entry);
+    }
+    function retune(entry, sound) {
+        if (sound === undefined) {
+            removeAt(entry.index);
+            return false;
+        }
+        entry.key = pose.key;
+        if (sound !== entry.sound) {
+            stopEntry(entry);
+            entry.sound = sound;
+            entry.handle = playAt(sound, pose.position[0], pose.position[1], pose.position[2]);
+        }
+        applyPose(entry);
+        return true;
+    }
+    function applyPose(entry) {
+        const position = pose.position;
+        if (position[0] === entry.x && position[1] === entry.y && position[2] === entry.z)
+            return;
+        entry.x = position[0];
+        entry.y = position[1];
+        entry.z = position[2];
+        if (entry.handle !== null) {
+            target.x = entry.x;
+            target.y = entry.y;
+            target.z = entry.z;
+            entry.handle.setPosition(target);
+        }
+    }
+    function reconcile(sounds) {
+        for (let index = entries.length - 1; index >= 0; index -= 1) {
+            const entry = entries[index];
+            if (!options.sources.read(entry.id, pose))
+                removeAt(index);
+        }
+        for (const id of options.sources.ids()) {
+            if (byId.has(id) || !options.sources.read(id, pose))
+                continue;
+            const sound = sounds[pose.key];
+            if (sound !== undefined)
+                start(id, pose.key, sound);
+        }
+    }
+    return {
+        step() {
+            const sounds = options.sounds();
+            if (sounds === undefined) {
+                if (entries.length > 0)
+                    clear();
+                soundsRef = undefined;
+                idsRef = null;
+                return;
+            }
+            if (sounds !== soundsRef) {
+                soundsRef = sounds;
+                reconcileNext = true;
+            }
+            const ids = options.sources.ids();
+            if (ids !== idsRef) {
+                idsRef = ids;
+                reconcileNext = true;
+            }
+            if (reconcileNext) {
+                reconcileNext = false;
+                reconcile(sounds);
+            }
+            // Backwards so a retune that drops an entry does not shift the ones still to visit.
+            for (let index = entries.length - 1; index >= 0; index -= 1) {
+                const entry = entries[index];
+                if (!options.sources.read(entry.id, pose)) {
+                    removeAt(index);
+                    continue;
+                }
+                if (pose.key !== entry.key) {
+                    if (!retune(entry, sounds[pose.key]))
+                        continue;
+                }
+                else {
+                    applyPose(entry);
+                }
+                // A stolen or failed voice is retried while its emitter lives, as the per-frame rebuild did.
+                if (entry.handle === null)
+                    entry.handle = playAt(entry.sound, entry.x, entry.y, entry.z);
+            }
+        },
+        count() {
+            return entries.length;
+        },
+        dispose() {
+            clear();
+            soundsRef = undefined;
+            idsRef = null;
+        },
+    };
+}

package/dist/audio/eventFeedback.d.ts

@@ -42,8 +42,9 @@ export type AnyFeedbackBinding = {
 }[FeedbackEventName];
 /**
  * The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the
- * local player reads as hurt, damage anywhere else as a hit; a wave start has no event of its own,
- * so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+ * local player reads as hurt, damage anywhere else as a hit; an event that carries a `position`
+ * (damage, death) pans and attenuates its cue, and one without still plays centred. A wave start has
+ * no event of its own, so a game announces it through `notify("wave")` or `attachWaveFeedback`.
  */
 export declare const DEFAULT_FEEDBACK_BINDINGS: readonly AnyFeedbackBinding[];
 /** A resolved trigger: pooled per binding, so a busy event stream allocates nothing to decide. */
@@ -58,11 +59,20 @@ export interface ResolvedFeedback {
 }
 /** Everything the feedback seam reaches outside itself. Injected so it runs headless. */
 export interface FeedbackDeps {
-    /** Play one catalog sound through the game's audio seam. */
-    play(sound: string): void;
+    /**
+     * Play one catalog sound through the game's audio seam. `position` is the event's own position
+     * when it carries one, so the engine pans and attenuates the cue; omit it and the cue plays
+     * centred at full gain.
+     */
+    play(sound: string, position?: readonly [number, number, number]): void;
     /** Add camera trauma `0..1`; called with `shake x motionScale`. */
     shake?(amount: number): void;
-    haptics?(pulse: HapticPulse): void; /** Show a caption line for `cue`; only called when captions are on. */
+    /**
+     * One-shot rumble for the local player. Wire it to `createHapticsRoute` so a gamepad takes the
+     * pulse when one is connected and a phone feels it through vibration otherwise.
+     */
+    haptics?(pulse: HapticPulse): void;
+    /** Show a caption line for `cue`; only called when captions are on. */
     caption?(text: string, cue: FeedbackCue): void;
     /** The local player, for `scope: "local"`. */
     localUserId(): string | null;

package/dist/audio/eventFeedback.js

@@ -54,8 +54,9 @@ export const DEFAULT_FEEDBACK_REACTIONS = {
 };
 /**
  * The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the
- * local player reads as hurt, damage anywhere else as a hit; a wave start has no event of its own,
- * so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+ * local player reads as hurt, damage anywhere else as a hit; an event that carries a `position`
+ * (damage, death) pans and attenuates its cue, and one without still plays centred. A wave start has
+ * no event of its own, so a game announces it through `notify("wave")` or `attachWaveFeedback`.
  */
 export const DEFAULT_FEEDBACK_BINDINGS = [
     { event: "combat.damage", cue: "hurt", scope: "local", detail: (event) => `${Math.round(event.amount)}` },
@@ -138,8 +139,11 @@ export function createEventFeedback(deps, options = {}) {
                 return true;
         }
     }
-    function fire(trigger, captionText) {
-        deps.play(trigger.sound);
+    function fire(trigger, captionText, position) {
+        if (position === undefined)
+            deps.play(trigger.sound);
+        else
+            deps.play(trigger.sound, position);
         if (trigger.haptics !== undefined)
             deps.haptics?.(trigger.haptics);
         if (trigger.shake > 0) {
@@ -150,7 +154,7 @@ export function createEventFeedback(deps, options = {}) {
         if (captionsOn && captionText !== undefined)
             deps.caption?.(captionText, trigger.cue);
     }
-    function react(cue, captionText) {
+    function react(cue, captionText, position) {
         const reaction = reactions[cue];
         const trigger = cueTriggers[cue];
         const time = now();
@@ -161,7 +165,7 @@ export function createEventFeedback(deps, options = {}) {
         }
         lastPlayed[cue] = time;
         const text = captionText ?? trigger.caption ?? reaction.caption;
-        fire(trigger, text);
+        fire(trigger, text, position);
         return true;
     }
     return {
@@ -176,7 +180,8 @@ export function createEventFeedback(deps, options = {}) {
                 const detail = binding.detail?.(payload);
                 const base = binding.caption ?? reactions[binding.cue].caption;
                 const captionText = base === undefined ? detail : detail === undefined ? base : `${base} ${detail}`;
-                return react(binding.cue, captionText) ? binding.cue : null;
+                const position = payload.position;
+                return react(binding.cue, captionText, position) ? binding.cue : null;
             }
             return null;
         },

package/dist/audio/hapticsRoute.d.ts

@@ -0,0 +1,28 @@
+import type { HapticPulse } from "@jgengine/core/input/haptics";
+/** Where a pulse actually landed: a gamepad, the device's own motor, or nowhere. */
+export type HapticsSink = "gamepad" | "vibration" | "none";
+/** The browser reach of {@link createHapticsRoute}; injected so the route runs headless. */
+export interface HapticsRouteOptions {
+    /** Connected pads. Default `navigator.getGamepads`. */
+    gamepads?(): ArrayLike<Gamepad | null>;
+    /** Device vibration, called with the pulse length in ms. Default `navigator.vibrate`; `null` for a device without one. */
+    vibrate?: ((ms: number) => void) | null;
+    /** Where `gamepadconnected`/`gamepaddisconnected` arrive. Default `window`; `null` reads pads per pulse. */
+    events?: Pick<Window, "addEventListener" | "removeEventListener"> | null;
+}
+/** Route haptic pulses to whatever the player can feel them on. */
+export interface HapticsRoute {
+    /** Send one pulse: the gamepad if a pad is connected, else the phone's motor, else nothing. */
+    deliver(pulse: HapticPulse): HapticsSink;
+    /** Drop the connection listeners. Safe twice. */
+    dispose(): void;
+}
+/**
+ * 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 declare function createHapticsRoute(pad: (pulse: HapticPulse) => void, options?: HapticsRouteOptions): HapticsRoute;

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/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;