@jgengine/react 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/hudLanes.d.ts

@@ -0,0 +1,96 @@
+import { type HudAnchor, type HudRect, type HudSize } from "@jgengine/core/ui/hudLayout";
+/**
+ * One HUD block's claim on a lane. Two blocks that name the same `anchor` and
+ * `lane` stack in `order` order; a lane is a column, so lanes in the same anchor
+ * sit side by side. The shell resolves every claim into a rectangle, which is
+ * what keeps blocks from arranging themselves into each other.
+ */
+export interface HudLaneSlot {
+    id: string;
+    /** The anchored corner/edge the lane hangs from. */
+    anchor: HudAnchor;
+    /** Lane name inside the anchor. Default `"main"`. */
+    lane?: string;
+    /** Stack position within the lane, ascending away from the anchored edge. Default `0`. */
+    order?: number;
+    /** Declared width in px. Falls back to the size the block measured. */
+    width?: number;
+    /** Declared height in px. Falls back to the size the block measured. */
+    height?: number;
+    /**
+     * Game override: an exact rectangle in HUD space. The block is placed there
+     * and takes no part in lane stacking, so a game keeps full control of its own
+     * placement.
+     */
+    rect?: HudRect;
+}
+/** One block's resolved placement. */
+export interface HudLanePlacement {
+    id: string;
+    anchor: HudAnchor;
+    lane: string;
+    rect: HudRect;
+}
+/** How the shell lays out lanes. */
+export interface HudLaneConfig {
+    /** Gap between stacked blocks and between lanes, in px. Default `10`. */
+    gap?: number;
+    /** Inset from the frame edge, in px. Default `0` — the HUD layer already carries its padding. */
+    pad?: number;
+    /** Size used for a block that declares and has not yet measured one. */
+    fallback?: HudSize;
+}
+/** The resolved layout of every claimed block. */
+export interface HudLaneLayout {
+    placements: HudLanePlacement[];
+    /** Rectangle by block id, for renderers that only lookup. */
+    rects: Record<string, HudRect>;
+}
+/**
+ * Resolve lane claims into non-overlapping rectangles for one frame.
+ *
+ * Blocks are grouped by anchor, then by lane (first-declared lane first), then
+ * sorted by `order`. A lane is one column: its blocks stack top-to-bottom with
+ * `gap` between them, and the anchor's lanes sit side by side with the same gap.
+ * The whole group is aligned to its anchored edge and the block is aligned
+ * within its lane, so a block added at any viewport can only take free space —
+ * never a neighbour's. A block carrying `rect` is placed there untouched.
+ *
+ * @capability hud-lanes lay HUD blocks out in non-overlapping anchored lanes
+ */
+export declare function resolveHudLanes(slots: readonly HudLaneSlot[], viewport: HudSize, config?: HudLaneConfig): HudLaneLayout;
+/** One intersection between two rendered HUD blocks. */
+export interface HudBlockOverlap {
+    a: string;
+    b: string;
+    /** Overlapping area in px². */
+    area: number;
+    /** The intersection itself, in the same space as the inputs. */
+    rect: HudRect;
+}
+/** A rendered block, as measured from the DOM. */
+export interface HudBlockBounds {
+    id: string;
+    rect: HudRect;
+}
+/** Options for {@link hudBlockOverlaps}. */
+export interface HudBlockOverlapOptions {
+    /** Ignore intersections smaller than this many px². Default `1`. */
+    minArea?: number;
+}
+/**
+ * Every pair of rendered HUD blocks that intersects. This is the development-time
+ * check behind the console report: it reads what actually hit the screen rather
+ * than what a layout intended, so a block that overflows its own box or a game
+ * override that lands on a neighbour is named too.
+ *
+ * @capability hud-overlap-report name every intersecting pair of rendered HUD blocks
+ */
+export declare function hudBlockOverlaps(blocks: readonly HudBlockBounds[], options?: HudBlockOverlapOptions): HudBlockOverlap[];
+/**
+ * The console block for a set of overlaps — one line per pair naming both block
+ * ids, plus the viewport they collided at. Empty string when nothing intersects.
+ *
+ * @capability hud-overlap-report format the intersecting HUD block pairs for a development console
+ */
+export declare function formatHudOverlapReport(overlaps: readonly HudBlockOverlap[], viewport: HudSize): string;

package/dist/hudLanes.js

@@ -0,0 +1,148 @@
+import { HUD_ANCHOR_FRACTIONS, } from "@jgengine/core/ui/hudLayout";
+const DEFAULT_GAP = 10;
+const DEFAULT_FALLBACK = { width: 240, height: 44 };
+/**
+ * Resolve lane claims into non-overlapping rectangles for one frame.
+ *
+ * Blocks are grouped by anchor, then by lane (first-declared lane first), then
+ * sorted by `order`. A lane is one column: its blocks stack top-to-bottom with
+ * `gap` between them, and the anchor's lanes sit side by side with the same gap.
+ * The whole group is aligned to its anchored edge and the block is aligned
+ * within its lane, so a block added at any viewport can only take free space —
+ * never a neighbour's. A block carrying `rect` is placed there untouched.
+ *
+ * @capability hud-lanes lay HUD blocks out in non-overlapping anchored lanes
+ */
+export function resolveHudLanes(slots, viewport, config = {}) {
+    const gap = config.gap ?? DEFAULT_GAP;
+    const pad = config.pad ?? 0;
+    const fallback = config.fallback ?? DEFAULT_FALLBACK;
+    const placements = [];
+    const rects = {};
+    const byAnchor = new Map();
+    slots.forEach((slot, index) => {
+        const claims = byAnchor.get(slot.anchor) ?? [];
+        claims.push({ slot, index });
+        byAnchor.set(slot.anchor, claims);
+    });
+    const place = (id, anchor, lane, rect) => {
+        placements.push({ id, anchor, lane, rect });
+        rects[id] = rect;
+    };
+    for (const [anchor, claims] of byAnchor) {
+        const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+        for (const claim of claims) {
+            if (claim.slot.rect === undefined)
+                continue;
+            place(claim.slot.id, anchor, claim.slot.lane ?? "main", claim.slot.rect);
+        }
+        const flowing = claims.filter((claim) => claim.slot.rect === undefined);
+        if (flowing.length === 0)
+            continue;
+        const lanes = new Map();
+        for (const claim of flowing) {
+            const name = claim.slot.lane ?? "main";
+            const members = lanes.get(name) ?? [];
+            members.push(claim);
+            lanes.set(name, members);
+        }
+        const sizeOf = (claim) => ({
+            width: claim.slot.width ?? fallback.width,
+            height: claim.slot.height ?? fallback.height,
+        });
+        const laneSize = new Map();
+        for (const [name, members] of lanes) {
+            members.sort((a, b) => (a.slot.order ?? 0) - (b.slot.order ?? 0) || a.index - b.index);
+            let width = 0;
+            let height = 0;
+            members.forEach((claim, position) => {
+                const size = sizeOf(claim);
+                width = Math.max(width, size.width);
+                height += size.height + (position === 0 ? 0 : gap);
+            });
+            laneSize.set(name, { width, height });
+        }
+        const laneWidths = [...laneSize.values()].map((size) => size.width);
+        const groupWidth = laneWidths.reduce((sum, width) => sum + width, 0) + gap * Math.max(0, laneWidths.length - 1);
+        const groupHeight = Math.max(...[...laneSize.values()].map((size) => size.height));
+        let groupLeft = pad;
+        if (fx === 1)
+            groupLeft = viewport.width - pad - groupWidth;
+        else if (fx === 0.5)
+            groupLeft = (viewport.width - groupWidth) / 2;
+        let groupTop = pad;
+        if (fy === 1)
+            groupTop = viewport.height - pad - groupHeight;
+        else if (fy === 0.5)
+            groupTop = (viewport.height - groupHeight) / 2;
+        let columnX = groupLeft;
+        for (const [name, members] of lanes) {
+            const lane = laneSize.get(name);
+            const columnY = fy === 0 ? groupTop : fy === 1 ? groupTop + (groupHeight - lane.height) : groupTop + (groupHeight - lane.height) / 2;
+            let cursor = columnY;
+            for (const claim of members) {
+                const size = sizeOf(claim);
+                const alignedX = fx === 0 ? columnX : fx === 1 ? columnX + (lane.width - size.width) : columnX + (lane.width - size.width) / 2;
+                place(claim.slot.id, anchor, name, {
+                    x: alignedX,
+                    y: cursor,
+                    width: size.width,
+                    height: size.height,
+                });
+                cursor += size.height + gap;
+            }
+            columnX += lane.width + gap;
+        }
+    }
+    return { placements, rects };
+}
+/**
+ * Every pair of rendered HUD blocks that intersects. This is the development-time
+ * check behind the console report: it reads what actually hit the screen rather
+ * than what a layout intended, so a block that overflows its own box or a game
+ * override that lands on a neighbour is named too.
+ *
+ * @capability hud-overlap-report name every intersecting pair of rendered HUD blocks
+ */
+export function hudBlockOverlaps(blocks, options = {}) {
+    const minArea = options.minArea ?? 1;
+    const out = [];
+    for (let i = 0; i < blocks.length; i += 1) {
+        for (let j = i + 1; j < blocks.length; j += 1) {
+            const a = blocks[i];
+            const b = blocks[j];
+            const width = Math.min(a.rect.x + a.rect.width, b.rect.x + b.rect.width) - Math.max(a.rect.x, b.rect.x);
+            const height = Math.min(a.rect.y + a.rect.height, b.rect.y + b.rect.height) - Math.max(a.rect.y, b.rect.y);
+            if (width <= 0 || height <= 0)
+                continue;
+            const area = width * height;
+            if (area < minArea)
+                continue;
+            out.push({
+                a: a.id,
+                b: b.id,
+                area,
+                rect: {
+                    x: Math.max(a.rect.x, b.rect.x),
+                    y: Math.max(a.rect.y, b.rect.y),
+                    width,
+                    height,
+                },
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The console block for a set of overlaps — one line per pair naming both block
+ * ids, plus the viewport they collided at. Empty string when nothing intersects.
+ *
+ * @capability hud-overlap-report format the intersecting HUD block pairs for a development console
+ */
+export function formatHudOverlapReport(overlaps, viewport) {
+    if (overlaps.length === 0)
+        return "";
+    const header = `HUD BLOCK OVERLAP at ${Math.round(viewport.width)}x${Math.round(viewport.height)}`;
+    const lines = overlaps.map((overlap) => `${overlap.a} intersects ${overlap.b} by ${Math.round(overlap.area)} px² (${Math.round(overlap.rect.x)},${Math.round(overlap.rect.y)} ${Math.round(overlap.rect.width)}x${Math.round(overlap.rect.height)})`);
+    return [header, ...lines].join("\n");
+}

package/dist/hudLanesPreview.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The same shape Deepward's top-left HUD uses — two blocks that used to arrange
+ * themselves into each other. Both declare `lane="status"`, so the shell stacks
+ * them; the second lane sits beside the first and the right-hand lane mirrors it.
+ * Screenshots at any viewport without a block landing on a neighbour.
+ *
+ * @capability hud-lanes two HUD blocks stacked in one lane, plus a second lane beside it
+ */
+export declare function HudLanesPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/hudLanesPreview.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HudFrame } from "./hudFrame.js";
+import { HudSurface } from "./hudSurface.js";
+import { HudThemeRoot } from "./hudThemeRoot.js";
+import { HudCanvas, HudPanel, useHudLayout } from "./hudLayout.js";
+function Chip({ label, value }) {
+    return (_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 10 }, children: [_jsx("span", { style: { color: "var(--jg-text-dim, rgba(255,255,255,0.62))", fontSize: 12 }, children: label }), _jsx("span", { style: { fontSize: 12, fontVariantNumeric: "tabular-nums" }, children: value })] }));
+}
+/**
+ * The same shape Deepward's top-left HUD uses — two blocks that used to arrange
+ * themselves into each other. Both declare `lane="status"`, so the shell stacks
+ * them; the second lane sits beside the first and the right-hand lane mirrors it.
+ * Screenshots at any viewport without a block landing on a neighbour.
+ *
+ * @capability hud-lanes two HUD blocks stacked in one lane, plus a second lane beside it
+ */
+export function HudLanesPreview({ className }) {
+    const layout = useHudLayout();
+    return (_jsx("div", { className: className, style: {
+            position: "relative",
+            width: "100%",
+            height: "100%",
+            overflow: "hidden",
+            background: "radial-gradient(ellipse at 30% 20%, #3b5a46, #1b2a24 55%, #0f1714)",
+        }, children: _jsx(HudThemeRoot, { children: _jsxs(HudCanvas, { layout: layout, editChord: false, children: [_jsx(HudPanel, { id: "vitals", lane: "status", anchor: "top-left", width: 260, height: 104, children: _jsx(HudFrame, { title: "Warden \u00B7 Lv 12", padding: 10, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: [_jsx(Chip, { label: "HP", value: "78 / 100" }), _jsx(Chip, { label: "MP", value: "50 / 80" }), _jsx(Chip, { label: "Lantern", value: "burning" })] }) }) }), _jsx(HudPanel, { id: "quest-log", lane: "status", anchor: "top-left", order: 1, width: 260, height: 132, children: _jsx(HudSurface, { title: "Expedition", padding: 10, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: [_jsx(Chip, { label: "Reach the drowned keep", value: "1 / 3" }), _jsx(Chip, { label: "Recover the tide sigil", value: "0 / 1" }), _jsx(Chip, { label: "Return to camp", value: "\u2014" })] }) }) }), _jsx(HudPanel, { id: "party", lane: "roster", anchor: "top-left", width: 190, height: 248, children: _jsx(HudSurface, { title: "Party", padding: 10, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: [_jsx(Chip, { label: "Mara", value: "Stable" }), _jsx(Chip, { label: "Osk", value: "Wounded" }), _jsx(Chip, { label: "Bel", value: "Stable" }), _jsx(Chip, { label: "Tallow", value: "Missing" })] }) }) }), _jsx(HudPanel, { id: "radar", lane: "radar", anchor: "top-right", width: 180, height: 180, children: _jsx(HudSurface, { title: "Survey", padding: 10, children: _jsx("div", { style: {
+                                    height: 122,
+                                    borderRadius: 999,
+                                    border: "1px solid var(--jg-slot-border, rgba(255,255,255,0.2))",
+                                    background: "radial-gradient(circle at 50% 50%, rgba(120,200,160,0.24), rgba(0,0,0,0.35))",
+                                } }) }) }), _jsx(HudPanel, { id: "hint", lane: "radar", anchor: "top-right", order: 1, width: 180, height: 64, children: _jsx(HudSurface, { padding: 10, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4 }, children: [_jsx(Chip, { label: "Hold", value: "Lantern up" }), _jsx(Chip, { label: "Tide", value: "Rising" })] }) }) })] }) }) }));
+}

package/dist/hudLayout.d.ts

@@ -64,9 +64,16 @@ export declare function HudCanvas({ layout, editChord, compactScale, showDuring,
   *
  * @capability hud-panel anchored HUD slot — drop any widget in a named, player-movable panel
  */
-export declare function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, width, height, type, className, style, children, }: {
+export declare function HudPanel({ id, anchor, lane, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, width, height, type, className, style, children, }: {
     id: string;
     anchor?: HudAnchor;
+    /**
+     * Placement lane inside the anchor. Blocks naming the same lane stack in
+     * `order` and can never overlap; lanes in one anchor sit side by side. A block
+     * that has been moved (drag/edit, or a scene-document `ui.panels` entry) leaves
+     * the lane and keeps its authored position, so a game override always wins.
+     */
+    lane?: string;
     /** Stack position within the region, ascending outward from the screen edge. Default 0. */
     order?: number;
     /** Behavior on compact displays. Default `"keep"`. */

package/dist/hudLayout.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
 import { HUD_ANCHOR_FRACTIONS, anchoredPlacement, createHudLayout, isPanelDraggable, registerActiveHudLayout, } from "@jgengine/core/ui/hudLayout";
 import { resizePanelSize, resolvePanelResize, } from "@jgengine/core/ui/hudDocument";
@@ -9,6 +9,7 @@ import { useDisplayProfile } from "./display.js";
 import { useEngineState } from "./engineStore.js";
 import { useGameLayoutMode, useRegisterLayoutRegion } from "./gameViewport.js";
 import { useOptionalGamePhase } from "./hooks.js";
+import { formatHudOverlapReport, hudBlockOverlaps, resolveHudLanes } from "./hudLanes.js";
 import { useHudLayoutPersist } from "./hudLayoutPersist.js";
 import { useHudViewport } from "./hudViewport.js";
 import { hudFont, hudType } from "./hudTokens.js";
@@ -34,13 +35,21 @@ const WINDOW_ATTR = "data-hud-window";
 /**
  * Dev-only, prod-safe. The on-screen boundary overlay must never reach players,
  * so anything we cannot positively identify as a dev build resolves to `false`.
+ *
+ * `import.meta.env.DEV` is read as a literal member chain because Vite replaces
+ * exactly those words at transform time; reading `env` off a cast `import.meta`
+ * survives to the browser as `undefined` and every dev-only report stays dark.
  */
 function isDevBuild() {
     try {
-        const meta = import.meta;
-        if (meta.env?.DEV === true)
+        // Literal members on purpose: Vite replaces exactly `import.meta.env.DEV`.
+        // Inlined as plain `@ts-ignore` because a workspace-wide type program that
+        // includes `vite/client` would otherwise fail an unused-directive check.
+        // @ts-ignore -- `vite/client` types are not part of this package's own tsconfig
+        if (import.meta.env.DEV === true)
             return true;
-        if (meta.env?.PROD === true)
+        // @ts-ignore -- `vite/client` types are not part of this package's own tsconfig
+        if (import.meta.env.PROD === true)
             return false;
     }
     catch {
@@ -108,6 +117,21 @@ function collectBoundarySurfaces(canvas) {
     }
     return out;
 }
+/**
+ * The nearest ancestor that actually has a box. `HudThemeRoot` is
+ * `display: contents`, so `canvas.parentElement` can be a layout-free element
+ * whose rect is 0x0 — measuring it would silently disable every check below.
+ */
+function measurableHost(canvas) {
+    let element = canvas.parentElement;
+    while (element !== null) {
+        const rect = element.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0)
+            return element;
+        element = element.parentElement;
+    }
+    return canvas;
+}
 function sizeStyle(panel) {
     if (panel === undefined)
         return {};
@@ -197,6 +221,7 @@ export function useHudLayout(options) {
     }, [layout, storageKey, documentUi]);
     return layout;
 }
+const EMPTY_LANE_RECTS = {};
 const HudCanvasContext = createContext(null);
 function HudEditBar({ layout }) {
     return (_jsxs("div", { "data-hud-edit-bar": "", style: {
@@ -305,7 +330,82 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
         }
         return refs;
     }, []);
-    const value = useMemo(() => ({ layout, canvasRef, regions, compact }), [layout, regions, compact]);
+    const [laneLayer, setLaneLayer] = useState(null);
+    const [laneFrame, setLaneFrame] = useState(null);
+    const [laneRevision, setLaneRevision] = useState(0);
+    const laneSlots = useRef(new Map());
+    const laneSizes = useRef(new Map());
+    const declareLane = useCallback((slot) => {
+        const previous = laneSlots.current.get(slot.id);
+        if (previous !== undefined &&
+            previous.anchor === slot.anchor &&
+            previous.lane === slot.lane &&
+            previous.order === slot.order &&
+            previous.width === slot.width &&
+            previous.height === slot.height &&
+            previous.rect === slot.rect) {
+            return;
+        }
+        laneSlots.current.set(slot.id, slot);
+        setLaneRevision((value) => value + 1);
+    }, []);
+    const removeLane = useCallback((id) => {
+        if (!laneSlots.current.delete(id))
+            return;
+        laneSizes.current.delete(id);
+        setLaneRevision((value) => value + 1);
+    }, []);
+    const reportLaneSize = useCallback((id, size) => {
+        const previous = laneSizes.current.get(id);
+        if (previous !== undefined &&
+            Math.abs(previous.width - size.width) < 0.5 &&
+            Math.abs(previous.height - size.height) < 0.5) {
+            return;
+        }
+        laneSizes.current.set(id, size);
+        setLaneRevision((value) => value + 1);
+    }, []);
+    const laneRects = useMemo(() => {
+        if (laneFrame === null || laneSlots.current.size === 0)
+            return EMPTY_LANE_RECTS;
+        const slots = [];
+        for (const slot of laneSlots.current.values()) {
+            const measured = laneSizes.current.get(slot.id);
+            slots.push(measured === undefined
+                ? slot
+                : { ...slot, width: slot.width ?? measured.width, height: slot.height ?? measured.height });
+        }
+        return resolveHudLanes(slots, laneFrame, { gap: REGION_GAP }).rects;
+    }, [laneFrame, laneRevision]);
+    useEffect(() => {
+        if (laneLayer === null)
+            return;
+        const measure = () => {
+            const rect = laneLayer.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return;
+            setLaneFrame((prev) => prev !== null && Math.abs(prev.width - rect.width) < 0.5 && Math.abs(prev.height - rect.height) < 0.5
+                ? prev
+                : { width: rect.width, height: rect.height });
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(laneLayer);
+        return () => observer.disconnect();
+    }, [laneLayer]);
+    const value = useMemo(() => ({
+        layout,
+        canvasRef,
+        regions,
+        compact,
+        laneLayer,
+        laneRects,
+        declareLane,
+        removeLane,
+        reportLaneSize,
+    }), [layout, regions, compact, laneLayer, laneRects, declareLane, removeLane, reportLaneSize]);
     const editing = useEngineState(layout).editing;
     useEffect(() => registerActiveHudLayout(layout), [layout]);
     const chordEnabled = editChord !== false;
@@ -350,7 +450,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     useEffect(() => {
         if (!fitEnabled)
             return;
-        const host = canvasRef.current?.parentElement;
+        const host = canvasRef.current === null ? null : measurableHost(canvasRef.current);
         if (host === undefined || host === null || typeof ResizeObserver === "undefined")
             return;
         const measure = () => {
@@ -365,13 +465,14 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     }, [fitEnabled]);
     useEffect(() => {
         const canvas = canvasRef.current;
-        const host = canvas?.parentElement;
-        if (canvas === null || canvas === undefined || host === undefined || host === null)
+        if (canvas === null)
             return;
+        const host = measurableHost(canvas);
         if (typeof requestAnimationFrame !== "function")
             return;
         let frame = 0;
         let lastReport = "";
+        let lastOverlapReport = "";
         const dev = isDevBuild();
         const check = () => {
             frame = 0;
@@ -398,21 +499,46 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
             // cross an edge — a closed/parked/off-screen menu is never an offender.
             const escaped = overflowingPanels(surfaces, viewportSize);
             const report = escaped.length === 0 ? "" : JSON.stringify(escaped);
-            if (report === lastReport)
-                return;
-            lastReport = report;
-            if (report === "") {
-                canvas.removeAttribute("data-hud-overflow");
-            }
-            else {
-                canvas.setAttribute("data-hud-overflow", report);
-                console.warn(`[jgengine] HUD UI escapes the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+            if (report !== lastReport) {
+                lastReport = report;
+                if (report === "") {
+                    canvas.removeAttribute("data-hud-overflow");
+                }
+                else {
+                    canvas.setAttribute("data-hud-overflow", report);
+                    console.warn(`[jgengine] HUD UI escapes the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+                }
+                if (dev) {
+                    setOffenders(escaped.map((overflow) => {
+                        const rect = surfaces.find((s) => s.id === overflow.id)?.rect;
+                        return { ...overflow, x: rect?.x ?? 0, y: rect?.y ?? 0, width: rect?.width ?? 0, height: rect?.height ?? 0 };
+                    }));
+                }
             }
-            if (dev) {
-                setOffenders(escaped.map((overflow) => {
-                    const rect = surfaces.find((s) => s.id === overflow.id)?.rect;
-                    return { ...overflow, x: rect?.x ?? 0, y: rect?.y ?? 0, width: rect?.width ?? 0, height: rect?.height ?? 0 };
-                }));
+            const blocks = [...canvas.querySelectorAll("[data-hud-panel]")]
+                .filter((el) => isSurfaceShown(el))
+                .map((el) => {
+                const rect = el.getBoundingClientRect();
+                return {
+                    id: surfaceId(el),
+                    rect: {
+                        x: rect.left - hostRect.left,
+                        y: rect.top - hostRect.top,
+                        width: rect.width,
+                        height: rect.height,
+                    },
+                };
+            });
+            const overlapReport = dev ? formatHudOverlapReport(hudBlockOverlaps(blocks), viewportSize) : "";
+            if (overlapReport !== lastOverlapReport) {
+                lastOverlapReport = overlapReport;
+                if (overlapReport === "") {
+                    canvas.removeAttribute("data-hud-overlap");
+                }
+                else {
+                    canvas.setAttribute("data-hud-overlap", overlapReport);
+                    console.warn(`[jgengine] ${overlapReport}`);
+                }
             }
         };
         const schedule = () => {
@@ -462,7 +588,14 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                         pointerEvents: "none",
                         zIndex: 1,
                         ...REGION_LAYOUT[anchor],
-                    } }, anchor))), children, offenders.length > 0 ? (_jsx("div", { "data-hud-overflow-overlay": "", style: { position: "absolute", inset: 0, pointerEvents: "none", zIndex: EDIT_BAR_Z - 1 }, children: offenders.map((o) => (_jsx("div", { style: {
+                    } }, anchor))), _jsx("div", { "data-hud-lane-layer": "", style: {
+                        position: "absolute",
+                        inset: 0,
+                        padding: `${PAD_TOP} ${PAD_RIGHT} ${PAD_BOTTOM} ${PAD_LEFT}`,
+                        boxSizing: "border-box",
+                        pointerEvents: "none",
+                        zIndex: 1,
+                    }, children: _jsx("div", { ref: setLaneLayer, style: { position: "relative", width: "100%", height: "100%" } }) }), children, offenders.length > 0 ? (_jsx("div", { "data-hud-overflow-overlay": "", style: { position: "absolute", inset: 0, pointerEvents: "none", zIndex: EDIT_BAR_Z - 1 }, children: offenders.map((o) => (_jsx("div", { style: {
                             position: "absolute",
                             left: o.x / scale,
                             top: o.y / scale,
@@ -537,13 +670,13 @@ function HudChip({ label, anchor, children, }) {
   *
  * @capability hud-panel anchored HUD slot — drop any widget in a named, player-movable panel
  */
-export function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }) {
+export function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }) {
     const ctx = useContext(HudCanvasContext);
     const phase = useOptionalGamePhase();
     const layoutMode = useGameLayoutMode();
     if (ctx === null)
         throw new Error("HudPanel must be rendered inside a HudCanvas");
-    const { layout, canvasRef, regions, compact } = ctx;
+    const { layout, canvasRef, regions, compact, laneLayer, laneRects, declareLane, removeLane, reportLaneSize } = ctx;
     const onMobile = isMobileMode(layoutMode);
     const registeredOnRef = useRef(null);
     if (registeredOnRef.current !== layout) {
@@ -582,6 +715,59 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     // A flowing panel portals into its anchor region, which HudCanvas only provides after its first commit.
     const awaitingRegion = panel !== undefined && (compact || !panel.moved) && regions[compact ? anchor : panel.placement.anchor] === undefined;
     useRegisterLayoutRegion(regionSpec, rootRef, region && !regionHidden && !awaitingRegion);
+    const laneActive = lane !== undefined && !regionHidden && !(panel !== undefined && panel.moved);
+    const laneRect = lane === undefined ? undefined : laneRects[id];
+    const [laneSize, setLaneSize] = useState(null);
+    useEffect(() => {
+        if (!laneActive)
+            return;
+        declareLane({
+            id,
+            anchor: panel?.placement.anchor ?? anchor,
+            lane,
+            order,
+            width: panel?.width ?? width,
+            height: panel?.height ?? height,
+        });
+        return () => removeLane(id);
+    }, [
+        laneActive,
+        declareLane,
+        removeLane,
+        id,
+        panel?.placement.anchor,
+        lane,
+        order,
+        panel?.width,
+        width,
+        panel?.height,
+        height,
+    ]);
+    const laneMounted = laneRect !== undefined;
+    useEffect(() => {
+        if (!laneActive || !laneMounted)
+            return;
+        const element = rootRef.current;
+        if (element === null)
+            return;
+        const measure = () => {
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 && rect.height <= 0)
+                return;
+            setLaneSize((previous) => previous !== null &&
+                Math.abs(previous.width - rect.width) < 0.5 &&
+                Math.abs(previous.height - rect.height) < 0.5
+                ? previous
+                : { width: rect.width, height: rect.height });
+            reportLaneSize(id, { width: rect.width, height: rect.height });
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [laneActive, laneMounted, id, reportLaneSize]);
     const onPointerDown = (event) => {
         if (!draggable || event.button !== 0)
             return;
@@ -712,6 +898,31 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     if (!hudVisibleInPhase(showDuring, phase))
         return null;
     const authoredSize = sizeStyle(panel);
+    if (laneActive) {
+        if (laneRect === undefined || laneLayer === null)
+            return null;
+        const declaredWidth = panel.width ?? width;
+        const declaredHeight = panel.height ?? height;
+        const settled = laneSize !== null || declaredWidth !== undefined || declaredHeight !== undefined;
+        const chipped = compact && compactMode === "chip";
+        const passThrough = interactive === false && !editing && !chipped;
+        return createPortal(_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-hud-lane": lane, "data-dragging": dragging ? "" : undefined, "data-hud-priority": priority, "data-hud-mobile-behavior": mobileBehavior, "data-hud-type": panel.type ?? type, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
+                position: "absolute",
+                left: laneRect.x,
+                top: laneRect.y,
+                ...(declaredWidth === undefined ? {} : { width: declaredWidth }),
+                ...(declaredHeight === undefined ? {} : { height: declaredHeight }),
+                visibility: settled ? undefined : "hidden",
+                pointerEvents: passThrough ? "none" : "auto",
+                touchAction: draggable ? "none" : undefined,
+                userSelect: editing || dragging ? "none" : undefined,
+                cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
+                outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
+                outlineOffset: editing ? 2 : undefined,
+                boxSizing: "border-box",
+                ...style,
+            }, children: [chipped ? (_jsx(HudChip, { label: chip ?? id, anchor: anchor, children: children })) : (children), editingChrome] }), laneLayer);
+    }
     const flow = compact || !panel.moved;
     if (flow) {
         const regionEl = regions[compact ? anchor : panel.placement.anchor];

package/dist/index.d.ts

@@ -67,6 +67,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLanes.js";
 export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";

package/dist/index.js

@@ -67,6 +67,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLanes.js";
 export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";

package/dist/previewFixtures.js

@@ -1,5 +1,6 @@
 import { BarsPreview } from "./barsPreview.js";
 import { HudChromePreview } from "./hudChromePreview.js";
+import { HudLanesPreview } from "./hudLanesPreview.js";
 import { HudThemePreview } from "./hudThemePreview.js";
 import { IconsPreview } from "./iconsPreview.js";
 import { StreetGeometryPreview } from "./streetGeometryPreview.js";
@@ -20,6 +21,11 @@ import { ScrollRailPreview } from "./scrollRailPreview.js";
  * declares.
  */
 export const PREVIEW_FIXTURES = {
+    HudLanesPreview: {
+        name: "HudLanesPreview",
+        description: "Two HUD blocks stacked in one lane, a second lane beside it, and the mirrored right-hand lane.",
+        component: HudLanesPreview,
+    },
     ScrollRailPreview: { name: "ScrollRailPreview", description: "Reachable caller-owned settings categories in shared scrolling chrome.", component: ScrollRailPreview },
     HudChromePreview: {
         name: "HudChromePreview",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,7 @@
     "styles": "bun scripts/styles.ts"
   },
   "dependencies": {
-    "@jgengine/core": "^0.30.0"
+    "@jgengine/core": "^0.32.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.30.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -410,6 +410,7 @@
 - `GameContextRace` (interface): interface GameContextRace { state(id: string, config?: RaceStateConfig): RaceState } — ⚠ undocumented
 - `GameContextTurn` (interface): interface GameContextTurn { loop(id: string, config?: TurnLoopConfig): TurnLoop } — ⚠ undocumented
 - `GameContextWorld` (interface): interface GameContextWorld { ground: TerrainField; groundHeightAt(x: number, z: number): number; solids: WorldSolids } — ⚠ undocumented
+- `GameFeedback` (interface): interface GameFeedback — The game-announced feel seam on `ctx.game`: name a moment the engine has no event for and the shell plays its cue's sound, rumble, camera kick and caption. The reaction table lives in the shell, so a game never encodes what a hit or a wave should sound like.
 - `HitReactionInput` (interface): interface HitReactionInput { from: string; to: string; config: HitReactionConfig | ImpactPresetName; power?: number } — ⚠ undocumented · used by `resolveHitReaction` (@jgengine/core/combat): Resolves hit feel (hitstop, knockback impulse, camera shake) from either a named `impactPresets` event (`resolveHitReaction("explosion", inp…
 - `MoveTowardCommitOptions` (interface): interface MoveTowardCommitOptions extends MoveTowardOptions — Options for {@link SceneEntityContext.moveTowardCommit}: {@link MoveTowardOptions} plus an optional facing turn.
 - `SceneEntityContext` (interface): interface SceneEntityContext { spawn(name: string, options?: SpawnOptions): string; despawn(instanceId: string): boolean; update: EntityStore["update"]; setPose(instanceId: string, pose: EntityPose): boolean; setVelocity: EntityStore["setVelocity"]; setPoseConstraint: … — ⚠ undocumented
@@ -728,7 +729,7 @@
 - `GameLoop` (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
 - `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: … — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
-- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
 - `PlayableGame` (type): type PlayableGame = EnginePlayableGame< ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps> > & { /** HUD theme the shell applies at the `GameUI` root. Unset uses `defaultHudTheme`; `false` opts out of the default theme and the en… — The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle.
 - `StatBar` (function): function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }: { statId?: string; entityId?: string; tone?: StatTone; label?: string; showValue?: boolean; width?: number; icon?: ReactNode; style?: CSSProperties; className?: string; }… — A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player). Renders nothing until the stat exists.
 - `StoreHandle` (interface): interface StoreHandle<T> — A typed, cast-free handle onto one slot of the reactive game store (`ctx.game.store`). The single type parameter is fixed at definition; `read`/`write`/`update` never widen to `unknown`, so no call site repeats `store.get(key) as T`. Writes flow through the engine store, so they bump `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host authority — the same guarantees a hand-rolled `store.get`/`store.set` pair gives up the moment it forks run state into a module-level singleton.

package/skills/jgengine-ui/SKILL.md

@@ -46,6 +46,7 @@ Existing React games keep their entity store and use the focused
 
 - **Refusals and notices are engine feedback, not per-game toasts.** Return `{ reason: "insufficient-gold", message: "Needs 40 more gold" }` from a command's `validate`: the shell shows `message` in the shared notice feed with the deny cue and stacks repeats. Push other player messages with `ctx.game.notices.push({ text, tone })` (info/success/warn/deny) from game logic instead of a hand-built toast list. The stack renders inside the HUD theme root, so it takes the game's `hudTheme` colours and font; a top or bottom stack moves clear of `HudCanvas` panels and touch controls in its column and sits above `ModalHost` (z 85). Tune or hide it with `notices: { placement, offset, avoidHud, zIndex, cues, hidden }` (`hidden` keeps cues and lets the game render `useNoticeList(ctx.game.notices)` itself); `push({ text, silent: true })` skips one notice's sound.
 - **UI sounds come from `useUiCue()`.** Engine primitives already sound through the shell; for game-owned markup call `cue("click" | "hover" | "open" | "close" | "confirm" | "deny" | "notify")` from buttons and panels; replace a default by declaring `audio.sounds["ui.click"]`, or silence with `audio.uiCues: { hover: false }` / `false`.
+- **A hit, kill, pickup, objective, wave and refusal react without any sound authored.** The shell maps the events the engine already announces (`combat.damage`, `entity.died`, `worldItem.picked_up`, `quest.completed`, `stat.levelUp`, `command.refused`) to a `feel.<cue>` reaction - sound, gamepad pulse, camera kick and caption - and merges procedural defaults on an `sfx` bus. Replace a sound by declaring `audio.sounds["feel.hit"]`, tune or silence with `audio.feedbackCues`, and announce a wave through `attachWaveFeedback(runner, ctx.game.feedback)` or any custom moment with `ctx.game.feedback.cue("wave", "WAVE 3")`. Captions follow the accessibility setting; sound follows the `sfx` bus volume and mute rows in Settings.
 - Every rejected verb displays its reason on the triggering surface. Use `useServerSession(transport, gameId)` for join lifecycle. Join failure blocks play with `JoinGate` and retry; returning `{ ok: false }` without feedback is incomplete.
 - Placement previews display claim cost and affordability inline with `TerritoryOverlay`.
 - `ChatPanel` owns collapsed/expanded state, own-message styling, Enter focus and Escape blur; standalone hosts pass `messages`, `userId`, and `onSend` (typed `{ ok, reason }`), while context-backed games use channel props. Use native inputs so shell typing-target suspension applies.

package/skills/jgengine-ui/api.md

@@ -786,6 +786,9 @@
 - `HUD_THEME_PRESETS` (const): const HUD_THEME_PRESETS: { "arcane-stone": HudTheme; "survival-wood": HudTheme; "military-flat": HudTheme; "sleek-hex": HudTheme; "elemental-circle": HudTheme; "sandbox-slot": HudTheme; ember: HudTheme; synthwave: HudTheme; fieldkit: HudTheme; } — Built-in theme presets for demos/scaffold only — not product identity; games author their own theme.
 - `HealthBar` (const): const HealthBar: (props: AtomicBarProps) => React.JSX.Element — Player/enemy health — danger-flashes to `--jg-health-low` below a quarter full.
 - `Hotbar` (function): function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }: { inventoryId: string; activeSlot?: number; keys?: readonly string[]; slotSize?: number; /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */ itemIcon?: … — A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
+- `HudBlockBounds` (interface): interface HudBlockBounds — A rendered block, as measured from the DOM.
+- `HudBlockOverlap` (interface): interface HudBlockOverlap — One intersection between two rendered HUD blocks.
+- `HudBlockOverlapOptions` (interface): interface HudBlockOverlapOptions — Options for {@link hudBlockOverlaps}.
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
 - `HudCompactMode` (type): type HudCompactMode = "keep" | "chip" | "hide" — How a panel behaves on compact (phone-scale) displays. `keep` stays visible at the global compact scale, `chip` collapses to a small tap-to-expand pill, `hide` unmounts entirely.
 - `HudEditChord` (interface): interface HudEditChord { hold: string; press: string } — ⚠ undocumented · used by `HudCanvas`: Full-viewport HUD surface.
@@ -793,9 +796,13 @@
 - `HudFrameProps` (interface): interface HudFrameProps — Props for {@link HudFrame}.
 - `HudFrameShape` (type): type HudFrameShape = "rounded" | "circle" | "square" — Frame corner shape — `rounded` (the variation's default radius), `circle` (fully round), or `square` (no radius).
 - `HudFrameVariation` (type): type HudFrameVariation = "glass" | "plate" | "retro" | "themed" — Frame skin — `glass` (the shared dark-glass panel), `plate` (a heavier opaque plate), `retro` (a hard black-outlined frame), or `themed` (driven by the `--jg-frame-*` `HudTheme` tokens).
+- `HudLaneConfig` (interface): interface HudLaneConfig — How the shell lays out lanes.
+- `HudLaneLayout` (interface): interface HudLaneLayout — The resolved layout of every claimed block.
+- `HudLanePlacement` (interface): interface HudLanePlacement — One block's resolved placement.
+- `HudLaneSlot` (interface): interface HudLaneSlot — One HUD block's claim on a lane. Two blocks that name the same `anchor` and `lane` stack in `order` order; a lane is a column, so lanes in the same anchor sit side by side. The shell resolves every claim into a rectangle, which is what keeps blocks from arranging themselves into each other.
 - `HudLayoutPersist` (type): type HudLayoutPersist = (id: string, panel: EditorUiPanelLayout) => void — Host-owned callback that commits one HUD panel layout into the scene document (typically an undoable `setUiPanel` dispatch). Injected by the editor so product UI never reaches for editor globals.
 - `HudLayoutPersistProvider` (function): function HudLayoutPersistProvider({ onPanelCommit, children, }: { onPanelCommit: HudLayoutPersist; children?: ReactNode; }): React.JSX.Element — Provides {@link HudLayoutPersist} / `onPanelCommit` to descendant `useHudLayout` calls. Mount around game UI when a host can accept document UI patches (editor). Absent provider → canvas moves/resizes are no-ops for document writes.
-- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
 - `HudSkin` (interface): interface HudSkin — A game-authored visual skin layered over a {@link HudTheme}.
 - `HudSkinMaterial` (interface): interface HudSkinMaterial — Optional raster-backed materials for shared HUD chrome.
 - `HudSkinPreview` (function): function HudSkinPreview({ className }: { className?: string }): React.JSX.Element — Procedural two-skin fixture for visual regression captures.
@@ -1033,8 +1040,10 @@
 - `defaultHudTheme` (const): const defaultHudTheme: HudTheme — The engine's default HUD look, applied by the shell at the HUD root of every game that does not opt out: a strong system UI font stack, layered translucent panels with a lit top rim and crisp hairline borders, a 12px type floor, and motion that honours reduced-motion. Games override any part with their own theme on a HUD ancestor.
 - `deriveHudTheme` (function): function deriveHudTheme(seed: HudThemeSeed): HudTheme — Derives a coherent full theme from an accent/surface pair — shades, edges, dim text, frames, bar troughs, and slots all fall out of the seed, so a game gets one consistent look across the `packages/react` primitives and the `registry/jgengine` blocks without naming 50 tokens. Hex seeds only (`#rgb` or `#rrggbb`).
 - `eventMeterNeedsHeartbeat` (function): function eventMeterNeedsHeartbeat(meter: EventMeter, previous: EventMeterView | null): boolean — True when `meter`'s value/fraction/tier/ready diverge from `previous` — the re-render check `useEventMeter` polls on its heartbeat.
+- `formatHudOverlapReport` (function): function formatHudOverlapReport(overlaps: readonly HudBlockOverlap[], viewport: HudSize): string — The console block for a set of overlaps — one line per pair naming both block ids, plus the viewport they collided at. Empty string when nothing intersects.
 - `formatTimerMs` (function): function formatTimerMs(ms: number, format: TimerFormat = "mm:ss"): string — Format a millisecond duration as digital timer text — `mm:ss` (default), `m:ss.d` (with tenths), or `ss.d` (seconds + tenths). Negative inputs clamp to zero. No genre meaning: the same helper serves a round clock, a respawn countdown, or an ability charge readout.
 - `guestIdentity` (function): function guestIdentity(seed?: string): IdentitySource — ⚠ undocumented
+- `hudBlockOverlaps` (function): function hudBlockOverlaps(blocks: readonly HudBlockBounds[], options: HudBlockOverlapOptions = {}): HudBlockOverlap[] — Every pair of rendered HUD blocks that intersects. This is the development-time check behind the console report: it reads what actually hit the screen rather than what a layout intended, so a block that overflows its own box or a game override that lands on a neighbour is named too.
 - `hudSkinVars` (function): function hudSkinVars(skin?: HudSkin): CSSProperties — Converts a skin into the CSS variables consumed by shared HUD components.
 - `hudTheme` (function): function hudTheme(overrides: HudThemeOverrides): HudTheme — Builds a full {@link HudTheme} from per-group partials, filling the rest from {@link defaultHudTheme}. Reach for this when a game wants to name exact values; use {@link deriveHudTheme} when a seed color pair is enough.
 - `hudThemeVars` (function): function hudThemeVars(theme: HudTheme): CSSProperties — Emits theme CSS properties, resetting inherited bar fills when absent. Spread onto a HUD ancestor.
@@ -1049,6 +1058,7 @@
 - `previewFixtureNames` (function): function previewFixtureNames(): string[] — Sorted list of registered fixture names, for discovery/listing.
 - `relativeSavedAt` (function): function relativeSavedAt(savedAt: number, nowMs = Date.now()): string — Turn a `savedAt` timestamp into a compact relative label ("just now", "4m ago", "2d ago"). Presentation-only helper — the model stores raw ms.
 - `resolveDialogueInvoke` (function): function resolveDialogueInvoke(choice: DialogueChoice, result: CheckResult | null): { command: string; args?: unknown } | null — ⚠ undocumented
+- `resolveHudLanes` (function): function resolveHudLanes(slots: readonly HudLaneSlot[], viewport: HudSize, config: HudLaneConfig = {}): HudLaneLayout — Resolve lane claims into non-overlapping rectangles for one frame.
 - `resolveHudTheme` (function): function resolveHudTheme(theme?: HudThemePreset | HudTheme): HudTheme — Resolves a preset name (or a full theme) to a `HudTheme`; falls back to the default theme.
 - `resolvePreviewFixture` (function): function resolvePreviewFixture(name: string): PreviewFixture | undefined — Resolve a fixture by name, or `undefined` when it is not registered.
 - `runDialogueChoice` (function): function runDialogueChoice(commands: { run(name: string, input?: unknown): unknown }, choice: DialogueChoice, result: CheckResult | null): void — Route a {@link DialogueBox} choice through the `features.dialogue` bridge: resolve the choice's invoke (honoring a skill-check `result`), run that command, and otherwise close the dialogue — the write side that replaces a per-game `onChoice` that hand-rolls `resolveDialogueInvoke` + `dialogue.close`.
@@ -1533,12 +1543,29 @@
 - `HudInteractProvider` (function): function HudInteractProvider({ onInteract, children }: { onInteract: HudInteractListener; children?: ReactNode }): ReactNode — Routes interactions from every engine HUD primitive below it (buttons, panels, windows, action slots) to one listener — the seam a UI sound or haptics system hooks without per-button wiring. Primitives also expose `data-jg-cue` and a per-instance `onInteract`.
 - `useHudInteract` (function): function useHudInteract(source: string, cue?: string, onInteract?: HudInteractListener): (kind: HudInteractKind) => void — Returns a reporter that calls the instance listener, then the nearest {@link HudInteractProvider}.
 
+## @jgengine/react/hudLanes
+
+- `HudBlockBounds` (interface): interface HudBlockBounds — A rendered block, as measured from the DOM.
+- `HudBlockOverlap` (interface): interface HudBlockOverlap — One intersection between two rendered HUD blocks.
+- `HudBlockOverlapOptions` (interface): interface HudBlockOverlapOptions — Options for {@link hudBlockOverlaps}.
+- `HudLaneConfig` (interface): interface HudLaneConfig — How the shell lays out lanes.
+- `HudLaneLayout` (interface): interface HudLaneLayout — The resolved layout of every claimed block.
+- `HudLanePlacement` (interface): interface HudLanePlacement — One block's resolved placement.
+- `HudLaneSlot` (interface): interface HudLaneSlot — One HUD block's claim on a lane. Two blocks that name the same `anchor` and `lane` stack in `order` order; a lane is a column, so lanes in the same anchor sit side by side. The shell resolves every claim into a rectangle, which is what keeps blocks from arranging themselves into each other.
+- `formatHudOverlapReport` (function): function formatHudOverlapReport(overlaps: readonly HudBlockOverlap[], viewport: HudSize): string — The console block for a set of overlaps — one line per pair naming both block ids, plus the viewport they collided at. Empty string when nothing intersects.
+- `hudBlockOverlaps` (function): function hudBlockOverlaps(blocks: readonly HudBlockBounds[], options: HudBlockOverlapOptions = {}): HudBlockOverlap[] — Every pair of rendered HUD blocks that intersects. This is the development-time check behind the console report: it reads what actually hit the screen rather than what a layout intended, so a block that overflows its own box or a game override that lands on a neighbour is named too.
+- `resolveHudLanes` (function): function resolveHudLanes(slots: readonly HudLaneSlot[], viewport: HudSize, config: HudLaneConfig = {}): HudLaneLayout — Resolve lane claims into non-overlapping rectangles for one frame.
+
+## @jgengine/react/hudLanesPreview
+
+- `HudLanesPreview` (function): function HudLanesPreview({ className }: { className?: string }): React.JSX.Element — The same shape Deepward's top-left HUD uses — two blocks that used to arrange themselves into each other. Both declare `lane="status"`, so the shell stacks them; the second lane sits beside the first and the right-hand lane mirrors it. Screenshots at any viewport without a block landing on a neighbour.
+
 ## @jgengine/react/hudLayout
 
 - `HudCanvas` (function): function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: { layout: HudLayoutStore; editChord?: HudEditChord | false; /** Zoom applied to the whole HUD on compact displays. Default 0.85. */ compactScale?: number; /** Opt-in play-phase gate: render the HUD only … — Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine anchor regions and stack automatically with a gap — no per-panel pixel offsets, no manual clearance for sibling panels, the touch-control dock (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the whole surface scales down and each panel applies its `compact` behavior.
 - `HudCompactMode` (type): type HudCompactMode = "keep" | "chip" | "hide" — How a panel behaves on compact (phone-scale) displays. `keep` stays visible at the global compact scale, `chip` collapses to a small tap-to-expand pill, `hide` unmounts entirely.
 - `HudEditChord` (interface): interface HudEditChord { hold: string; press: string } — ⚠ undocumented · used by `HudCanvas`: Full-viewport HUD surface.
-- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** Stack … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
+- `HudPanel` (function): function HudPanel({ id, anchor = "top-left", lane, order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }: { id: string; anchor?: HudAnchor; /** … — A HUD block that lives in one of the nine anchor regions. Panels sharing a region stack outward from the screen edge in ascending `order`. On fine pointers panels stay draggable through the edit chord; a dragged panel leaves the flow and keeps its custom placement. On compact displays custom placements are ignored and the `compact` behavior applies.
 - `hudVisibleInPhase` (function): function hudVisibleInPhase(showDuring: readonly GamePhase[] | undefined, phase: GamePhase): boolean — Whether a HUD element opted into `showDuring` is visible in the current phase; `undefined` = always visible (default).
 - `useHudLayout` (function): function useHudLayout(options?: { storageKey?: string; snap?: number; locked?: boolean; /** * Scene-document `ui` section — source of truth for panel placement/size. * When provided, hydrates the layout store (and wins over legacy localStorage). */ documentUi?: EditorUiDocument; /** * When true (def… — Layout state for `HudCanvas` — panel placements, edit-mode drag/resize, and per-game persistence.
 
@@ -2112,15 +2139,64 @@
 - `EntityAudioEmitters` (function): function EntityAudioEmitters({ engine, entitySounds, }: { engine: AudioEngine; entitySounds: Record<string, string> | undefined; }): null — ⚠ undocumented
 - `ObjectAudioEmitters` (function): function ObjectAudioEmitters({ engine, objectSounds, }: { engine: AudioEngine; objectSounds: Record<string, string> | undefined; }): null — ⚠ undocumented
 
+## @jgengine/shell/audio/CaptionOverlay
+
+- `CaptionOverlay` (function): function CaptionOverlay({ feed, max = 2, zIndex = 84, }: { feed: CaptionFeed; /** How many lines to show at once. Default 2. */ max?: number; zIndex?: number; }): ReactNode — 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.
+
+## @jgengine/shell/audio/FeedbackHost
+
+- `FeedbackHost` (function): function FeedbackHost({ ctx, engine }: { ctx: GameContext; engine: AudioEngine }): ReactNode — 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.
+
 ## @jgengine/shell/audio/audioEngine
 
 - `AudioEmitterHandle` (interface): interface AudioEmitterHandle { isPlaying?(): boolean; setPosition(position: Vec3): void; setRate(rate: number): void; setGain(gain: number): void; setLowpass(hz: number): void; setHighpass(hz: number): void; setVelocity(velocity: Vec3): void; stop(): void } — ⚠ undocumented
-- `AudioEngine` (interface): interface AudioEngine { setListenerPose(pose: ListenerPose | Vec3): void; setVoiceLimit(maxTotal: number, overflow?: VoiceAllocatorConfig["overflow"]): void; playOneShot(soundId: string, position?: Vec3): void; playLoop(soundId: string, position?: Vec3): AudioEm… — ⚠ undocumented · used by `createAudioEngine`: Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
+- `AudioEngine` (interface): interface AudioEngine { setListenerPose(pose: ListenerPose | Vec3): void; setVoiceLimit(maxTotal: number, overflow?: VoiceAllocatorConfig["overflow"]): void; play(soundId: string, position?: Vec3): void; playOneShot(soundId: string, position?: Vec3): void; playL… — ⚠ undocumented · used by `createAudioEngine`: Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
+- `AudioLevel` (interface): interface AudioLevel — Master-output level, `0..1`. Pooled by {@link AudioEngine.measure} - read it, don't retain it.
 - `AudioSceneConfig` (interface): interface AudioSceneConfig { sounds?: Record<string, SoundDef>; maxVoices?: number; voiceOverflow?: VoiceAllocatorConfig["overflow"]; voiceAllocator?: VoiceAllocator; buses?: Record<string, AudioBusDef>; music?: Record<string, MusicTheme>; musicBus?: string } — ⚠ undocumented · used by `createAudioEngine`: Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
 - `ListenerPose` (interface): interface ListenerPose — Position and orientation for a spatial-audio listener.
+- `MAX_PENDING_CUES` (const): const MAX_PENDING_CUES: 16 — Cues held while the browser keeps the audio context suspended, before any user gesture.
 - `Vec3` (interface): interface Vec3 { x: number; y: number; z: number } — ⚠ undocumented · used by `coverPoints` (@jgengine/core/ai/tacticalQueries): Returns boundary locations that are hidden from a threat.
 - `createAudioEngine` (function): function createAudioEngine(config: AudioSceneConfig = {}): AudioEngine — Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
 
+## @jgengine/shell/audio/audioProbe
+
+- `AudioProbe` (interface): interface AudioProbe — The read-only handle a capture script or devtools uses to prove the mix is producing sound.
+- `installAudioProbe` (function): function installAudioProbe(engine: AudioEngine): () => void — 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.
+
+## @jgengine/shell/audio/busMix
+
+- `MASTER_MUTE_SETTING_ID` (const): const MASTER_MUTE_SETTING_ID: "sound.muted" — Persisted mute for the whole mix, next to `sound.master`.
+- `busMuteSettingId` (function): function busMuteSettingId(busId: string): string — Persisted mute for one bus, next to its `busVolumeSettingId(busId)` volume.
+
+## @jgengine/shell/audio/captions
+
+- `Caption` (interface): interface Caption — One caption line as the overlay renders it.
+- `CaptionFeed` (interface): interface CaptionFeed — A capped, self-expiring list of caption lines that the accessibility captions setting turns on.
+- `CaptionFeedConfig` (interface): interface CaptionFeedConfig — Tunables for {@link createCaptionFeed}; all retunable at runtime.
+- `createCaptionFeed` (function): function createCaptionFeed(config: CaptionFeedConfig = {}): CaptionFeed — 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.
+
+## @jgengine/shell/audio/eventFeedback
+
+- `AnyFeedbackBinding` (type): type AnyFeedbackBinding = { [Name in FeedbackEventName]: FeedbackBinding<Name> }[FeedbackEventName] — Any row of the event mapping, whichever event it binds.
+- `DEFAULT_FEEDBACK_BINDINGS` (const): const DEFAULT_FEEDBACK_BINDINGS: readonly AnyFeedbackBinding[] — The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the local player reads as hurt, damage anywhere else as a hit; a wave start has no event of its own, so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+- `DEFAULT_FEEDBACK_REACTIONS` (const): const DEFAULT_FEEDBACK_REACTIONS: Readonly<Record<FeedbackCue, FeedbackReaction>> — The default reactions. They are data: a game overrides one through `audio.feedbackCues` (sound) or `createEventFeedback({ reactions })` (haptics, shake, caption), and replaces the mapping through `bindings` without touching the shell.
+- `EventFeedback` (interface): interface EventFeedback — The event-to-reaction seam. One instance per running world.
+- `EventFeedbackOptions` (interface): interface EventFeedbackOptions — Options a game or host may override.
+- `FeedbackAnnouncer` (interface): interface FeedbackAnnouncer — The slice of `ctx.game.feedback` a wave runner needs, so this runs headless in a test.
+- `FeedbackBinding` (type): type FeedbackBinding<Name extends FeedbackEventName = FeedbackEventName> = { event: Name; cue: FeedbackCue; /** Default `"any"`. `"local"` only fires for the local player's own target/user/refusal. */ scope?: FeedbackScope; /** Overrides the cue's caption for this event, e.g. "You died". */ caption?… — One row of the event mapping: `event` announces, `cue` reacts.
+- `FeedbackDeps` (interface): interface FeedbackDeps — Everything the feedback seam reaches outside itself. Injected so it runs headless.
+- `FeedbackEventName` (type): type FeedbackEventName = | "combat.damage" | "entity.died" | "worldItem.picked_up" | "quest.completed" | "stat.levelUp" | "command.refused" — Event names the default mapping listens to; a game may add its own through `bindings`.
+- `FeedbackReaction` (interface): interface FeedbackReaction — One cue's reaction: what plays, what the hand feels, what the screen does, and what a caption says.
+- `FeedbackScope` (type): type FeedbackScope = "local" | "remote" | "any" — Which side of an event a binding reacts to: the local player's, someone else's, or either.
+- `ResolvedFeedback` (interface): interface ResolvedFeedback — A resolved trigger: pooled per binding, so a busy event stream allocates nothing to decide.
+- `attachEventFeedback` (function): function attachEventFeedback(events: Pick<GameEvents, "on">, feedback: EventFeedback, eventsToBind: readonly FeedbackEventName[] = Object.keys( DEFAULT_FEEDBACK_BINDINGS.reduce<Record<string, true>>((names, binding) => { names[binding.event] = true; return names; }, {}), ) as FeedbackEventName[]): (… — Subscribe the feedback seam to a game's event bus, including `feedback.cue` for moments the game announces itself. Returns the detach function; the mapping and reactions stay override-able through the seam's `retune`.
+- `attachWaveFeedback` (function): function attachWaveFeedback(runner: Pick<WaveRunner, "state" | "subscribe">, announce: FeedbackAnnouncer): () => void — Announce each new wave a {@link WaveRunner} starts as the `wave` cue, once per boundary. A wave has no event of its own, so this is the engine-side hookup for tower defense and wave survival games: `attachWaveFeedback(runner, ctx.game.feedback)`. Nothing is polled, the runner's own notification drives it, and one `update` that crosses two waves still fires once - the cue has a cooldown and the next boundary is announced by the next crossing.
+- `createEventFeedback` (function): function createEventFeedback(deps: FeedbackDeps, options: EventFeedbackOptions = {}): EventFeedback — Build the event-to-sound/haptic/shake/caption seam. The mapping is data ({@link DEFAULT_FEEDBACK_BINDINGS}), reactions are data ({@link DEFAULT_FEEDBACK_REACTIONS}), and the resolved trigger for each binding is allocated once - handling an event allocates only the caption string it actually shows, never per frame.
+
+## @jgengine/shell/audio/gestureResume
+
+- `installGestureResume` (function): function installGestureResume(engine: Pick<AudioEngine, "resume">, target: Pick<Document, "addEventListener" | "removeEventListener"> | null = typeof document === "undefined" ? null : document): () => void — Resume the audio context on the first real user gesture. Chrome keeps a freshly created `AudioContext` suspended until the page sees a trusted input, so pressing a key, tapping or clicking is the only moment sound may start; the engine then flushes any cue it held. One listener set per game, removed on unmount.
+
 ## @jgengine/shell/audio/loopParams
 
 - `MAX_LOOP_CUTOFF` (const): const MAX_LOOP_CUTOFF: 22050 — Highest live filter cutoff, Hz; the engine also caps it at the context's Nyquist frequency.

package/skills/jgengine-ui/capabilities.md

@@ -64,6 +64,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `readModelAnimationParams` (function) · `import { readModelAnimationParams } from "@jgengine/shell/render/useModelAnimation"`
 
+## attach-event-feedback — one call wires every announced combat/loot/objective/refusal event to its reaction
+
+- `attachEventFeedback` (function) · `import { attachEventFeedback } from "@jgengine/shell/audio/eventFeedback"`
+
+## attach-wave-feedback — fire the wave cue once whenever a wave runner crosses into a new wave
+
+- `attachWaveFeedback` (function) · `import { attachWaveFeedback } from "@jgengine/shell/audio/eventFeedback"`
+
+## audio-probe — read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+
+- `installAudioProbe` (function) · `import { installAudioProbe } from "@jgengine/shell/audio/audioProbe"`
+
 ## authored-flocks — render authored habitat agents through caller-selected animated species models with velocity orientation and bounded model lifetime
 
 - `AuthoredFlocks` (function) · `import { AuthoredFlocks } from "@jgengine/shell/world/AuthoredFlocks"`
@@ -114,6 +126,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `isCameraOccluderTransparent` (function) · `import { isCameraOccluderTransparent } from "@jgengine/shell/camera"`
 
+## caption-feed — bounded, self-expiring, deduped caption lines for the accessibility captions overlay
+
+- `createCaptionFeed` (function) · `import { createCaptionFeed } from "@jgengine/shell/audio/captions"`
+
+## caption-overlay — render the caption feed as a themed, screen-reader-announced line stack gated by the captions accessibility setting
+
+- `CaptionOverlay` (function) · `import { CaptionOverlay } from "@jgengine/shell/audio/CaptionOverlay"`
+
 ## capture-canvas — read the live R3F frame to a PNG data URL (needs preserveDrawingBuffer)
 
 - `captureCanvas` (function) · `import { captureCanvas } from "@jgengine/shell/render/sceneCapture"`
@@ -285,6 +305,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `EntitySummary` (function) · `import { EntitySummary } from "@jgengine/react"`
 
+## event-feedback — map announced gameplay events (damage, kill, pickup, objective, wave, refusal) to a sound, gamepad pulse, camera shake and caption through one data mapping
+
+- `createEventFeedback` (function) · `import { createEventFeedback } from "@jgengine/shell/audio/eventFeedback"`
+
 ## event-meter-hud — render a core event/heat meter's live value, fraction, tier, and ready state in a HUD gauge
 
 - `useEventMeter` (function) · `import { useEventMeter } from "@jgengine/react"`
@@ -293,6 +317,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `FastTravelMenu` (function) · `import { FastTravelMenu } from "@jgengine/react"`
 
+## feedback-host — mount event feedback, gesture-gated audio and captions for a running game in one component
+
+- `FeedbackHost` (function) · `import { FeedbackHost } from "@jgengine/shell/audio/FeedbackHost"`
+
 ## floating-text — overlay that renders on-screen floating combat text with per-kind color, alpha, and pop-in scale
 
 - `FloatingText` (function) · `import { FloatingText } from "@jgengine/react"`
@@ -309,6 +337,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `GameContextBridge` (function) · `import { GameContextBridge } from "@jgengine/react"`
 
+## gesture-resume — unlock the audio context on the first pointer/key/touch gesture, so pre-gesture cues play instead of vanishing
+
+- `installGestureResume` (function) · `import { installGestureResume } from "@jgengine/shell/audio/gestureResume"`
+
 ## ground-edge-fade — fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
 
 - `applyGroundEdgeFade` (function) · `import { applyGroundEdgeFade } from "@jgengine/shell/terrain"`
@@ -359,6 +391,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `HudInteractProvider` (function) · `import { HudInteractProvider } from "@jgengine/react/hudInteract"`
 
+## hud-lanes — two HUD blocks stacked in one lane, plus a second lane beside it
+
+- `HudLanesPreview` (function) · `import { HudLanesPreview } from "@jgengine/react/hudLanesPreview"`
+- `resolveHudLanes` (function) · `import { resolveHudLanes } from "@jgengine/react"`
+
 ## hud-layout — persistent, live-editable HUD panel layout state for `HudCanvas`
 
 - `useHudLayout` (function) · `import { useHudLayout } from "@jgengine/react"`
@@ -371,6 +408,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useHudLayoutPersist` (function) · `import { useHudLayoutPersist } from "@jgengine/react"`
 
+## hud-overlap-report — format the intersecting HUD block pairs for a development console
+
+- `formatHudOverlapReport` (function) · `import { formatHudOverlapReport } from "@jgengine/react"`
+- `hudBlockOverlaps` (function) · `import { hudBlockOverlaps } from "@jgengine/react"`
+
 ## hud-panel — anchored HUD slot — drop any widget in a named, player-movable panel
 
 - `HudPanel` (function) · `import { HudPanel } from "@jgengine/react"`

package/skills/jgengine-ui/reference.md

@@ -351,7 +351,7 @@ Canyon Chase is the worked example: `movement: { axis: "horizontal" }` steering,
 **`presentation: "hud"` games get 3D parity.** A pure-HUD game (no camera rig) now reaches the same input/audio seams as a 3D game:
 - **Touch gestures** — the shell mounts a headless `TouchPlaySurface` in the hud branch too, so `touch.gestures` (swipe/tap) reach actions without the game hand-wiring pointer events on its own canvas. The visible dock stays game-authored per the rule above.
 - **No phantom reservations** — camera action names (`turnLeft`/`turnRight`/`interact`/…) are reserved *only* when a camera rig is active, so a hud game may bind them directly instead of renaming to `steer*`.
-- **Audio actually plays** — audio resumes on the first pointer gesture in hud games (not just 3D), and `playOneShot` self-resumes the suspended context. Trigger sound from anywhere holding `ctx` via `ctx.game.audio.play(soundId, at?)` / `ctx.game.audio.resume()` — the reachable seam over the shell's audio engine.
+- **Audio actually plays** - audio resumes on the first pointer gesture in hud games (not just 3D), and `playOneShot` self-resumes the suspended context. Cues played before any gesture wait in a bounded queue and play on the first real input instead of vanishing. Trigger sound from anywhere holding `ctx` via `ctx.game.audio.play(soundId, at?)` / `ctx.game.audio.resume()` - the reachable seam over the shell's audio engine. Bus gain and mute compose (`engine.setBusMute`), so a muted bus keeps the player's chosen volume for unmute, and Settings carries per-bus and master mute. `ctx.game.feedback.cue("wave", "WAVE 3")` raises the engine's own reaction for a moment no event covers.
 
 ## 10. Progressive instruction