@jgengine/shell 0.11.0 → 0.13.0

package/dist/Shell3dPresentation.js

@@ -0,0 +1,302 @@
+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 { contextVerbInput, } from "@jgengine/core/interaction/contextMenu";
+import { createSelectionSet, isMarquee, screenRect, selectWithinRect, } from "@jgengine/core/scene/selection";
+import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
+import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
+import { BUILT_IN_SETTING_CATEGORIES, } from "@jgengine/core/settings/settingsModel";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
+import { resolveGameLook } from "@jgengine/core/render/lookPreset";
+import { GameViewportProvider } from "@jgengine/react/gameViewport";
+import { GameProvider } from "@jgengine/react/provider";
+import { SettingsProvider } from "@jgengine/react/settings";
+import { resolveWorldSky } from "./worldSky.js";
+import { pointerAimFor, pointerContextMenu } from "./shellPointer.js";
+import { AudioListener, EntityAudioEmitters, ObjectAudioEmitters } from "./audio/AudioComponents.js";
+import { PostProcessing } from "./postfx/PostProcessing.js";
+import { EnvironmentLighting } from "./render/EnvironmentLighting.js";
+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 { SkyDaylight, TimeOfDayDaylight } from "./environment.js";
+import { resolveSkyLightOwnership, skyEmitsLights } from "./environment/skyLightingPolicy.js";
+import { EnvironmentScene } from "./environment/EnvironmentScene.js";
+import { PointerProbe } from "./pointer/PointerProbe.js";
+import { MarqueeBox, ContextMenuView } from "./pointer/PointerOverlays.js";
+import { createPointerService } from "./pointer/pointerService.js";
+import { Reticle, WorldEntityBars, WorldNameplates } from "./world/WorldHud.js";
+import { GridWorldScene } from "./world/GridWorldScene.js";
+import { PlaceScene } from "./world/PlaceScene.js";
+import { WorldItems } from "./world/WorldItems.js";
+import { TouchControlsDock, TouchPlaySurface, touchDockClearance } from "./touch/TouchControlsOverlay.js";
+import { SettingsRuntime } from "./settings/SettingsRuntime.js";
+import { SettingsChrome } from "./settings/SettingsChrome.js";
+import { AudioSettingsBridge } from "./settings/appliedSettings.js";
+import { ConfiguredLighting, BackdropFog } from "./render/SceneLighting.js";
+import { WorldView, RemotePlayers } from "./world/WorldScene.js";
+import { FrameDriver } from "./drivers/FrameDriver.js";
+import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
+import { CombatPresentation } from "./CombatPresentation.js";
+import { resolvePresentationEffects, resolveWorldOverlayBars, } from "./presentationResolve.js";
+const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
+const DEFAULT_BACKGROUND_COLOR = "#14161b";
+/** 3D play surface: canvas, world overlays, and shared chrome. @internal */
+export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, }) {
+    const GameUI = playable.GameUI;
+    const WorldOverlay = playable.WorldOverlay;
+    const pointerService = useMemo(() => createPointerService(), []);
+    const selection = useMemo(() => createSelectionSet(), [playable]);
+    const controlledEntityId = ctx.player.possession.active(ctx.player.userId);
+    const cameraConfig = playable.camera?.followEntityId !== undefined
+        ? playable.camera
+        : { ...playable.camera, followEntityId: controlledEntityId };
+    const rigKind = resolveRigKind(cameraConfig);
+    const firstPerson = rigKind === "first";
+    const showReticle = (firstPerson && playable.camera?.firstPerson?.reticle !== false) || rigKind === "shoulder";
+    const rtsPanKeysEnabled = !rtsPanKeysConflict(playable.game.input);
+    const bars = resolveWorldOverlayBars(playable.worldHealthBars);
+    const nameplates = resolveWorldOverlayBars(playable.nameplates);
+    const effects = resolvePresentationEffects(playable.presentationEffects);
+    const resolveEntityRole = (entity) => playable.content.entityById?.(entity.name)?.role;
+    const pointer = playable.pointer;
+    const pointerUsesLeft = pointer !== undefined && (pointer.select === true || pointer.moveCommand !== undefined);
+    const selectFilter = pointer?.selectFilter;
+    const worldSky = resolveWorldSky(playable.game.world);
+    const world = playable.game.world;
+    const biomeBands = world?.kind === "environment" ? world.terrain?.biomeBands : undefined;
+    const AutoEnvironment = playable.environment ??
+        (world?.kind === "environment"
+            ? () => _jsx(EnvironmentScene, { feature: world })
+            : world?.kind === "place"
+                ? () => _jsx(PlaceScene, { feature: world })
+                : world?.kind === "biomes" || world?.kind === "voxel" || world?.kind === "plots" || world?.kind === "tilemap"
+                    ? () => _jsx(GridWorldScene, { feature: world })
+                    : undefined);
+    const resolvedLook = resolveGameLook({
+        look: playable.look,
+        lighting: playable.lighting,
+        backdrop: playable.backdrop,
+        postProcessing: playable.postProcessing,
+        hasWorldSky: worldSky !== undefined,
+    });
+    const cinematicLook = (playable.look ?? "cinematic") !== "flat";
+    const backdrop = resolvedLook.backdrop;
+    const backdropSky = backdrop?.sky !== undefined ? resolveSkyDescriptor(backdrop.sky) : undefined;
+    const effectiveSky = backdropSky ?? worldSky;
+    const backgroundColor = backdrop?.background ?? (effectiveSky === undefined ? DEFAULT_BACKGROUND_COLOR : undefined);
+    const lighting = resolvedLook.lighting;
+    const orthographic = playable.camera?.projection === "orthographic";
+    const pointerDownRef = useRef(null);
+    const marqueeStartRef = useRef(null);
+    const [marquee, setMarquee] = useState(null);
+    const [selectedIds, setSelectedIds] = useState(() => new Set());
+    const [contextMenu, setContextMenu] = useState(null);
+    const localXY = (event) => {
+        const rect = wrapperRef.current?.getBoundingClientRect();
+        return rect === undefined
+            ? { x: event.clientX, y: event.clientY }
+            : { x: event.clientX - rect.left, y: event.clientY - rect.top };
+    };
+    const commitSelection = (ids) => {
+        selection.replace(ids);
+        setSelectedIds(new Set(ids));
+    };
+    const finishMarquee = (rect) => {
+        const candidates = [];
+        for (const entity of ctx.scene.entity.list()) {
+            if (selectFilter !== undefined && !selectFilter(entity.id))
+                continue;
+            const screen = pointerService.screenOf(entity.position);
+            if (screen !== null)
+                candidates.push({ id: entity.id, x: screen.x, y: screen.y });
+        }
+        commitSelection(selectWithinRect(candidates, rect));
+    };
+    /** 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 handlePointerDown = (event) => {
+        if (isWorldPointerTarget(event))
+            wrapperRef.current?.focus();
+        trackPointerAxis(event);
+        audioEngine.resume();
+        if (contextMenu !== null)
+            setContextMenu(null);
+        if (event.button === 0 && isWorldPointerTarget(event)) {
+            const point = localXY(event);
+            pointerDownRef.current = point;
+            if (pointer?.select === true)
+                marqueeStartRef.current = point;
+        }
+    };
+    const handlePointerMove = (event) => {
+        trackPointerAxis(event);
+        if (pointer?.select !== true)
+            return;
+        const start = marqueeStartRef.current;
+        if (start === null || (event.buttons & 1) === 0)
+            return;
+        const point = localXY(event);
+        setMarquee(screenRect(start.x, start.y, point.x, point.y));
+    };
+    const handlePointerUp = (event) => {
+        if (event.button !== 0 || pointerDownRef.current === null)
+            return;
+        const start = pointerDownRef.current;
+        pointerDownRef.current = null;
+        marqueeStartRef.current = null;
+        const end = localXY(event);
+        const rect = screenRect(start.x, start.y, end.x, end.y);
+        const wasMarquee = marquee !== null && isMarquee(rect, PRIMARY_CLICK_MOVE_THRESHOLD_PX);
+        setMarquee(null);
+        if (pointer?.select === true && wasMarquee) {
+            finishMarquee(rect);
+            return;
+        }
+        if (cameraDraggingRef.current)
+            return;
+        if (pointer?.grabWorldItems === true) {
+            const hit = pointerService.worldHit();
+            const itemInstanceId = hit?.entity ?? null;
+            const record = itemInstanceId === null ? null : ctx.scene.worldItem.get(itemInstanceId);
+            if (record !== null && itemInstanceId !== null) {
+                const itemEntity = ctx.scene.entity.get(itemInstanceId);
+                const localPlayer = ctx.scene.entity.get(ctx.player.userId);
+                const pickupRadius = playable.worldItem?.pickupRadius ?? DEFAULT_PICKUP_RADIUS;
+                const withinRadius = itemEntity !== null &&
+                    localPlayer !== null &&
+                    Math.hypot(localPlayer.position[0] - itemEntity.position[0], localPlayer.position[1] - itemEntity.position[1], localPlayer.position[2] - itemEntity.position[2]) <= pickupRadius;
+                if (withinRadius) {
+                    ctx.scene.worldItem.pickup(itemInstanceId, ctx.player.userId);
+                    return;
+                }
+            }
+        }
+        if (pointer?.select === true) {
+            const hit = pointerService.worldHit();
+            if (hit !== null && hit.entity !== null && (selectFilter === undefined || selectFilter(hit.entity))) {
+                commitSelection([hit.entity]);
+            }
+            else {
+                commitSelection([]);
+            }
+            return;
+        }
+        if (pointer?.moveCommand !== undefined) {
+            const hit = pointerService.worldHit();
+            if (hit !== null && ctx.game.commands.has(pointer.moveCommand)) {
+                ctx.game.commands.run(pointer.moveCommand, { point: hit.point, entity: hit.entity, object: hit.object });
+            }
+            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)
+            primaryClickRef.current = true;
+    };
+    const handleContextMenu = (event) => {
+        if (pointer === undefined)
+            return;
+        if (!isWorldPointerTarget(event))
+            return;
+        event.preventDefault();
+        const hit = pointerService.worldHit();
+        if (hit === null)
+            return;
+        if (pointer.contextMenu === true && (hit.entity !== null || hit.object !== null)) {
+            const menu = pointerContextMenu(ctx, playable, hit);
+            if (menu !== null) {
+                const point = localXY(event);
+                setContextMenu({ menu, x: point.x, y: point.y });
+                return;
+            }
+        }
+        if (pointer.select === true && pointer.orderCommand !== undefined && selection.size() > 0) {
+            if (ctx.game.commands.has(pointer.orderCommand)) {
+                ctx.game.commands.run(pointer.orderCommand, { selection: selection.list(), point: hit.point });
+            }
+            return;
+        }
+        if (pointer.secondaryCommand !== undefined && ctx.game.commands.has(pointer.secondaryCommand)) {
+            const aim = (pointer.aim === true ? pointerAimFor(ctx, pointerService) : undefined) ?? {
+                yaw: yawRef.current,
+                pitch: pitchRef.current,
+            };
+            ctx.game.commands.run(pointer.secondaryCommand, { point: hit.point, entity: hit.entity, object: hit.object, aim });
+        }
+    };
+    const handleVerbPick = (verb) => {
+        const state = contextMenu;
+        setContextMenu(null);
+        if (state !== null && ctx.game.commands.has(verb.command)) {
+            ctx.game.commands.run(verb.command, contextVerbInput(state.menu, verb));
+        }
+    };
+    const controlsActive = playControlsActive(ctx);
+    const settingsDisabled = playable.settings === false;
+    const settingsConfig = playable.settings === false || playable.settings === undefined ? {} : playable.settings;
+    const settingsSurface = settingsDisabled ? false : settingsConfig.surface ?? false;
+    const settingsVariant = settingsConfig.variant ?? "panel";
+    const hideCategories = settingsDisabled ? BUILT_IN_SETTING_CATEGORIES : settingsConfig.hide ?? [];
+    const fovControlEnabled = !orthographic && playable.camera?.playerFov?.control !== false;
+    const settingsHostsFov = !settingsDisabled && !hideCategories.includes("gameplay") && fovControlEnabled;
+    const settingsActions = settingsDisabled
+        ? []
+        : (settingsConfig.actions ?? []).map((action) => ({
+            id: action.id,
+            label: action.label,
+            kind: action.kind ?? "default",
+            description: action.description,
+            run: () => action.run(ctx),
+        }));
+    const touchScale = compact ? 0.88 : 1;
+    const dockMounted = !poster &&
+        !orientationGate &&
+        coarsePointer &&
+        controlsActive &&
+        touchScheme !== null &&
+        (touchScheme.joystick !== null || touchScheme.buttons.length > 0);
+    const keys = createShellKeyHandlers({
+        f2HeldRef,
+        tracker,
+        devtoolsEnabled,
+        setDevtoolsOpen,
+        controlsActive: () => playControlsActive(ctx),
+        exitPointerLockOnDevtools: true,
+    });
+    return (_jsx(SettingsProvider, { store: settingsStore, children: _jsxs(PlayerFovProvider, { config: playable.camera, orthographic: orthographic, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: playable.audio?.buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: playable.audio?.buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: hideCategories, fovEnabled: fovControlEnabled, 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, ...(poster && posterFrozen ? { "data-poster-ready": "" } : {}), className: "relative h-full w-full bg-neutral-950 outline-none", style: {
+                            "--jg-hud-dock-clearance": `${dockMounted ? touchDockClearance(touchScheme, touchScale) : 0}px`,
+                        }, onKeyDown: keys.onKeyDown, onKeyUp: keys.onKeyUp, onBlur: keys.onBlur, onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, onContextMenu: handleContextMenu, onWheel: (event) => {
+                            if (!event.shiftKey)
+                                return;
+                            event.preventDefault();
+                            if (event.deltaY < 0 && ctx.game.commands.has("ui.hotbarScrollNext")) {
+                                ctx.game.commands.run("ui.hotbarScrollNext", {});
+                            }
+                            else if (event.deltaY > 0 && ctx.game.commands.has("ui.hotbarScrollPrev")) {
+                                ctx.game.commands.run("ui.hotbarScrollPrev", {});
+                            }
+                        }, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsxs(Canvas, { frameloop: poster && posterFrozen ? "demand" : "always", orthographic: orthographic, camera: orthographic
+                                        ? {
+                                            zoom: playable.camera?.frustum?.zoom ?? CAMERA_FRUSTUM_DEFAULTS.zoom,
+                                            near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
+                                            far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
+                                        }
+                                        : {
+                                            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 }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? _jsx(EnvironmentLighting, {}) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : 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, 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 }) })) : 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(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, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality })) : null] }), !poster &&
+                                    !orientationGate &&
+                                    coarsePointer &&
+                                    controlsActive &&
+                                    touchScheme !== null &&
+                                    (touchScheme.gestures !== null || touchScheme.look) ? (_jsx(TouchPlaySurface, { scheme: touchScheme, sink: touchSink, yawRef: yawRef, pitchRef: pitchRef, maxPitch: playable.camera?.firstPerson?.maxPitch ?? 1.45, onPrimaryTap: () => {
+                                        primaryClickRef.current = true;
+                                    } })) : null, _jsx(ShellGameUiChrome, { ctx: ctx, playable: playable, GameUI: GameUI, uiScale: graphics.uiScale, orientationGate: orientationGate, onRuntimeError: reportRuntimeError }), !poster && !orientationGate && showReticle ? _jsx(Reticle, {}) : null, dockMounted && touchScheme !== null ? (_jsx(TouchControlsDock, { scheme: touchScheme, sink: touchSink, style: touchStyle, scale: touchScale })) : null, orientationGateEl, marquee !== null ? _jsx(MarqueeBox, { rect: marquee }) : null, contextMenu !== null ? (_jsx(ContextMenuView, { menu: contextMenu.menu, x: contextMenu.x, y: contextMenu.y, onPick: handleVerbPick, onClose: () => setContextMenu(null) })) : null, _jsx(ShellDebugOverlays, { ctx: ctx, playable: playable, multiplayer: multiplayer, diagnostics: diagnostics, devtoolsEnabled: devtoolsEnabled, devtoolsOpen: devtoolsOpen, hideDiagnostics: poster }), poster || orthographic || settingsHostsFov ? null : _jsx(PlayerFovSlider, {}), poster ? null : _jsx(SettingsChrome, {})] }) }) })] }) }));
+}

package/dist/ShellChrome.d.ts

@@ -0,0 +1,51 @@
+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";
+import type { PlayableGame } from "./registry.js";
+/** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport. @internal */
+export declare function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+    GameUI: ComponentType;
+    uiScale: number;
+    orientationGate: boolean;
+    onRuntimeError: (error: unknown, phase: string, componentStack?: string) => void;
+}): import("react").JSX.Element;
+/** Devtools + diagnostic overlays shared by HUD and 3D presentation paths. @internal */
+export declare function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, devtoolsEnabled, devtoolsOpen, hideDiagnostics, }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+    multiplayer: ShellMultiplayer | null;
+    diagnostics: RuntimeDiagnostic[];
+    devtoolsEnabled: boolean;
+    devtoolsOpen: boolean;
+    hideDiagnostics?: boolean;
+}): import("react").JSX.Element;
+/** Key handler bundle shared by HUD and 3D presentation paths. @internal */
+export type ShellKeyHandlers = {
+    onKeyDown: (event: {
+        code: string;
+        preventDefault: () => void;
+    }) => void;
+    onKeyUp: (event: {
+        code: string;
+    }) => void;
+    onBlur: () => void;
+};
+/** F2 chord + gameplay action tracker key handlers shared by both presentation paths. @internal */
+export declare function createShellKeyHandlers({ f2HeldRef, tracker, devtoolsEnabled, setDevtoolsOpen, controlsActive, exitPointerLockOnDevtools, }: {
+    f2HeldRef: {
+        current: boolean;
+    };
+    tracker: {
+        handleDown: (code: string) => void;
+        handleUp: (code: string) => void;
+        reset: () => void;
+    };
+    devtoolsEnabled: boolean;
+    setDevtoolsOpen: (update: boolean | ((current: boolean) => boolean)) => void;
+    controlsActive: () => boolean;
+    /** 3D path exits pointer lock when opening devtools. */
+    exitPointerLockOnDevtools?: boolean;
+}): ShellKeyHandlers;

package/dist/ShellChrome.js

@@ -0,0 +1,51 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { GamePhaseStamp } from "./GamePhaseStamp.js";
+/** 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, {}) })] }) }));
+}
+/** 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 }))] }));
+}
+/** 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.code === "F2") {
+                event.preventDefault();
+                f2HeldRef.current = true;
+                return;
+            }
+            if (f2HeldRef.current) {
+                if (event.code === "KeyD" && devtoolsEnabled) {
+                    event.preventDefault();
+                    if (exitPointerLockOnDevtools)
+                        document.exitPointerLock?.();
+                    setDevtoolsOpen((current) => !current);
+                }
+                return;
+            }
+            if (event.code === "Tab" || event.code === "Space")
+                event.preventDefault();
+            if (controlsActive())
+                tracker.handleDown(event.code);
+        },
+        onKeyUp: (event) => {
+            if (event.code === "F2") {
+                f2HeldRef.current = false;
+                return;
+            }
+            if (controlsActive())
+                tracker.handleUp(event.code);
+        },
+        onBlur: () => {
+            f2HeldRef.current = false;
+            tracker.reset();
+        },
+    };
+}

package/dist/ShellHudPresentation.d.ts

@@ -0,0 +1,41 @@
+import type { Dispatch, MutableRefObject, RefObject, 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 { 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";
+/** 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, }: {
+    playable: PlayableGame;
+    ctx: GameContext;
+    multiplayer: ShellMultiplayer | null;
+    tracker: ActionStateTracker<string>;
+    pointerAxisRef: MutableRefObject<PointerAxisState | null>;
+    gateRef: MutableRefObject<boolean>;
+    wrapperRef: RefObject<HTMLDivElement | null>;
+    f2HeldRef: MutableRefObject<boolean>;
+    yawRef: MutableRefObject<number>;
+    pitchRef: MutableRefObject<number>;
+    touchScheme: TouchScheme | null;
+    touchSink: {
+        onCodeDown: (code: string) => void;
+        onCodeUp: (code: string) => void;
+    };
+    orientationGate: boolean;
+    orientationGateEl: React.ReactNode;
+    coarsePointer: boolean;
+    uiScale: number;
+    diagnostics: RuntimeDiagnostic[];
+    devtoolsEnabled: boolean;
+    devtoolsOpen: boolean;
+    setDevtoolsOpen: Dispatch<SetStateAction<boolean>>;
+    reportRuntimeError: (error: unknown, phase: string, componentStack?: string) => void;
+    trackPointerAxis: (event: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    deactivatePointerAxis: () => void;
+    onPointerResumeAudio: () => void;
+}): import("react").JSX.Element;

package/dist/ShellHudPresentation.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { playControlsActive } from "@jgengine/core/game/controlGate";
+import { GameViewportProvider } from "@jgengine/react/gameViewport";
+import { HudOnlyDriver } from "./drivers/HudOnlyDriver.js";
+import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
+import { TouchPlaySurface } from "./touch/TouchControlsOverlay.js";
+/** 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, }) {
+    const GameUI = playable.GameUI;
+    const keys = createShellKeyHandlers({
+        f2HeldRef,
+        tracker,
+        devtoolsEnabled,
+        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 })] }) }));
+}

package/dist/audio/audioEngine.d.ts

@@ -16,6 +16,10 @@ export interface AudioSceneConfig {
 }
 export interface AudioEmitterHandle {
     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;
     stop(): void;
 }
 export interface AudioEngine {