@jgengine/shell 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -26,6 +26,47 @@ 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.25.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.25.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.22.0`; `@jgengine/github` is `0.12.0`.
+- The frame panel from `@jgengine/react/hudPanel` is now `HudSurface` in `@jgengine/react/hudSurface` (`HudSurfaceProps`, `HudSurfaceElevation`). `HudPanel`, `HudPanelProps` and `HudPanelElevation` from `@jgengine/react/hudPanel` stay as deprecated aliases for this release. The `HudCanvas` layout slot keeps the name `HudPanel`.
+- Engine HUD control sounds (button click/hover, panel and window open/close) no longer turn off with `notices: false` or `notices.cues: false`. Set `audio.hudCues: false` to silence them; `notices.cues` now covers notice sounds only.
+- The notice stack now defaults to z-index 85 (was 45), above `ModalHost`. Pass `notices.zIndex` to put it back under a game overlay.
+
+### Added
+
+- `HudSurface` takes `as` (`section`, `aside`, `nav`, ...) to render as a landmark.
+- `notices.offset`, `notices.avoidHud` and `notices.zIndex`, with matching `NoticeStack` props. The offset adds to the device safe-area inset.
+- `ctx.game.notices.push({ text, silent: true })` shows a notice without its sound.
+
+### Changed
+
+- The engine stylesheet (`@jgengine/react/styles.css` and the injected copy) sits in the `components.jgengine` cascade layer, after a `theme, base, components, utilities` layer order, so plain game CSS and Tailwind utilities override engine buttons and panels without `!important`.
+- `HudSurface` padding comes from `--jg-panel-padding` (default 12px); the `padding` prop sets that variable instead of an inline `padding`, so a game class or media query can override it.
+- `HudButton` labels wrap (`white-space: normal`, line height 1.2, 4px vertical padding) instead of overflowing on one line.
+- The shell renders the notice stack inside the HUD theme root, so notices use the game's `hudTheme` colours and font.
+- A top or bottom notice stack moves clear of `HudCanvas` panels and touch controls registered in its column (Harbor Heat's courier card, action bars).
+
+### Fixed
+
+- Flowing `HudCanvas` panels now register their layout region once their anchor region mounts; before, most never registered, so layout collision checks and region consumers missed them.
+
+## 0.24.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.24.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.21.0`; `@jgengine/github` is `0.11.0`.
+
+### Added
+
+- `buildGroundCoverageMask`, `createGroundEdgeFade` and `applyGroundEdgeFade` (`@jgengine/shell/terrain`) fade any ground material out at the outer edge of a merged mesh footprint, leaving seams between layers inside it crisp.
+
+### Changed
+
+- City studio ground (roads, junctions, block land, sidewalks, medians, drives, parks, crops, curbs, markings) now fades into the terrain where the town's ground ends instead of stopping at a hard edge. `meta.edgeFade: false` on the city volume keeps the old hard edge.
+
 ## 0.23.0
 
 ### Migrate

package/dist/ShellChrome.js

@@ -11,7 +11,7 @@ import { SettingsPlayControlGate } from "./settings/SettingsRuntime.js";
 const DevtoolsOverlay = lazy(() => import("./devtools/DevtoolsOverlay.js").then((module) => ({ default: module.DevtoolsOverlay })));
 /** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport → HUD theme root. @internal */
 export function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }) {
-    return (_jsx(GameUiErrorBoundary, { onRuntimeError: onRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(SettingsPlayControlGate, { ctx: ctx }), _jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: uiScale, children: orientationGate ? null : (_jsx(ShellUiCues, { ctx: ctx, enabled: playable.notices !== false && playable.notices?.cues !== false, children: _jsx(HudThemeRoot, { theme: playable.hudTheme, children: _jsx(GameUI, {}) }) })) }), orientationGate ? null : _jsx(ShellNotices, { ctx: ctx, config: playable.notices, scale: uiScale })] }) }));
+    return (_jsx(GameUiErrorBoundary, { onRuntimeError: onRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(SettingsPlayControlGate, { ctx: ctx }), _jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: uiScale, children: orientationGate ? null : (_jsx(ShellUiCues, { ctx: ctx, enabled: playable.audio?.hudCues !== false, children: _jsxs(HudThemeRoot, { theme: playable.hudTheme, children: [_jsx(GameUI, {}), _jsx(ShellNotices, { ctx: ctx, config: playable.notices, scale: uiScale })] }) })) })] }) }));
 }
 /** Devtools + diagnostic overlays shared by HUD and 3D presentation paths. @internal */
 export function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, devtoolsEnabled, devtoolsOpen, hideDiagnostics = false, }) {

package/dist/ShellNotices.d.ts

@@ -3,11 +3,11 @@ import type { NoticePresentationConfig } from "@jgengine/core/game/playableGame"
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 /**
  * Wire `ctx.game.notices` for the player: refused commands with a `message` become deny notices, each new
- * notice plays its tone's UI cue, and the default stack renders it. Returns the detach function.
+ * notice plays its tone's UI cue unless pushed `silent`, and the default stack renders it. Returns the detach function.
  * @internal
  */
 export declare function attachShellNotices(ctx: GameContext, config?: NoticePresentationConfig): () => void;
-/** The shell-mounted notice feed; `playable.notices: false` removes it. @internal */
+/** The shell-mounted notice feed, rendered inside the HUD theme root; `playable.notices: false` removes it. @internal */
 export declare function ShellNotices({ ctx, config, scale, }: {
     ctx: GameContext;
     config: NoticePresentationConfig | false | undefined;
@@ -15,8 +15,8 @@ export declare function ShellNotices({ ctx, config, scale, }: {
 }): import("react").JSX.Element | null;
 /**
  * Plays the UI cue for every engine HUD primitive interaction below it (button activate/hover, panel
- * open/close), so `HudButton`, `HudPanel`, windows and action slots sound without per-button wiring.
- * Off with `playable.notices: false` or `notices.cues: false`; `audio.uiCues` silences individual cues.
+ * open/close), so `HudButton`, `HudSurface`, windows and action slots sound without per-button wiring.
+ * Off with `audio.hudCues: false` (notice sounds are separate: `notices.cues`); `audio.uiCues` silences individual cues.
  * @internal
  */
 export declare function ShellUiCues({ ctx, enabled, children }: {

package/dist/ShellNotices.js

@@ -7,7 +7,7 @@ import { NoticeStack } from "@jgengine/react/notices";
 import { playUiCue, uiCueForInteraction } from "@jgengine/react/uiCues";
 /**
  * Wire `ctx.game.notices` for the player: refused commands with a `message` become deny notices, each new
- * notice plays its tone's UI cue, and the default stack renders it. Returns the detach function.
+ * notice plays its tone's UI cue unless pushed `silent`, and the default stack renders it. Returns the detach function.
  * @internal
  */
 export function attachShellNotices(ctx, config = {}) {
@@ -18,25 +18,28 @@ export function attachShellNotices(ctx, config = {}) {
         : attachRefusalNotices(ctx.game.events, notices, { localUserId: () => ctx.player.userId });
     const detachCues = config.cues === false
         ? () => undefined
-        : notices.onPush((notice) => ctx.game.audio.play(uiCueSoundId(NOTICE_TONE_CUES[notice.tone])));
+        : notices.onPush((notice) => {
+            if (notice.silent !== true)
+                ctx.game.audio.play(uiCueSoundId(NOTICE_TONE_CUES[notice.tone]));
+        });
     return () => {
         detachRefusals();
         detachCues();
     };
 }
-/** The shell-mounted notice feed; `playable.notices: false` removes it. @internal */
+/** The shell-mounted notice feed, rendered inside the HUD theme root; `playable.notices: false` removes it. @internal */
 export function ShellNotices({ ctx, config, scale, }) {
     const enabled = config !== false;
     const settings = config === false ? undefined : config;
     useEffect(() => (enabled ? attachShellNotices(ctx, settings) : undefined), [ctx, enabled, settings]);
     if (!enabled || settings?.hidden === true)
         return null;
-    return _jsx(NoticeStack, { feed: ctx.game.notices, placement: settings?.placement ?? "top", scale: scale });
+    return (_jsx(NoticeStack, { feed: ctx.game.notices, placement: settings?.placement ?? "top", offset: settings?.offset, avoidHud: settings?.avoidHud ?? true, zIndex: settings?.zIndex ?? 85, scale: scale }));
 }
 /**
  * Plays the UI cue for every engine HUD primitive interaction below it (button activate/hover, panel
- * open/close), so `HudButton`, `HudPanel`, windows and action slots sound without per-button wiring.
- * Off with `playable.notices: false` or `notices.cues: false`; `audio.uiCues` silences individual cues.
+ * open/close), so `HudButton`, `HudSurface`, windows and action slots sound without per-button wiring.
+ * Off with `audio.hudCues: false` (notice sounds are separate: `notices.cues`); `audio.uiCues` silences individual cues.
  * @internal
  */
 export function ShellUiCues({ ctx, enabled, children }) {

package/dist/scene/CityRenderer.js

@@ -14,7 +14,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  * All geometry derives from the document volume, so editor sliders re-render the district live and
  * games consume the same authored volume unchanged.
  */
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 import { roundPathCorners, buildIntersectionMarkings, buildRoadRibbon, buildTrimmedIntersections, dashSegments, GROUND_DECAL_LAYERS, } from "@jgengine/core/world/roads";
@@ -30,6 +30,7 @@ import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { getBuildingKit } from "../structures/buildingKitRegistry.js";
 import { createCityWindowMaterial } from "./cityWindowMaterial.js";
 import { createSurfaceRibbonMaterial } from "../terrain/surfaceRibbonMaterial.js";
+import { applyGroundEdgeFade, buildGroundCoverageMask, createGroundEdgeFade } from "../terrain/groundEdgeFade.js";
 import { useTerrainQuality } from "../terrain/terrainQuality.js";
 import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
 import { junctionSurface } from "./cityJunctionSurface.js";
@@ -91,6 +92,22 @@ const CROP_LAYER = 0.42;
 const RACE_SURFACE_LAYER = 0.28;
 const RACE_PAINT_LAYER = 0.3;
 const BRIDGE_DECK_LIFT = 0.12;
+/** Ground meshes bottom layer first; the index is each mesh's `renderOrder`, so blended layers draw under the ones above. */
+const GROUND_LAYERS = [
+    "urban",
+    "asphalt",
+    "gravel",
+    "patches",
+    "curbs",
+    "markings",
+    "land",
+    "medians",
+    "sidewalks",
+    "parks",
+    "pavementDrives",
+    "gravelDrives",
+    "crops",
+];
 /** Compact carriageway-union — same seam as StreetGeometryPreview and playground `cityScene`. */
 const JUNCTION_OPTS = { curbReturnRadius: 2, apronMargin: 0.25, filletSegments: 6, elevation: ROAD_LAYER, maxSegmentLength: 2 };
 const SPECIES_PROXY = { broadleaf: "oak", conifer: "pine", palm: "palm", cypress: "cypress" };
@@ -1506,34 +1523,72 @@ function OneCity({ object, context }) {
     }, [race]);
     const quality = useTerrainQuality();
     const surfaceDetail = object.meta?.["surfaceDetail"] !== false;
-    const groundMaterials = useMemo(() => {
-        if (!surfaceDetail)
+    // Every opaque ground layer fades out where the district's merged ground footprint meets bare
+    // terrain; seams between layers inside it stay crisp. The urban sheet is left out of the
+    // footprint because it already fades over its own street-distance reach.
+    const edgeFadeOn = object.meta?.["edgeFade"] !== false;
+    const edgeFade = useMemo(() => (edgeFadeOn ? createGroundEdgeFade() : null), [edgeFadeOn]);
+    useEffect(() => () => edgeFade?.dispose(), [edgeFade]);
+    const fadeWidth = Math.min(4, Math.max(1.5, (resolved?.rules.streetWidth ?? 3) * 0.6));
+    const footprint = useMemo(() => {
+        if (edgeFade === null || ground === null)
             return null;
-        const make = (surface, color, vertexColors, roughness, scale = 1) => createSurfaceRibbonMaterial({ surface, color, vertexColors, roughness, scale, halfWidth: 1, quality });
+        const layers = GROUND_LAYERS.filter((layer) => layer !== "urban" && layer !== "curbs" && layer !== "markings").map((layer) => ground[layer]);
+        return buildGroundCoverageMask(layers, { width: fadeWidth });
+    }, [edgeFade, ground, fadeWidth]);
+    useLayoutEffect(() => {
+        edgeFade?.setMask(footprint, fadeWidth);
+    }, [edgeFade, footprint, fadeWidth]);
+    const groundMaterials = useMemo(() => {
+        const make = (surface, color, vertexColors, roughness, scale = 1) => surfaceDetail
+            ? createSurfaceRibbonMaterial({ surface, color, vertexColors, roughness, scale, halfWidth: 1, quality })
+            : new THREE.MeshStandardMaterial({ color, vertexColors, roughness, metalness: 0, side: THREE.DoubleSide });
         const urban = make("dirt", "#ffffff", true, 1);
         urban.transparent = true;
         urban.depthWrite = false;
-        return {
+        const materials = {
             urban,
-            land: make("dirt", "#ffffff", true, 1),
             asphalt: make("road", ASPHALT_COLOR, true, 0.96),
             gravel: make("gravel", GRAVEL_COLOR, false, 1),
-            sidewalks: make("pavement", SIDEWALK_COLOR, false, 1, 1.6),
             patches: make("road", ASPHALT_COLOR, true, 0.96),
+            curbs: new THREE.MeshStandardMaterial({ color: CURB_COLOR, roughness: 0.9, metalness: 0, side: THREE.DoubleSide }),
+            markings: new THREE.MeshStandardMaterial({
+                color: MARKING_COLOR,
+                vertexColors: true,
+                roughness: 0.8,
+                metalness: 0,
+                side: THREE.DoubleSide,
+                polygonOffset: true,
+                polygonOffsetFactor: -1,
+                polygonOffsetUnits: -1,
+            }),
+            land: make("dirt", "#ffffff", true, 1),
             medians: make("grass", MEDIAN_COLOR, false, 1),
+            sidewalks: make("pavement", SIDEWALK_COLOR, false, 1, 1.6),
+            parks: make("ground", "#ffffff", true, 1),
             pavementDrives: make("concrete", PAVEMENT_COLOR, false, 1, 1.6),
             gravelDrives: make("gravel", GRAVEL_COLOR, false, 1),
-            parks: make("ground", "#ffffff", true, 1),
             crops: make("dirt", "#ffffff", true, 1),
         };
-    }, [surfaceDetail, quality]);
+        if (edgeFade !== null) {
+            for (const layer of GROUND_LAYERS)
+                if (layer !== "urban")
+                    applyGroundEdgeFade(materials[layer], edgeFade);
+        }
+        return materials;
+    }, [surfaceDetail, quality, edgeFade]);
     useEffect(() => () => {
-        for (const material of Object.values(groundMaterials ?? {}))
+        for (const material of Object.values(groundMaterials))
             material.dispose();
     }, [groundMaterials]);
     if (resolved === null)
         return null;
-    return (_jsxs("group", { children: [ground?.urban != null ? (_jsx("mesh", { geometry: ground.urban, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.urban }), children: groundMaterials === null ? (_jsx("meshStandardMaterial", { vertexColors: true, transparent: true, depthWrite: false, roughness: 1, metalness: 0, side: THREE.DoubleSide })) : null })) : null, ground?.land != null ? (_jsx("mesh", { geometry: ground.land, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.land }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.asphalt != null ? (_jsx("mesh", { geometry: ground.asphalt, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.asphalt }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: ASPHALT_COLOR, vertexColors: true, roughness: 0.96, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.gravel != null ? (_jsx("mesh", { geometry: ground.gravel, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.gravel }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: GRAVEL_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.sidewalks != null ? (_jsx("mesh", { geometry: ground.sidewalks, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.sidewalks }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: SIDEWALK_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.patches != null ? (_jsx("mesh", { geometry: ground.patches, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.patches }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: ASPHALT_COLOR, vertexColors: true, roughness: 0.96, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.curbs != null ? (_jsx("mesh", { geometry: ground.curbs, receiveShadow: true, castShadow: true, children: _jsx("meshStandardMaterial", { color: CURB_COLOR, roughness: 0.9, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.markings != null ? (_jsx("mesh", { geometry: ground.markings, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: MARKING_COLOR, vertexColors: true, roughness: 0.8, metalness: 0, side: THREE.DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, ground?.medians != null ? (_jsx("mesh", { geometry: ground.medians, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.medians }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: MEDIAN_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.pavementDrives != null ? (_jsx("mesh", { geometry: ground.pavementDrives, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.pavementDrives }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: PAVEMENT_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.gravelDrives != null ? (_jsx("mesh", { geometry: ground.gravelDrives, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.gravelDrives }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { color: GRAVEL_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.parks != null ? (_jsx("mesh", { geometry: ground.parks, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.parks }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, ground?.crops != null ? (_jsx("mesh", { geometry: ground.crops, receiveShadow: true, ...(groundMaterials === null ? {} : { material: groundMaterials.crops }), children: groundMaterials === null ? _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) : null })) : null, bridges?.deck != null ? (_jsx("mesh", { geometry: bridges.deck, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: CONCRETE_COLOR, roughness: 0.85, metalness: 0.05, side: THREE.DoubleSide }) })) : null, bridges !== null && bridges.concrete.length > 0 ? (_jsx(InstancedBoxes, { matrices: bridges.concrete, color: CONCRETE_COLOR })) : null, bridges !== null && bridges.steel.length > 0 ? _jsx(InstancedBoxes, { matrices: bridges.steel, color: STEEL_COLOR }) : null, tunnels?.roof != null ? (_jsx("mesh", { geometry: tunnels.roof, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: TUNNEL_COLOR, roughness: 0.95, metalness: 0, side: THREE.DoubleSide }) })) : null, tunnels !== null && tunnels.stone.length > 0 ? _jsx(InstancedBoxes, { matrices: tunnels.stone, color: TUNNEL_COLOR }) : null, massing !== null ? massing.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `massing:${i}`)) : null, furniture !== null ? furniture.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `furniture:${i}`)) : null, race !== null ? race.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `race:${i}`)) : null, _jsx(DetailBuildings, { buildings: detail.buildings, palette: palette, kitName: resolved?.rules.buildingKit ?? "" })] }));
+    return (_jsxs("group", { children: [GROUND_LAYERS.map((layer, order) => {
+                const geometry = ground?.[layer];
+                if (geometry == null)
+                    return null;
+                return (_jsx("mesh", { geometry: geometry, material: groundMaterials[layer], renderOrder: order, receiveShadow: layer !== "markings", castShadow: layer === "curbs" }, layer));
+            }), bridges?.deck != null ? (_jsx("mesh", { geometry: bridges.deck, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: CONCRETE_COLOR, roughness: 0.85, metalness: 0.05, side: THREE.DoubleSide }) })) : null, bridges !== null && bridges.concrete.length > 0 ? (_jsx(InstancedBoxes, { matrices: bridges.concrete, color: CONCRETE_COLOR })) : null, bridges !== null && bridges.steel.length > 0 ? _jsx(InstancedBoxes, { matrices: bridges.steel, color: STEEL_COLOR }) : null, tunnels?.roof != null ? (_jsx("mesh", { geometry: tunnels.roof, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: TUNNEL_COLOR, roughness: 0.95, metalness: 0, side: THREE.DoubleSide }) })) : null, tunnels !== null && tunnels.stone.length > 0 ? _jsx(InstancedBoxes, { matrices: tunnels.stone, color: TUNNEL_COLOR }) : null, massing !== null ? massing.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `massing:${i}`)) : null, furniture !== null ? furniture.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `furniture:${i}`)) : null, race !== null ? race.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `race:${i}`)) : null, _jsx(DetailBuildings, { buildings: detail.buildings, palette: palette, kitName: resolved?.rules.buildingKit ?? "" })] }));
 }
 /** One instanced unit-box mesh from precomposed matrices (bridge parts). */
 function InstancedBoxes({ matrices, color }) {

package/dist/terrain/groundEdgeFade.d.ts

@@ -0,0 +1,67 @@
+import * as THREE from "three";
+/** Options for {@link buildGroundCoverageMask}. */
+export interface GroundCoverageOptions {
+    /** Metres inside the outer edge over which ground goes from clear to opaque. */
+    width: number;
+    /** Gaps between layers narrower than twice this (metres) count as inside, not as an outer edge. Default 1.5. */
+    closeRadius?: number;
+    /** Finest cell size in metres. Default 0.5. */
+    cell?: number;
+    /** Upper bound on cells per axis; large districts get coarser cells. Default 640. */
+    maxCells?: number;
+}
+/**
+ * How far each point of a merged ground footprint lies inside its outer edge, as a grid over world
+ * XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more
+ * inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+ */
+export interface GroundCoverageMask {
+    data: Uint8Array;
+    columns: number;
+    rows: number;
+    originX: number;
+    originZ: number;
+    cell: number;
+}
+/**
+ * Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a
+ * {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged
+ * footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical
+ * faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export declare function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null;
+/** Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile. */
+export interface GroundEdgeFade {
+    readonly uniforms: {
+        uJgFadeMask: {
+            value: THREE.Texture;
+        };
+        /** `(originX, originZ, columns * cell, rows * cell)`. */
+        uJgFadeBounds: {
+            value: THREE.Vector4;
+        };
+        /** Mask width in metres; scales the noise that breaks up the edge. */
+        uJgFadeWidth: {
+            value: number;
+        };
+    };
+    /** Swap in a new mask (`null` = fully opaque everywhere). The previous texture is disposed. */
+    setMask(mask: GroundCoverageMask | null, width: number): void;
+    dispose(): void;
+}
+/**
+ * Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export declare function createGroundEdgeFade(): GroundEdgeFade;
+/**
+ * Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge,
+ * opaque `width` metres inside, with a noise-broken line. Seams between layers inside the
+ * footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary
+ * melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending
+ * `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes
+ * with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export declare function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M;

package/dist/terrain/groundEdgeFade.js

@@ -0,0 +1,234 @@
+import * as THREE from "three";
+const DIAGONAL = Math.SQRT2;
+/** Two-pass chamfer distance (in cells) from every cell to the nearest seed cell. */
+function chamfer(seed, columns, rows) {
+    const d = new Float32Array(columns * rows);
+    for (let i = 0; i < d.length; i += 1)
+        d[i] = seed[i] === 1 ? 0 : Infinity;
+    for (let j = 0; j < rows; j += 1) {
+        for (let i = 0; i < columns; i += 1) {
+            const k = j * columns + i;
+            let best = d[k];
+            if (i > 0)
+                best = Math.min(best, d[k - 1] + 1);
+            if (j > 0) {
+                best = Math.min(best, d[k - columns] + 1);
+                if (i > 0)
+                    best = Math.min(best, d[k - columns - 1] + DIAGONAL);
+                if (i + 1 < columns)
+                    best = Math.min(best, d[k - columns + 1] + DIAGONAL);
+            }
+            d[k] = best;
+        }
+    }
+    for (let j = rows - 1; j >= 0; j -= 1) {
+        for (let i = columns - 1; i >= 0; i -= 1) {
+            const k = j * columns + i;
+            let best = d[k];
+            if (i + 1 < columns)
+                best = Math.min(best, d[k + 1] + 1);
+            if (j + 1 < rows) {
+                best = Math.min(best, d[k + columns] + 1);
+                if (i + 1 < columns)
+                    best = Math.min(best, d[k + columns + 1] + DIAGONAL);
+                if (i > 0)
+                    best = Math.min(best, d[k + columns - 1] + DIAGONAL);
+            }
+            d[k] = best;
+        }
+    }
+    return d;
+}
+/**
+ * Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a
+ * {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged
+ * footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical
+ * faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export function buildGroundCoverageMask(geometries, options) {
+    const width = Math.max(1e-3, options.width);
+    const closeRadius = Math.max(0, options.closeRadius ?? 1.5);
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const geometry of geometries) {
+        const position = geometry?.getAttribute("position");
+        if (position === undefined)
+            continue;
+        for (let v = 0; v < position.count; v += 1) {
+            const x = position.getX(v);
+            const z = position.getZ(v);
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+    }
+    if (!Number.isFinite(minX))
+        return null;
+    const maxCells = Math.max(8, Math.floor(options.maxCells ?? 640));
+    const pad = closeRadius + 2;
+    const spanX = maxX - minX + pad * 2;
+    const spanZ = maxZ - minZ + pad * 2;
+    const cell = Math.max(options.cell ?? 0.5, spanX / maxCells, spanZ / maxCells);
+    const columns = Math.max(2, Math.ceil(spanX / cell));
+    const rows = Math.max(2, Math.ceil(spanZ / cell));
+    const originX = minX - pad;
+    const originZ = minZ - pad;
+    const covered = new Uint8Array(columns * rows);
+    let any = false;
+    for (const geometry of geometries) {
+        const position = geometry?.getAttribute("position");
+        if (geometry == null || position === undefined)
+            continue;
+        const index = geometry.getIndex();
+        const count = index === null ? position.count : index.count;
+        for (let t = 0; t + 2 < count; t += 3) {
+            const a = index === null ? t : index.getX(t);
+            const b = index === null ? t + 1 : index.getX(t + 1);
+            const c = index === null ? t + 2 : index.getX(t + 2);
+            const ax = position.getX(a);
+            const az = position.getZ(a);
+            const bx = position.getX(b);
+            const bz = position.getZ(b);
+            const cx = position.getX(c);
+            const cz = position.getZ(c);
+            const area = (bx - ax) * (cz - az) - (bz - az) * (cx - ax);
+            if (Math.abs(area) < 1e-6)
+                continue;
+            const sign = area > 0 ? 1 : -1;
+            const i0 = Math.max(0, Math.floor((Math.min(ax, bx, cx) - originX) / cell - 0.5));
+            const i1 = Math.min(columns - 1, Math.ceil((Math.max(ax, bx, cx) - originX) / cell - 0.5));
+            const j0 = Math.max(0, Math.floor((Math.min(az, bz, cz) - originZ) / cell - 0.5));
+            const j1 = Math.min(rows - 1, Math.ceil((Math.max(az, bz, cz) - originZ) / cell - 0.5));
+            for (let j = j0; j <= j1; j += 1) {
+                const pz = originZ + (j + 0.5) * cell;
+                for (let i = i0; i <= i1; i += 1) {
+                    const px = originX + (i + 0.5) * cell;
+                    const e0 = ((bx - ax) * (pz - az) - (bz - az) * (px - ax)) * sign;
+                    const e1 = ((cx - bx) * (pz - bz) - (cz - bz) * (px - bx)) * sign;
+                    const e2 = ((ax - cx) * (pz - cz) - (az - cz) * (px - cx)) * sign;
+                    if (e0 >= 0 && e1 >= 0 && e2 >= 0) {
+                        covered[j * columns + i] = 1;
+                        any = true;
+                    }
+                }
+            }
+        }
+    }
+    if (!any)
+        return null;
+    // Morphological closing: grow the footprint by `closeRadius`, then measure inward from the grown
+    // edge less that radius, so a narrow gap between two layers never reads as an outer edge.
+    const toCovered = chamfer(covered, columns, rows);
+    const outsideGrown = new Uint8Array(columns * rows);
+    for (let k = 0; k < outsideGrown.length; k += 1)
+        outsideGrown[k] = toCovered[k] * cell > closeRadius ? 1 : 0;
+    const toOutside = chamfer(outsideGrown, columns, rows);
+    const data = new Uint8Array(columns * rows);
+    for (let k = 0; k < data.length; k += 1) {
+        // Centre-to-centre distance overshoots the edge between two cells by half a cell.
+        const inside = (toOutside[k] - 0.5) * cell - closeRadius;
+        data[k] = Math.round(Math.max(0, Math.min(1, inside / width)) * 255);
+    }
+    return { data, columns, rows, originX, originZ, cell };
+}
+function opaqueTexture() {
+    const texture = new THREE.DataTexture(new Uint8Array([255]), 1, 1, THREE.RedFormat);
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export function createGroundEdgeFade() {
+    const uniforms = {
+        uJgFadeMask: { value: opaqueTexture() },
+        uJgFadeBounds: { value: new THREE.Vector4(-1e6, -1e6, 2e6, 2e6) },
+        uJgFadeWidth: { value: 1 },
+    };
+    return {
+        uniforms,
+        setMask(mask, width) {
+            uniforms.uJgFadeMask.value.dispose();
+            if (mask === null) {
+                uniforms.uJgFadeMask.value = opaqueTexture();
+                uniforms.uJgFadeBounds.value.set(-1e6, -1e6, 2e6, 2e6);
+            }
+            else {
+                const texture = new THREE.DataTexture(mask.data, mask.columns, mask.rows, THREE.RedFormat);
+                texture.magFilter = THREE.LinearFilter;
+                texture.minFilter = THREE.LinearFilter;
+                texture.wrapS = THREE.ClampToEdgeWrapping;
+                texture.wrapT = THREE.ClampToEdgeWrapping;
+                // One byte per texel: rows are not 4-byte aligned unless `columns` happens to be.
+                texture.unpackAlignment = 1;
+                texture.needsUpdate = true;
+                uniforms.uJgFadeMask.value = texture;
+                uniforms.uJgFadeBounds.value.set(mask.originX, mask.originZ, mask.columns * mask.cell, mask.rows * mask.cell);
+            }
+            uniforms.uJgFadeWidth.value = Math.max(1e-3, width);
+        },
+        dispose() {
+            uniforms.uJgFadeMask.value.dispose();
+        },
+    };
+}
+const FADE_FRAGMENT_GLSL = /* glsl */ `
+{
+  float jgFadeIn = texture2D(uJgFadeMask, (vJgFadePos - uJgFadeBounds.xy) / uJgFadeBounds.zw).r;
+  // Two octaves of value noise keep the edge from reading as a traced outline.
+  float jgFadeN = jgFadeNoise(vJgFadePos / max(0.6, uJgFadeWidth * 1.2)) * 0.7 + jgFadeNoise(vJgFadePos / max(0.25, uJgFadeWidth * 0.3) + 17.3) * 0.3 - 0.5;
+  diffuseColor.a *= smoothstep(0.0, 1.0, (jgFadeIn - 0.15 + jgFadeN * 0.35) / 0.7);
+}
+`;
+const FADE_NOISE_GLSL = /* glsl */ `
+float jgFadeHash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
+}
+float jgFadeNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(jgFadeHash(i), jgFadeHash(i + vec2(1.0, 0.0)), u.x), mix(jgFadeHash(i + vec2(0.0, 1.0)), jgFadeHash(i + vec2(1.0, 1.0)), u.x), u.y);
+}
+`;
+/**
+ * Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge,
+ * opaque `width` metres inside, with a noise-broken line. Seams between layers inside the
+ * footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary
+ * melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending
+ * `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes
+ * with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export function applyGroundEdgeFade(material, fade) {
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey;
+    material.transparent = true;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        Object.assign(shader.uniforms, fade.uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", "#include <common>\nvarying vec2 vJgFadePos;")
+            .replace("#include <begin_vertex>", "#include <begin_vertex>\nvJgFadePos = (modelMatrix * vec4(transformed, 1.0)).xz;");
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec2 vJgFadePos;
+uniform sampler2D uJgFadeMask;
+uniform vec4 uJgFadeBounds;
+uniform float uJgFadeWidth;
+${FADE_NOISE_GLSL}`)
+            .replace("#include <alphamap_fragment>", `#include <alphamap_fragment>\n${FADE_FRAGMENT_GLSL}`);
+    };
+    material.customProgramCacheKey = () => `${previousKey.call(material)}-jgedgefade`;
+    material.needsUpdate = true;
+    return material;
+}

package/dist/terrain/index.d.ts

@@ -14,3 +14,4 @@ export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, type TerrainD
 export { createTerrainPaintTextures, MAX_TERRAIN_PAINT_LAYERS, packTerrainPaintWeights, terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness, type TerrainPaintSlot, type TerrainPaintTextures, type TerrainPaintWeights, type TerrainSurfaceClass, } from "./terrainSurfaces.js";
 export { TerrainQualityContext, useTerrainQuality } from "./terrainQuality.js";
 export { createSurfaceRibbonMaterial, resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonEdgeMargin, ribbonSurfaceFrame, useSurfaceRibbonMaterial, type RibbonSurfaceStyle, type SurfaceRibbonMaterialOptions, } from "./surfaceRibbonMaterial.js";
+export { applyGroundEdgeFade, buildGroundCoverageMask, createGroundEdgeFade, type GroundCoverageMask, type GroundCoverageOptions, type GroundEdgeFade, } from "./groundEdgeFade.js";

package/dist/terrain/index.js

@@ -14,3 +14,4 @@ export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, } from "./ter
 export { createTerrainPaintTextures, MAX_TERRAIN_PAINT_LAYERS, packTerrainPaintWeights, terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness, } from "./terrainSurfaces.js";
 export { TerrainQualityContext, useTerrainQuality } from "./terrainQuality.js";
 export { createSurfaceRibbonMaterial, resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonEdgeMargin, ribbonSurfaceFrame, useSurfaceRibbonMaterial, } from "./surfaceRibbonMaterial.js";
+export { applyGroundEdgeFade, buildGroundCoverageMask, createGroundEdgeFade, } from "./groundEdgeFade.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.23.0",
-    "@jgengine/react": "^0.23.0",
-    "@jgengine/ws": "^0.23.0"
+    "@jgengine/core": "^0.25.0",
+    "@jgengine/react": "^0.25.0",
+    "@jgengine/ws": "^0.25.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.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.23.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -232,7 +232,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.23.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/SKILL.md

@@ -32,8 +32,8 @@ Existing React games keep their entity store and use the focused
 - **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
 - **Route the front-end with `useMenuRouter`, and generate the credits.** `useMenuRouter(root)` is the screen stack behind title → save select → settings → credits: `open`/`back`/`replace`/`reset`, `path` for depth, and Escape-to-back bound by default (`escapeToBack: false` when the game owns Escape). `menuStackReducer` is the same transition as a pure function. For credits, `creditsForSourceIds(ids)` (`@jgengine/assets/credits`) turns the pack ids a game declares to `buildCatalog` into licensed, attributed sections, `mergeCredits` folds them into hand-authored lines, and `CreditsScreen` renders the result HudTheme-skinned.
 - **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the whole `--jg-*` vocabulary — bar fills and troughs, `HudFrame variation="themed"`, painted slots, the minimap ring, plus surfaces, edges, text, status colors, fonts, and rarity — so one theme spread on any HUD ancestor reskins the `@jgengine/react` primitives and the `registry/jgengine` blocks together. Author your own with `deriveHudTheme({ accent, surface })` or `hudTheme({ ... })`; `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. A component that needs a token no theme emits fails `check-hud-tokens` — add it to `HudTheme` rather than inventing a second vocabulary. Caller `style`/`renderItem` overrides still win.
-- **The shell applies `defaultHudTheme` at the GameUI root.** `HudThemeRoot` wraps every `GameUI` in a `display: contents` `[data-jg-hud]` element carrying the theme vars and injects the engine stylesheet (`jg-*` keyframes, `[data-jg-*]` interaction states, reduced motion). Set `defineGame({ hudTheme })` to swap the root theme, `hudTheme: false` to opt out; a theme spread inside `GameUI` still wins. Games outside the shell add `@import "@jgengine/react/styles.css";` to `src/index.css` (the `jgengine create` template does). The theme also carries a type scale with a 12px floor, spacing, motion, elevation, and hover/press/focus/disabled tokens; read them in inline styles through `hudType`, `hudSpace`, `hudTransition`, `hudElevation`, and `HUD_FOCUS_RING` (`@jgengine/react/hudTokens`) — never hardcode text under 12px.
-- **Build interactive chrome from `HudButton`, `HudPanel`, and `TweenNumber`.** `HudButton` gives hover lift, press scale, focus ring, and disabled from tokens; `HudPanel` gives elevation, header slots, and an `open` enter/exit transition; `TweenNumber` / `useTweenedValue` roll counters with an up/down delta flash. Each takes `cue` (`data-jg-cue`) and `onInteract`; `HudInteractProvider` routes every primitive's hover/press/activate/open/close to one listener; the shell mounts one that plays the matching UI cue, so engine primitives sound with no wiring (`cue="confirm"` picks the activate sound).
+- **The shell applies `defaultHudTheme` at the GameUI root.** `HudThemeRoot` wraps every `GameUI` in a `display: contents` `[data-jg-hud]` element carrying the theme vars and injects the engine stylesheet (`jg-*` keyframes, `[data-jg-*]` interaction states, reduced motion). Set `defineGame({ hudTheme })` to swap the root theme, `hudTheme: false` to opt out; a theme spread inside `GameUI` still wins. Games outside the shell add `@import "@jgengine/react/styles.css";` to `src/index.css` (the `jgengine create` template does). Every engine rule sits in the `components.jgengine` cascade layer, so plain game CSS and Tailwind utilities override engine buttons and panels without `!important`. The theme also carries a type scale with a 12px floor, spacing, motion, elevation, and hover/press/focus/disabled tokens; read them in inline styles through `hudType`, `hudSpace`, `hudTransition`, `hudElevation`, and `HUD_FOCUS_RING` (`@jgengine/react/hudTokens`) — never hardcode text under 12px.
+- **Build interactive chrome from `HudButton`, `HudSurface`, and `TweenNumber`.** `HudButton` gives hover lift, press scale, focus ring, and disabled from tokens, and wraps long labels; `HudSurface` (`@jgengine/react/hudSurface`; `HudPanel` from `@jgengine/react/hudPanel` is its deprecated old name, not the `HudCanvas` slot) gives elevation, header slots, an `as` landmark element, padding from `--jg-panel-padding`, and an `open` enter/exit transition; `TweenNumber` / `useTweenedValue` roll counters with an up/down delta flash. Each takes `cue` (`data-jg-cue`) and `onInteract`; `HudInteractProvider` routes every primitive's hover/press/activate/open/close to one listener; the shell mounts one that plays the matching UI cue, so engine primitives sound with no wiring (`cue="confirm"` picks the activate sound). `audio.hudCues: false` silences those control sounds; notice sounds are separate (`notices.cues`).
 - **Paint slot icons with `IconTreatment`, never render raw `itemId` strings.** It draws a `GameIcon` glyph over a school/element-keyed gradient with gloss, vignette, and optional count/keycap badges, reading the `--jg-slot-*` / `--jg-accent` tokens. `treatedItemIcon(itemId)` / `treatedActionIcon(action)` are ready adapters for hotbars and ability bars.
 - **Player death gets a visible screen and respawn feedback — never a silent teleport.** Build the moment `game-design` requires: an authored death/downed overlay that reads the lethal event, communicates the consequence, and surfaces the way back (respawn/revive/restart). Drive it from `createDownedState` (`@jgengine/core/combat`) rather than a hand-rolled flag, and mount it inside `HudCanvas`.
 - **Browser interruption listeners are shared.** Use `useBrowserSuspension` from `@jgengine/react/browserLifecycle` for blur, hidden-page and pointer-lock loss. Keep the decision to pause, release controls or preserve multiplayer simulation in the callback; use options to disable unwanted triggers.
@@ -43,7 +43,7 @@ Existing React games keep their entity store and use the focused
 
 ## Shared-world interaction rules
 
-- **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. Tune or hide the stock feed with `notices: { placement, hidden }` (`hidden` keeps cues and lets the game render `useNoticeList(ctx.game.notices)` itself).
+- **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`.
 - 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`.

package/skills/jgengine-ui/api.md

@@ -601,7 +601,7 @@
 - `ComboMeterTheme` (interface): interface ComboMeterTheme — Reskin tokens for {@link ComboMeterHud}.
 - `Compass` (function): function Compass({ facingYaw, center, markers, width = 340, fov = (Math.PI * 2) / 3, kindStyles = DEFAULT_MARKER_KINDS, className, }: CompassProps): ReactNode — Horizontal compass strip centered on the player's facing direction, with the eight cardinals and optional marker pips from static views, an external source, or a native `MarkerSet`.
 - `CompassProps` (interface): interface CompassProps { facingYaw: number; center?: WorldXZ; markers?: MarkerCollection; width?: number; fov?: number; kindStyles?: Record<string, MarkerKindStyle>; className?: string } — ⚠ undocumented · used by `Compass`: Horizontal compass strip centered on the player's facing direction, with the eight cardinals and optional marker pips from static views, an …
-- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudPanel}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
+- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudSurface}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
 - `ConfirmDialogProps` (interface): interface ConfirmDialogProps — Props for {@link ConfirmDialog}.
 - `ControlHint` (interface): interface ControlHint — One row of a control legend. Name the game action(s) whose bound key(s) to show (`action`) so the glyphs come straight from the keybind map — never re-typed — or give literal `keys` for controls that live outside the map (`"Mouse"`, `"LMB"`). `label` says what the control does.
 - `ControlsList` (function): function ControlsList({ bindings, controls, hideOnCoarsePointer = true, separator = " / ", className, rowClassName, keysClassName, keyClassName, separatorClassName, labelClassName, renderKey, renderRow, }: { bindings?: ActionCodesMap; controls: readonly ControlHint[]; hideOnCoarsePointer?: boolean; … — Renders a controls legend whose key glyphs come from the game's keybind map, so bindings live in one place and never drift from a hand-typed table. Hides itself on coarse-pointer devices (a touchscreen has no keyboard) via the same `data-jg-kbd-hint` marker as `KeyHint`. Headless: every part carries a `className` slot and `data-*` hook; pass `renderKey`/`renderRow` to fully own the markup.
@@ -772,7 +772,7 @@
 - `PartyFrame` (function): function PartyFrame({ className, rowClassName, dotClassName, emptyState, renderMember, }: { className?: string; rowClassName?: string; dotClassName?: string; emptyState?: ReactNode; renderMember?: (member: PartyMemberEntry) => ReactNode; }): React.JSX.Element — ⚠ undocumented
 - `PartyInviteToast` (function): function PartyInviteToast({ className, acceptClassName, declineClassName, renderInvite, }: { className?: string; acceptClassName?: string; declineClassName?: string; renderInvite?: (invite: PartyInviteEntry) => ReactNode; }): React.JSX.Element | null — ⚠ undocumented
 - `PartyMemberRow` (function): function PartyMemberRow({ member, className, dotClassName, children, }: { member: PartyMemberEntry; className?: string; dotClassName?: string; children?: ReactNode; }): React.JSX.Element — ⚠ undocumented
-- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudPanel}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
+- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudSurface}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
 - `PauseMenuItem` (interface): interface PauseMenuItem — One selectable row in a {@link PauseMenu}'s slot list (Settings, Save, Quit, …).
 - `PauseMenuProps` (interface): interface PauseMenuProps — Props for {@link PauseMenu}.
 - `PhotoModeControls` (function): function PhotoModeControls({ store, onCapture, className, style }: PhotoModeControlsProps): ReactNode — Photo-mode toolbar — a hide/show-HUD toggle, a capture button, and an exit button, bound to a `createPhotoModeStore`. Presentation-only: the game wires `onCapture` to shell `captureCanvas`/`downloadImage` and reads `hideHud` to drop its gameplay HUD.
@@ -1241,7 +1241,7 @@
 
 ## @jgengine/react/engineStyles
 
-- `ENGINE_STYLESHEET` (const): const ENGINE_STYLESHEET: string — The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudPanel}, the quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`). Generic HUD rules sit in `:where()` so any game selector wins. The shell injects it; games that mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
+- `ENGINE_STYLESHEET` (const): const ENGINE_STYLESHEET: string — The engine stylesheet: every `jg-*` keyframe the shared blocks and registry components animate with, the `[data-jg-*]` interaction-state rules behind {@link HudButton} / {@link HudSurface}, the quiet hover/press/focus defaults for plain buttons inside the HUD root, and reduced-motion handling (`prefers-reduced-motion` or `[data-reduced-motion="true"]` zero `--jg-motion-scale`). Every rule sits in the `components.jgengine` cascade layer, so unlayered game CSS, a game's own `components` rules and Tailwind utilities win without `!important`. It first declares `theme, base, components, utilities` so Tailwind v4's preflight stays below engine controls even when the engine sheet loads first. The shell injects it; games that mount outside the shell import `@jgengine/react/styles.css`, which holds the same text.
 - `ensureEngineStyles` (function): function ensureEngineStyles(doc: Document | undefined = typeof document === "undefined" ? undefined : document): void — Injects {@link ENGINE_STYLESHEET} into `doc` once. Safe to call repeatedly and during SSR (no-op).
 - `useEngineStyles` (function): function useEngineStyles(): void — Ensures the engine stylesheet is in the document before the calling component paints. Engine primitives call it, so they animate and show interaction states even outside the shell.
 
@@ -1407,9 +1407,9 @@
 
 ## @jgengine/react/hudPanel
 
-- `HudPanel` (const): const HudPanel: React.ForwardRefExoticComponent<HudPanelProps & React.RefAttributes<HTMLDivElement>> — Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with a short rise-and-fade and stays mounted through its exit when `open` turns false (`data-state="open" | "closed"`); reduced motion skips both. `className` and `style` restyle it.
-- `HudPanelElevation` (type): type HudPanelElevation = "raised" | "overlay" | "modal" — Shadow height of a {@link HudPanel}.
-- `HudPanelProps` (interface): interface HudPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> — Props for {@link HudPanel}.
+- `HudPanel` (const): const HudPanel: React.ForwardRefExoticComponent<HudSurfaceProps & React.RefAttributes<HTMLElement>> — Old name of the themed frame {@link HudSurface} (`@jgengine/react/hudSurface`), renamed so it no longer shares a name with the `HudCanvas` layout slot `HudPanel`.
+- `HudPanelElevation` (type): type HudPanelElevation = HudSurfaceElevation — Old name of {@link HudSurfaceElevation} (`@jgengine/react/hudSurface`).
+- `HudPanelProps` (type): type HudPanelProps = HudSurfaceProps — Old name of {@link HudSurfaceProps} (`@jgengine/react/hudSurface`).
 
 ## @jgengine/react/hudSkin
 
@@ -1422,6 +1422,13 @@
 
 - `HudSkinPreview` (function): function HudSkinPreview({ className }: { className?: string }): React.JSX.Element — Procedural two-skin fixture for visual regression captures.
 
+## @jgengine/react/hudSurface
+
+- `HudSurface` (const): const HudSurface: React.ForwardRefExoticComponent<HudSurfaceProps & React.RefAttributes<HTMLElement>> — Themed panel/window frame over the `HudTheme` frame, elevation, and motion tokens. It enters with a short rise-and-fade and stays mounted through its exit when `open` turns false (`data-state="open" | "closed"`); reduced motion skips both. Padding comes from `--jg-panel-padding`, and the engine rules sit in a cascade layer, so a game's `className` restyles it without `!important`. Not the `HudCanvas` layout slot (`HudPanel` in `@jgengine/react/hudLayout`).
+- `HudSurfaceElement` (type): type HudSurfaceElement = "div" | "section" | "aside" | "nav" | "header" | "footer" | "article" | "main" | "form" | "dialog" — Block elements a {@link HudSurface} can render as, so it can be a landmark.
+- `HudSurfaceElevation` (type): type HudSurfaceElevation = "raised" | "overlay" | "modal" — Shadow height of a {@link HudSurface}.
+- `HudSurfaceProps` (interface): interface HudSurfaceProps extends Omit<HTMLAttributes<HTMLElement>, "title"> — Props for {@link HudSurface}.
+
 ## @jgengine/react/hudTheme
 
 - `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.
@@ -1600,13 +1607,13 @@
 
 ## @jgengine/react/modals
 
-- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudPanel}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
+- `ConfirmDialog` (function): function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }: ConfirmDialogProps): ReactNode — A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over a `HudTheme`-token-driven {@link HudSurface}. Presentation-only: wire `onConfirm`/`onCancel` to a modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies the copy.
 - `ConfirmDialogProps` (interface): interface ConfirmDialogProps — Props for {@link ConfirmDialog}.
 - `ModalControls` (interface): interface ModalControls — Stack-bound controls handed to a {@link ModalHost} render callback.
 - `ModalHost` (function): function ModalHost({ stack, children, showBackdrop = true, backdrop, closeOnBackdrop = true, closeOnEsc = true, zIndexBase = 80, onInteract, className, style, }: ModalHostProps): ReactNode — Full-screen modal host: watches a stack, renders only the topmost modal centered over a dimmed backdrop, and manages accessibility — the panel is a `role="dialog" aria-modal`, focus moves into it on open and is trapped with Tab/Shift+Tab cycling, Escape and (optionally) a backdrop click cancel the top modal, and focus returns to the previously focused element on close. It renders nothing when the stack is empty. Skin the panel and backdrop via `HudTheme` tokens.
 - `ModalHostProps` (interface): interface ModalHostProps — Props for {@link ModalHost}.
 - `ModalStackView` (interface): interface ModalStackView — React chrome over the headless modal stack (`@jgengine/core/ui/modalStack`) — the blocking-overlay layer a game raises over its scene: a pause menu, a "quit to menu?" confirm, a reward popup. {@link useModalStack} is the DATA/HOOK layer (subscribe + the active record), {@link ModalHost} renders the top modal with a backdrop, focus trap, and Esc-to-cancel, and {@link ConfirmDialog} / {@link PauseMenu} are ready-to-wire, HudTheme-token-driven building blocks. All unskinned and game-owned: the model never interprets a modal's `kind`, so a game switches on it to pick which of these (or its own) content to show, and reskins everything via `HudTheme` tokens and the frame.
-- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudPanel}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
+- `PauseMenu` (function): function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }: PauseMenuProps): ReactNode — A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudSurface}. It ships the common shape every game's pause screen needs and nothing genre-specific — the game supplies the title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
 - `PauseMenuItem` (interface): interface PauseMenuItem — One selectable row in a {@link PauseMenu}'s slot list (Settings, Save, Quit, …).
 - `PauseMenuProps` (interface): interface PauseMenuProps — Props for {@link PauseMenu}.
 - `useModalStack` (function): function useModalStack(stack: ModalStack): ModalStackView — Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
@@ -1615,7 +1622,7 @@
 
 - `Notice` (interface): interface Notice — A live notice as the HUD renders it.
 - `NoticePlacement` (type): type NoticePlacement = "top" | "center" | "bottom" — Where {@link NoticeStack} sits: below top-edge HUD bars, over the play area, or above bottom action bars.
-- `NoticeStack` (function): function NoticeStack({ feed, placement = "top", scale = 1, renderNotice, }: { /** Defaults to the surrounding game's `ctx.game.notices`. */ feed?: NoticeFeed; placement?: NoticePlacement; /** Multiplies text and spacing (the shell passes the player's UI scale). */ scale?: number; renderNotice?: (not… — Animated, toned notice stack for a {@link NoticeFeed} — the default renderer the shell mounts for `ctx.game.notices`. Uses `--jg-*` theme vars with fallbacks, 14px text, and never takes pointer input.
+- `NoticeStack` (function): function NoticeStack({ feed, placement = "top", offset, avoidHud = true, zIndex = 85, scale = 1, renderNotice, }: { /** Defaults to the surrounding game's `ctx.game.notices`. */ feed?: NoticeFeed; placement?: NoticePlacement; /** Distance from the band's screen edge (px or CSS length), added to the … — Animated, toned notice stack for a {@link NoticeFeed} — the default renderer the shell mounts for `ctx.game.notices` inside the HUD theme root. Uses `--jg-*` theme vars with fallbacks, 14px text, and never takes pointer input. A top or bottom stack keeps clear of HUD panels registered in its column and sits above modal overlays.
 - `NoticeTone` (type): type NoticeTone = "info" | "success" | "warn" | "deny" — How a notice reads: neutral info, a win, a caution, or a refused action.
 - `useNoticeList` (function): function useNoticeList(feed: NoticeFeed | null): readonly Notice[] — Live notices of `feed`, re-rendering on change and pruning each one when it expires.
 
@@ -2828,6 +2835,9 @@
 - `GrassRange` (type): type GrassRange = number | readonly [min: number, max: number] — ⚠ undocumented
 - `GrassShaderUniforms` (interface): interface GrassShaderUniforms { uTime: THREE.IUniform<number>; uWindDirection: THREE.IUniform<THREE.Vector2>; uWindStrength: THREE.IUniform<number>; uWindSpeed: THREE.IUniform<number>; uWindGustScale: THREE.IUniform<number>; uWindFlutter: THREE.IUniform<number>; uColorB… — ⚠ undocumented
 - `GrassWindOptions` (interface): interface GrassWindOptions { direction?: readonly [x: number, z: number]; strength?: number; speed?: number; gustScale?: number; flutter?: number; layered?: boolean } — ⚠ undocumented
+- `GroundCoverageMask` (interface): interface GroundCoverageMask — How far each point of a merged ground footprint lies inside its outer edge, as a grid over world XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+- `GroundCoverageOptions` (interface): interface GroundCoverageOptions — Options for {@link buildGroundCoverageMask}.
+- `GroundEdgeFade` (interface): interface GroundEdgeFade — Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile.
 - `HeightfieldColorFn` (type): type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void — Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`.
 - `HeightfieldDisplaceOptions` (interface): interface HeightfieldDisplaceOptions — Options for {@link displaceHeightfieldGeometry}.
 - `HeightfieldRect` (interface): interface HeightfieldRect — XZ rectangle in world units — matches the shape of a terraform snapshot's `bounds`.
@@ -2861,6 +2871,9 @@
 - `TerrainSurfaceClass` (type): type TerrainSurfaceClass = "ground" | "grass" | "dirt" | "gravel" | "rock" | "sand" | "mud" | "snow" | "road" — Procedural ground response the terrain shader renders for a painted surface id.
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
+- `applyGroundEdgeFade` (function): function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M — Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge, opaque `width` metres inside, with a noise-broken line. Seams between layers inside the footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+- `buildGroundCoverageMask` (function): function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null — Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+- `createGroundEdgeFade` (function): function createGroundEdgeFade(): GroundEdgeFade — Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
 - `createSurfaceRibbonMaterial` (function): function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial — A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own procedural surface functions, so a dirt track or asphalt strip matches painted ground: the authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
 - `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground. Paint lives on a coarse cell grid; when the source exposes that grid, each sample smoothly blends the four surrounding cell centres (unpainted cells contribute the caller's base color in `out`), so painted paths and clearings get soft edges instead of grid-aligned stair steps.
 - `createTerrainPaintTextures` (function): function createTerrainPaintTextures(weights: TerrainPaintWeights): TerrainPaintTextures — Uploads packed paint coverage ({@link packTerrainPaintWeights}) as two linear-filtered RGBA textures plus per-slot hue, surface class, roughness and pattern scale for the terrain surface material.
@@ -2893,6 +2906,9 @@
 - `GrassRange` (type): type GrassRange = number | readonly [min: number, max: number] — ⚠ undocumented
 - `GrassShaderUniforms` (interface): interface GrassShaderUniforms { uTime: THREE.IUniform<number>; uWindDirection: THREE.IUniform<THREE.Vector2>; uWindStrength: THREE.IUniform<number>; uWindSpeed: THREE.IUniform<number>; uWindGustScale: THREE.IUniform<number>; uWindFlutter: THREE.IUniform<number>; uColorB… — ⚠ undocumented
 - `GrassWindOptions` (interface): interface GrassWindOptions { direction?: readonly [x: number, z: number]; strength?: number; speed?: number; gustScale?: number; flutter?: number; layered?: boolean } — ⚠ undocumented
+- `GroundCoverageMask` (interface): interface GroundCoverageMask — How far each point of a merged ground footprint lies inside its outer edge, as a grid over world XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+- `GroundCoverageOptions` (interface): interface GroundCoverageOptions — Options for {@link buildGroundCoverageMask}.
+- `GroundEdgeFade` (interface): interface GroundEdgeFade — Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile.
 - `HeightfieldColorFn` (type): type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void — Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`.
 - `HeightfieldDisplaceOptions` (interface): interface HeightfieldDisplaceOptions — Options for {@link displaceHeightfieldGeometry}.
 - `HeightfieldRect` (interface): interface HeightfieldRect — XZ rectangle in world units — matches the shape of a terraform snapshot's `bounds`.
@@ -2926,6 +2942,9 @@
 - `TerrainSurfaceClass` (type): type TerrainSurfaceClass = "ground" | "grass" | "dirt" | "gravel" | "rock" | "sand" | "mud" | "snow" | "road" — Procedural ground response the terrain shader renders for a painted surface id.
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
+- `applyGroundEdgeFade` (function): function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M — Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge, opaque `width` metres inside, with a noise-broken line. Seams between layers inside the footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+- `buildGroundCoverageMask` (function): function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null — Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+- `createGroundEdgeFade` (function): function createGroundEdgeFade(): GroundEdgeFade — Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
 - `createSurfaceRibbonMaterial` (function): function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial — A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own procedural surface functions, so a dirt track or asphalt strip matches painted ground: the authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
 - `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground. Paint lives on a coarse cell grid; when the source exposes that grid, each sample smoothly blends the four surrounding cell centres (unpainted cells contribute the caller's base color in `out`), so painted paths and clearings get soft edges instead of grid-aligned stair steps.
 - `createTerrainPaintTextures` (function): function createTerrainPaintTextures(weights: TerrainPaintWeights): TerrainPaintTextures — Uploads packed paint coverage ({@link packTerrainPaintWeights}) as two linear-filtered RGBA textures plus per-slot hue, surface class, roughness and pattern scale for the terrain surface material.
@@ -2991,6 +3010,15 @@
 - `GrassShaderUniforms` (interface): interface GrassShaderUniforms { uTime: THREE.IUniform<number>; uWindDirection: THREE.IUniform<THREE.Vector2>; uWindStrength: THREE.IUniform<number>; uWindSpeed: THREE.IUniform<number>; uWindGustScale: THREE.IUniform<number>; uWindFlutter: THREE.IUniform<number>; uColorB… — ⚠ undocumented
 - `GrassWindOptions` (interface): interface GrassWindOptions { direction?: readonly [x: number, z: number]; strength?: number; speed?: number; gustScale?: number; flutter?: number; layered?: boolean } — ⚠ undocumented
 
+## @jgengine/shell/terrain/groundEdgeFade
+
+- `GroundCoverageMask` (interface): interface GroundCoverageMask — How far each point of a merged ground footprint lies inside its outer edge, as a grid over world XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+- `GroundCoverageOptions` (interface): interface GroundCoverageOptions — Options for {@link buildGroundCoverageMask}.
+- `GroundEdgeFade` (interface): interface GroundEdgeFade — Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile.
+- `applyGroundEdgeFade` (function): function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M — Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge, opaque `width` metres inside, with a noise-broken line. Seams between layers inside the footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+- `buildGroundCoverageMask` (function): function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null — Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+- `createGroundEdgeFade` (function): function createGroundEdgeFade(): GroundEdgeFade — Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
+
 ## @jgengine/shell/terrain/heightfieldGeometry
 
 - `HeightfieldColorFn` (type): type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void — Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`.

package/skills/jgengine-ui/capabilities.md

@@ -266,6 +266,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `GameContextBridge` (function) · `import { GameContextBridge } from "@jgengine/react"`
 
+## 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"`
+- `buildGroundCoverageMask` (function) · `import { buildGroundCoverageMask } from "@jgengine/shell/terrain"`
+- `createGroundEdgeFade` (function) · `import { createGroundEdgeFade } from "@jgengine/shell/terrain"`
+
 ## heavy-models — models over the per-model triangle budget, for perf probes and smoke assertions
 
 - `heavyModels` (function) · `import { heavyModels } from "@jgengine/shell/render/modelLoad"`
@@ -330,6 +336,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StatBar` (function) · `import { StatBar } from "@jgengine/react"`
 
+## hud-surface — themed panel frame with elevation, header slots, landmark element, and open/close transitions
+
+- `HudSurface` (const) · `import { HudSurface } from "@jgengine/react/hudSurface"`
+
 ## hud-theme — game-authored token object covering bars, frames, slots, chrome, text, status colors, fonts, and rarity
 
 - `HudThemePalette` (interface) · `import { HudThemePalette } from "@jgengine/react"`
@@ -496,7 +506,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
 
-## notice-feed — render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking)
+## notice-feed — render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking, HUD avoidance)
 
 - `NoticeStack` (function) · `import { NoticeStack } from "@jgengine/react/notices"`
 

package/skills/jgengine-ui/reference-primitives.md

@@ -70,7 +70,7 @@ instead of mirroring external entities into `createMarkerSet`.
 
 **Toggleable game windows** are already shipped, not hand-rolled open/close state: `usePanels(defs)` + `<PanelHost>` + `<Window>` (`@jgengine/react`) over the headless `@jgengine/core/ui/panelModel` are THE way to build openable windows — bag (`B`), character (`C`), spellbook, quest log — with keybind toggles, drag-to-move, close buttons, ESC-to-close, and z-stack ordering all handled. Declare each window in `defs` (id, keybind, title), mount one `<PanelHost>`, and render each panel's body inside a `<Window>`; the game owns the body content and skin, the model owns focus/stacking/keybind wiring. Never re-derive window toggling from local `useState` booleans and hand-rolled keydown listeners.
 
-Window title-bar movement belongs to one primary pointer. Release, cancellation, capture loss, blur, and window unmount retire that gesture's listeners; another pointer cannot move it. Controlled positions and panel z-order remain caller-owned. Windows without a `variation` render on `HudPanel` (theme frame plus modal elevation) and rise in on open; `PanelHost` keeps a closed window mounted for its short exit transition, and closing retires any drag in progress. `ModalHost` fades its backdrop and lifts the dialog in, and plays the same exit when the stack empties; `ConfirmDialog` and `PauseMenu` are built from `HudPanel` and `HudButton`.
+Window title-bar movement belongs to one primary pointer. Release, cancellation, capture loss, blur, and window unmount retire that gesture's listeners; another pointer cannot move it. Controlled positions and panel z-order remain caller-owned. Windows without a `variation` render on `HudSurface` (theme frame plus modal elevation) and rise in on open; `PanelHost` keeps a closed window mounted for its short exit transition, and closing retires any drag in progress. `ModalHost` fades its backdrop and lifts the dialog in, and plays the same exit when the stack empties; `ConfirmDialog` and `PauseMenu` are built from `HudSurface` and `HudButton`.
 
 **Character sheet / paperdoll** is already shipped, not hand-rolled: `<CharacterSheet>` / `<Paperdoll>` / `<StatList>` (`@jgengine/react`) compose the paperdoll equip layout (worn `EquipmentSlots` arranged around a portrait) and the derived-stat readout into one window body. `Paperdoll` is the equip-slot arrangement, `StatList` the derived-stat rows, `CharacterSheet` the batteries-included default that pairs them — the game composes and reskins them (slot layout, stat labels/terminology, skin) rather than re-deriving a paperdoll from raw divs and manual stat math.
 

package/skills/jgengine-world/reference.md

@@ -48,8 +48,12 @@ noise-warped edge that fades into the terrain around the authored width; pavemen
 edge with tyre lanes and cracks. Tune with `meta.edgeSoftness` (0 = hard) and `meta.wear` (0..1);
 `meta.surfaceDetail: false` or `<AuthoredScene pathSurfaceDetail={false}>` keeps flat ribbons.
 `road({ surface })` picks the carriageway surface (default `"road"`, `false` for flat colour), and
-city studio ground takes `meta.surfaceDetail: false` on its volume. Custom ribbons use
-`createSurfaceRibbonMaterial` with `ribbonSurfaceFrame` from `@jgengine/shell/terrain`.
+city studio ground takes `meta.surfaceDetail: false` on its volume. City ground layers fade out
+where the district's merged footprint meets bare terrain, keeping seams between layers crisp;
+`meta.edgeFade: false` on the volume keeps hard outer edges. Custom ribbons use
+`createSurfaceRibbonMaterial` with `ribbonSurfaceFrame` from `@jgengine/shell/terrain`; custom
+ground meshes get the same outer-edge fade from `buildGroundCoverageMask`, `createGroundEdgeFade`
+and `applyGroundEdgeFade`.
 
 Custom ground consumers can use `createTerrainPaintColorSampler` from `@jgengine/shell/terrain`
 with a `TerrainPaintSource` (an editable terrain's layer/surface/weight channels). The returned