@jgengine/core 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/game/notices.d.ts

@@ -10,6 +10,8 @@ export interface NoticeInput {
     key?: string;
     /** Lifetime in ms. Defaults to the feed's `ttlMs`, or `denyTtlMs` for deny. */
     ttlMs?: number;
+    /** Skip this push's sound cue (the notice still shows). Default false. */
+    silent?: boolean;
 }
 /** A live notice as the HUD renders it. */
 export interface Notice {
@@ -22,6 +24,8 @@ export interface Notice {
     /** Clock time (ms) of the latest push. */
     at: number;
     expiresAt: number;
+    /** Set when the latest push asked for no sound cue. */
+    silent?: true;
 }
 /** Plain JSON state of a {@link NoticeFeed}. */
 export interface NoticeFeedState {

package/dist/game/notices.js

@@ -33,18 +33,19 @@ export function createNoticeFeed(config = {}) {
             const key = input.key ?? `${tone}:${input.text}`;
             const time = now();
             const life = input.ttlMs ?? (tone === "deny" ? denyTtlMs : ttlMs);
+            const quiet = input.silent === true ? { silent: true } : {};
             const live = prunedAt(time);
             const index = live.findIndex((notice) => notice.key === key);
             let notice;
             if (index >= 0) {
-                const previous = live[index];
-                notice = { ...previous, text: input.text, tone, count: previous.count + 1, at: time, expiresAt: time + life };
+                const { silent: _previousSilent, ...previous } = live[index];
+                notice = { ...previous, text: input.text, tone, count: previous.count + 1, at: time, expiresAt: time + life, ...quiet };
                 const next = [...live];
                 next[index] = notice;
                 set(next);
             }
             else {
-                notice = { id: `notice-${counter}`, text: input.text, tone, key, count: 1, at: time, expiresAt: time + life };
+                notice = { id: `notice-${counter}`, text: input.text, tone, key, count: 1, at: time, expiresAt: time + life, ...quiet };
                 counter += 1;
                 const next = [...live, notice];
                 set(cap > 0 && next.length > cap ? next.slice(next.length - cap) : next);

package/dist/game/playableGame.d.ts

@@ -35,11 +35,17 @@ import type { RarityStyle } from "./worldItem.js";
 export interface NoticePresentationConfig extends NoticeFeedConfig {
     /** Screen band for the feed. "top" sits below top-edge HUD bars, "center" over the play area, "bottom" above action bars. Default "top". */
     placement?: "top" | "center" | "bottom";
+    /** Distance from the band's screen edge (px or a CSS length), added to the device safe-area inset. Default `clamp(64px, 14%, 150px)` for top, `clamp(120px, 22%, 230px)` for bottom, 34% for center. */
+    offset?: number | string;
+    /** Move the top/bottom stack clear of HUD panels and touch controls registered in its column. Default true. */
+    avoidHud?: boolean;
+    /** Stacking order. Default 85, above `ModalHost` (80) and `PanelHost` (40), so notices stay readable over pause screens. */
+    zIndex?: number;
     /** Keep the feed and cues but render nothing (the game draws `ctx.game.notices` itself). Default false. */
     hidden?: boolean;
     /** Show refused commands' `message` as deny notices. Default true. */
     refusals?: boolean;
-    /** Play a UI cue per new notice (deny → deny, success → confirm, else notify). Default true. */
+    /** Play a UI cue per new notice (deny → deny, success → confirm, else notify); a push with `silent: true` skips its own. Independent of the HUD control sounds (`audio.hudCues`). Default true. */
     cues?: boolean;
 }
 export type { CameraFollowState, CameraKeyframe, CameraProjection, CameraRigKind, CameraWeaponView, CameraShakeConfig, ChaseCameraConfig, ChaseView, CinematicCameraConfig, FirstPersonCameraConfig, GameCameraConfig, InspectionCameraConfig, InspectionZoomAnchor, LockOnCameraConfig, ObserverCameraConfig, PlayerFovConfig, RtsCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig, TurntableCameraConfig, } from "./cameraConfig.js";
@@ -708,6 +714,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         buses?: Record<string, AudioBusDef>;
         music?: Record<string, MusicTheme>;
         musicBus?: string;
+        /** Play UI cues for engine HUD controls (`HudButton` click/hover, `HudSurface` and window open/close, action slots). Independent of notice sounds (`notices.cues`). Default true. */
+        hudCues?: boolean;
         /** Default UI cues (`ui.click`, `ui.deny`, ...) on a "ui" bus. A sound named `ui.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
         uiCues?: UiCueOverrides;
     };

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.23.0";
+export declare const VERSION = "0.25.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,41 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.23.0";
+export const VERSION = "0.25.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "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).",
+            "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.",
+        ],
+        removed: [],
+    },
+    "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.",
+        ],
+        removed: [],
+    },
     "0.23.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.23.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.20.0`; `@jgengine/github` is `0.10.0`.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

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-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