@jgengine/shell 0.19.0 → 0.21.0

package/dist/GamePlayerShell.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 import { createActionStateTracker, toActionStateBindingMap, } from "@jgengine/core/input/actionBindings";
 import { RESERVED_INPUT_ACTIONS } from "./boundActionDispatch.js";
 import { deriveTouchScheme, withTouchCodes, DEFAULT_TOUCH_STYLE } from "@jgengine/core/input/touchScheme";
@@ -13,14 +13,16 @@ import { RotateDeviceScreen } from "@jgengine/react/rotateDevice";
 import { createSettingsStore } from "@jgengine/core/settings/settingsModel";
 import { applyBindingOverrides, clearBindingOverride, loadBindingOverrides, saveBindingOverride, } from "@jgengine/core/input/bindingOverrides";
 import { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "@jgengine/core/ui/orientation";
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams";
 import { armTextureErrors } from "@jgengine/core/devtools/textureErrors";
 import { readUrlFlag, subscribeUrlChange, writeUrlParam } from "@jgengine/core/devtools/urlFlags";
 import { createAudioEngine } from "./audio/audioEngine.js";
 import { attachAudioEventWire } from "./audio/audioWire.js";
 import { installAgentBridge } from "./devtools/agentBridge.js";
-import { withDevtoolsLatency } from "./devtools/DevtoolsOverlay.js";
-import { resolveRigKind } from "./camera/index.js";
+import { attachPlaytestProbe } from "./devtools/playtestProbe.js";
+import { withDevtoolsLatency } from "./devtools/latencyInstrumentation.js";
+import { resolveRigKind } from "./camera/rigResolve.js";
 import { contextModels } from "./render/resolveModel.js";
 import { OrientationHint } from "./touch/OrientationHint.js";
 import { useTouchStyle, useTouchJoystickVariant, useGraphicsSettings } from "./settings/appliedSettings.js";
@@ -29,7 +31,13 @@ import { EMPTY_RESERVED } from "./shellConstants.js";
 import { JoinGate } from "./JoinGate.js";
 import { useShellMultiplayerSync } from "./useShellMultiplayerSync.js";
 import { ShellHudPresentation } from "./ShellHudPresentation.js";
-import { Shell3dPresentation } from "./Shell3dPresentation.js";
+import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { resolveInputSink } from "./inputSink.js";
+import { observableShellTracker, attachShellInputPublication } from "./shellInputPublication.js";
+import { attachShellControlSuspension } from "./shellControlSuspension.js";
+import { LazyShell3dPresentation } from "./lazyShell3dPresentation.js";
+import { createPresentationDiagnosticOwnership, createPlaySurfaceFocusOwnership, PresentationRecovery } from "./presentationRecovery.js";
 const DEV_USER_ID = "dev-player";
 /** The query param that mirrors the devtools overlay into the URL — present = open. */
 const DEBUG_PARAM = "debug";
@@ -73,8 +81,11 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const posterSettledRef = useRef(false);
     const [ctx, setCtx] = useState(null);
     const [diagnostics, setDiagnostics] = useState([]);
+    const diagnosticSequence = useRef(0);
+    const presentationDiagnostics = useRef(createPresentationDiagnosticOwnership());
     const [remotePlayers, setRemotePlayers] = useState([]);
     const wrapperRef = useRef(null);
+    const recoveredFocus = useRef(createPlaySurfaceFocusOwnership());
     const yawRef = useRef(0);
     const pitchRef = useRef(0);
     const serverIdRef = useRef(null);
@@ -100,7 +111,7 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     [ctx, effectiveInput, contextVersion]);
     const activeBindingMap = useMemo(() => toActionStateBindingMap(withTouchCodes(activeInput)), [activeInput]);
     // One tracker per context, rebound in place so keys held across a context swap stay held.
-    const tracker = useMemo(() => createActionStateTracker(activeBindingMap), [ctx]);
+    const tracker = useMemo(() => observableShellTracker(createActionStateTracker(activeBindingMap)), [ctx]);
     const boundMapRef = useRef(activeBindingMap);
     if (boundMapRef.current !== activeBindingMap) {
         boundMapRef.current = activeBindingMap;
@@ -115,8 +126,10 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     };
     const deactivatePointerAxis = () => {
         const state = pointerAxisRef.current;
-        if (state !== null && state.active)
+        if (state !== null && state.active) {
             pointerAxisRef.current = { ...state, active: false };
+            tracker.notify("discrete");
+        }
     };
     // Reads fresh every render: the ctx-version useSyncExternalStore below re-renders on store
     // writes, so a gameplay setTouchControlsMode("car") swaps the visible control set that frame.
@@ -138,9 +151,31 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
         onCodeUp: (code) => tracker.handleUp(code),
         onAnalog: (values) => {
             analogRef.current = values;
+            tracker.notify("analog");
         },
     }), [tracker]);
+    useLayoutEffect(() => {
+        if (ctx === null)
+            return;
+        return attachShellControlSuspension({
+            ctx, tracker, pointerAxisRef, analogRef, primaryClickRef, cameraDraggingRef, f2HeldRef,
+        });
+    }, [ctx, tracker]);
     const gateRef = useRef(false);
+    useLayoutEffect(() => {
+        if (ctx === null || poster)
+            return;
+        return attachShellInputPublication({
+            ctx, tracker,
+            active: () => !gateRef.current && playControlsActive(ctx),
+            analog: () => analogRef.current,
+            pointer: () => pointerAxisRef.current,
+            sink: () => resolveInputSink({
+                serverAuthoritative: isServerAuthoritative(playable.game.multiplayer) && multiplayer !== null,
+                backend: multiplayer?.backend ?? null, serverId: serverIdRef.current,
+            }),
+        });
+    }, [ctx, tracker, multiplayer, playable, poster]);
     const orientationPlatform = coarsePointer ? "mobile" : "desktop";
     const orientationRequirement = useMemo(() => resolveOrientationRequirement(playable.orientation, orientationPlatform), [playable, orientationPlatform]);
     const liveOrientation = portrait ? "portrait" : "landscape";
@@ -150,6 +185,8 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const orientationGateEl = orientationGate ? (_jsx(RotateDeviceScreen, { requiredOrientation: orientationRequirement.required ?? "landscape", title: orientationRequirement.required === "portrait" ? "Turn your phone upright" : "Turn your phone sideways", description: `${playable.game.name} is built for ${orientationRequirement.required ?? "landscape"} play.` })) : orientationHint && orientationRequirement.preferred !== null ? (_jsx(OrientationHint, { wanted: orientationRequirement.preferred })) : null;
     const audioEngine = useMemo(() => createAudioEngine({
         sounds: playable.audio?.sounds,
+        maxVoices: playable.audio?.maxVoices,
+        voiceOverflow: playable.audio?.voiceOverflow,
         buses: playable.audio?.buses,
         music: playable.audio?.music,
         musicBus: playable.audio?.musicBus,
@@ -185,10 +222,59 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const userId = multiplayer?.userId ?? DEV_USER_ID;
     const reportRuntimeError = (error, phase, componentStack) => {
         const diagnostic = logRuntimeError(error, phase, componentStack);
-        setDiagnostics((current) => [...current.slice(-4), { ...diagnostic, id: Date.now() + current.length }]);
+        const id = ++diagnosticSequence.current;
+        presentationDiagnostics.current.register(error, id, phase);
+        setDiagnostics((current) => [...current.slice(-4), { ...diagnostic, id }]);
+    };
+    const recoveryTrace = useRef([]);
+    const traceRecovery = (event) => {
+        if (!devtoolsEnabled)
+            return;
+        const wrapper = wrapperRef.current;
+        const active = document.activeElement;
+        const rect = wrapper?.getBoundingClientRect();
+        recoveryTrace.current.push({ ...event, at: performance.now(), connected: wrapper?.isConnected ?? false,
+            rects: wrapper?.getClientRects().length ?? 0, width: rect?.width ?? null, height: rect?.height ?? null,
+            display: wrapper === null ? null : getComputedStyle(wrapper).display,
+            active: active?.tagName ?? null, ownsFocus: active === wrapper, focusInside: wrapper?.contains(active) ?? false });
+    };
+    useEffect(() => {
+        recoveryTrace.current = [];
+        if (!devtoolsEnabled)
+            return;
+        return devtools.probes.register("presentationRecovery", () => recoveryTrace.current);
+    }, [ctx, devtoolsEnabled]);
+    const revealRecoveredPresentation = () => {
+        if (ctx === null)
+            return;
+        traceRecovery({ phase: "shell-reveal-layout" });
+        recoveredFocus.current.reveal(ctx, wrapperRef.current, document.activeElement, document.body);
+        traceRecovery({ phase: "shell-focus-result" });
+    };
+    const retireRecoveredPresentation = (error) => {
+        traceRecovery({ phase: "shell-recovered-callback" });
+        const owned = presentationDiagnostics.current.recovered(error);
+        setDiagnostics((current) => current.filter((diagnostic) => !owned.has(diagnostic.id)));
+        if (ctx !== null)
+            recoveredFocus.current.request(ctx);
+        revealRecoveredPresentation();
     };
     useEffect(() => {
         setDiagnostics([]);
+        let detachProbe = () => { };
+        let ownedContext = null;
+        const disposeOwnedContext = () => {
+            const context = ownedContext;
+            ownedContext = null;
+            if (context === null)
+                return;
+            try {
+                playable.loop.onDispose(context);
+            }
+            catch (error) {
+                reportRuntimeError(error, "dispose");
+            }
+        };
         try {
             const models = contextModels(playable);
             const context = createGameContext({
@@ -197,19 +283,31 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
                 player: { userId, isNew: true },
                 ...(models === undefined ? {} : { models }),
             });
+            ownedContext = context;
             if (playable.localPlayers !== undefined)
                 localPlayers(context).retune(playable.localPlayers);
             playable.loop.onInit(context);
             playable.loop.onNewPlayer(context);
             onContextReady?.(context);
+            const probe = playable.capture?.probe;
+            if (probe !== undefined && typeof window !== "undefined") {
+                detachProbe = attachPlaytestProbe(window, () => probe(context));
+            }
             setCtx(context);
         }
         catch (error) {
+            disposeOwnedContext();
             reportRuntimeError(error, "init");
             setCtx(null);
         }
         return () => {
-            setCtx(null);
+            try {
+                detachProbe();
+            }
+            finally {
+                disposeOwnedContext();
+                setCtx(null);
+            }
         };
     }, [playable, userId]);
     const authoritativeFrameRef = useRef(null);
@@ -254,12 +352,12 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
         deactivatePointerAxis,
     };
     if (rigKind === "none" || playable.presentation === "hud") {
-        return (_jsx(ShellHudPresentation, { ...shared, uiScale: graphics.uiScale, onPointerResumeAudio: () => audioEngine.resume() }));
+        return (_jsx(PresentationRecovery, { ctx: ctx, onRuntimeError: reportRuntimeError, onRetryCommitted: () => wrapperRef.current?.focus({ preventScroll: true }), onRecoveredDraw: retireRecoveredPresentation, onRecoveryEvent: traceRecovery, children: _jsx(ShellHudPresentation, { ...shared, serverIdRef: serverIdRef, uiScale: graphics.uiScale, onPointerResumeAudio: () => audioEngine.resume(), settingsStore: settingsStore, bindingOverrides: bindingOverrides, rebindAction: rebindAction, resetActionBinding: resetActionBinding, audioEngine: audioEngine, poster: poster }) }));
     }
-    return (_jsx(Shell3dPresentation, { ...shared, primaryClickRef: primaryClickRef, cameraDraggingRef: cameraDraggingRef, serverIdRef: serverIdRef, remotePlayers: remotePlayers, touchStyle: touchStyle, compact: compact, graphics: graphics, settingsStore: settingsStore, bindingOverrides: bindingOverrides, rebindAction: rebindAction, resetActionBinding: resetActionBinding, audioEngine: audioEngine, poster: poster, posterFrozen: posterFrozen, onPosterSettled: () => {
-            if (posterSettledRef.current)
-                return;
-            posterSettledRef.current = true;
-            setPosterFrozen(true);
-        }, authoritativeFrameRef: authoritativeFrameRef }));
+    return (_jsx(PresentationRecovery, { ctx: ctx, onRuntimeError: reportRuntimeError, onRetryCommitted: () => wrapperRef.current?.focus({ preventScroll: true }), onRecoveredDraw: retireRecoveredPresentation, onRecoveryEvent: traceRecovery, children: _jsx(LazyShell3dPresentation, { ...shared, onPresentationReveal: revealRecoveredPresentation, primaryClickRef: primaryClickRef, cameraDraggingRef: cameraDraggingRef, serverIdRef: serverIdRef, remotePlayers: remotePlayers, touchStyle: touchStyle, compact: compact, graphics: graphics, settingsStore: settingsStore, bindingOverrides: bindingOverrides, rebindAction: rebindAction, resetActionBinding: resetActionBinding, audioEngine: audioEngine, poster: poster, posterFrozen: posterFrozen, onPosterSettled: () => {
+                if (posterSettledRef.current)
+                    return;
+                posterSettledRef.current = true;
+                setPosterFrozen(true);
+            }, authoritativeFrameRef: authoritativeFrameRef }) }));
 }

package/dist/Shell3dPresentation.d.ts

@@ -1,6 +1,6 @@
 import { type Dispatch, type MutableRefObject, type RefObject, type SetStateAction } from "react";
 import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
-import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { observableShellTracker } from "./shellInputPublication.js";
 import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
 import type { TouchJoystickVariant, TouchScheme, TouchStyle } from "@jgengine/core/input/touchScheme";
 import { type SettingsStore } from "@jgengine/core/settings/settingsModel";
@@ -18,7 +18,7 @@ export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracke
     playable: PlayableGame;
     ctx: GameContext;
     multiplayer: ShellMultiplayer | null;
-    tracker: ActionStateTracker<string>;
+    tracker: ReturnType<typeof observableShellTracker>;
     pointerAxisRef: MutableRefObject<PointerAxisState | null>;
     gateRef: MutableRefObject<boolean>;
     wrapperRef: RefObject<HTMLDivElement | null>;

package/dist/Shell3dPresentation.js

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Canvas } from "@react-three/fiber";
-import { useMemo, useRef, useState, } from "react";
+import { useMemo, useEffect, useRef, useState, useSyncExternalStore, } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import { contextVerbInput, } from "@jgengine/core/interaction/contextMenu";
 import { createSelectionSet, isMarquee, screenRect, selectWithinRect, } from "@jgengine/core/scene/selection";
@@ -15,7 +15,9 @@ import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { GameProvider } from "@jgengine/react/provider";
 import { SettingsProvider } from "@jgengine/react/settings";
 import { resolveWorldSky } from "./worldSky.js";
+import { resolveRuntimeCameraConfig } from "./camera/rigResolve.js";
 import { pointerAimFor, pointerContextMenu } from "./shellPointer.js";
+import { shellPointerInput } from "./shellPointerInput.js";
 import { AudioListener, EntityAudioEmitters, ObjectAudioEmitters } from "./audio/AudioComponents.js";
 import { PostProcessing } from "./postfx/PostProcessing.js";
 import { EnvironmentLighting } from "./render/EnvironmentLighting.js";
@@ -23,6 +25,7 @@ import { CollisionDebugWorld } from "./devtools/CollisionDebugWorld.js";
 import { DevtoolsRendererProbe } from "./devtools/DevtoolsOverlay.js";
 import { CAMERA_TRANSPARENT_USERDATA, GameCameraRig, PlayerFovProvider, PlayerFovSlider, resolveRigKind, rtsPanKeysConflict, } from "./camera/index.js";
 import { CullingProvider } from "./visibility/CullingProvider.js";
+import { BuildingRenderBudget } from "./structures/BuildingRenderBudget.js";
 import { SkyDaylight, TimeOfDayDaylight } from "./environment.js";
 import { bearingFromDirection } from "./environment/daylightCycle.js";
 import { resolveSkyLightOwnership, skyEmitsLights } from "./environment/skyLightingPolicy.js";
@@ -81,12 +84,14 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const pointerService = useMemo(() => createPointerService(), []);
     const selection = useMemo(() => createSelectionSet(), [playable]);
     const controlledEntityId = ctx.player.possession.active(ctx.player.userId);
-    const cameraConfig = playable.camera?.followEntityId !== undefined
+    const cameraOverride = useSyncExternalStore(ctx.camera.subscribe, ctx.camera.rig, ctx.camera.rig);
+    const configuredCamera = playable.camera?.followEntityId !== undefined
         ? playable.camera
         : { ...playable.camera, followEntityId: controlledEntityId };
+    const cameraConfig = resolveRuntimeCameraConfig(configuredCamera, cameraOverride);
     const rigKind = resolveRigKind(cameraConfig);
     const firstPerson = rigKind === "first";
-    const showReticle = (firstPerson && playable.camera?.firstPerson?.reticle !== false) || rigKind === "shoulder";
+    const showReticle = (firstPerson && cameraConfig?.firstPerson?.reticle !== false) || rigKind === "shoulder";
     const rtsPanKeysEnabled = !rtsPanKeysConflict(playable.game.input);
     const bars = resolveWorldOverlayBars(playable.worldHealthBars);
     const nameplates = resolveWorldOverlayBars(playable.nameplates);
@@ -152,7 +157,36 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     };
     /** DOM UI sits in the same wrapper as the canvas — only canvas-targeted clicks are world input. */
     const isWorldPointerTarget = (event) => event.target instanceof HTMLCanvasElement;
+    const pointerInput = useMemo(() => shellPointerInput(tracker, () => playControlsActive(ctx)), [tracker, ctx]);
+    useEffect(() => {
+        const clearGesture = () => { pointerDownRef.current = null; marqueeStartRef.current = null; setMarquee(null); };
+        const up = (event) => {
+            pointerInput.up(event);
+            if (!(event.target instanceof Node) || !wrapperRef.current?.contains(event.target))
+                clearGesture();
+        };
+        const cancel = (event) => { pointerInput.cancel(event.pointerId); clearGesture(); };
+        const retire = () => { pointerInput.cancel(); clearGesture(); };
+        const blur = () => { tracker.reset(); retire(); };
+        const move = (event) => { pointerInput.move(event, false); };
+        const detachReset = pointerInput.attachReset(tracker, clearGesture);
+        window.addEventListener("pointerup", up);
+        window.addEventListener("pointermove", move);
+        window.addEventListener("pointercancel", cancel);
+        window.addEventListener("blur", blur);
+        return () => {
+            window.removeEventListener("pointerup", up);
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointercancel", cancel);
+            window.removeEventListener("blur", blur);
+            detachReset();
+            pointerInput.cancel();
+        };
+    }, [pointerInput, tracker]);
     const handlePointerDown = (event) => {
+        pointerInput.down(event, isWorldPointerTarget(event));
+        if (!playControlsActive(ctx))
+            return;
         if (isWorldPointerTarget(event))
             wrapperRef.current?.focus();
         trackPointerAxis(event);
@@ -167,6 +201,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
         }
     };
     const handlePointerMove = (event) => {
+        pointerInput.move(event, isWorldPointerTarget(event));
         trackPointerAxis(event);
         if (pointer?.select !== true)
             return;
@@ -177,6 +212,13 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
         setMarquee(screenRect(start.x, start.y, point.x, point.y));
     };
     const handlePointerUp = (event) => {
+        const boundPointer = pointerInput.up(event);
+        if (!playControlsActive(ctx)) {
+            pointerDownRef.current = null;
+            marqueeStartRef.current = null;
+            setMarquee(null);
+            return;
+        }
         if (event.button !== 0 || pointerDownRef.current === null)
             return;
         const start = pointerDownRef.current;
@@ -227,7 +269,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
             return;
         }
         const moved = (end.x - start.x) ** 2 + (end.y - start.y) ** 2;
-        if (moved <= PRIMARY_CLICK_MOVE_THRESHOLD_PX * PRIMARY_CLICK_MOVE_THRESHOLD_PX)
+        if (!boundPointer && moved <= PRIMARY_CLICK_MOVE_THRESHOLD_PX * PRIMARY_CLICK_MOVE_THRESHOLD_PX)
             primaryClickRef.current = true;
     };
     const handleContextMenu = (event) => {
@@ -331,9 +373,9 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                             fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                             far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting, profile: graphics.profile })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
-                                                        cameraDraggingRef.current = dragging;
-                                                    } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input, feel: playable.gamepad, seats: localPlayers(ctx), onSeatJoin: (slot) => {
+                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting, profile: graphics.profile })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsx(GameProvider, { context: ctx, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, diagnostics: devtoolsEnabled }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                                            cameraDraggingRef.current = dragging;
+                                                        } }), _jsx(PointerProbe, { service: pointerService })] }) }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input, feel: playable.gamepad, seats: localPlayers(ctx), onSeatJoin: (slot) => {
                                                 try {
                                                     playable.loop.onNewPlayer(ctx, { userId: slot.userId, isNew: true });
                                                 }

package/dist/ShellChrome.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from "react";
+import { type ComponentType } from "react";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import { type RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
@@ -27,6 +27,7 @@ export type ShellKeyHandlers = {
     onKeyDown: (event: {
         code: string;
         target?: EventTarget | null;
+        defaultPrevented?: boolean;
         preventDefault: () => void;
     }) => void;
     onKeyUp: (event: {

package/dist/ShellChrome.js

@@ -1,21 +1,32 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useEffect, useState } from "react";
 import { HudViewportProvider } from "@jgengine/react/hudViewport";
 import { GameProvider } from "@jgengine/react/provider";
-import { DevtoolsOverlay } from "./devtools/DevtoolsOverlay.js";
 import { DiagnosticOverlay, GameUiErrorBoundary, } from "./diagnostics/RuntimeDiagnostics.js";
+import { DevtoolsRuntime } from "./devtools/DevtoolsRuntime.js";
 import { GamePhaseStamp } from "./GamePhaseStamp.js";
+import { SettingsPlayControlGate } from "./settings/SettingsRuntime.js";
+const DevtoolsOverlay = lazy(() => import("./devtools/DevtoolsOverlay.js").then((module) => ({ default: module.DevtoolsOverlay })));
 /** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport. @internal */
 export function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }) {
-    return (_jsx(GameUiErrorBoundary, { onRuntimeError: onRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: uiScale, children: orientationGate ? null : _jsx(GameUI, {}) })] }) }));
+    return (_jsx(GameUiErrorBoundary, { onRuntimeError: onRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(SettingsPlayControlGate, { ctx: ctx }), _jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: uiScale, children: orientationGate ? null : _jsx(GameUI, {}) })] }) }));
 }
 /** Devtools + diagnostic overlays shared by HUD and 3D presentation paths. @internal */
 export function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, devtoolsEnabled, devtoolsOpen, hideDiagnostics = false, }) {
-    return (_jsxs(_Fragment, { children: [devtoolsEnabled ? (_jsx(DevtoolsOverlay, { open: devtoolsOpen, ctx: ctx, playable: playable, multiplayer: multiplayer })) : null, hideDiagnostics ? null : (_jsx(DiagnosticOverlay, { diagnostics: diagnostics, gameName: playable.game.name }))] }));
+    const [openedOnce, setOpenedOnce] = useState(false);
+    useEffect(() => { if (devtoolsOpen)
+        setOpenedOnce(true); }, [devtoolsOpen]);
+    return (_jsxs(_Fragment, { children: [devtoolsEnabled ? _jsx(DevtoolsRuntime, { ctx: ctx, playable: playable }) : null, devtoolsEnabled && (devtoolsOpen || openedOnce) ? (_jsx(Suspense, { fallback: devtoolsOpen ? _jsx("div", { role: "status", style: { position: "absolute", right: 16, top: 16, zIndex: 90, color: "#e2e8f0", background: "#0f172a", padding: "10px 14px", borderRadius: 8 }, children: "Loading developer tools\u2026" }) : null, children: _jsx(DevtoolsOverlay, { open: devtoolsOpen, ctx: ctx, playable: playable, multiplayer: multiplayer }) })) : null, hideDiagnostics ? null : (_jsx(DiagnosticOverlay, { diagnostics: diagnostics, gameName: playable.game.name }))] }));
 }
 /** F2 chord + gameplay action tracker key handlers shared by both presentation paths. @internal */
 export function createShellKeyHandlers({ f2HeldRef, tracker, devtoolsEnabled, setDevtoolsOpen, controlsActive, exitPointerLockOnDevtools = false, }) {
     return {
         onKeyDown: (event) => {
+            if (event.defaultPrevented) {
+                f2HeldRef.current = false;
+                tracker.reset();
+                return;
+            }
             const target = event.target;
             if (target?.closest?.("input, textarea, select, [contenteditable]:not([contenteditable=false])")) {
                 f2HeldRef.current = false;
@@ -36,10 +47,15 @@ export function createShellKeyHandlers({ f2HeldRef, tracker, devtoolsEnabled, se
                 }
                 return;
             }
-            if (event.code === "Tab" || event.code === "Space")
-                event.preventDefault();
-            if (controlsActive())
+            if (target?.closest?.('button, a[href], [role="button"], [role="link"], [role="dialog"], [role="menu"], [role="listbox"], [role="grid"], [role="gridcell"], [role="toolbar"]')) {
+                tracker.reset();
+                return;
+            }
+            if (controlsActive()) {
+                if (event.code === "Tab" || event.code === "Space")
+                    event.preventDefault();
                 tracker.handleDown(event.code);
+            }
         },
         onKeyUp: (event) => {
             if (event.code === "F2") {

package/dist/ShellHudPresentation.d.ts

@@ -2,10 +2,13 @@ import { type Dispatch, type MutableRefObject, type RefObject, type SetStateActi
 import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
 import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
+import { type SettingsStore } from "@jgengine/core/settings/settingsModel";
 import type { TouchScheme } from "@jgengine/core/input/touchScheme";
 import type { RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
+import type { AudioEngine } from "./audio/audioEngine.js";
 /**
  * Marks a HUD-only page ready for capture (`data-jg-capture="ready"`) unless a capture host already
  * owns the flag. A HUD game has no `<canvas>`, so capture tools that wait for one would time out.
@@ -15,10 +18,11 @@ export declare function markHudCaptureReady(root: {
     dataset: DOMStringMap;
 }): void;
 /** HUD-only play surface for non-3D shells. @internal */
-export declare function ShellHudPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, touchScheme, touchSink, orientationGate, orientationGateEl, coarsePointer, uiScale, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, onPointerResumeAudio, }: {
+export declare function ShellHudPresentation({ playable, ctx, multiplayer, serverIdRef, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, touchScheme, touchSink, orientationGate, orientationGateEl, coarsePointer, uiScale, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, onPointerResumeAudio, settingsStore, bindingOverrides, rebindAction, resetActionBinding, audioEngine, poster, }: {
     playable: PlayableGame;
     ctx: GameContext;
     multiplayer: ShellMultiplayer | null;
+    serverIdRef: MutableRefObject<string | null>;
     tracker: ActionStateTracker<string>;
     pointerAxisRef: MutableRefObject<PointerAxisState | null>;
     gateRef: MutableRefObject<boolean>;
@@ -46,4 +50,10 @@ export declare function ShellHudPresentation({ playable, ctx, multiplayer, track
     }) => void;
     deactivatePointerAxis: () => void;
     onPointerResumeAudio: () => void;
+    settingsStore: SettingsStore;
+    bindingOverrides: BindingOverrides;
+    rebindAction: (action: string, code: string) => void;
+    resetActionBinding: (action: string) => void;
+    audioEngine: AudioEngine;
+    poster: boolean;
 }): import("react").JSX.Element;

package/dist/ShellHudPresentation.js

@@ -1,9 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect } from "react";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { BUILT_IN_SETTING_CATEGORIES } from "@jgengine/core/settings/settingsModel";
+import { SettingsProvider } from "@jgengine/react/settings";
 import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { HudOnlyDriver } from "./drivers/HudOnlyDriver.js";
 import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
+import { AudioSettingsBridge } from "./settings/appliedSettings.js";
+import { SettingsRuntime } from "./settings/SettingsRuntime.js";
+import { SettingsChrome } from "./settings/SettingsChrome.js";
 import { TouchPlaySurface } from "./touch/TouchControlsOverlay.js";
 /**
  * Marks a HUD-only page ready for capture (`data-jg-capture="ready"`) unless a capture host already
@@ -15,7 +20,7 @@ export function markHudCaptureReady(root) {
         root.dataset.jgCapture = "ready";
 }
 /** HUD-only play surface for non-3D shells. @internal */
-export function ShellHudPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, touchScheme, touchSink, orientationGate, orientationGateEl, coarsePointer, uiScale, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, onPointerResumeAudio, }) {
+export function ShellHudPresentation({ playable, ctx, multiplayer, serverIdRef, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, touchScheme, touchSink, orientationGate, orientationGateEl, coarsePointer, uiScale, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, onPointerResumeAudio, settingsStore, bindingOverrides, rebindAction, resetActionBinding, audioEngine, poster, }) {
     const GameUI = playable.GameUI;
     useEffect(() => {
         // Two frames so the first GameUI paint has landed before tools capture.
@@ -35,9 +40,18 @@ export function ShellHudPresentation({ playable, ctx, multiplayer, tracker, poin
         setDevtoolsOpen,
         controlsActive: () => playControlsActive(ctx),
     });
-    return (_jsx("div", { ref: wrapperRef, tabIndex: 0, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: keys.onKeyDown, onKeyUp: keys.onKeyUp, onBlur: keys.onBlur, onPointerDown: onPointerResumeAudio, onPointerMove: trackPointerAxis, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsx(HudOnlyDriver, { ctx: ctx, playable: playable, tracker: tracker, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError }), !orientationGate &&
-                    coarsePointer &&
-                    touchScheme !== null &&
-                    touchScheme.gestures !== null &&
-                    playControlsActive(ctx) ? (_jsx(TouchPlaySurface, { scheme: touchScheme, sink: touchSink, yawRef: yawRef, pitchRef: pitchRef, maxPitch: 0, onPrimaryTap: () => undefined })) : null, _jsx(ShellGameUiChrome, { ctx: ctx, playable: playable, GameUI: GameUI, uiScale: uiScale, orientationGate: orientationGate, onRuntimeError: reportRuntimeError }), orientationGateEl, _jsx(ShellDebugOverlays, { ctx: ctx, playable: playable, multiplayer: multiplayer, diagnostics: diagnostics, devtoolsEnabled: devtoolsEnabled, devtoolsOpen: devtoolsOpen })] }) }));
+    const settingsDisabled = playable.settings === false;
+    const settingsConfig = playable.settings === false || playable.settings === undefined ? {} : playable.settings;
+    const settingsActions = (settingsConfig.actions ?? []).map((action) => ({
+        id: action.id,
+        label: action.label,
+        kind: action.kind ?? "default",
+        description: action.description,
+        run: () => action.run(ctx),
+    }));
+    return (_jsxs(SettingsProvider, { store: settingsStore, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: playable.audio?.buses }), _jsx(SettingsRuntime, { variant: settingsConfig.variant ?? "panel", surface: settingsDisabled ? false : settingsConfig.surface ?? false, actions: settingsActions, input: playable.game.input ?? {}, buses: playable.audio?.buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: settingsDisabled ? BUILT_IN_SETTING_CATEGORIES : settingsConfig.hide ?? [], fovEnabled: false, graphics: playable.graphics, hideBindings: settingsConfig.hideBindings ?? [], touchStyle: coarsePointer && touchScheme !== null && (touchScheme.joystick !== null || touchScheme.buttons.length > 0), overrides: bindingOverrides, rebind: rebindAction, resetBinding: resetActionBinding, children: _jsx("div", { ref: wrapperRef, tabIndex: 0, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: keys.onKeyDown, onKeyUp: keys.onKeyUp, onBlur: keys.onBlur, onPointerDown: onPointerResumeAudio, onPointerMove: trackPointerAxis, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsx(HudOnlyDriver, { ctx: ctx, multiplayer: multiplayer, serverIdRef: serverIdRef, playable: playable, tracker: tracker, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError }), !orientationGate &&
+                                coarsePointer &&
+                                touchScheme !== null &&
+                                touchScheme.gestures !== null &&
+                                playControlsActive(ctx) ? (_jsx(TouchPlaySurface, { scheme: touchScheme, sink: touchSink, yawRef: yawRef, pitchRef: pitchRef, maxPitch: 0, onPrimaryTap: () => undefined })) : null, _jsx(ShellGameUiChrome, { ctx: ctx, playable: playable, GameUI: GameUI, uiScale: uiScale, orientationGate: orientationGate, onRuntimeError: reportRuntimeError }), orientationGateEl, _jsx(ShellDebugOverlays, { ctx: ctx, playable: playable, multiplayer: multiplayer, diagnostics: diagnostics, devtoolsEnabled: devtoolsEnabled, devtoolsOpen: devtoolsOpen }), poster ? null : _jsx(SettingsChrome, {})] }) }) })] }));
 }

package/dist/audio/audioEngine.d.ts

@@ -1,5 +1,6 @@
 import { type AudioBusDef, type SoundDef } from "@jgengine/core/audio/audioFalloff";
 import type { MusicTheme } from "@jgengine/core/audio/music";
+import { type VoiceAllocator, type VoiceAllocatorConfig } from "@jgengine/core/audio/voiceAllocator";
 import { type CrossfadeOptions } from "./musicDirector.js";
 export interface Vec3 {
     x: number;
@@ -16,6 +17,12 @@ export interface ListenerPose {
 }
 export interface AudioSceneConfig {
     sounds?: Record<string, SoundDef>;
+    /** SFX playback/patch slots, including pending loads; individual synth oscillators share one slot. Default 64; zero disables SFX. */
+    maxVoices?: number;
+    /** Budget overflow policy. Default "steal-lowest"; lower priorities never steal higher ones. */
+    voiceOverflow?: VoiceAllocatorConfig["overflow"];
+    /** Dedicated caller-owned allocator for inspectable reservations and injected storage. Music has its own lifecycle. */
+    voiceAllocator?: VoiceAllocator;
     buses?: Record<string, AudioBusDef>;
     /** Procedural music themes, crossfaded by {@link AudioEngine.playMusic}. Mixed through the `musicBus` (default "music") so the settings volume applies. */
     music?: Record<string, MusicTheme>;
@@ -23,6 +30,8 @@ export interface AudioSceneConfig {
     musicBus?: string;
 }
 export interface AudioEmitterHandle {
+    /** Whether playback is reserved or playing; false after stop, stealing, failed load, or natural end. Optional for legacy hosts. */
+    isPlaying?(): boolean;
     setPosition(position: Vec3): void;
     /** Live pitch of a retained loop: `rate` multiplies the authored playback rate (1 = authored), clamped to 0.25–4 and ramped ~20 ms to avoid zipper noise (#1051). */
     setRate(rate: number): void;
@@ -37,7 +46,10 @@ export interface AudioEmitterHandle {
     stop(): void;
 }
 export interface AudioEngine {
+    /** Full listener orientation, or a legacy position using forward -Z and up +Y. */
     setListenerPose(pose: ListenerPose | Vec3): void;
+    /** Retune the SFX budget and optional admission policy, stopping the lowest-priority oldest voices first. */
+    setVoiceLimit(maxTotal: number, overflow?: VoiceAllocatorConfig["overflow"]): void;
     playOneShot(soundId: string, position?: Vec3): void;
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
     /** Crossfade the procedural soundtrack to `themeId` (null fades out). No-op when no `music` catalog is configured. */
@@ -47,4 +59,8 @@ export interface AudioEngine {
     resume(): void;
     dispose(): void;
 }
+/**
+ * Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
+ * @capability bounded-spatial-audio play positional or flat cues with listener orientation, voice budgets, and per-source cleanup
+ */
 export declare function createAudioEngine(config?: AudioSceneConfig): AudioEngine;