@jgengine/react 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -26,6 +26,59 @@ 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.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
+
+- **Bump lockstep SDK packages to `^0.30.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.27.0`; `@jgengine/github` is `0.17.0`.
+
+### Added
+
+- `ColorblindFrame` (`@jgengine/react/accessibility`) wraps the 3D canvas and applies the player's colour-vision mode to that box alone, so HUD, menu and caption text keep their own contrast. `colorblindFrameFilter` (`@jgengine/core/ui/accessibility`) resolves a mode to the CSS filter, and `useColorblindMode` reads the mode from the settings store the settings rows write; the 3D shell does both for the mounted game.
+- `SettingsSection` (`@jgengine/react/settingsBlocks`) is one `useMenuNav` menu: a d-pad or left stick moves between rows and left/right steps the focused value — slider by its step, toggle flipped, select to the next option, confirm arms a keybind — through the same `onAdjust` path the arrow keys use. `onAdjust` (`@jgengine/react/menuNav`) is the option that makes left/right adjust instead of move.
+- `createStanding` (`@jgengine/core/progression/standing`) holds per-faction or per-district standing over authored tracks and moves it from named outcomes, so an outcome that resolves to nothing throws at the call instead of silently moving nothing.
+- `createGateSet` (`@jgengine/core/progression/gates`) evaluates authored milestones against standing and money, and refuses to load when a gate's unlock id resolves to nothing.
+- `createCareerBank` (`@jgengine/core/progression/careerBank`) keeps persistent career money apart from a run's haul, so a failed run loses the haul and keeps the bank.
+- `createUpgradeTree` (`@jgengine/core/progression/upgrades`) prices each rank from the shared curve primitive and gates purchases on prerequisites and standing.
+
+### Changed
+
+- `AccessibilityProvider` (`@jgengine/react/accessibility`) sets its data attributes and text-scale var without filtering its own subtree. A colour matrix over the HUD and menu root recoloured the text the rest of the UI assumes, so wrap the game canvas in `ColorblindFrame` instead; a custom root can still offset it with its own `ColorblindFilters` and `filter: url(#jg-cb-<mode>)`.
+- World health bars and nameplates derive their range from the render camera and the target height when a game sets no `maxDistance`: an overhead camera reaches the units it looks down at, and a bar is kept while the target it annotates still covers 18 px, instead of hiding every target past a fixed 60 units.
+- A configured `worldHealthBars.maxDistance` or `nameplates.maxDistance` that hides every target in view now warns once with the nearest measured distance and the prop to raise, instead of rendering nothing.
+
 ## 0.29.0
 
 ### Migrate

package/dist/accessibility.d.ts

@@ -1,5 +1,6 @@
 import { type CSSProperties, type ReactNode } from "react";
-import { type AccessibilityState, type AccessibilityStore } from "@jgengine/core/ui/accessibility";
+import { type AccessibilityState, type AccessibilityStore, type ColorblindMode } from "@jgengine/core/ui/accessibility";
+import type { SettingsStore } from "@jgengine/core/settings/settingsModel";
 interface AccessibilityContextValue {
     state: AccessibilityState;
     store: AccessibilityStore;
@@ -8,21 +9,53 @@ interface AccessibilityContextValue {
 export declare function useAccessibility(): AccessibilityContextValue;
 /**
  * Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that
- * `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered
- * automatically inside the provider; export standalone for custom roots.
+ * `filter: url(#jg-cb-<mode>)` references. Mounted by {@link ColorblindFrame};
+ * export it standalone for a root that applies the filter itself.
  *
  * @capability colorblind-filters SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
  */
 export declare function ColorblindFilters(): ReactNode;
+/** Props for {@link ColorblindFrame}. */
+export interface ColorblindFrameProps {
+    /** The player's colour-vision mode. `none` (default) renders the frame untouched. */
+    mode?: ColorblindMode;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Apply the player's colour-vision mode to one rendered frame: a box carrying
+ * `filter: url(#jg-cb-<mode>)` plus the filter defs it references. Put it around the canvas of a 3D
+ * game and nothing else — the filter is one compositor pass over that box's pixels, so HUD, menu and
+ * caption text outside it keep the contrast and hues the rest of the UI assumes.
+ *
+ * The filter needs no framebuffer copy and no extra WebGL draw: the browser filters the canvas layer
+ * as it composites, so switching modes costs nothing per frame beyond that pass. Gameplay stays
+ * unaffected; the cost is one full-screen colour-matrix pass while a mode other than `none` is set.
+ *
+ * @capability colorblind-frame apply the player's colour-vision mode to the 3D frame alone, leaving HUD and menu text unfiltered
+ */
+export declare function ColorblindFrame({ mode, children, className, style }: ColorblindFrameProps): ReactNode;
+/**
+ * The live colour-vision mode from a settings store — the same store the settings rows write, so the
+ * frame follows the player's choice the moment they pick it. Pass the store the shell owns; read
+ * `useAccessibilitySettings().colorblind` instead when a `SettingsProvider` is above the caller.
+ *
+ * @capability colorblind-frame-mode read the live colour-vision mode from the settings store that the settings rows write
+ */
+export declare function useColorblindMode(store: SettingsStore): ColorblindMode;
 /**
  * Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for
- * text to scale off, sets `data-reduced-motion` / `data-high-contrast` /
- * `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree
- * in the selected colorblind `feColorMatrix` filter. Reads a
+ * text to scale off, and sets `data-reduced-motion` / `data-high-contrast` /
+ * `data-colorblind` / `data-captions` for CSS to respond to. Reads a
  * `createAccessibilityStore` and re-renders on change; provides the state to
  * `useAccessibility`.
  *
- * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+ * It deliberately does not filter its own subtree: this is the HUD and menu root, and a colour matrix
+ * over text costs the contrast the rest of the UI was designed around. Wrap the 3D canvas in
+ * {@link ColorblindFrame} instead.
+ *
+ * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var and reduced-motion/high-contrast/colorblind/captions data attrs
  */
 export declare function AccessibilityProvider({ store, children, className, style, }: {
     store: AccessibilityStore;

package/dist/accessibility.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useSyncExternalStore } from "react";
-import { COLORBLIND_MATRICES, } from "@jgengine/core/ui/accessibility";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useSyncExternalStore, } from "react";
+import { COLORBLIND_MATRICES, colorblindFrameFilter, } from "@jgengine/core/ui/accessibility";
+import { readColorblind } from "@jgengine/core/settings/accessibilitySettings";
 const AccessibilityContext = createContext(null);
 const FILTER_MODES = [
     "protanopia",
@@ -17,31 +18,58 @@ export function useAccessibility() {
 }
 /**
  * Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that
- * `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered
- * automatically inside the provider; export standalone for custom roots.
+ * `filter: url(#jg-cb-<mode>)` references. Mounted by {@link ColorblindFrame};
+ * export it standalone for a root that applies the filter itself.
  *
  * @capability colorblind-filters SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
  */
 export function ColorblindFilters() {
     return (_jsx("svg", { "aria-hidden": true, width: 0, height: 0, style: { position: "absolute" }, "data-colorblind-filters": true, children: _jsx("defs", { children: FILTER_MODES.map((mode) => (_jsx("filter", { id: `jg-cb-${mode}`, colorInterpolationFilters: "sRGB", children: _jsx("feColorMatrix", { type: "matrix", values: COLORBLIND_MATRICES[mode] ?? "" }) }, mode))) }) }));
 }
+/**
+ * Apply the player's colour-vision mode to one rendered frame: a box carrying
+ * `filter: url(#jg-cb-<mode>)` plus the filter defs it references. Put it around the canvas of a 3D
+ * game and nothing else — the filter is one compositor pass over that box's pixels, so HUD, menu and
+ * caption text outside it keep the contrast and hues the rest of the UI assumes.
+ *
+ * The filter needs no framebuffer copy and no extra WebGL draw: the browser filters the canvas layer
+ * as it composites, so switching modes costs nothing per frame beyond that pass. Gameplay stays
+ * unaffected; the cost is one full-screen colour-matrix pass while a mode other than `none` is set.
+ *
+ * @capability colorblind-frame apply the player's colour-vision mode to the 3D frame alone, leaving HUD and menu text unfiltered
+ */
+export function ColorblindFrame({ mode = "none", children, className, style }) {
+    const filter = colorblindFrameFilter(mode);
+    return (_jsxs(_Fragment, { children: [_jsx(ColorblindFilters, {}), _jsx("div", { className: className, "data-colorblind-frame": mode, style: filter === null ? style : { ...style, filter }, children: children })] }));
+}
+/**
+ * The live colour-vision mode from a settings store — the same store the settings rows write, so the
+ * frame follows the player's choice the moment they pick it. Pass the store the shell owns; read
+ * `useAccessibilitySettings().colorblind` instead when a `SettingsProvider` is above the caller.
+ *
+ * @capability colorblind-frame-mode read the live colour-vision mode from the settings store that the settings rows write
+ */
+export function useColorblindMode(store) {
+    return useSyncExternalStore(store.subscribe, () => readColorblind(store), () => readColorblind(store));
+}
 /**
  * Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for
- * text to scale off, sets `data-reduced-motion` / `data-high-contrast` /
- * `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree
- * in the selected colorblind `feColorMatrix` filter. Reads a
+ * text to scale off, and sets `data-reduced-motion` / `data-high-contrast` /
+ * `data-colorblind` / `data-captions` for CSS to respond to. Reads a
  * `createAccessibilityStore` and re-renders on change; provides the state to
  * `useAccessibility`.
  *
- * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+ * It deliberately does not filter its own subtree: this is the HUD and menu root, and a colour matrix
+ * over text costs the contrast the rest of the UI was designed around. Wrap the 3D canvas in
+ * {@link ColorblindFrame} instead.
+ *
+ * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var and reduced-motion/high-contrast/colorblind/captions data attrs
  */
 export function AccessibilityProvider({ store, children, className, style, }) {
     const state = useSyncExternalStore(store.subscribe, store.get, store.get);
     const rootStyle = { ...style };
     rootStyle["--jg-text-scale"] = String(state.textScale);
-    if (state.colorblind !== "none")
-        rootStyle.filter = `url(#jg-cb-${state.colorblind})`;
-    return (_jsx(AccessibilityContext.Provider, { value: { state, store }, children: _jsxs("div", { className: className, "data-accessibility": true, "data-reduced-motion": state.reducedMotion, "data-high-contrast": state.highContrast, "data-colorblind": state.colorblind, "data-captions": state.captions, style: rootStyle, children: [_jsx(ColorblindFilters, {}), children] }) }));
+    return (_jsx(AccessibilityContext.Provider, { value: { state, store }, children: _jsx("div", { className: className, "data-accessibility": true, "data-reduced-motion": state.reducedMotion, "data-high-contrast": state.highContrast, "data-colorblind": state.colorblind, "data-captions": state.captions, style: rootStyle, children: children }) }));
 }
 /**
  * OS "reduce motion" preference (`prefers-reduced-motion: reduce`) as a live

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"`. */