@jgengine/shell 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -26,6 +26,57 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.32.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.32.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.29.0`; `@jgengine/github` is `0.19.0`.
+
+### Added
+
+- Audio mixing grew a mute that composes with gain: `AudioEngine.setBusMute` / `setMasterMute` keep the player's volume while silencing a bus, `masterLevel()` / `busLevel()` report the composed value, and Settings carries a mute row per bus plus "Mute all" (`sound.muted`, `sound.bus.<id>.muted`). `AudioEngine.play` and `playOneShot` hold cues in a bounded 16-slot queue while the browser keeps the context suspended and play them on the first gesture instead of dropping them; `installGestureResume` wires that gesture for both presentation paths.
+- `AudioEngine.measure()` reads master RMS and peak from a lazily built analyser, and `installAudioProbe` publishes `window.__jgengineAudio` so a headless capture can prove sound with a measured level rather than a screenshot.
+- `@jgengine/core/audio/feedbackCues` ships seven procedural reactions - `hit`, `hurt`, `kill`, `pickup`, `objective`, `wave`, `deny` - on an `sfx` bus, merged into every game's catalog as `feel.<cue>`. A game sound with that id replaces one; `audio.feedbackCues` replaces or silences them.
+- `@jgengine/shell/audio/eventFeedback` maps the events the engine already announces to those reactions: `combat.damage` (local player reads as hurt, anything else as a hit), `entity.died`, `worldItem.picked_up`, `quest.completed`, `stat.levelUp` and `command.refused`. Each row carries a sound, a gamepad pulse, camera trauma and a caption; the mapping and reactions are data (`DEFAULT_FEEDBACK_BINDINGS`, `DEFAULT_FEEDBACK_REACTIONS`) a game can replace, cooldowns fold a burst into one impact, reduced motion keeps sound and rumble but drops the camera kick, and the resolved reaction is pooled so handling an event allocates nothing per frame. `attachWaveFeedback(runner, ctx.game.feedback)` announces each new wave.
+- `ctx.game.feedback.cue(cue, caption?)` announces a moment no engine event covers and emits `feedback.cue`.
+- `@jgengine/shell/audio/captions` and `CaptionOverlay` render a bounded, deduping, self-expiring caption line under the accessibility captions setting; `FeedbackHost` mounts the whole layer - feedback mapping, gesture resume, audio probe and captions - for both the 3D and HUD presentation paths.
+
+### Changed
+
+- The CI gate runs nine test shards instead of ten, and a `types` job whose stages overlap, so a docs-only pull request fits the account's 20-job runner cap with room for another run beside it. `scripts/test-shard.ts` owns which files each shard runs and what it prepares first; `bun scripts/type-shard.ts` runs the `check-types` plan two stages at a time and then the tsc fan-out alone.
+
+## 0.31.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.31.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.28.0`; `@jgengine/github` is `0.18.0`.
+
+### Added
+
+- `createAgent` (`@jgengine/core/agents/agent`) runs one resident's whole loop on the world clock: needs decay through `sim/needs`, a utility brain picks among the targets the game offers, an authored day plan says where the agent belongs, and the agent falls back to a declared target when its pick disappears. Mood, action and the far flag snapshot and restore with the needs.
+- `createMoodReader` / `readMood` (`@jgengine/core/agents/mood`) derive a 0-100 mood and a caller-labelled tier from weighted need satisfaction, plus named sources a queue, a litter patch or a cold snap raises and clears.
+- `createAgentSchedule` (`@jgengine/core/agents/schedule`) resolves an authored day plan through `sim/routine` and adds a work beat: a stop names the places it patrols, so a janitor is an agent with a route rather than a special case. Off-hours behaviour is a stop without a beat.
+- `createRelationshipBook` (`@jgengine/core/agents/relationships`) keeps undirected familiarity and opinion per pair. A social action moves both and reports the milestones crossed, friends prefer each other's company, and a bonded pair refuses to split. Pair keys come from `relation/keyedValues` and crossings from `relation/thresholds`.
+- `GameSave.deleteSlot(slot)` and `SaveStore.deleteSlot(slot)` remove one slot's payload and drop it from the slot index; they resolve `true` when a document was removed and `false` for an unknown slot. Deleting the active slot resets the live state to the initial document. `load()` no longer lists a slot that holds nothing, so a deleted slot cannot return.
+- `HudPanel` takes `lane` (`@jgengine/react`): blocks naming the same anchor and lane stack without overlap, lanes in one anchor sit side by side, and `resolveHudLanes` resolves the rectangles. A moved panel leaves its lane and keeps its authored placement.
+- `hudBlockOverlaps` and `formatHudOverlapReport` (`@jgengine/react`) name every pair of rendered HUD blocks whose rectangles intersect, with both ids and the viewport; `HudCanvas` warns with that report in a dev build.
+- `rollDrop` (`@jgengine/core/loot/drop`) rolls one deterministic item from a seed and `compareToEquipped` turns it into per-stat deltas against worn gear with a weighted verdict a HUD can render.
+- `createRunHaul` (`@jgengine/core/loot/haul`) gates carried loot by weight through the shared encumbrance rules, banks what the persistent stash fits, and discards the run's haul when the game calls `fail`.
+- `salvageItem` and `createItemLedger` (`@jgengine/core/loot/salvage`) break an item down for the currency its level and rarity say and claim the instance, so a salvaged item cannot be salvaged, equipped or sold again.
+- `stockVendor` and `createVendorRotation` (`@jgengine/core/loot/vendor`) fill a `ShopStock` with rolled items priced through the economy wallet, with a run-count restock rule the game authors.
+- `markerProximity` on `createMissionRuntime` picks the plane a marker proximity test compares in: `"horizontal"` (default) measures ground distance and allows the actor a `tolerance` (default 8 m) above or below the marker, `"spatial"` is the straight 3D check for worlds with stacked platforms. `MissionMarkerPlane`, `MissionMarkerProximity` and `DEFAULT_MARKER_TOLERANCE` are exported with it.
+
+### Changed
+
+- `evaluatePressure` (`@jgengine/core/ai/director/pressure`) reads pressure as player control: a healthy player further into a run is leaned on harder, a hurt player is eased off, and every effect stays inside the rule's `maxTier`.
+- Loot bases and affixes take `minLevel`, so `rollLoot` only draws from entries at or below the item level. Loot bases take `mass`; rolled items carry it for carry checks.
+
+### Fixed
+
+- `HudCanvas` resolved its host with `canvas.parentElement`, which is `HudThemeRoot`'s `display: contents` element and measures 0x0 — the boundary overlay, the HUD-fit measurement and the new overlap report never ran under the standard HUD root. It now uses the nearest ancestor with a real box.
+- The HUD boundary check returned early whenever nothing overflowed, so a later report in the same pass could never run.
+- `reach`, `interact` and the `left-area` fail condition compared a marker in 3D, so a marker authored at `y=0` under rising ground was unreachable. They now read the same plane.
+
 ## 0.30.0
 
 ### Migrate

package/dist/Shell3dPresentation.js

@@ -417,5 +417,5 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                     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, joystickVariant: touchJoystickVariant })) : 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, {})] }) }) })] }) }));
+                                    } })) : null, _jsx(ShellGameUiChrome, { ctx: ctx, playable: playable, GameUI: GameUI, uiScale: graphics.uiScale, orientationGate: orientationGate, onRuntimeError: reportRuntimeError, audioEngine: audioEngine }), !poster && !orientationGate && showReticle ? _jsx(Reticle, {}) : null, dockMounted && touchScheme !== null ? (_jsx(TouchControlsDock, { scheme: touchScheme, sink: touchSink, style: touchStyle, scale: touchScale, joystickVariant: touchJoystickVariant })) : 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

@@ -1,16 +1,18 @@
 import { type ComponentType } from "react";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import { type RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
+import type { AudioEngine } from "./audio/audioEngine.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
 /** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport → HUD theme root. @internal */
-export declare function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }: {
+export declare function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, audioEngine, }: {
     ctx: GameContext;
     playable: PlayableGame;
     GameUI: ComponentType;
     uiScale: number;
     orientationGate: boolean;
     onRuntimeError: (error: unknown, phase: string, componentStack?: string) => void;
+    audioEngine: AudioEngine;
 }): 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, }: {

package/dist/ShellChrome.js

@@ -6,14 +6,15 @@ import { HudViewportProvider } from "@jgengine/react/hudViewport";
 import { GameProvider } from "@jgengine/react/provider";
 import { DiagnosticOverlay, GameUiErrorBoundary, } from "./diagnostics/RuntimeDiagnostics.js";
 import { DevtoolsRuntime } from "./devtools/DevtoolsRuntime.js";
+import { FeedbackHost } from "./audio/FeedbackHost.js";
 import { GamePhaseStamp } from "./GamePhaseStamp.js";
 import { ShellNotices, ShellUiCues } from "./ShellNotices.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 → HUD theme root. @internal */
-export function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }) {
+export function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, audioEngine, }) {
     const accessibility = useAccessibilitySettings();
-    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(ShellUiCues, { ctx: ctx, enabled: playable.audio?.hudCues !== false, children: _jsxs(HudThemeRoot, { theme: playable.hudTheme, accessibility: accessibility, children: [_jsx(GameUI, {}), _jsx(ShellNotices, { ctx: ctx, config: playable.notices, scale: uiScale })] }) })) })] }) }));
+    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(ShellUiCues, { ctx: ctx, enabled: playable.audio?.hudCues !== false, children: _jsxs(HudThemeRoot, { theme: playable.hudTheme, accessibility: accessibility, children: [_jsx(GameUI, {}), _jsx(ShellNotices, { ctx: ctx, config: playable.notices, scale: uiScale }), _jsx(FeedbackHost, { ctx: ctx, engine: audioEngine })] }) })) })] }) }));
 }
 /** Devtools + diagnostic overlays shared by HUD and 3D presentation paths. @internal */
 export function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, devtoolsEnabled, devtoolsOpen, hideDiagnostics = false, }) {

package/dist/ShellHudPresentation.js

@@ -54,5 +54,5 @@ export function ShellHudPresentation({ playable, ctx, multiplayer, serverIdRef,
                                 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, {})] }) }) })] }));
+                                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, audioEngine: audioEngine }), orientationGateEl, _jsx(ShellDebugOverlays, { ctx: ctx, playable: playable, multiplayer: multiplayer, diagnostics: diagnostics, devtoolsEnabled: devtoolsEnabled, devtoolsOpen: devtoolsOpen }), poster ? null : _jsx(SettingsChrome, {})] }) }) })] }));
 }

package/dist/audio/CaptionOverlay.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from "react";
+import type { CaptionFeed } from "./captions.js";
+/**
+ * The captions line: a bounded, bottom-centred stack that renders only while the accessibility
+ * captions setting is on. Reads HudTheme tokens, so a game's theme reskins it, and lives in the same
+ * overlay layer as the notice stack.
+ *
+ * @capability caption-overlay render the caption feed as a themed, screen-reader-announced line stack gated by the captions accessibility setting
+ */
+export declare function CaptionOverlay({ feed, max, zIndex, }: {
+    feed: CaptionFeed;
+    /** How many lines to show at once. Default 2. */
+    max?: number;
+    zIndex?: number;
+}): ReactNode;

package/dist/audio/CaptionOverlay.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { useAccessibilitySettings } from "@jgengine/react/accessibilitySettings";
+const PRUNE_MS = 250;
+/**
+ * The captions line: a bounded, bottom-centred stack that renders only while the accessibility
+ * captions setting is on. Reads HudTheme tokens, so a game's theme reskins it, and lives in the same
+ * overlay layer as the notice stack.
+ *
+ * @capability caption-overlay render the caption feed as a themed, screen-reader-announced line stack gated by the captions accessibility setting
+ */
+export function CaptionOverlay({ feed, max = 2, zIndex = 84, }) {
+    const accessibility = useAccessibilitySettings();
+    const [changed, setChanged] = useState(0);
+    const lines = accessibility.captions ? feed.list().slice(-max) : [];
+    useEffect(() => feed.subscribe(() => setChanged((current) => current + 1)), [feed]);
+    useEffect(() => {
+        if (lines.length === 0)
+            return;
+        const timer = setInterval(() => feed.prune(), PRUNE_MS);
+        return () => clearInterval(timer);
+    }, [feed, lines.length, changed]);
+    if (!accessibility.captions || lines.length === 0)
+        return null;
+    return (_jsx("div", { "data-jg-captions": "", "aria-live": "polite", "aria-atomic": "false", style: {
+            position: "absolute",
+            left: "50%",
+            bottom: "clamp(64px, 12vh, 132px)",
+            transform: "translateX(-50%)",
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: 4,
+            maxWidth: "min(720px, 82vw)",
+            pointerEvents: "none",
+            zIndex,
+        }, children: lines.map((line) => (_jsxs("div", { "data-jg-caption": line.kind, style: {
+                background: "var(--jg-frame-bg, rgba(8, 11, 16, 0.82))",
+                border: "var(--jg-frame-border, 1px solid rgba(255, 255, 255, 0.12))",
+                borderRadius: "var(--jg-frame-radius, 10px)",
+                color: "var(--jg-text, #f8fafc)",
+                fontFamily: "var(--jg-font-body, ui-sans-serif, system-ui, sans-serif)",
+                fontSize: "clamp(0.95rem, 1.5vw, 1.15rem)",
+                fontWeight: 600,
+                letterSpacing: "0.01em",
+                padding: "6px 12px",
+                textAlign: "center",
+                textShadow: "0 1px 2px rgba(0, 0, 0, 0.6)",
+            }, children: [line.text, line.count > 1 ? _jsxs("span", { style: { opacity: 0.7 }, children: [" x", line.count] }) : null] }, line.id))) }));
+}

package/dist/audio/FeedbackHost.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { AudioEngine } from "./audioEngine.js";
+/**
+ * Mounts the engine's feel layer for one game: announced events become a sound, a gamepad pulse, a
+ * camera kick and a caption line; the audio context unlocks on the first gesture; and the caption
+ * stack follows the accessibility setting. Games supply sounds, never the rules.
+ *
+ * @capability feedback-host mount event feedback, gesture-gated audio and captions for a running game in one component
+ */
+export declare function FeedbackHost({ ctx, engine }: {
+    ctx: GameContext;
+    engine: AudioEngine;
+}): ReactNode;

package/dist/audio/FeedbackHost.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { useAccessibilitySettings } from "@jgengine/react/accessibilitySettings";
+import { cameraShake } from "../camera/shakeChannel.js";
+import { installAudioProbe } from "./audioProbe.js";
+import { CaptionOverlay } from "./CaptionOverlay.js";
+import { createCaptionFeed } from "./captions.js";
+import { attachEventFeedback, createEventFeedback } from "./eventFeedback.js";
+import { installGestureResume } from "./gestureResume.js";
+/**
+ * Mounts the engine's feel layer for one game: announced events become a sound, a gamepad pulse, a
+ * camera kick and a caption line; the audio context unlocks on the first gesture; and the caption
+ * stack follows the accessibility setting. Games supply sounds, never the rules.
+ *
+ * @capability feedback-host mount event feedback, gesture-gated audio and captions for a running game in one component
+ */
+export function FeedbackHost({ ctx, engine }) {
+    const accessibility = useAccessibilitySettings();
+    const feed = useMemo(() => createCaptionFeed(), []);
+    const motionScale = useRef(accessibility.reducedMotion ? 0 : 1);
+    motionScale.current = accessibility.reducedMotion ? 0 : 1;
+    const feedback = useMemo(() => {
+        const haptics = () => ctx.input.haptics(ctx.player.userId);
+        return createEventFeedback({
+            play: (sound) => ctx.game.audio.play(sound),
+            shake: (amount) => cameraShake(amount),
+            haptics: (pulse) => haptics().pulse("feedback", pulse, 2),
+            caption: (text, cue) => feed.push(text, cue),
+            localUserId: () => ctx.player.userId,
+            localEntityId: () => ctx.player.possession.active(ctx.player.userId),
+            motionScale: () => motionScale.current,
+        }, { captions: accessibility.captions });
+    }, [ctx, feed, accessibility.captions]);
+    useEffect(() => {
+        feedback.retune({ captions: accessibility.captions });
+    }, [feedback, accessibility.captions]);
+    useEffect(() => attachEventFeedback(ctx.game.events, feedback), [ctx, feedback]);
+    useEffect(() => installGestureResume(engine), [engine]);
+    useEffect(() => installAudioProbe(engine), [engine]);
+    useEffect(() => () => feed.clear(), [feed]);
+    return accessibility.captions ? _jsx(CaptionOverlay, { feed: feed }) : null;
+}

package/dist/audio/audioEngine.d.ts

@@ -50,15 +50,40 @@ export interface AudioEngine {
     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;
+    /**
+     * One-call playback. Before a user gesture the browser keeps the context suspended, so the cue is
+     * held in a small bounded queue and played when {@link resume} succeeds instead of being dropped
+     * silently. Allocation happens per played cue, never per frame.
+     */
+    play(soundId: string, position?: Vec3): 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. */
     playMusic(themeId: string | null, options?: CrossfadeOptions): void;
     setBusGain(busId: string, gain: number): void;
+    /** Mute one bus without losing its gain: unmuting restores exactly the volume the player set. */
+    setBusMute(busId: string, muted: boolean): void;
     setMasterGain(gain: number): void;
+    setMasterMute(muted: boolean): void;
+    /** Master gain after volume and mute compose (`gain × (muted ? 0 : 1)`). */
+    masterLevel(): number;
+    /** Effective gain of `busId` after its authored gain, the player's volume and its mute compose. */
+    busLevel(busId: string): number;
+    /**
+     * Peak and RMS of the master output sampled on the Web Audio render clock. Pools its buffers, so
+     * calling it every frame allocates nothing; a silent (or unsupported) engine reports `0`.
+     */
+    measure(): AudioLevel;
     resume(): void;
     dispose(): void;
 }
+/** Master-output level, `0..1`. Pooled by {@link AudioEngine.measure} - read it, don't retain it. */
+export interface AudioLevel {
+    rms: number;
+    peak: number;
+}
+/** Cues held while the browser keeps the audio context suspended, before any user gesture. */
+export declare const MAX_PENDING_CUES = 16;
 /**
  * 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

package/dist/audio/audioEngine.js

@@ -9,15 +9,24 @@ import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 /** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
 const LOOP_PARAM_SMOOTH_TC = 0.02;
 const ZERO_VELOCITY = { x: 0, y: 0, z: 0 };
+/** Cues held while the browser keeps the audio context suspended, before any user gesture. */
+export const MAX_PENDING_CUES = 16;
 function createNoopEngine() {
+    const level = { rms: 0, peak: 0 };
     return {
         setListenerPose: () => undefined,
         setVoiceLimit: () => undefined,
+        play: () => undefined,
         playOneShot: () => undefined,
         playLoop: () => null,
         playMusic: () => undefined,
         setBusGain: () => undefined,
+        setBusMute: () => undefined,
         setMasterGain: () => undefined,
+        setMasterMute: () => undefined,
+        masterLevel: () => 0,
+        busLevel: () => 0,
+        measure: () => level,
         resume: () => undefined,
         dispose: () => undefined,
     };
@@ -93,12 +102,36 @@ export function createAudioEngine(config = {}) {
         return createNoopEngine();
     }
     const busGains = new Map();
+    // Authored gain survives a mute, so unmuting restores the player's volume exactly.
+    const busMix = new Map();
+    let masterVolume = 1;
+    let masterMuted = false;
+    function applyMaster() {
+        masterGain.gain.value = masterLevel();
+    }
+    function masterLevel() {
+        return masterMuted ? 0 : masterVolume;
+    }
+    function busMixOf(busId) {
+        let mix = busMix.get(busId);
+        if (mix === undefined) {
+            mix = { gain: busDefs[busId]?.gain ?? 1, muted: false };
+            busMix.set(busId, mix);
+        }
+        return mix;
+    }
+    function busLevel(busId) {
+        const mix = busMix.get(busId);
+        if (mix === undefined)
+            return busDefs[busId]?.gain ?? 1;
+        return mix.muted ? 0 : mix.gain;
+    }
     function busGainNode(busId) {
         let node = busGains.get(busId);
         if (node === undefined) {
             node = context.createGain();
             try {
-                node.gain.value = busDefs[busId]?.gain ?? 1;
+                node.gain.value = busLevel(busId);
                 node.connect(masterGain);
                 busGains.set(busId, node);
             }
@@ -109,6 +142,11 @@ export function createAudioEngine(config = {}) {
         }
         return node;
     }
+    function applyBus(busId) {
+        const node = busGains.get(busId);
+        if (node !== undefined)
+            node.gain.value = busLevel(busId);
+    }
     let noiseBuffer = null;
     function sharedNoiseBuffer() {
         if (noiseBuffer === null)
@@ -166,6 +204,106 @@ export function createAudioEngine(config = {}) {
     let listenerVelocity = { x: 0, y: 0, z: 0 };
     const nyquist = context.sampleRate / 2;
     const activeSpatialUpdaters = new Set();
+    // Browser autoplay: until the first user gesture the context stays suspended and a played cue
+    // would vanish. Hold a bounded FIFO of ids (preallocated slots) and flush it on resume.
+    const pendingCues = Array.from({ length: MAX_PENDING_CUES }, () => ({
+        soundId: null,
+        hasPosition: false,
+        x: 0,
+        y: 0,
+        z: 0,
+    }));
+    let pendingHead = 0;
+    let pendingCount = 0;
+    function contextRunning() {
+        const state = context.state;
+        return state === undefined || state === "running";
+    }
+    function queueCue(soundId, position) {
+        let slot;
+        if (pendingCount < MAX_PENDING_CUES) {
+            slot = pendingCues[(pendingHead + pendingCount) % MAX_PENDING_CUES];
+            pendingCount += 1;
+        }
+        else {
+            // Full: drop the oldest cue, which the player has already stopped hearing.
+            slot = pendingCues[pendingHead];
+            pendingHead = (pendingHead + 1) % MAX_PENDING_CUES;
+        }
+        slot.soundId = soundId;
+        slot.hasPosition = position !== undefined;
+        slot.x = position?.x ?? 0;
+        slot.y = position?.y ?? 0;
+        slot.z = position?.z ?? 0;
+    }
+    /** Play what was held pre-gesture, oldest first, once the context can actually render it. */
+    function flushPending() {
+        while (pendingCount > 0) {
+            const slot = pendingCues[pendingHead];
+            pendingHead = (pendingHead + 1) % MAX_PENDING_CUES;
+            pendingCount -= 1;
+            const soundId = slot.soundId;
+            slot.soundId = null;
+            if (soundId === null)
+                continue;
+            playInternal(soundId, slot.hasPosition ? { x: slot.x, y: slot.y, z: slot.z } : undefined, false);
+        }
+    }
+    function playCue(soundId, position) {
+        if (disposed)
+            return;
+        if (!contextRunning()) {
+            queueCue(soundId, position);
+            void context.resume().catch(() => undefined);
+            return;
+        }
+        playInternal(soundId, position, false);
+    }
+    let analyser = null;
+    let analyserSamples = null;
+    const level = { rms: 0, peak: 0 };
+    function measure() {
+        if (disposed) {
+            level.rms = 0;
+            level.peak = 0;
+            return level;
+        }
+        if (analyser === null) {
+            try {
+                analyser = context.createAnalyser();
+                analyser.fftSize = 1024;
+                analyser.smoothingTimeConstant = 0;
+                masterGain.disconnect();
+                masterGain.connect(analyser);
+                analyser.connect(context.destination);
+                analyserSamples = new Float32Array(analyser.fftSize);
+            }
+            catch {
+                analyser = null;
+                level.rms = 0;
+                level.peak = 0;
+                return level;
+            }
+        }
+        if (analyserSamples === null) {
+            level.rms = 0;
+            level.peak = 0;
+            return level;
+        }
+        analyser.getFloatTimeDomainData(analyserSamples);
+        let sum = 0;
+        let peak = 0;
+        for (let index = 0; index < analyserSamples.length; index += 1) {
+            const sample = analyserSamples[index];
+            sum += sample * sample;
+            const magnitude = Math.abs(sample);
+            if (magnitude > peak)
+                peak = magnitude;
+        }
+        level.rms = Math.sqrt(sum / analyserSamples.length);
+        level.peak = Math.min(1, peak);
+        return level;
+    }
     function playInternal(soundId, position, loop) {
         if (disposed)
             return null;
@@ -416,11 +554,11 @@ export function createAudioEngine(config = {}) {
             for (const updateGain of activeSpatialUpdaters)
                 updateGain();
         },
+        play(soundId, position) {
+            playCue(soundId, position);
+        },
         playOneShot(soundId, position) {
-            if (disposed)
-                return;
-            void context.resume().catch(() => undefined);
-            playInternal(soundId, position, false);
+            playCue(soundId, position);
         },
         playLoop(soundId, position) {
             return playInternal(soundId, position, true);
@@ -434,17 +572,37 @@ export function createAudioEngine(config = {}) {
         setBusGain(busId, gain) {
             if (disposed)
                 return;
-            busGainNode(busId).gain.value = gain;
+            busMixOf(busId).gain = gain;
+            applyBus(busId);
+        },
+        setBusMute(busId, muted) {
+            if (disposed)
+                return;
+            busMixOf(busId).muted = muted;
+            applyBus(busId);
         },
         setMasterGain(gain) {
             if (disposed)
                 return;
-            masterGain.gain.value = gain;
+            masterVolume = gain;
+            applyMaster();
         },
+        setMasterMute(muted) {
+            if (disposed)
+                return;
+            masterMuted = muted;
+            applyMaster();
+        },
+        masterLevel,
+        busLevel,
+        measure,
         resume() {
             if (disposed)
                 return;
-            void context.resume().catch(() => undefined);
+            void context.resume().then(() => {
+                if (!disposed && contextRunning())
+                    flushPending();
+            }).catch(() => undefined);
         },
         dispose() {
             if (disposed)

package/dist/audio/audioProbe.d.ts

@@ -0,0 +1,22 @@
+import type { AudioEngine, AudioLevel } from "./audioEngine.js";
+/** The read-only handle a capture script or devtools uses to prove the mix is producing sound. */
+export interface AudioProbe {
+    /** Master RMS and peak since the last read, `0..1`. Non-zero RMS means audio reached the output. */
+    measure(): AudioLevel;
+    /** Master gain after volume and mute. */
+    masterLevel(): number;
+    /** One bus's effective gain after its volume and mute. */
+    busLevel(busId: string): number;
+}
+declare global {
+    interface Window {
+        __jgengineAudio?: AudioProbe;
+    }
+}
+/**
+ * Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can
+ * state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+ *
+ * @capability audio-probe read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+ */
+export declare function installAudioProbe(engine: AudioEngine): () => void;

package/dist/audio/audioProbe.js

@@ -0,0 +1,20 @@
+/**
+ * Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can
+ * state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+ *
+ * @capability audio-probe read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+ */
+export function installAudioProbe(engine) {
+    if (typeof window === "undefined")
+        return () => undefined;
+    const probe = {
+        measure: () => engine.measure(),
+        masterLevel: () => engine.masterLevel(),
+        busLevel: (busId) => engine.busLevel(busId),
+    };
+    window.__jgengineAudio = probe;
+    return () => {
+        if (window.__jgengineAudio === probe)
+            delete window.__jgengineAudio;
+    };
+}

package/dist/audio/busMix.d.ts

@@ -0,0 +1,4 @@
+/** Persisted mute for the whole mix, next to `sound.master`. */
+export declare const MASTER_MUTE_SETTING_ID = "sound.muted";
+/** Persisted mute for one bus, next to its `busVolumeSettingId(busId)` volume. */
+export declare function busMuteSettingId(busId: string): string;

package/dist/audio/busMix.js

@@ -0,0 +1,7 @@
+import { busVolumeSettingId } from "@jgengine/core/settings/settingsModel";
+/** Persisted mute for the whole mix, next to `sound.master`. */
+export const MASTER_MUTE_SETTING_ID = "sound.muted";
+/** Persisted mute for one bus, next to its `busVolumeSettingId(busId)` volume. */
+export function busMuteSettingId(busId) {
+    return `${busVolumeSettingId(busId)}.muted`;
+}

package/dist/audio/captions.d.ts

@@ -0,0 +1,48 @@
+/** One caption line as the overlay renders it. */
+export interface Caption {
+    id: number;
+    text: string;
+    /** Free-string kind the game styles ("hit", "pickup", "wave"). */
+    kind: string;
+    /** How many identical lines stacked into this one. */
+    count: number;
+    at: number;
+    expiresAt: number;
+}
+/** Tunables for {@link createCaptionFeed}; all retunable at runtime. */
+export interface CaptionFeedConfig {
+    /** Maximum live lines. Default 3. */
+    cap?: number;
+    /** Line lifetime in ms. Default 2400. */
+    ttlMs?: number;
+    /** Injected clock; default `Date.now`. */
+    now?: () => number;
+}
+/** A capped, self-expiring list of caption lines that the accessibility captions setting turns on. */
+export interface CaptionFeed {
+    /** Show `text`; an identical line still live stacks into one with a count. */
+    push(text: string, kind?: string): Caption;
+    /** Live lines, oldest first. Stable reference until the next change. */
+    list(): readonly Caption[];
+    /** Drop expired lines as of the feed clock. */
+    prune(nowMs?: number): void;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    retune(config: Omit<CaptionFeedConfig, "now">): void;
+    snapshot(): {
+        captions: Caption[];
+        counter: number;
+    };
+    restore(state: {
+        captions: Caption[];
+        counter: number;
+    }): void;
+}
+/**
+ * The caption list the feedback seam writes to and the HUD overlay reads: bounded, self-expiring, and
+ * deduped so three hits read as "Hit x3" rather than three copies. Pure state with an injected clock,
+ * so it runs headless.
+ *
+ * @capability caption-feed bounded, self-expiring, deduped caption lines for the accessibility captions overlay
+ */
+export declare function createCaptionFeed(config?: CaptionFeedConfig): CaptionFeed;