@jgengine/shell 0.18.1 → 0.21.0

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

@@ -1,16 +1,28 @@
-import type { Dispatch, MutableRefObject, RefObject, SetStateAction } from "react";
+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 { 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.
+ * @internal
+ */
+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>;
@@ -38,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,12 +1,38 @@
 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
+ * owns the flag. A HUD game has no `<canvas>`, so capture tools that wait for one would time out.
+ * @internal
+ */
+export function markHudCaptureReady(root) {
+    if (root.dataset.jgCapture === undefined)
+        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.
+        let second = 0;
+        const first = requestAnimationFrame(() => {
+            second = requestAnimationFrame(() => markHudCaptureReady(document.documentElement));
+        });
+        return () => {
+            cancelAnimationFrame(first);
+            cancelAnimationFrame(second);
+        };
+    }, []);
     const keys = createShellKeyHandlers({
         f2HeldRef,
         tracker,
@@ -14,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/AudioComponents.js

@@ -2,15 +2,19 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { Quaternion, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { createListenerVelocityTrack, stepListenerVelocity } from "./loopParams.js";
 export function AudioListener({ engine }) {
     const camera = useThree((state) => state.camera);
-    useFrame(() => {
+    const trackRef = useRef(createListenerVelocityTrack());
+    useFrame((_, dt) => {
         const direction = camera.getWorldDirection(new Vector3());
         const up = camera.up.clone().applyQuaternion(camera.getWorldQuaternion(new Quaternion()));
+        const position = { x: camera.position.x, y: camera.position.y, z: camera.position.z };
         engine.setListenerPose({
-            position: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
+            position,
             forward: { x: direction.x, y: direction.y, z: direction.z },
             up: { x: up.x, y: up.y, z: up.z },
+            velocity: stepListenerVelocity(trackRef.current, position, dt),
         });
     });
     return null;

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;
@@ -11,9 +12,17 @@ export interface ListenerPose {
     position: Vec3;
     forward: Vec3;
     up: Vec3;
+    /** World velocity of the listener, for doppler on loops whose sound declares `doppler`. Default zero. */
+    velocity?: Vec3;
 }
 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>;
@@ -21,15 +30,26 @@ 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;
     /** Live volume of a retained loop: `gain` scales the source (0–1), clamped and ramped ~20 ms (#1051). */
     setGain(gain: number): void;
+    /** Live lowpass cutoff of a retained loop in Hz, clamped and ramped like rate. */
+    setLowpass(hz: number): void;
+    /** Live highpass cutoff of a retained loop in Hz, clamped and ramped like rate. */
+    setHighpass(hz: number): void;
+    /** Emitter world velocity for doppler; ignored unless the sound declares `doppler`. */
+    setVelocity(velocity: Vec3): void;
     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. */
@@ -39,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;