@jgengine/core 0.22.0 → 0.23.0

package/dist/meta/changelog.js

@@ -1,7 +1,98 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.22.0";
+export const VERSION = "0.23.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "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`.",
+        ],
+        added: [
+            "`player_pose` agent-bridge verb (`@jgengine/shell`, `window.__jgengineAgent`, `drive --rpc '{\"method\":\"player_pose\"}'`) returns the local player's position and heading, and `debug_snapshot` carries the same `player` field, so a drive can prove movement from position deltas instead of screenshots.",
+            "`sim_advance` agent-bridge verb (`@jgengine/shell`, `drive --rpc '{\"method\":\"sim_advance\",\"seconds\":30}'`) steps the mounted sim driver — input, movement, `onTick`, behaviors, bound actions — in 0.05 s frames without rendering, so a headless drive can reach waves, shifts and timers that never arrive at software-rendered frame rates. Capped at 120 s per call.",
+            "`time_scale` agent-bridge verb sets the game clock's timescale and reports `{ timescale, now }`.",
+            "`GameContextObjectEntry.scenery` (`@jgengine/core`): an object kind placed once and left alone. Its runtime placements now render through the shared instanced static-object batches that editor-authored props already used.",
+            "`BUILDING_STYLE_PROBABILITIES` and `resolveBuildingProbabilities` (`@jgengine/core/world/buildings`): each `BuildingStyle` now carries facade-part probabilities, so an industrial yard shows few windows and roof plant, a ruin loses awnings and clotheslines, coastal fronts gain awnings. `building({ probabilities })` overrides any part.",
+            "`debug_summary` agent-bridge verb and `debug_snapshot` `detail: \"summary\"`: fps, frame/sim ms, draw calls, triangles, entities, warnings and top culprit in about 1 KB. `drive --rpc '{\"method\":\"debug_snapshot\"}'` prints the summary; `\"detail\":\"full\"` keeps the full snapshot.",
+            "`modelLoadStarts()` (`@jgengine/shell/render/modelLoad`) counts model streaming bursts for capture quiescence checks.",
+            "`jgengine` warns when it is not the CLI the caller meant: a global install run inside a jgengine checkout, a project-local `jgengine` shadowed, or a CLI built for an older SDK than the project installs. Harness runs print the CLI version and harness revision.",
+            "`withGraphicsQualityOverride` and `parseGraphicsQuality` (`@jgengine/core/settings/graphicsSettings`) pin a graphics tier for one session without persisting it.",
+            "The player shell reads `?quality=<tier>` and pins that tier for the page. `bun run shoot`/`drive --quality draft` use it (low tier, half size) for fast iteration shots; `--quality full` stays the default for PR evidence.",
+            "`jgengine doctor` flags a silent game: one that neither declares `defineGame({ audio })` cues nor calls `ctx.game.audio.play`/`loop`. Four reference games shipped without a single sound; the fix text points at procedural `SoundDef` synth patches, which need no asset files.",
+            "`drive --key mouse0:<ms>` (also `mouse1`, `mouse2`) holds that mouse button over the play canvas, matching the shell's pointer binding codes, so hold-to-fire weapons can be driven headlessly. Keyboard codes are unchanged.",
+            "`drive --right-click-at x,y` sends a native right click in CSS viewport pixels, so RTS move/attack/gather orders and context actions can be driven headlessly; `--click-at` stays a left click.",
+            "`ctx.scene.entity.selection` (`@jgengine/core`): the player's selected entities as a reactive `SelectionSet`. The shell pointer (`pointer.select` click / marquee) now writes it instead of private component state, so game HUDs can show the selected unit's card or a \"3 units selected\" summary and can set the selection themselves (select-all, control groups); the selection ring follows either way. Despawned ids drop out.",
+            "`LightingConfig.iblAmbientScale` (default 0.5) and `LightingConfig.fallbackKey` (default true); `balanceLightingForIbl` in `@jgengine/core/render/lightingBalance` applies them.",
+            "`DirectionalLightingConfig.shadowRadius` (PCF penumbra in texels, default 1.25).",
+            "`DEFAULT_AO` in `@jgengine/core/render/postProcessing` and `mergePostProcessing` in `@jgengine/core/render/lookPreset`.",
+            "Loaded GLB models get a default painted finish: flat-colour, vertex-colour and palette-atlas materials have their exported roughness/metalness/`envMapIntensity` normalized and compile with one shared object-space detail shader (mottling, wear, roughness break-up, micro-normal, cavity). Normal-mapped, cutout and transparent materials are untouched.",
+            "`GraphicsProfile.surfaceDetail` (`\"off\" | \"lite\" | \"full\"`, `@jgengine/core/settings/graphicsProfile`): `\"lite\"` on low, `\"full\"` on medium and up.",
+            "`ModelConfig.surfaceDetail: false` opts one model out; `defineGame({ surfaceDetail: false })` opts a game out.",
+            "`createSurfaceRibbonMaterial`, `ribbonSurfaceFrame`, `resolvePathSurface` and `useSurfaceRibbonMaterial` (`@jgengine/shell/terrain`) shade ground ribbons with the terrain's procedural surface functions, plus wear and a noise-warped soft edge.",
+            "`road({ surface })` (`@jgengine/core/world/features`) picks the carriageway surface; `false` keeps flat colour.",
+            "`AuthoredScene`/`AuthoredPaths` `pathSurfaceDetail`/`surfaceDetail` props and path `meta.surface`, `meta.edgeSoftness`, `meta.wear`, `meta.surfaceDetail`.",
+            "`EditableTerrain.gridBounds` (`@jgengine/core/world/terraform`) exposes the world extent of the paint/height cell grid.",
+            "Painted terrain renders each layer's `surface` as its own procedural ground (grass, dirt, gravel, rock, sand, mud, snow, road) with albedo variation, roughness and micro-normals, blended along noise-warped, height-aware edges, in play and in the editor viewport. No game config or assets needed.",
+            "`TerrainDetailConfig.surfaceStrength` (0..1, default 1) scales the per-surface response; `detail: false` opts a terrain out to the flat vertex-colour ground.",
+            "`@jgengine/shell/terrain` exports `packTerrainPaintWeights`, `createTerrainPaintTextures`, `terrainSurfaceClass`, `createTerrainDetailMaterial` and `TerrainQualityContext`/`useTerrainQuality`.",
+            "`ctx.game.notices` (`@jgengine/core/game/notices`, `createNoticeFeed`): a player-facing notice feed with info/success/warn/deny tones, stacking dedupe (repeats show ×N and refresh their lifetime), a cap, TTL, `onPush`, `retune` and `snapshot`/`restore`. Pure state on the context clock, so headless and hosted runs are unaffected.",
+            "The shell mounts `NoticeStack` (`@jgengine/react/notices`) for every game: animated toned cards below top HUD bars, 14px text on `--jg-*` vars with fallbacks, no pointer capture. Configure with `notices: { placement, hidden, refusals, cues, cap, ttlMs }` or remove with `notices: false`.",
+            "Refusal feedback: `validate` may return `{ reason, message }`. `reason` stays the machine code; a `message` is shown automatically as a deduped deny notice with the deny cue when the local player's command is refused, locally or from a host. `ctx.game.commands` emits a `command.refused` event for every refusal; `attachRefusalNotices` is the headless hookup.",
+            "UI sound cues: `useUiCue()` / `playUiCue` (`@jgengine/react/uiCues`) play `click`, `hover`, `open`, `close`, `confirm`, `deny`, `notify`. Soft procedural defaults (`@jgengine/core/audio/uiCues`) mix on a new \"ui\" bus with a \"UI volume\" setting under master volume. A game sound named `ui.<cue>` replaces one; `audio.uiCues` overrides or silences cues (`false` for all).",
+            "`notice_push` and `run_command` agent-bridge verbs for `drive --rpc`.",
+            "`ui-feedback` dev probe (apps/dev) exercising refusals, the feed and cues.",
+            "`HudTheme` gains a type scale with a 12px floor, spacing, motion (durations and easings), elevation (layered shadows and a lit top rim), and hover/press/focus/disabled state tokens; `hudThemeVars` emits them as `--jg-type-*`, `--jg-space-*`, `--jg-motion-*`, `--jg-ease*`, `--jg-elevation-*`, `--jg-highlight`, `--jg-hover-*`, `--jg-press-*`, `--jg-focus-ring`, and `--jg-disabled-opacity`. `@jgengine/react/hudTokens` reads them in inline styles (`hudType`, `hudSpace`, `hudTransition`, `hudElevation`, `hudFont`, `HUD_FOCUS_RING`).",
+            "Engine stylesheet `@jgengine/react/styles.css` (also `ENGINE_STYLESHEET` / `useEngineStyles` in `@jgengine/react/engineStyles`): every `jg-*` keyframe the shared blocks and registry use, `[data-jg-*]` interaction states, quiet hover/press/focus defaults for plain HUD buttons, and reduced-motion handling for `prefers-reduced-motion` and `[data-reduced-motion=\"true\"]`. The `jgengine create` template imports it.",
+            "`HudThemeRoot`: the shell wraps every `GameUI` in it, applying `defaultHudTheme` and the stylesheet. `defineGame({ hudTheme })` swaps the root theme; `hudTheme: false` opts out.",
+            "Primitives `HudButton`, `HudPanel` (open/close transition via `usePresence`), and `TweenNumber` / `useTweenedValue` with an up/down delta flash; `useReducedMotion` in `@jgengine/react/accessibility`.",
+            "`HudInteractProvider` / `useHudInteract`, plus `cue` and `onInteract` on the primitives, windows, modals, and `ActionButton`: one seam for a UI sound system.",
+        ],
+        changed: [
+            "Static-object batches group same-model props per 64 m cell from 3 placements (was 24 m cells and more than 8), so sparse city dressing such as palms, lamps and benches shares draws. Harbor Heat's opening drops from 5,310 to 4,650 draw calls.",
+            "`building()` districts with a non-generic `style` generate a different facade mix than before (previously a style changed colours only). `generic` is unchanged.",
+            "`bun run shoot/drive` and the scaffolded/bundled `shoot.mjs`/`drive.mjs` parse one shared flag table: `--click-at`, `--right-click-at`, `--width`, `--height`, `--port`, `--size`, `--settle`, `--param`, `--probe`, `--reload`, key chords and mouse holds work in both; unknown flags fail instead of being ignored or taken as a game id; dev-runner-only flags are refused by name in the portable harness.",
+            "Play-mode capture readiness waits until staged `--state`/`--run` commands have ticked, their entities mounted and model streaming stopped, and never declares ready over \"Loading game view…\". A rejected staged command fails the capture.",
+            "Play-mode captures of a game with a start menu and no `capture.play` click its start action and report what they clicked.",
+            "Monorepo tests, type-checks and `bun run gen` resolve `@jgengine/*` to package source through the `paths` in `tsconfig.base.json` (`bun run gen:source-paths` keeps every workspace tsconfig in sync), so a fresh checkout or worktree is testable with no build. Published packages are unchanged: `exports` still point at `dist`, and the built output is byte-identical.",
+            "The export manifest is computed from the files each package's build emits, not from `dist` on disk, so it can no longer drift with a stale or partial build. `bun run ship:preflight` now fails with the fix (`bun run gen`) when any generated artifact is stale.",
+            "`bun run agent:worktree -- <name>` produces a clean, ready worktree locally and in cloud sessions: it links dependencies, `Games` and the dev runner's ignored assets from the main checkout instead of installing and building. `agent:bootstrap` only installs; pass `--build` to also build dist.",
+            "The procedural IBL probe has a zenith/horizon/ground gradient and an HDR sun disc plus a broad lobe, with the horizon leaning toward the ambient colour, at intensity 0.45 (was a 2-colour gradient at 0.35), so forms get a lit and a shaded side from IBL alone.",
+            "Under IBL (every look but `\"flat\"`), authored ambient is halved, and lighting with no directional light gets a soft shadowless key light (intensity 0.6, tinted by the ambient colour).",
+            "A post chain that omits `ao` now runs `DEFAULT_AO` on medium tier and above; `ao: false` still opts out. `NEUTRAL_POST_PROCESSING` no longer sets `ao: false`.",
+            "Styled look presets deep-merge their post stages under a partial game `postProcessing` instead of being dropped whole.",
+            "Shadows use `PCFShadowMap` instead of `PCFSoftShadowMap`, which three r182 compiles as unfiltered basic shadows (stair-stepped edges), with a default radius of 1.25 texels on configured and cascaded lights.",
+            "GTAO samples are tiered: 8 on medium, 12 on high (was 16), 16 on ultra.",
+            "A model `material.rim` override now chains the material's live program cache key instead of a snapshot.",
+            "Authored paths now render as dirt (or their `meta.surface`/kind) with wheel ruts and edges that fade into the terrain, instead of flat-colour ribbons with hard cut edges.",
+            "`road()` carriageways, curbs, sidewalks and welded junctions, and city studio ground (streets, block land, sidewalks, drives, parks), shade with matching procedural asphalt, gravel, concrete and dirt. City volumes opt out with `meta.surfaceDetail: false`.",
+            "Terrain noise and micro-normal GLSL moved to shared exports in `terrainSurfaceShader.ts` so terrain and ribbons compile the same code.",
+            "A terrain without `detail` now renders with default procedural detail instead of flat vertex colour.",
+            "Slope rock no longer fades with `detail.strength`; it follows `surfaceStrength`.",
+            "The textured terrain path's normal map is applied in view space (it was added to the view-space normal as a world-space offset).",
+            "The `low` graphics tier takes a cheap terrain surface path without micro-normals.",
+            "The shell plays UI cues for every engine HUD primitive (`HudButton`, `HudPanel`, `Window`, `ModalHost`, `ActionButton`): activate → `click` (or the primitive's `cue` when it names a cue, e.g. `cue=\"confirm\"`), button/action hover → `hover`, panel open/close → `open`/`close`. Off with `notices: false` or `notices.cues: false`; `audio.uiCues` silences single cues. `uiCueForInteraction` (`@jgengine/react/uiCues`) exposes the mapping.",
+            "`CommandRejection`, `CommandValidationError`, `CommandResult`, `RunCommandResult` and `TransportRunCommandResult` carry an optional `message`; the ws hosts forward it. Results without one are unchanged.",
+            "`defaultHudTheme` is the engine's default look: a system UI font stack led by Inter, layered translucent panels with a lit rim and hairline borders, and gradient slots.",
+            "`Window` / `PanelHost` render on `HudPanel` with enter and exit transitions and a `HudButton` close; `ModalHost` fades its backdrop and lifts its dialog, with an exit; `ConfirmDialog` / `PauseMenu` use `HudPanel` and `HudButton`; `HudFrame` and `ActionButton` read the font, elevation, focus, and motion tokens.",
+            "Text under 12px in `@jgengine/react` and `registry/jgengine` now uses the type scale's `xs` step (12px floor).",
+            "Games on the `rts` and `topDown` camera rigs hear positional sound again. The spatial-audio listener sat at the camera, 35–50 m above the ground, so the default 24 m falloff silenced every ground event even at screen centre; for these rigs it now sits where the camera looks at the ground. Chase, first-person and other rigs keep the camera-anchored listener.",
+            "The bundled `jgengine drive` and `jgengine shoot` harnesses let Chrome pick a free debug port instead of guessing one from the clock, so they no longer attach to another Chrome that holds the same port. An interrupted drive or shoot (SIGINT/SIGTERM) now closes its Chrome instead of leaving it running.",
+            "`jgengine doctor` flags component folders reached through a `tsconfig` path alias (such as a shared `@/components/ui/*` registry) that game code imports but `src/index.css` never scans with `@source`. Their Tailwind classes were silently not generated, so those HUD blocks rendered tiny and unstyled; the fix text names the exact `@source` line to add.",
+            "`jgengine doctor` now flags a 3D game that sets neither a `look` preset nor `postProcessing`; such a game renders the unstyled `\"neutral\"` look with no tone-map grade, AO or bloom. Its fix text no longer claims cinematic is the default. Write `look: \"neutral\"` when unstyled output is deliberate.",
+            "`jgengine create` scaffolds name `look: \"cinematic\"` explicitly, so a new 3D game starts graded instead of on the unstyled default.",
+            "Generated city districts (`@jgengine/shell` `CityRenderer`) fade their developed ground to transparent over its outer 9 m, so it melts into the terrain or authored paint beyond it instead of ending in a hard, stair-stepped green rim.",
+            "City districts (`@jgengine/shell` `CityRenderer`) draw a crossing of gravel lanes as gravel instead of a dark asphalt slab; a crossing that touches any paved street stays asphalt.",
+            "The published CLI and scaffold browser driver restore game keyboard focus before key holds and wait for a rendered frame under the held key. Menu clicks and slow headless rendering no longer silently swallow movement inputs; failed frame sampling releases held keys.",
+            "After a click on a control that then unmounts (a start screen's \"Play\", a menu's last button), `@jgengine/shell` returns focus to the play surface instead of leaving it on `<body>`, so gameplay keys work without an extra click on the canvas.",
+            "`sim_advance` (`@jgengine/shell` agent bridge) yields to the browser every ten simulated seconds, so models for entities spawned mid-advance mount as in play; a 30 s advance through Beacon Bastion's first wave previously left every raider with health bars but no model.",
+            "Generated city districts no longer lay a checkerboard over their ground. The developed-ground fabric drew one flat quad per 2.5 m cell with a per-cell random roll that flipped neighbours between zone bands; it is now one shared-vertex sheet coloured from smooth noise, so yards and lots blend.",
+            "Authored terrain paint (paths, clearings, painted layers) now blends smoothly between neighbouring cells in the runtime ground and the editor sculpt view, instead of snapping each vertex to its 2 m cell and drawing grid-aligned stair-step edges. Unpainted cells blend toward the caller's base ground color, so painted edges fade into the terrain palette.",
+            "A terrain detail `material` no longer overrides the ground's authored roughness with its roughness map. The map now varies roughness around the authored value, so scanned ground maps (roughness near 0.45) stop giving dry terrain a wet specular sheen; games no longer need to lower `material.strength` to stay matte.",
+            "A terrain without a `waterLevel` no longer paints the detail shader's beach sand band. Previously the band defaulted to water at height 0, so any flat terrain near 0 (a park, a meadow) rendered as beach; six reference games set `detail.waterLevel` far below the world only to avoid it. Set `waterLevel` on the terrain or `detail.waterLevel` to keep a shoreline.",
+            "Atomic vitals bars (`HealthBar`, `ManaBar`, … in `@jgengine/react`) cap their frame at a quarter of the bar height, so thin bars (e.g. `height: \"4px\"`) show their fill instead of only the two 2px frame lines.",
+            "Built-in world health bars (`worldHealthBars`, `@jgengine/shell`) span about 1.4 m at the entity's on-screen scale (28–112 px) instead of a fixed 112 px, so top-down and RTS cameras no longer paint bars ten times wider than the units under them.",
+        ],
+        removed: [],
+    },
     "0.22.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.22.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.19.0`; `@jgengine/github` is `0.9.0`.",

package/dist/render/lightingBalance.d.ts

@@ -0,0 +1,13 @@
+import type { DirectionalLightingConfig, LightingConfig } from "../game/playableGame.js";
+/** Ambient multiplier applied under image-based light when `iblAmbientScale` is unset. */
+export declare const DEFAULT_IBL_AMBIENT_SCALE = 0.5;
+/** Soft key added when authored lighting has no directional light: high, off to one side, shadowless. */
+export declare const FALLBACK_KEY_LIGHT: Readonly<DirectionalLightingConfig>;
+/**
+ * Rebalance authored lighting for a scene that also has image-based light: trim the flat ambient term
+ * by `iblAmbientScale` (default 0.5) and, when no directional light is authored, add
+ * {@link FALLBACK_KEY_LIGHT} tinted by the ambient colour so forms keep a lit and a shaded side.
+ * Returns the input unchanged when there is nothing to adjust.
+ * @capability balance-ibl-lighting trim flat ambient under IBL and add a key light to directionless lighting
+ */
+export declare function balanceLightingForIbl(lighting: LightingConfig | undefined): LightingConfig | undefined;

package/dist/render/lightingBalance.js

@@ -0,0 +1,32 @@
+/** Ambient multiplier applied under image-based light when `iblAmbientScale` is unset. */
+export const DEFAULT_IBL_AMBIENT_SCALE = 0.5;
+/** Soft key added when authored lighting has no directional light: high, off to one side, shadowless. */
+export const FALLBACK_KEY_LIGHT = {
+    position: [-22, 40, 16],
+    intensity: 0.6,
+    castShadow: false,
+};
+/**
+ * Rebalance authored lighting for a scene that also has image-based light: trim the flat ambient term
+ * by `iblAmbientScale` (default 0.5) and, when no directional light is authored, add
+ * {@link FALLBACK_KEY_LIGHT} tinted by the ambient colour so forms keep a lit and a shaded side.
+ * Returns the input unchanged when there is nothing to adjust.
+ * @capability balance-ibl-lighting trim flat ambient under IBL and add a key light to directionless lighting
+ */
+export function balanceLightingForIbl(lighting) {
+    if (lighting === undefined)
+        return undefined;
+    const scale = Math.max(0, lighting.iblAmbientScale ?? DEFAULT_IBL_AMBIENT_SCALE);
+    const needsKey = (lighting.directional?.length ?? 0) === 0 && lighting.fallbackKey !== false;
+    const trims = lighting.ambient !== undefined && scale !== 1;
+    if (!needsKey && !trims)
+        return lighting;
+    const next = { ...lighting };
+    if (trims)
+        next.ambient = { ...lighting.ambient, intensity: (lighting.ambient.intensity ?? 0.55) * scale };
+    if (needsKey) {
+        const color = lighting.ambient?.color ?? lighting.hemisphere?.skyColor;
+        next.directional = [color === undefined ? FALLBACK_KEY_LIGHT : { ...FALLBACK_KEY_LIGHT, color }];
+    }
+    return next;
+}

package/dist/render/lookPreset.d.ts

@@ -34,7 +34,7 @@ export interface ResolvedGameLook {
 export declare const CINEMATIC_SKY: SkyEnvironmentConfig;
 /** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
 export declare const CINEMATIC_POST_PROCESSING: PostProcessingConfig;
-/** Unstyled baseline: a stable linear presentation with no genre-specific grading. */
+/** Unstyled baseline: no bloom or grade; contact AO stays at the graphics-tier default. */
 export declare const NEUTRAL_POST_PROCESSING: PostProcessingConfig;
 /** High-contrast physically based presentation for authored HDR environments. */
 export declare const PHOTOREAL_POST_PROCESSING: PostProcessingConfig;
@@ -44,11 +44,20 @@ export declare const TOON_POST_PROCESSING: PostProcessingConfig;
 export declare const COMIC_POST_PROCESSING: PostProcessingConfig;
 /** Chunky pixels and posterized colour with no smoothing — a low-resolution retro look. */
 export declare const RETRO_POST_PROCESSING: PostProcessingConfig;
+/**
+ * Deep-merge a game's partial post chain over a preset's. Every field the game set wins, including
+ * `false` to drop a stage; fields it left unset come from the preset, and stage objects merge field by
+ * field (tuples such as `grade.lift` replace whole).
+ * @capability merge-post-processing layer a partial post chain over a look preset without losing its stages
+ */
+export declare function mergePostProcessing(preset: PostProcessingConfig, authored: PostProcessingConfig | undefined): PostProcessingConfig;
 /**
  * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
  * `"flat"` passes the explicit knobs through untouched.
  * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
  * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
+ * A styled preset's post stages are deep-merged under a partial game `postProcessing`
+ * ({@link mergePostProcessing}); under `"neutral"` a game's own chain is used as authored.
  * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
  */
 export declare function resolveGameLook(input: GameLookInput): ResolvedGameLook;

package/dist/render/lookPreset.js

@@ -9,11 +9,10 @@ export const CINEMATIC_POST_PROCESSING = {
     ao: { intensity: 1.4 },
     grade: {},
 };
-/** Unstyled baseline: a stable linear presentation with no genre-specific grading. */
+/** Unstyled baseline: no bloom or grade; contact AO stays at the graphics-tier default. */
 export const NEUTRAL_POST_PROCESSING = {
     toneMapping: "agx",
     bloom: false,
-    ao: false,
     grade: false,
 };
 /** High-contrast physically based presentation for authored HDR environments. */
@@ -56,11 +55,37 @@ const PRESET_POST = {
     retro: RETRO_POST_PROCESSING,
     cinematic: CINEMATIC_POST_PROCESSING,
 };
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeStage(preset, authored) {
+    if (authored === undefined)
+        return preset;
+    if (!isPlainObject(authored) || !isPlainObject(preset))
+        return authored;
+    const merged = { ...preset };
+    for (const [key, value] of Object.entries(authored))
+        merged[key] = mergeStage(preset[key], value);
+    return merged;
+}
+/**
+ * Deep-merge a game's partial post chain over a preset's. Every field the game set wins, including
+ * `false` to drop a stage; fields it left unset come from the preset, and stage objects merge field by
+ * field (tuples such as `grade.lift` replace whole).
+ * @capability merge-post-processing layer a partial post chain over a look preset without losing its stages
+ */
+export function mergePostProcessing(preset, authored) {
+    if (authored === undefined)
+        return preset;
+    return mergeStage(preset, authored);
+}
 /**
  * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
  * `"flat"` passes the explicit knobs through untouched.
  * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
  * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
+ * A styled preset's post stages are deep-merged under a partial game `postProcessing`
+ * ({@link mergePostProcessing}); under `"neutral"` a game's own chain is used as authored.
  * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
  */
 export function resolveGameLook(input) {
@@ -76,6 +101,6 @@ export function resolveGameLook(input) {
     return {
         lighting: input.lighting,
         backdrop,
-        postProcessing: input.postProcessing ?? PRESET_POST[look],
+        postProcessing: mergePostProcessing(PRESET_POST[look], input.postProcessing),
     };
 }

package/dist/render/postProcessing.d.ts

@@ -109,7 +109,10 @@ export interface PostProcessingConfig {
      */
     aa?: PostAaMode;
     bloom?: BloomConfig | false;
-    /** Ambient occlusion. Heavier than the other stages — omit or `false` on low-end targets. Default off (omitted). */
+    /**
+     * Ambient occlusion (contact shading). Omitted runs {@link DEFAULT_AO} on graphics tiers whose
+     * `postStages.ao` is on (medium and up); `false` turns it off everywhere.
+     */
     ao?: AoConfig | false;
     /** Depth-of-field / bokeh. Heavier stage — omit or `false` to skip. Default off (omitted). */
     dof?: DofConfig | false;
@@ -117,6 +120,8 @@ export interface PostProcessingConfig {
     /** Art-style stage: outlines, cel bands, pixelation. Default off (omitted). */
     stylize?: StylizeConfig | false;
 }
+/** Contact shading used when a post chain leaves `ao` unset: soft creases, no dark halos. */
+export declare const DEFAULT_AO: Readonly<AoConfig>;
 /**
  * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film
  * grade with vignette + a touch of grain + chromatic aberration). Meant for a `StudioStage` where a

package/dist/render/postProcessing.js

@@ -1,3 +1,5 @@
+/** Contact shading used when a post chain leaves `ao` unset: soft creases, no dark halos. */
+export const DEFAULT_AO = { radius: 1.3, intensity: 1.3, distanceFalloff: 2.8, blend: 1 };
 /**
  * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film
  * grade with vignette + a touch of grain + chromatic aberration). Meant for a `StudioStage` where a

package/dist/runtime/commandDispatch.js

@@ -13,7 +13,14 @@ export function dispatchCommand(ctx, name, input) {
     const serverId = route.serverId();
     if (serverId === null)
         return { status: "rejected", reason: "not-joined" };
-    return route.transport.runCommand({ serverId, command: name, input }).then((result) => result.ok
-        ? { status: "applied", state: ctx }
-        : { status: "rejected", reason: result.reason }, (error) => ({ status: "rejected", reason: error instanceof Error ? error.message : "Command transport failed" }));
+    return route.transport.runCommand({ serverId, command: name, input }).then((result) => {
+        if (result.ok)
+            return { status: "applied", state: ctx };
+        ctx.game.events.emit("command.refused", result.message === undefined
+            ? { command: name, reason: result.reason, actor: null }
+            : { command: name, reason: result.reason, message: result.message, actor: null });
+        return result.message === undefined
+            ? { status: "rejected", reason: result.reason }
+            : { status: "rejected", reason: result.reason, message: result.message };
+    }, (error) => ({ status: "rejected", reason: error instanceof Error ? error.message : "Command transport failed" }));
 }

package/dist/runtime/commandRunner.d.ts

@@ -1,5 +1,7 @@
+/** `reason` is a stable machine code; `message`, when set, is player-facing text the client shows on refusal. */
 export type CommandValidationError = {
     reason: string;
+    message?: string;
 };
 /**
  * Which slice of a server has to be hydrated before some work runs against it. Both fields default to
@@ -71,6 +73,7 @@ export type RunCommandResult = {
 } | {
     ok: false;
     reason: string;
+    message?: string;
 };
 /** @internal */
 export declare function runCommand<TInput>(snapshot: import("./snapshot.js").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string, nowMs?: number): RunCommandResult;

package/dist/runtime/commandRunner.js

@@ -64,7 +64,9 @@ export function runCommand(snapshot, commands, commandName, input, actorUserId,
     }
     const validationError = command.validate(snapshot, parsed, actorUserId, nowMs);
     if (validationError) {
-        return { ok: false, reason: validationError.reason };
+        return validationError.message === undefined
+            ? { ok: false, reason: validationError.reason }
+            : { ok: false, reason: validationError.reason, message: validationError.message };
     }
     const next = command.apply(snapshot, parsed, actorUserId, nowMs);
     return {

package/dist/runtime/context/scene.d.ts

@@ -9,6 +9,7 @@ import { type CollisionMeshSource } from "../../scene/collisionMesh.js";
 import { type ObjectStore } from "../../scene/objectStore.js";
 import type { InventorySet, ItemTraits } from "../../inventory/inventoryModel.js";
 import { type PaintLayer } from "../../scene/paintLayer.js";
+import { type SelectionSet } from "../../scene/selection.js";
 import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
 import { type SpatialApi } from "../../scene/spatial.js";
 import { type Targeting } from "../../scene/targeting.js";
@@ -31,6 +32,8 @@ export interface SceneSubsystemDeps {
 /** @internal Always-on scene surface: entities, objects, colliders, spatial, raycast, targeting. */
 export interface SceneSubsystem {
     entities: EntityStore;
+    /** The player's selected entities, exposed as `ctx.scene.entity.selection`. */
+    entitySelection: SelectionSet;
     objects: ObjectStore;
     statsByInstance: Map<string, StatValueMap>;
     entityStats: EntityStatsApi;

package/dist/runtime/context/scene.js

@@ -28,6 +28,9 @@ export function createSceneSubsystem(d) {
     });
     const objects = createObjectStore();
     entities.subscribe(signalNotify);
+    // The player's selected entities (RTS units, picked actors): written by the shell pointer, readable
+    // by game HUDs; mutations notify like every ctx surface, and a despawned id leaves the selection.
+    const entitySelection = notifyAfter(createSelectionSet(), ["add", "remove", "toggle", "replace", "clear"], signalNotify);
     objects.subscribe(signalNotify);
     const statsByInstance = new Map();
     const entityStats = notifyAfter(createEntityStatsApi((instanceId) => statsByInstance.get(instanceId)), ["set", "delta"], signalNotify);
@@ -271,6 +274,8 @@ export function createSceneSubsystem(d) {
     }
     function despawnEntity(instanceId) {
         const existed = entities.despawn(instanceId);
+        if (entitySelection.has(instanceId))
+            entitySelection.remove(instanceId);
         statsByInstance.delete(instanceId);
         targeting.clearAll(instanceId);
         entityColliders.delete(instanceId);
@@ -355,6 +360,7 @@ export function createSceneSubsystem(d) {
     };
     return {
         entities,
+        entitySelection,
         objects,
         statsByInstance,
         entityStats,

package/dist/runtime/gameContext.js

@@ -1,5 +1,6 @@
 import { createAuthoredSimulation } from "../world/authoredSimulation.js";
 import { createCommandRegistry } from "../commands/commandRegistry.js";
+import { createNoticeFeed } from "../game/notices.js";
 import {} from "../game/cosmetics.js";
 import { groundFieldFor } from "../world/terrain.js";
 import { createWorldSolids, structureSolids } from "../world/worldSolids.js";
@@ -99,6 +100,14 @@ export function createGameContext(options) {
         return rawSocial;
     };
     const commandRegistry = createCommandRegistry();
+    const announceRefusal = (command, result, actor) => {
+        if (result.status !== "rejected")
+            return;
+        events.emit("command.refused", result.message === undefined
+            ? { command, reason: result.reason, actor }
+            : { command, reason: result.reason, message: result.message, actor });
+    };
+    const notices = createNoticeFeed({ now });
     if (definition.lifecycle !== undefined) {
         const lifecycle = definition.lifecycle;
         commandRegistry.define(lifecycle.commands?.start ?? "start", {
@@ -395,6 +404,7 @@ export function createGameContext(options) {
                 list: entities.list,
                 ids: entities.ids,
                 subscribeMembership: entities.subscribeMembership,
+                selection: scene.entitySelection,
                 subscribeBehaviors: entities.subscribeBehaviors,
                 spawnPoseOf: entities.spawnPoseOf,
                 resetToSpawn: entities.resetToSpawn,
@@ -466,6 +476,7 @@ export function createGameContext(options) {
                 run(name, input) {
                     const result = commandRegistry.run(ctx, name, input);
                     signal.notify();
+                    announceRefusal(name, result, null);
                     return result;
                 },
                 runAs(actorUserId, name, input) {
@@ -474,6 +485,7 @@ export function createGameContext(options) {
                     try {
                         const result = commandRegistry.run(ctx, name, input);
                         signal.notify();
+                        announceRefusal(name, result, actorUserId);
                         return result;
                     }
                     finally {
@@ -483,6 +495,7 @@ export function createGameContext(options) {
                 actor: () => actingUserId,
             },
             events,
+            notices,
             playEntityAnimation: (instanceId, event) => events.emit("entity.animation", { instanceId, event }),
             audio: {
                 play: (sound, at) => events.emit("audio.play", at === undefined ? { sound } : { sound, at }),

package/dist/runtime/gameContextTypes.d.ts

@@ -1,5 +1,6 @@
 import type { AuthoredSimulationRuntime } from "../world/authoredSimulation.js";
 import type { Territory } from "../world/territory.js";
+import type { NoticeFeed } from "../game/notices.js";
 import type { CurrencyDefinition } from "../economy/currency.js";
 import type { CardPile, CardPileConfig } from "../cards/cardPile.js";
 import type { EffectInput, EffectResult, EffectVia, ReceiveMap, SingleTargetEffectInput } from "../combat/effects.js";
@@ -104,6 +105,12 @@ export interface GameContextObjectEntry {
     verbs?: readonly ContextVerb[];
     colliders?: EntityColliderSet;
     halfExtents?: readonly [number, number, number];
+    /**
+     * Placed once and left alone (trees, lamps, benches, buildings): runtime placements of this kind
+     * render through shared instanced draws like editor-authored props. Leave unset for objects that
+     * spawn and despawn often, where regrouping would rebuild instance buffers.
+     */
+    scenery?: boolean;
 }
 export interface GameContextContent {
     itemById?(itemId: string): GameContextItemEntry | null | undefined;
@@ -282,6 +289,13 @@ export interface SceneEntityContext {
     vfxInstance: VfxInstanceStore;
     telegraph(input: TelegraphInput): () => void;
     hitReaction(input: HitReactionInput): HitReaction | null;
+    /**
+     * The player's selected entities — the RTS selection the shell pointer writes (`pointer.select`
+     * click / marquee) and the order command receives. Game HUDs read it to show the selected unit's
+     * card or a "3 units selected" summary, and may write it (select-all buttons, control groups).
+     * Mutations bump `ctx.version()`/notify `ctx.subscribe`; despawned ids drop out.
+     */
+    selection: SelectionSet;
     setTarget(fromId: string, toId: string | null): void;
     getTarget(fromId: string): string | null;
     cycleTarget(fromId: string, options?: CycleTargetOptions): string | null;
@@ -480,6 +494,11 @@ export interface GameContext {
         territory?: Territory;
         commands: GameContextCommands;
         events: GameEvents;
+        /**
+         * Player-facing notice feed (info/success/warn/deny) with stacking dedupe and TTL. The shell renders it
+         * and plays a UI cue per push; refused commands that return `{ reason, message }` land here automatically.
+         */
+        notices: NoticeFeed;
         audio: GameAudio;
         /** Play a model's one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an attack swing) — emits `entity.animation` for the shell to pick up. */
         playEntityAnimation(instanceId: string, event: string): void;

package/dist/runtime/transport.d.ts

@@ -40,9 +40,12 @@ export type RunCommandArgs = {
 };
 export type TransportRunCommandResult = {
     ok: true;
-} | {
+}
+/** `message` is the command's player-facing refusal text, when its `validate` gave one. */
+ | {
     ok: false;
     reason: string;
+    message?: string;
 };
 export type GameRuntimeServerView = {
     serverId: string;

package/dist/settings/graphicsProfile.d.ts

@@ -1,4 +1,9 @@
 import type { GraphicsQuality } from "./settingsModel.js";
+/**
+ * Procedural surface detail on loaded models: `"full"` adds mottling, wear, roughness break-up, a
+ * micro-normal and cavity shading; `"lite"` drops the micro-normal; `"off"` compiles the plain material.
+ */
+export type SurfaceDetailLevel = "off" | "lite" | "full";
 /** Serializable renderer budget selected by the player's graphics tier. */
 export interface GraphicsProfile {
     renderScale: number;
@@ -14,6 +19,8 @@ export interface GraphicsProfile {
         dof: boolean;
         smaa: boolean;
     };
+    /** Default painted-surface shader on loaded models. */
+    surfaceDetail: SurfaceDetailLevel;
 }
 /** Conservative defaults that preserve the existing high-quality shell behavior. */
 export declare const DEFAULT_GRAPHICS_PROFILES: Record<GraphicsQuality, GraphicsProfile>;

package/dist/settings/graphicsProfile.js

@@ -8,6 +8,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 128,
         anisotropy: 2,
         postStages: { ao: false, bloom: true, dof: false, smaa: true },
+        surfaceDetail: "lite",
     },
     medium: {
         renderScale: 1.5,
@@ -17,6 +18,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 256,
         anisotropy: 4,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
+        surfaceDetail: "full",
     },
     high: {
         renderScale: 2,
@@ -26,6 +28,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 512,
         anisotropy: 8,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
+        surfaceDetail: "full",
     },
     ultra: {
         renderScale: 2,
@@ -35,6 +38,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         particleCap: 1024,
         anisotropy: 16,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
+        surfaceDetail: "full",
     },
 };
 /** Resolve one tier and apply game-authored field and post-stage overrides. */

package/dist/settings/graphicsSettings.d.ts

@@ -38,3 +38,12 @@ export declare function readGraphicsSettings(store: Pick<SettingsStore, "get">,
  * resets the individual overrides instead of leaving stale toggles behind.
  */
 export declare function applyGraphicsQuality(store: Pick<SettingsStore, "set">, quality: GraphicsQuality, overrides?: GraphicsProfileOverrides): GraphicsProfile;
+/**
+ * Wrap a settings store so the graphics tier reads as `quality` for this session only: every
+ * graphics field resolves from that tier until the player changes it, and nothing is persisted.
+ * Capture hosts use it (`?quality=low`) to render cheap iteration shots without leaving the
+ * draft tier in the browser profile for the next full-quality shot.
+ */
+export declare function withGraphicsQualityOverride(store: SettingsStore, quality: GraphicsQuality, overrides?: GraphicsProfileOverrides): SettingsStore;
+/** Parse a `?quality=` value into a graphics tier, or null when absent or unknown. */
+export declare function parseGraphicsQuality(raw: string | null | undefined): GraphicsQuality | null;

package/dist/settings/graphicsSettings.js

@@ -79,3 +79,32 @@ export function applyGraphicsQuality(store, quality, overrides) {
     }
     return tier;
 }
+/**
+ * Wrap a settings store so the graphics tier reads as `quality` for this session only: every
+ * graphics field resolves from that tier until the player changes it, and nothing is persisted.
+ * Capture hosts use it (`?quality=low`) to render cheap iteration shots without leaving the
+ * draft tier in the browser profile for the next full-quality shot.
+ */
+export function withGraphicsQualityOverride(store, quality, overrides) {
+    const tier = resolveGraphicsProfile(quality, overrides?.[quality]);
+    const pinned = new Map([
+        [SETTING_IDS.graphicsQuality, quality],
+        [SETTING_IDS.graphicsRenderScale, tier.renderScale],
+        [SETTING_IDS.graphicsAnisotropy, String(tier.anisotropy)],
+        ...GRAPHICS_POST_STAGES.map((stage) => [graphicsPostStageSettingId(stage), tier.postStages[stage]]),
+    ]);
+    return {
+        get(id, fallback) {
+            return pinned.has(id) ? pinned.get(id) : store.get(id, fallback);
+        },
+        set(id, value) {
+            pinned.delete(id);
+            store.set(id, value);
+        },
+        subscribe: store.subscribe,
+    };
+}
+/** Parse a `?quality=` value into a graphics tier, or null when absent or unknown. */
+export function parseGraphicsQuality(raw) {
+    return isGraphicsQuality(raw) ? raw : null;
+}

package/dist/world/buildings.d.ts

@@ -140,6 +140,13 @@ export declare function resolveBuildingSurface(surface: BuildingSurface): Buildi
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, Record<BuildingPartKind, string>>;
+/**
+ * Facade part probabilities per style, so an industrial yard, a ruined block and a coastal strip
+ * differ in shape as well as colour. Unset parts keep the generic probabilities.
+ */
+export declare const BUILDING_STYLE_PROBABILITIES: Record<BuildingStyle, Partial<BuildingProbabilities>>;
+/** Style facade probabilities with explicit overrides applied on top. */
+export declare function resolveBuildingProbabilities(style?: BuildingStyle, overrides?: Partial<BuildingProbabilities>): Partial<BuildingProbabilities>;
 /**
  * Per-style facade-tone family: the wall colours a district spreads across its buildings so
  * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's