@jgengine/core 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -10,7 +10,53 @@ let consumers pick up the better stuff, not just to list what moved.
 Agents building on the published SDK can also read this programmatically:
 `import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
 same data as typed values, so an updater can diff its installed version against
-the latest and surface the migration steps.
+the latest and surface the migration steps. Easier still: `npx jgengine upgrade`
+run inside a game project diffs the installed `@jgengine/*` versions against the
+latest release and prints every Migrate step and Adopt-worthy addition in
+between (`--json` for structured output).
+
+## [Unreleased]
+
+<!--
+Every PR that changes `packages/*/src` records its consumer-facing change here, so
+the next release's notes are complete by construction. Add a bullet under the right
+subhead below. `bun run check-changelog` fails a source PR whose `[Unreleased]` block
+is untouched; pure refactors/tests bypass with `[skip changelog]` in a commit message.
+At publish, rename this heading to the new version and mirror the entries into
+`packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
+-->
+
+### Migrate
+
+- _Nothing yet._
+
+### Added
+
+### Changed
+
+### Removed
+
+## 0.14.0
+
+### Migrate
+
+- **Nothing required** — this release is additive drop-in primitives, editor authoring, CLI discovery, and fixes. Bump `@jgengine/*` pins to `^0.14.0` (CLI `jgengine` is 0.11.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- One behavior fix to know about: in a `rig: "chase"` game, on-foot movement and aim are now camera-relative (the chase rig reports its yaw to the shell like every other rig). If a game somehow relied on world-yaw-0 movement under a chase camera, that was the bug this fixes.
+
+### Added
+
+- One authoring gesture for scatterable coverage: `@jgengine/core/world/scatterCoverage` owns shared density/budget semantics (per-kind unit, requested→count→capped, one clamp-and-warn phrasing) for `grass_field`/`scatter`/`city`; the editor inspector leads each kind with the same Area → Assets → Density coverage section, scatter truncates to the shared 250k instance budget, and city single-sources its 2,600-lot cap.
+- **Created games ship a drive/playtest script** (#1248) — `npx jgengine create` scaffolds now include `scripts/drive.mjs` (`bun run drive`): dependency-free headless play/testing of the running game — ordered `--click`/`--key`/`--wait`/`--shot`/`--rpc` steps against the agent bridge, plus `--playtest --strict` progress/softlock verdicts off `capture.probe`. Shared Chrome/CDP machinery lives in `scripts/browser.mjs`; `scripts/shoot.mjs` is unchanged in behavior, now a thin CLI over it.
+- Editor: viewport clip preview for rigged assets (Animation dock "Clips" mode — pick a rig or placed instance, play/scrub/loop/speed any catalog clip) and an Inspector "Animation" section that authors a placement's `ModelConfig.animation` (role→clip dropdowns, auto/none, walk/run/fade, one-shot event bindings) as undoable `marker.meta.animation` edits. New subpaths: `@jgengine/editor/shell/clipPreview`, `@jgengine/editor/modelAnimationAuthoring`, `@jgengine/editor/ClipPreviewLayer`.
+- **`npx jgengine find <intent>`** — active capability discovery: searches every shipped domain's `capabilities.md` (staged inside the CLI tarball, so it works regardless of which `@jgengine/*` packages a project installed) and prints the drop-in primitive + its import for an intent like `"toggleable window"`, `inventory`, or `minimap`. Scaffolded games are now briefed (in `AGENTS.md` and the `jgengine` intake skill) to reach for it before hand-rolling a HUD/inventory/window/rig.
+- **`EntityPreview`** (`@jgengine/shell/render/EntityPreview`) — drop-in live 3D entity portrait for character screens, unit inspectors, and loadout viewers. Owns the nested `<Canvas>`, the `GameContextBridge`, and a `StudioStage` lighting rig with optional turntable / face-camera; the game passes its own `renderEntity` as children (or a native `model` + `instanceId`) and, bound to a live entity, the portrait walks/flinches/topples in sync with the world.
+- **`GameContextBridge`** (`@jgengine/react`) — re-provide the running `GameContext` across a nested React reconciler boundary (the R3F `<Canvas>`), so a game building its own preview canvas no longer re-derives the bridge by hand.
+
+### Changed
+
+- **Chase rig reports its yaw to the shell** — `ChaseRig` now writes the camera yaw back to the shared yaw ref like every other player-facing rig, so on-foot movement and aim in a `rig: "chase"` game are camera-relative instead of frozen to world yaw 0 (WASD no longer fights the camera the moment it swings behind the player). Interior views (cockpit/hood/rear) report the vehicle heading.
+- **Combat VFX no longer render as black squares under AO/DOF post-processing** (#1247) — GTAO/Bokeh scene prepasses skip overlay effects. Games with custom additive overlay effects opt out the same way: spread `POSTFX_OVERLAY_USERDATA` (`@jgengine/shell/postfx/postfxOverlay`) onto the overlay group's `userData`.
+- **`PanelHost` windows stack above the HUD by default** (`@jgengine/react`) — the host establishes its own stacking context at `zIndexBase` (default 40), so open windows always paint over stat bars / nameplates / frames instead of bleeding through. Overridable per instance.
 
 ## 0.13.0
 

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.13.0";
+export declare const VERSION = "0.14.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,27 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.13.0";
+export const VERSION = "0.14.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.14.0": {
+        migrate: [
+            "Bump lockstep SDK packages to ^0.14.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine is 0.11.0; @jgengine/github is unchanged at 0.1.0.",
+            "Nothing required — additive drop-in primitives, editor authoring, CLI discovery, and fixes. One behavior fix: in a rig: \"chase\" game, on-foot movement and aim are now camera-relative (the chase rig reports its yaw to the shell like every other rig).",
+        ],
+        added: [
+            "One authoring gesture for scatterable coverage — @jgengine/core/world/scatterCoverage owns shared density/budget semantics (per-kind unit, requested→count→capped, one clamp-and-warn phrasing) for grass_field/scatter/city; the editor inspector leads each kind with the same Area → Assets → Density coverage section.",
+            "Created games ship a drive/playtest script (#1248) — npx jgengine create scaffolds include scripts/drive.mjs (bun run drive): dependency-free headless play/testing via ordered --click/--key/--wait/--shot/--rpc steps against the agent bridge, plus --playtest --strict verdicts off capture.probe.",
+            "Editor viewport clip preview for rigged assets (Animation dock Clips mode) and an Inspector Animation section authoring a placement's ModelConfig.animation as undoable marker.meta.animation edits. New subpaths: @jgengine/editor/shell/clipPreview, @jgengine/editor/modelAnimationAuthoring, @jgengine/editor/ClipPreviewLayer.",
+            "npx jgengine find <intent> — active capability discovery: searches every shipped domain's capabilities.md and prints the drop-in primitive + its import for an intent like \"toggleable window\", inventory, or minimap.",
+            "EntityPreview (@jgengine/shell/render/EntityPreview) — drop-in live 3D entity portrait for character screens, unit inspectors, and loadout viewers; owns the nested Canvas, GameContextBridge, and a StudioStage lighting rig with optional turntable / face-camera.",
+            "GameContextBridge (@jgengine/react) — re-provide the running GameContext across a nested React reconciler boundary (the R3F Canvas).",
+        ],
+        changed: [
+            "Chase rig reports its yaw to the shell — on-foot movement and aim in a rig: \"chase\" game are camera-relative instead of frozen to world yaw 0; interior views (cockpit/hood/rear) report the vehicle heading.",
+            "Combat VFX no longer render as black squares under AO/DOF post-processing (#1247) — GTAO/Bokeh scene prepasses skip overlay effects; custom additive overlays opt out by spreading POSTFX_OVERLAY_USERDATA (@jgengine/shell/postfx/postfxOverlay) onto the overlay group's userData.",
+            "PanelHost windows stack above the HUD by default (@jgengine/react) — the host establishes its own stacking context at zIndexBase (default 40), overridable per instance.",
+        ],
+        removed: [],
+    },
     "0.13.0": {
         migrate: [
             "Bump lockstep SDK packages to ^0.13.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine is 0.10.0; @jgengine/github is unchanged.",

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

@@ -5,6 +5,7 @@ import { type EntityStatsApi, type StatValueMap } from "../../scene/entityStats.
 import { type EntityPosition, type EntityStore, type SceneEntity, type SpawnOptions } from "../../scene/entityStore.js";
 import { type Forms } from "../../scene/form.js";
 import { type EntityColliderSet, type MeasuredBounds } from "../../scene/colliders.js";
+import { type CollisionMeshSource } from "../../scene/collisionMesh.js";
 import { type ObjectStore } from "../../scene/objectStore.js";
 import { type PaintLayer } from "../../scene/paintLayer.js";
 import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
@@ -42,6 +43,7 @@ export interface SceneSubsystem {
     entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
     objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
     reportEntityBounds: (kind: string, bounds: MeasuredBounds | null) => boolean;
+    reportEntityCollisionMesh: (kind: string, mesh: CollisionMeshSource | null) => boolean;
     entityVisualScaleOf: (instanceId: string) => number;
     forms: Forms;
     paintLayer: PaintLayer;

package/dist/runtime/context/scene.js

@@ -2,7 +2,8 @@ import { createBodyBind } from "../../scene/bodyBind.js";
 import { createEntityStatsApi, seedStatValues, } from "../../scene/entityStats.js";
 import { createEntityStore, } from "../../scene/entityStore.js";
 import { createForms } from "../../scene/form.js";
-import { fittedEntityColliders, fittedObjectColliders, measuredEntityColliders, measuredObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { fittedEntityColliders, fittedObjectColliders, hasMeshColliderShape, measuredEntityColliders, measuredObjectColliders, meshEntityColliders, meshObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { prepareCollisionMeshSource } from "../../scene/collisionMesh.js";
 import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
 import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
 import { createPaintLayer } from "../../scene/paintLayer.js";
@@ -98,6 +99,38 @@ export function createSceneSubsystem(d) {
         signalNotify();
         return true;
     }
+    const meshEntityByKind = new Map();
+    const meshObjectByCatalogId = new Map();
+    function reportEntityCollisionMesh(kind, mesh) {
+        if (mesh === null) {
+            const existed = meshEntityByKind.delete(kind);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const prepared = prepareCollisionMeshSource(mesh);
+        const set = prepared === null ? null : meshEntityColliders(prepared);
+        if (set === null)
+            return false;
+        meshEntityByKind.set(kind, set);
+        signalNotify();
+        return true;
+    }
+    function reportObjectCollisionMesh(catalogId, mesh) {
+        if (mesh === null) {
+            const existed = meshObjectByCatalogId.delete(catalogId);
+            if (existed)
+                signalNotify();
+            return existed;
+        }
+        const prepared = prepareCollisionMeshSource(mesh);
+        const set = prepared === null ? null : meshObjectColliders(prepared);
+        if (set === null)
+            return false;
+        meshObjectByCatalogId.set(catalogId, set);
+        signalNotify();
+        return true;
+    }
     function reportObjectBounds(catalogId, bounds) {
         if (bounds === null) {
             const existed = measuredObjectByCatalogId.delete(catalogId);
@@ -122,6 +155,13 @@ export function createSceneSubsystem(d) {
         const kind = entities.get(instanceId)?.name;
         if (kind !== undefined) {
             const fitted = fittedEntitySetFor(kind);
+            // Index-derived mesh shapes win (identical on a headless host); otherwise a runtime-reported
+            // collision mesh upgrades the fitted/measured bounding box to the rendered triangles.
+            if (fitted !== null && hasMeshColliderShape(fitted))
+                return fitted;
+            const runtimeMesh = meshEntityByKind.get(kind);
+            if (runtimeMesh !== undefined)
+                return runtimeMesh;
             if (fitted !== null)
                 return fitted;
             const measured = measuredEntityByKind.get(kind);
@@ -149,6 +189,11 @@ export function createSceneSubsystem(d) {
         if (object === null)
             return null;
         const fitted = fittedObjectSetFor(object.catalogId);
+        if (fitted !== null && hasMeshColliderShape(fitted))
+            return fitted;
+        const runtimeMesh = meshObjectByCatalogId.get(object.catalogId);
+        if (runtimeMesh !== undefined)
+            return runtimeMesh;
         if (fitted !== null)
             return fitted;
         const measured = measuredObjectByCatalogId.get(object.catalogId);
@@ -291,6 +336,7 @@ export function createSceneSubsystem(d) {
         },
         collidersOf: objectCollidersOf,
         reportBounds: reportObjectBounds,
+        reportCollisionMesh: reportObjectCollisionMesh,
         selection: objectSelection,
     };
     return {
@@ -310,6 +356,7 @@ export function createSceneSubsystem(d) {
         entityCollidersOf,
         objectCollidersOf,
         reportEntityBounds,
+        reportEntityCollisionMesh,
         entityVisualScaleOf,
         forms,
         paintLayer,

package/dist/runtime/gameContext.js

@@ -56,7 +56,7 @@ export function createGameContext(options) {
         ...(occluder !== undefined ? { occluder } : {}),
         ...(options.models !== undefined ? { models: options.models } : {}),
     });
-    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
+    const { entities, objects, statsByInstance, entityStats, ensureInstanceStats, catalogEntry, spatial, combatSpatial, sceneRaycast, targeting, entityColliders, entityCollidersOf, objectCollidersOf, reportEntityBounds, reportEntityCollisionMesh, entityVisualScaleOf, forms, paintLayer, spawnEntity, despawnEntity, moveEntityTowardCommit, resetAllToSpawn, bind, sceneObjects, } = scene;
     // --- Shared game services (weapon, feed, features bag, commands, item use) ---
     const weapon = createWeaponStats((itemId) => content.itemById?.(itemId));
     const feed = createGameFeed(definition.feed);
@@ -369,6 +369,7 @@ export function createGameContext(options) {
                 },
                 collidersOf: entityCollidersOf,
                 reportBounds: reportEntityBounds,
+                reportCollisionMesh: reportEntityCollisionMesh,
                 visualScaleOf: entityVisualScaleOf,
                 form: forms,
                 paint: paintLayer,

package/dist/runtime/gameContextTypes.d.ts

@@ -35,6 +35,7 @@ import type { EntityStatsApi, StatCatalog } from "../scene/entityStats.js";
 import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import type { Forms } from "../scene/form.js";
 import type { EntityColliderSet, MeasuredBounds, ModelBodySource } from "../scene/colliders.js";
+import type { CollisionMeshSource } from "../scene/collisionMesh.js";
 import type { ObjectRaycastHit, ObjectRaycastInput } from "../scene/objectQuery.js";
 import type { ObjectStore } from "../scene/objectStore.js";
 import type { Roster } from "../scene/roster.js";
@@ -145,6 +146,15 @@ export interface SceneObjectContext extends ObjectStore {
      * @capability measured-colliders hitboxes and blocking bodies wrap what the renderer actually mounted — custom render props and dims-less models stop falling back to fixed-size boxes.
      */
     reportBounds(catalogId: string, bounds: MeasuredBounds | null): boolean;
+    /**
+     * Report the entity-local triangle soup the renderer actually mounted for `catalogId` — stored per
+     * catalog id as a blocking physical body whose raycasts hit the real surface (a BVH over the
+     * triangles) while movement obstruction keeps the conservative AABB. Consulted right after
+     * authored `colliders` / index collision meshes and before the fitted-box, measured-bounds, and
+     * visual-scale fallbacks. The shell reports rendered models automatically. Pass `null` to clear.
+     * Returns `false` when no valid triangle survives.
+     */
+    reportCollisionMesh(catalogId: string, mesh: CollisionMeshSource | null): boolean;
     /**
      * Per-instance selection/highlight state for placed objects — the reactive counterpart to
      * `worldHealthBars`/`nameplates` (entities), so a build-mode or RTS selection ring reads
@@ -275,6 +285,17 @@ export interface SceneEntityContext {
      * @capability measured-hitboxes an entity rendered with a custom mesh takes hits in a box matching its rendered bounds, not the fixed humanoid rectangle.
      */
     reportBounds(kind: string, bounds: MeasuredBounds | null): boolean;
+    /**
+     * Report the entity-local triangle soup the renderer actually mounted for `kind` — stored per kind
+     * as a damage hitbox that raycasts the model's own triangles (BVH), so shots aimed between a
+     * character's feet or past its shoulder miss instead of hitting a bounding box. Consulted right
+     * after authored `colliders` / index collision meshes and before the fitted-box and
+     * measured-bounds fallbacks. The shell reports rendered models automatically; authoritative hosts
+     * that never render should author `colliders` or index collision meshes for identical results.
+     * Pass `null` to clear. Returns `false` when no valid triangle survives.
+     * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — damage raycasts hit the rendered model's triangles, not its bounding box.
+     */
+    reportCollisionMesh(kind: string, mesh: CollisionMeshSource | null): boolean;
     /** Uniform visual scale from the entity's catalog entry (1 when unscaled). */
     visualScaleOf(instanceId: string): number;
     form: Forms;

package/dist/scene/builtinSceneKinds.d.ts

@@ -1,5 +1,10 @@
 import { type ParamSchema } from "./sceneKinds.js";
-/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+/**
+ * The scatter/foliage region schema. `palette` (what fills the area) leads the schema body and
+ * `density` is the single coverage slider hoisted into the shared `CoverageSection` (see the kind's
+ * `coverage` descriptor), so a scatter region reads as Area → Assets → Density like every other
+ * scatterable kind; the rest is kind-specific tuning.
+ */
 export declare const SCATTER_SCHEMA: ParamSchema;
 /** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
 export declare function registerBuiltinSceneKinds(): void;

package/dist/scene/builtinSceneKinds.js

@@ -15,10 +15,17 @@ import { registerSoilKind } from "../world/soilKind.js";
 import { registerPoleLineKind } from "../world/poleLineKind.js";
 import { registerBuildingGenerator } from "../world/buildingGenerator.js";
 import { registerCityKind } from "../world/cityKind.js";
+import { describeScatterCoverage, densityCoverage } from "../world/scatterCoverage.js";
 import { registerSceneKind } from "./sceneKinds.js";
-/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+/**
+ * The scatter/foliage region schema. `palette` (what fills the area) leads the schema body and
+ * `density` is the single coverage slider hoisted into the shared `CoverageSection` (see the kind's
+ * `coverage` descriptor), so a scatter region reads as Area → Assets → Density like every other
+ * scatterable kind; the rest is kind-specific tuning.
+ */
 export const SCATTER_SCHEMA = {
     fields: [
+        { type: "weightedList", key: "palette", label: "species (weighted)", itemLabel: "grass / tree id", default: [{ item: "grass", weight: 1 }] },
         { type: "range", key: "density", label: "density", min: 0, max: 2, step: 0.01, default: 0.15, unit: "/m²" },
         { type: "number", key: "minSpacing", label: "spacing", step: 0.25, default: 1.5, min: 0 },
         { type: "number", key: "minScale", label: "min scale", step: 0.05, default: 0.8, min: 0 },
@@ -27,7 +34,6 @@ export const SCATTER_SCHEMA = {
         { type: "number", key: "edgeFalloff", label: "edge fade", step: 0.5, default: 0, min: 0 },
         { type: "bool", key: "alignToNormal", label: "align to slope", default: false },
         { type: "bool", key: "autoAvoid", label: "auto-avoid gameplay spots", default: true },
-        { type: "weightedList", key: "palette", label: "species (weighted)", itemLabel: "grass / tree id", default: [{ item: "grass", weight: 1 }] },
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
@@ -45,6 +51,7 @@ export function registerBuiltinSceneKinds() {
         addCategory: "Studios",
         accent: "#34d399",
         schema: SCATTER_SCHEMA,
+        coverage: { spec: "scatter", densityKey: "density", assetsKey: "palette" },
         note: (object, params) => {
             const points = object.points ?? [];
             if (points.length < 3)
@@ -55,7 +62,7 @@ export function registerBuiltinSceneKinds() {
             }
             area = Math.abs(area) / 2;
             const density = typeof params["density"] === "number" ? params["density"] : 0;
-            return `≈ ${Math.floor(area * density).toLocaleString()} placements over ${Math.round(area).toLocaleString()} m²`;
+            return describeScatterCoverage(densityCoverage("scatter", area, density));
         },
     });
     registerWaterKind();

package/dist/scene/colliders.d.ts

@@ -128,6 +128,26 @@ export declare function measuredEntityColliders(bounds: MeasuredBounds): EntityC
  * @internal
  */
 export declare function measuredObjectColliders(bounds: MeasuredBounds): EntityColliderSet | null;
+/** Damage hitbox raycasting the actual triangles the renderer mounted for an entity kind — what
+ * `reportCollisionMesh` stores. Triangles are entity-local (scale/placement already applied), so the
+ * shape composes with identity `meshScale`/`meshTranslate`; bounds/broadphase read the clamped AABB.
+ * `null` when the mesh is degenerate, keeping the caller's existing fallback.
+ * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — the damage hitbox is the rendered model's own triangles, not a bounding box.
+ * @internal
+ */
+export declare function meshEntityColliders(mesh: PreparedCollisionMesh): EntityColliderSet | null;
+/** Blocking physical body raycasting the actual triangles the renderer mounted for an object catalog
+ * id — the mesh-accurate counterpart to `measuredObjectColliders`. Movement obstruction stays on the
+ * conservative AABB (no `boxes` decomposition at runtime); rays hit the real surface. `null` when
+ * degenerate.
+ * @internal
+ */
+export declare function meshObjectColliders(mesh: PreparedCollisionMesh): EntityColliderSet | null;
+/** True when any collider in the set already raycasts real triangles (index-derived mesh shapes win
+ * over runtime-measured ones — they are identical on a headless host).
+ * @internal
+ */
+export declare function hasMeshColliderShape(set: EntityColliderSet | null | undefined): boolean;
 /** @internal */
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
 /** @internal */

package/dist/scene/colliders.js

@@ -250,6 +250,84 @@ export function measuredObjectColliders(bounds) {
         },
     };
 }
+/** Root-node AABB of a prepared mesh (the BVH root bounds the whole soup) as a clamped
+ * entity-local box — `null` when degenerate. */
+function preparedMeshShape(mesh) {
+    const bounds = mesh.nodeBounds;
+    if (bounds.length < 6)
+        return null;
+    const min = [bounds[0], bounds[1], bounds[2]];
+    const max = [bounds[3], bounds[4], bounds[5]];
+    const box = measuredBox({ min, max });
+    if (box === null)
+        return null;
+    return {
+        kind: "mesh",
+        mesh,
+        meshScale: 1,
+        meshTranslate: [0, 0, 0],
+        halfExtents: box.halfExtents,
+        offset: box.offset,
+    };
+}
+/** Damage hitbox raycasting the actual triangles the renderer mounted for an entity kind — what
+ * `reportCollisionMesh` stores. Triangles are entity-local (scale/placement already applied), so the
+ * shape composes with identity `meshScale`/`meshTranslate`; bounds/broadphase read the clamped AABB.
+ * `null` when the mesh is degenerate, keeping the caller's existing fallback.
+ * @capability conforming-hitboxes shots aimed between a character's feet or past its shoulder MISS — the damage hitbox is the rendered model's own triangles, not a bounding box.
+ * @internal
+ */
+export function meshEntityColliders(mesh) {
+    const shape = preparedMeshShape(mesh);
+    if (shape === null)
+        return null;
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape,
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** Blocking physical body raycasting the actual triangles the renderer mounted for an object catalog
+ * id — the mesh-accurate counterpart to `measuredObjectColliders`. Movement obstruction stays on the
+ * conservative AABB (no `boxes` decomposition at runtime); rays hit the real surface. `null` when
+ * degenerate.
+ * @internal
+ */
+export function meshObjectColliders(mesh) {
+    const shape = preparedMeshShape(mesh);
+    if (shape === null)
+        return null;
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape,
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
+/** True when any collider in the set already raycasts real triangles (index-derived mesh shapes win
+ * over runtime-measured ones — they are identical on a headless host).
+ * @internal
+ */
+export function hasMeshColliderShape(set) {
+    if (set === null || set === undefined)
+        return false;
+    if (set.body?.shape.kind === "mesh")
+        return true;
+    for (const hitbox of set.hitboxes ?? []) {
+        if (hitbox.shape.kind === "mesh")
+            return true;
+    }
+    return false;
+}
 /** @internal */
 export function resolveColliders(set) {
     if (set === null || set === undefined)

package/dist/scene/collisionMesh.d.ts

@@ -77,6 +77,14 @@ export declare function voxelizeToBoxes(source: CollisionMeshSource, cellSize?:
     min: [number, number, number];
     max: [number, number, number];
 }[];
+/**
+ * Build a prepared BVH mesh straight from a runtime triangle soup (float positions + indices) —
+ * the renderer-fed counterpart to {@link prepareCollisionMesh}, feeding
+ * `ctx.scene.entity.reportCollisionMesh` / `ctx.scene.object.reportCollisionMesh` without a
+ * quantize/encode round-trip. Copies and sanitizes the input: triangles referencing out-of-range,
+ * non-finite, or repeated vertices are dropped. Returns `null` when no triangle survives.
+ */
+export declare function prepareCollisionMeshSource(source: CollisionMeshSource): PreparedCollisionMesh | null;
 /**
  * Decode a stored collision mesh and index it with a BVH. Memoized per data object, so the shell and
  * a headless host preparing the same catalog entry share one build. Returns `null` (also memoized)

package/dist/scene/collisionMesh.js

@@ -500,6 +500,54 @@ function buildBvh(positions, indices) {
         triOrder,
     };
 }
+/**
+ * Build a prepared BVH mesh straight from a runtime triangle soup (float positions + indices) —
+ * the renderer-fed counterpart to {@link prepareCollisionMesh}, feeding
+ * `ctx.scene.entity.reportCollisionMesh` / `ctx.scene.object.reportCollisionMesh` without a
+ * quantize/encode round-trip. Copies and sanitizes the input: triangles referencing out-of-range,
+ * non-finite, or repeated vertices are dropped. Returns `null` when no triangle survives.
+ */
+export function prepareCollisionMeshSource(source) {
+    const raw = source.positions;
+    const rawIndices = source.indices;
+    if (raw.length < 9 || raw.length % 3 !== 0)
+        return null;
+    if (rawIndices.length < 3 || rawIndices.length % 3 !== 0)
+        return null;
+    const vertexCount = raw.length / 3;
+    const positions = new Float32Array(raw.length);
+    const finite = new Uint8Array(vertexCount);
+    for (let v = 0; v < vertexCount; v += 1) {
+        const x = raw[v * 3];
+        const y = raw[v * 3 + 1];
+        const z = raw[v * 3 + 2];
+        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
+            continue;
+        positions[v * 3] = x;
+        positions[v * 3 + 1] = y;
+        positions[v * 3 + 2] = z;
+        finite[v] = 1;
+    }
+    const triangles = [];
+    for (let t = 0; t + 2 < rawIndices.length; t += 3) {
+        const a = rawIndices[t];
+        const b = rawIndices[t + 1];
+        const c = rawIndices[t + 2];
+        if (!Number.isInteger(a) || a < 0 || a >= vertexCount || finite[a] === 0)
+            continue;
+        if (!Number.isInteger(b) || b < 0 || b >= vertexCount || finite[b] === 0)
+            continue;
+        if (!Number.isInteger(c) || c < 0 || c >= vertexCount || finite[c] === 0)
+            continue;
+        if (a === b || b === c || a === c)
+            continue;
+        triangles.push(a, b, c);
+    }
+    if (triangles.length === 0)
+        return null;
+    const indices = new Uint32Array(triangles);
+    return { positions, indices, ...buildBvh(positions, indices) };
+}
 const preparedCache = new WeakMap();
 /**
  * Decode a stored collision mesh and index it with a BVH. Memoized per data object, so the shell and

package/dist/scene/sceneKinds.d.ts

@@ -145,6 +145,19 @@ export interface ParamSchema {
 export declare function findSchemaPreset(schema: ParamSchema, id: string): ParamPreset | undefined;
 /** Parsed params after `parseParams`: every schema field present with a validated, defaulted value. */
 export type ParsedParams = Record<string, number | boolean | string | WeightedParamEntry[]>;
+/**
+ * Marks a kind as *scatterable* — it fills an authored area with instances at one density under a
+ * bounded budget — so the editor renders the shared `CoverageSection` (Area → Assets → Density slider
+ * + budget note) that gives grass/scatter/city one authoring gesture. `spec` selects the unit + budget
+ * from `@jgengine/core/world/scatterCoverage`; `densityKey` is the single density slider hoisted into
+ * the coverage header (and hidden from the schema body below); `assetsKey` is the optional weighted
+ * "what fills it" palette summarized in the header.
+ */
+export interface SceneKindCoverage {
+    spec: import("../world/scatterCoverage.js").ScatterCoverageKind;
+    densityKey: string;
+    assetsKey?: string;
+}
 /**
  * Parse a raw `meta` bag against a schema into typed params — every field present, invalid/missing
  * values replaced by the field default, numbers clamped to their range. The single parser every
@@ -201,6 +214,12 @@ export interface SceneKindDefinition<TResolved = unknown> {
     resolve?: (object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => TResolved;
     /** Optional one-line readout under the inspector fields (estimate, dimensions) — owned by the studio. */
     note?: (object: SceneKindObject, params: ParsedParams) => string;
+    /**
+     * Optional scatterable-coverage descriptor. When set, the editor leads this kind's inspector with
+     * the shared Area / Assets / Density `CoverageSection` and surfaces the budget clamp-and-warn note,
+     * giving every scatterable kind (grass/scatter/city) one authoring pattern.
+     */
+    coverage?: SceneKindCoverage;
 }
 /** The raw document object a resolver receives — shape shared by markers, volumes, and paths. */
 export interface SceneKindObject {

package/dist/ui/hudScale.d.ts

@@ -37,7 +37,22 @@ export interface HudOverflow {
 }
 /** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
 export declare function rectOverflow(rect: HudRect, viewport: HudSize, tolerance?: number): Omit<HudOverflow, "id"> | null;
-/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+/**
+ * True when at least `minVisiblePx²` of `rect` actually falls inside `viewport`.
+ * The boundary check uses this to tell a *shown* surface from a *closed* one: a
+ * mail drawer parked fully off-screen (or a menu that has not been opened) never
+ * intersects the viewport, so it is not "escaping" — it is simply not on screen.
+ * Only a surface that is partly visible and partly past an edge is a real defect.
+ *
+ * @internal Consumed transitively through {@link overflowingPanels}; exported for unit tests.
+ */
+export declare function rectIntersectsViewport(rect: HudRect, viewport: HudSize, minVisiblePx?: number): boolean;
+/**
+ * Every panel rect that escapes the viewport — the data behind the HUD overflow
+ * gate. A rect is only reported when it is partly visible *and* crosses an edge;
+ * a fully off-screen (closed/hidden) surface is skipped, so parked drawers and
+ * unopened menus never raise a false alarm.
+ */
 export declare function overflowingPanels(panels: readonly {
     id: string;
     rect: HudRect;

package/dist/ui/hudScale.js

@@ -43,10 +43,31 @@ export function rectOverflow(rect, viewport, tolerance = 1.5) {
     const round = (n) => Math.round(n * 10) / 10;
     return { left: round(left), top: round(top), right: round(right), bottom: round(bottom) };
 }
-/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+/**
+ * True when at least `minVisiblePx²` of `rect` actually falls inside `viewport`.
+ * The boundary check uses this to tell a *shown* surface from a *closed* one: a
+ * mail drawer parked fully off-screen (or a menu that has not been opened) never
+ * intersects the viewport, so it is not "escaping" — it is simply not on screen.
+ * Only a surface that is partly visible and partly past an edge is a real defect.
+ *
+ * @internal Consumed transitively through {@link overflowingPanels}; exported for unit tests.
+ */
+export function rectIntersectsViewport(rect, viewport, minVisiblePx = 1) {
+    const visibleWidth = Math.min(rect.x + rect.width, viewport.width) - Math.max(rect.x, 0);
+    const visibleHeight = Math.min(rect.y + rect.height, viewport.height) - Math.max(rect.y, 0);
+    return visibleWidth >= minVisiblePx && visibleHeight >= minVisiblePx;
+}
+/**
+ * Every panel rect that escapes the viewport — the data behind the HUD overflow
+ * gate. A rect is only reported when it is partly visible *and* crosses an edge;
+ * a fully off-screen (closed/hidden) surface is skipped, so parked drawers and
+ * unopened menus never raise a false alarm.
+ */
 export function overflowingPanels(panels, viewport, tolerance = 1.5) {
     const out = [];
     for (const panel of panels) {
+        if (!rectIntersectsViewport(panel.rect, viewport))
+            continue;
         const overflow = rectOverflow(panel.rect, viewport, tolerance);
         if (overflow !== null)
             out.push({ id: panel.id, ...overflow });

package/dist/world/cityKind.js

@@ -32,6 +32,7 @@ import { parseParams, registerSceneKind, } from "../scene/sceneKinds.js";
 import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_STYLE } from "./buildings.js";
 import { buildLotPieces, pickClass, pickSpecies, rollClassPlacement, zoneBand, zoneMetric, } from "./cityContent.js";
 import { furnitureSpots } from "./streets.js";
+import { CITY_BUILDING_BUDGET, budgetWarning, placedCoverage } from "./scatterCoverage.js";
 import { generateStreets, streetNetworkMode, } from "./streetGenerator.js";
 import { buildablePolygon, carveCorridors, conformPolygonToRing, cutParcel, extractBlocks, isSliverBlock, pointsInPolygon, RingWalker, } from "./cityBlocks.js";
 import { fitRectInPolygon, rayDistanceToRing, pointInPolygon, polygonArea, polygonCentroid, polygonMeanWidth, polygonsOverlap, insetRingUniform, ringBounds, } from "./cityGeometry.js";
@@ -567,7 +568,8 @@ export function readCityRules(meta) {
 }
 /** Bounded-work caps so a huge volume can never generate unbounded content. */
 const MAX_STREETS = 320;
-const MAX_LOTS = 2600;
+/** Building budget — the shared scatterable cap so the inspector's "capped at N (budget)" note is truthful. */
+const MAX_LOTS = CITY_BUILDING_BUDGET;
 const MAX_INTERSECTIONS = 600;
 const MAX_TREES = 3200;
 const MAX_LIGHTS = 1200;
@@ -1530,6 +1532,7 @@ export function registerCityKind() {
         addCategory: "Studios",
         accent: "#8fa8c9",
         schema: CITY_SCHEMA,
+        coverage: { spec: "city", densityKey: "roadsideOccupancy" },
         resolve: (object, _params, context) => resolveCityObject(object, context),
         note: (object) => {
             const resolved = resolveCityObject(object);
@@ -1558,7 +1561,10 @@ export function registerCityKind() {
                 resolved.tunnels.length > 0 ? `${resolved.tunnels.length} tunnels` : "",
             ].filter((s) => s.length > 0);
             const head = mode === "circuit" ? `circuit · ${resolved.streets.length} streets` : `${resolved.streets.length} streets`;
-            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings · ${resolved.parks.length} parks` : " · no fabric";
+            // Shared clamp-and-warn: when the block/parcel pipeline hits the building budget, surface it in
+            // the same "capped at N (budget)" wording grass and scatter use.
+            const buildingCap = resolved.rules.fabric ? budgetWarning(placedCoverage("city", 0, resolved.lots.length)) : "";
+            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings${buildingCap} · ${resolved.parks.length} parks` : " · no fabric";
             return `${head}${fabric}${feats.length > 0 ? ` · ${feats.join(" · ")}` : ""}`;
         },
     });

package/dist/world/grassKind.js

@@ -8,6 +8,7 @@
  * @capability grass-field editor-authorable GPU grass patch
  */
 import { registerSceneKind } from "../scene/sceneKinds.js";
+import { budgetWarning, densityCoverage } from "./scatterCoverage.js";
 /** The editor volume kind marking a box as a GPU grass patch. */
 export const GRASS_FIELD_KIND = "grass_field";
 /** Grass defaults: a lush, lightly-swaying meadow. */
@@ -89,13 +90,15 @@ export function registerGrassKind() {
         addCategory: "Studios",
         accent: "#7fbf4d",
         schema: GRASS_SCHEMA,
+        coverage: { spec: "grass_field", densityKey: "density" },
         resolve: (object) => resolveGrassObject(object),
         note: (object) => {
             const resolved = resolveGrassObject(object);
             if (resolved === null)
                 return "Give the volume a box footprint.";
             const area = resolved.size[0] * resolved.size[1];
-            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈${Math.round(area * resolved.rules.density).toLocaleString()} blades`;
+            const coverage = densityCoverage("grass_field", area, resolved.rules.density);
+            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈ ${coverage.count.toLocaleString()} blades${budgetWarning(coverage)}`;
         },
     });
 }

package/dist/world/scatterCoverage.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The shared "how much stuff grows here" contract for scatterable scene kinds
+ * (`grass_field` / `scatter` / `city`). Every scatterable kind fills an authored AREA with instances
+ * at a DENSITY, and every kind caps the placed count at a bounded BUDGET so a huge or dense request
+ * can never generate unbounded work. Before this module each kind hand-rolled its own readout and
+ * clamp story (grass silently capped in the renderer, scatter never capped, city had no budget note);
+ * this is the one place that
+ *
+ * 1. names the per-kind unit noun + placement budget ({@link SCATTER_COVERAGE_SPECS}),
+ * 2. turns an area + density into a `requested` / placed `count` / `capped` triple
+ *    ({@link densityCoverage}, {@link placedCoverage}), and
+ * 3. renders the identical clamp-and-warn clause the inspector surfaces —
+ *    `requested N, capped at M (budget)` — via {@link budgetWarning} / {@link describeScatterCoverage}.
+ *
+ * Pure data + string helpers, no rendering. Each kind's `note` and the editor's shared
+ * `CoverageSection` consume it, so grass, scatter, and city tell one coverage story.
+ *
+ * @capability scatter-coverage shared density/budget semantics for scatterable kinds
+ */
+/** The scatterable kinds that share the coverage contract. */
+export type ScatterCoverageKind = "grass_field" | "scatter" | "city";
+/**
+ * Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass
+ * renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never
+ * renders more than this many placements regardless of density × area.
+ */
+export declare const SCATTER_INSTANCE_BUDGET = 250000;
+/** Max buildings a single `city` district generates — the block/parcel pipeline's bounded lot cap. */
+export declare const CITY_BUILDING_BUDGET = 2600;
+/** Per-kind coverage descriptor: the unit noun, whether density is per-m², and the placement budget. */
+export interface ScatterCoverageSpec {
+    kind: ScatterCoverageKind;
+    /** Plural noun for one placed instance: `blades` | `placements` | `buildings`. */
+    unit: string;
+    /** Density is per-square-meter (grass/scatter). City fills by street fabric, not by a per-m² dial. */
+    perArea: boolean;
+    /** Hard cap on placed instances for one patch/district. */
+    budget: number;
+}
+/** The coverage spec per scatterable kind — the single source for its unit + budget. */
+export declare const SCATTER_COVERAGE_SPECS: Record<ScatterCoverageKind, ScatterCoverageSpec>;
+/** The coverage spec for a scatterable kind, or `null` when the kind is not scatterable. */
+export declare function scatterCoverageSpec(kind: string): ScatterCoverageSpec | null;
+/**
+ * A resolved coverage readout: how many instances an authored patch WANTS (`requested`, when it can
+ * be computed cheaply from geometry × density), how many it will actually place after the budget
+ * clamp (`count`), the `budget` ceiling, and whether the request hit it (`capped`). `requested` is
+ * `null` for kinds whose pre-cap ask is not knowable without running the generator (city, where the
+ * count comes from the resolved street fabric).
+ */
+export interface ScatterCoverage {
+    kind: ScatterCoverageKind;
+    unit: string;
+    /** Footprint area in m² (0 when unknown / not applicable). */
+    area: number;
+    /** Instances the density asks for before the budget clamp; `null` when only the placed count is known. */
+    requested: number | null;
+    /** Instances actually placed: `min(requested, budget)`, or the generator's reported count. */
+    count: number;
+    budget: number;
+    capped: boolean;
+}
+/**
+ * Footprint area (m²) of a scatterable object: a closed path polygon (shoelace), a volume box
+ * (`halfExtents`), or a disc (`radius`). Structural so it accepts a `SceneKindObject`, an editor
+ * volume, or a scatter path without a hard type dependency.
+ */
+export declare function scatterFootprintArea(object: {
+    points?: readonly {
+        x: number;
+        z: number;
+    }[];
+    halfExtents?: {
+        x: number;
+        z: number;
+    };
+    radius?: number;
+}): number;
+/**
+ * Coverage for a per-m² kind (`grass_field` / `scatter`): `requested = floor(density × area)`, clamped
+ * to the kind's budget. `capped` is true when the request exceeds the budget.
+ */
+export declare function densityCoverage(kind: "grass_field" | "scatter", area: number, density: number): ScatterCoverage;
+/**
+ * Coverage for a kind whose placed `count` is already known from its generator (city, from its
+ * resolved lots). No pre-cap `requested` is available — the generator stops at the budget — so
+ * `capped` is inferred from the placed count reaching the ceiling.
+ */
+export declare function placedCoverage(kind: ScatterCoverageKind, area: number, placed: number): ScatterCoverage;
+/**
+ * The shared clamp-and-warn clause every scatterable kind appends, worded identically: `""` when
+ * under budget, else ` · requested N, capped at M (budget)` when the pre-cap ask is known, or
+ * ` · capped at M (budget)` when only the ceiling is (city). This is the "surfaced, never silent"
+ * budget signal from #1112.
+ */
+export declare function budgetWarning(coverage: ScatterCoverage): string;
+/** The full one-line coverage readout: `≈ N unit · A m²` plus the {@link budgetWarning} when capped. */
+export declare function describeScatterCoverage(coverage: ScatterCoverage): string;

package/dist/world/scatterCoverage.js

@@ -0,0 +1,101 @@
+/**
+ * The shared "how much stuff grows here" contract for scatterable scene kinds
+ * (`grass_field` / `scatter` / `city`). Every scatterable kind fills an authored AREA with instances
+ * at a DENSITY, and every kind caps the placed count at a bounded BUDGET so a huge or dense request
+ * can never generate unbounded work. Before this module each kind hand-rolled its own readout and
+ * clamp story (grass silently capped in the renderer, scatter never capped, city had no budget note);
+ * this is the one place that
+ *
+ * 1. names the per-kind unit noun + placement budget ({@link SCATTER_COVERAGE_SPECS}),
+ * 2. turns an area + density into a `requested` / placed `count` / `capped` triple
+ *    ({@link densityCoverage}, {@link placedCoverage}), and
+ * 3. renders the identical clamp-and-warn clause the inspector surfaces —
+ *    `requested N, capped at M (budget)` — via {@link budgetWarning} / {@link describeScatterCoverage}.
+ *
+ * Pure data + string helpers, no rendering. Each kind's `note` and the editor's shared
+ * `CoverageSection` consume it, so grass, scatter, and city tell one coverage story.
+ *
+ * @capability scatter-coverage shared density/budget semantics for scatterable kinds
+ */
+/**
+ * Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass
+ * renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never
+ * renders more than this many placements regardless of density × area.
+ */
+export const SCATTER_INSTANCE_BUDGET = 250_000;
+/** Max buildings a single `city` district generates — the block/parcel pipeline's bounded lot cap. */
+export const CITY_BUILDING_BUDGET = 2_600;
+/** The coverage spec per scatterable kind — the single source for its unit + budget. */
+export const SCATTER_COVERAGE_SPECS = {
+    grass_field: { kind: "grass_field", unit: "blades", perArea: true, budget: SCATTER_INSTANCE_BUDGET },
+    scatter: { kind: "scatter", unit: "placements", perArea: true, budget: SCATTER_INSTANCE_BUDGET },
+    city: { kind: "city", unit: "buildings", perArea: false, budget: CITY_BUILDING_BUDGET },
+};
+/** The coverage spec for a scatterable kind, or `null` when the kind is not scatterable. */
+export function scatterCoverageSpec(kind) {
+    return SCATTER_COVERAGE_SPECS[kind] ?? null;
+}
+const nonNegative = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
+/**
+ * Footprint area (m²) of a scatterable object: a closed path polygon (shoelace), a volume box
+ * (`halfExtents`), or a disc (`radius`). Structural so it accepts a `SceneKindObject`, an editor
+ * volume, or a scatter path without a hard type dependency.
+ */
+export function scatterFootprintArea(object) {
+    const points = object.points;
+    if (points !== undefined && points.length >= 3) {
+        let sum = 0;
+        for (let i = 0, j = points.length - 1; i < points.length; j = i, i += 1) {
+            sum += points[j].x * points[i].z - points[i].x * points[j].z;
+        }
+        return Math.abs(sum) / 2;
+    }
+    const he = object.halfExtents;
+    if (he !== undefined)
+        return nonNegative(Math.abs(he.x) * 2) * nonNegative(Math.abs(he.z) * 2);
+    if (object.radius !== undefined)
+        return Math.PI * nonNegative(object.radius) ** 2;
+    return 0;
+}
+/**
+ * Coverage for a per-m² kind (`grass_field` / `scatter`): `requested = floor(density × area)`, clamped
+ * to the kind's budget. `capped` is true when the request exceeds the budget.
+ */
+export function densityCoverage(kind, area, density) {
+    const spec = SCATTER_COVERAGE_SPECS[kind];
+    const a = nonNegative(area);
+    const requested = Math.floor(nonNegative(density) * a);
+    const count = Math.min(requested, spec.budget);
+    return { kind, unit: spec.unit, area: a, requested, count, budget: spec.budget, capped: requested > spec.budget };
+}
+/**
+ * Coverage for a kind whose placed `count` is already known from its generator (city, from its
+ * resolved lots). No pre-cap `requested` is available — the generator stops at the budget — so
+ * `capped` is inferred from the placed count reaching the ceiling.
+ */
+export function placedCoverage(kind, area, placed) {
+    const spec = SCATTER_COVERAGE_SPECS[kind];
+    const count = Math.max(0, Math.floor(nonNegative(placed)));
+    return { kind, unit: spec.unit, area: nonNegative(area), requested: null, count, budget: spec.budget, capped: count >= spec.budget };
+}
+const fmt = (n) => Math.round(n).toLocaleString();
+/**
+ * The shared clamp-and-warn clause every scatterable kind appends, worded identically: `""` when
+ * under budget, else ` · requested N, capped at M (budget)` when the pre-cap ask is known, or
+ * ` · capped at M (budget)` when only the ceiling is (city). This is the "surfaced, never silent"
+ * budget signal from #1112.
+ */
+export function budgetWarning(coverage) {
+    if (!coverage.capped)
+        return "";
+    if (coverage.requested !== null && coverage.requested > coverage.budget) {
+        return ` · requested ${fmt(coverage.requested)}, capped at ${fmt(coverage.budget)} (budget)`;
+    }
+    return ` · capped at ${fmt(coverage.budget)} (budget)`;
+}
+/** The full one-line coverage readout: `≈ N unit · A m²` plus the {@link budgetWarning} when capped. */
+export function describeScatterCoverage(coverage) {
+    const head = `≈ ${fmt(coverage.count)} ${coverage.unit}`;
+    const area = coverage.area > 0 ? ` · ${fmt(coverage.area)} m²` : "";
+    return `${head}${area}${budgetWarning(coverage)}`;
+}

package/dist/world/scatterRegion.js

@@ -1,5 +1,6 @@
 import { masksInfluence, } from "./geometry.js";
 import { scatter } from "./scatter.js";
+import { SCATTER_INSTANCE_BUDGET } from "./scatterCoverage.js";
 /** The editor path kind that marks a closed polyline as a foliage/scatter region. */
 export const SCATTER_PATH_KIND = "scatter";
 /** Defaults a bare scatter region fills with: sparse grass, lightly spaced. */
@@ -192,6 +193,11 @@ export function resolveScatterRegion(region, terrain, avoid) {
             scale: rules.minScale + (rules.maxScale - rules.minScale) * scaleRoll,
             ...(normal === undefined ? {} : { normal }),
         });
+        // Bounded work: a single region never emits more than the shared instance budget, matching the
+        // grass patch cap so the inspector's "capped at N (budget)" note is truthful. Placements are
+        // generated in deterministic scatter order, so the truncated set is deterministic too.
+        if (instances.length >= SCATTER_INSTANCE_BUDGET)
+            break;
     }
     return instances;
 }

package/dist/world.d.ts

@@ -121,6 +121,7 @@ export { composeRealm } from "./world/realm.js";
 export { createRegionField, isRegionField, type RegionField } from "./world/regions.js";
 export { buildRoadRibbon, dashSegments } from "./world/roads.js";
 export { scatter, type ScatterPoint } from "./world/scatter.js";
+export { CITY_BUILDING_BUDGET, SCATTER_COVERAGE_SPECS, SCATTER_INSTANCE_BUDGET, budgetWarning, densityCoverage, describeScatterCoverage, placedCoverage, scatterCoverageSpec, scatterFootprintArea, type ScatterCoverage, type ScatterCoverageKind, type ScatterCoverageSpec, } from "./world/scatterCoverage.js";
 export { pickWeighted, scatterItems, type ScatterInstance } from "./world/scatterItems.js";
 export { SCATTER_PATH_KIND, clearanceZonesFrom, distanceToPolygonEdge, isScatterPath, pointInPolygon, polygonArea, polygonBounds, readScatterPalette, readScatterRules, resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, type ScatterTerrain, } from "./world/scatterRegion.js";
 export { SOIL_KIND, SOIL_SCHEMA, type SoilRules } from "./world/soilKind.js";

package/dist/world.js

@@ -121,6 +121,7 @@ export { composeRealm } from "./world/realm.js";
 export { createRegionField, isRegionField } from "./world/regions.js";
 export { buildRoadRibbon, dashSegments } from "./world/roads.js";
 export { scatter } from "./world/scatter.js";
+export { CITY_BUILDING_BUDGET, SCATTER_COVERAGE_SPECS, SCATTER_INSTANCE_BUDGET, budgetWarning, densityCoverage, describeScatterCoverage, placedCoverage, scatterCoverageSpec, scatterFootprintArea, } from "./world/scatterCoverage.js";
 export { pickWeighted, scatterItems } from "./world/scatterItems.js";
 export { SCATTER_PATH_KIND, clearanceZonesFrom, distanceToPolygonEdge, isScatterPath, pointInPolygon, polygonArea, polygonBounds, readScatterPalette, readScatterRules, resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, } from "./world/scatterRegion.js";
 export { SOIL_KIND, SOIL_SCHEMA } from "./world/soilKind.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jgengine/core",
-  "version": "0.13.0",
-  "description": "jgengine core — agent-first game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. https://jgengine.com",
+  "version": "0.14.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",
     "agent-first",

package/skills/jgengine/SKILL.md

@@ -5,7 +5,7 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
 
 ## 1. Establish the target
 
@@ -20,6 +20,8 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 
 For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
+For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -43,7 +45,7 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 Within each selected domain:
 
 0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports.
+1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 2. Open `api.md` only when exact signatures or export inventory are needed.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.

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.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -220,7 +220,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.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-world/api.md

@@ -925,7 +925,7 @@
 
 ## @jgengine/core/scene/builtinSceneKinds
 
-- `SCATTER_SCHEMA` (const): const SCATTER_SCHEMA: ParamSchema — The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`.
+- `SCATTER_SCHEMA` (const): const SCATTER_SCHEMA: ParamSchema — The scatter/foliage region schema. `palette` (what fills the area) leads the schema body and `density` is the single coverage slider hoisted into the shared `CoverageSection` (see the kind's `coverage` descriptor), so a scatter region reads as Area → Assets → Density like every other scatterable kind; the rest is kind-specific tuning.
 
 ## @jgengine/core/scene/captureCheck
 
@@ -955,6 +955,7 @@
 - `PreparedCollisionMesh` (interface): interface PreparedCollisionMesh — Decoded, BVH-indexed triangles ready for per-ray queries — build once per asset via {@link prepareCollisionMesh}. Treat the fields as opaque; they exist so the raycast hot path can run allocation-free over flat arrays.
 - `encodeCollisionMesh` (function): function encodeCollisionMesh(source: CollisionMeshSource): CollisionMeshData | null — Quantize a triangle soup onto the 16-bit grid, weld coincident vertices, and drop triangles that collapse — the reindex-time compressor producing {@link CollisionMeshData}. Returns `null` when no finite, non-degenerate triangle survives.
 - `prepareCollisionMesh` (function): function prepareCollisionMesh(data: CollisionMeshData): PreparedCollisionMesh | null — Decode a stored collision mesh and index it with a BVH. Memoized per data object, so the shell and a headless host preparing the same catalog entry share one build. Returns `null` (also memoized) when the payload is malformed.
+- `prepareCollisionMeshSource` (function): function prepareCollisionMeshSource(source: CollisionMeshSource): PreparedCollisionMesh | null — Build a prepared BVH mesh straight from a runtime triangle soup (float positions + indices) — the renderer-fed counterpart to {@link prepareCollisionMesh}, feeding `ctx.scene.entity.reportCollisionMesh` / `ctx.scene.object.reportCollisionMesh` without a quantize/encode round-trip. Copies and sanitizes the input: triangles referencing out-of-range, non-finite, or repeated vertices are dropped. Returns `null` when no triangle survives.
 - `raycastCollisionMesh` (function): function raycastCollisionMesh(mesh: PreparedCollisionMesh, origin: EntityPosition, direction: EntityPosition, maxDistance: number, position: EntityPosition, rotationY: number, scale: number, translate: EntityPosition): CollisionMeshHit | null — Nearest triangle hit for a world-space ray against a prepared mesh placed like its rendered model: model space scaled uniformly by `scale`, translated by entity-local `translate`, yaw-rotated by `rotationY`, and moved to `position` — the same composition {@link "scene/colliders".ModelBodySource} fitting applies to the AABB. Allocation-free until the returned hit. `distance` is world distance along `direction` (callers pass `direction` normalized); `normal` is the world-space geometric triangle normal facing the ray.
 
 ## @jgengine/core/scene/companion
@@ -1098,6 +1099,7 @@
 - `ParamSchema` (interface): interface ParamSchema — A kind's full parameter surface: an ordered list of fields the inspector renders top-to-bottom.
 - `ParsedParams` (type): type ParsedParams = Record<string, number | boolean | string | WeightedParamEntry[]> — Parsed params after `parseParams`: every schema field present with a validated, defaulted value.
 - `RangeParamField` (interface): interface RangeParamField — A numeric slider row: bounded range with a live readout.
+- `SceneKindCoverage` (interface): interface SceneKindCoverage — Marks a kind as *scatterable* — it fills an authored area with instances at one density under a bounded budget — so the editor renders the shared `CoverageSection` (Area → Assets → Density slider + budget note) that gives grass/scatter/city one authoring gesture. `spec` selects the unit + budget from `@jgengine/core/world/scatterCoverage`; `densityKey` is the single density slider hoisted into the coverage header (and hidden from the schema body below); `assetsKey` is the optional weighted "what fills it" palette summarized in the header.
 - `SceneKindDefinition` (interface): interface SceneKindDefinition<TResolved = unknown> — A registered scene kind — everything the editor/engine need to author and render a studio without bespoke code. `schema` drives the inspector + parse; `resolve` (optional) turns one document object into pure renderable data a matching `shell` renderer consumes; `add*` fields build the `+ Add` menu.
 - `SceneKindObject` (interface): interface SceneKindObject — The raw document object a resolver receives — shape shared by markers, volumes, and paths.
 - `SceneKindResolveContext` (interface): interface SceneKindResolveContext — Ground sampler + options a resolver may read (terrain height/normal snap).
@@ -1453,6 +1455,7 @@
 - `BuildingIndex` (interface): interface BuildingIndex — ⚠ undocumented
 - `BuildingPaletteOverrides` (type): type BuildingPaletteOverrides = Partial<BuildingPalette> — ⚠ undocumented
 - `BuildingStyle` (type): type BuildingStyle = | "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial" — ⚠ undocumented
+- `CITY_BUILDING_BUDGET` (const): const CITY_BUILDING_BUDGET: 2600 — Max buildings a single `city` district generates — the block/parcel pipeline's bounded lot cap.
 - `CITY_DEFAULTS` (const): const CITY_DEFAULTS: CityRules — City defaults: a zoned mixed metropolis — towers downtown, slabs mid-ring, houses at the edge.
 - `CITY_KIND` (const): const CITY_KIND: "city" — The editor volume kind marking a box as a procedural city district.
 - `CITY_LOT_CLASSES` (const): const CITY_LOT_CLASSES: readonly CityLotClass[] — All classes, for schema hints and validation.
@@ -1697,6 +1700,8 @@
 - `RosterEntry` (interface): interface RosterEntry — ⚠ undocumented
 - `RoundGround` (interface): interface RoundGround — A planet/sphere you play on the outside of. Sized by `radius` only.
 - `RoundGroundSize` (interface): interface RoundGroundSize — Size of a `round` ground: the planet/sphere radius in world units. Nothing else.
+- `SCATTER_COVERAGE_SPECS` (const): const SCATTER_COVERAGE_SPECS: Record<ScatterCoverageKind, ScatterCoverageSpec> — The coverage spec per scatterable kind — the single source for its unit + budget.
+- `SCATTER_INSTANCE_BUDGET` (const): const SCATTER_INSTANCE_BUDGET: 250000 — Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never renders more than this many placements regardless of density × area.
 - `SCATTER_PATH_KIND` (const): const SCATTER_PATH_KIND: "scatter" — The editor path kind that marks a closed polyline as a foliage/scatter region.
 - `SHAPE_BOX` (const): const SHAPE_BOX: 0 — ⚠ undocumented
 - `SHAPE_SPHERE` (const): const SHAPE_SPHERE: 1 — ⚠ undocumented
@@ -1710,6 +1715,9 @@
 - `SampleReason` (type): type SampleReason = "accepted" | "exhausted" | "empty-region" — Why a sample ended: a clean hit, budget exhausted, or the region was degenerate.
 - `SampleRegion` (interface): interface SampleRegion<P extends SamplePoint = SamplePoint> — A geometric region a sampler can draw from. Built-ins cover point sets, rect/box, circle/sphere, annulus/shell, polygon, and weighted composites; {@link customRegion} wraps a caller-defined sampler + bounds. `sample` draws one raw candidate under the region's own distribution policy; `contains` is the membership test reused for include/exclude constraints and rejection.
 - `SampleResult` (interface): interface SampleResult<P extends SamplePoint = SamplePoint> — Structured single-sample outcome — never a bare point, so failure and fallback are visible.
+- `ScatterCoverage` (interface): interface ScatterCoverage — A resolved coverage readout: how many instances an authored patch WANTS (`requested`, when it can be computed cheaply from geometry × density), how many it will actually place after the budget clamp (`count`), the `budget` ceiling, and whether the request hit it (`capped`). `requested` is `null` for kinds whose pre-cap ask is not knowable without running the generator (city, where the count comes from the resolved street fabric).
+- `ScatterCoverageKind` (type): type ScatterCoverageKind = "grass_field" | "scatter" | "city" — The shared "how much stuff grows here" contract for scatterable scene kinds (`grass_field` / `scatter` / `city`). Every scatterable kind fills an authored AREA with instances at a DENSITY, and every kind caps the placed count at a bounded BUDGET so a huge or dense request can never generate unbounded work. Before this module each kind hand-rolled its own readout and clamp story (grass silently capped in the renderer, scatter never capped, city had no budget note); this is the one place that
+- `ScatterCoverageSpec` (interface): interface ScatterCoverageSpec — Per-kind coverage descriptor: the unit noun, whether density is per-m², and the placement budget.
 - `ScatterInstance` (interface): interface ScatterInstance — ⚠ undocumented
 - `ScatterPoint` (interface): interface ScatterPoint — ⚠ undocumented
 - `ScatterTerrain` (interface): interface ScatterTerrain — Ground sampler a scatter resolve reads height/normal from (the sculpt terrain or the game's ground).
@@ -1848,6 +1856,7 @@
 - `boundaryNeighbors` (function): function boundaryNeighbors(grid: FootprintGrid, cells: readonly GridCell[]): AdjacentCell[] — Every occupied cell orthogonally touching `cells` but outside them — the connective-piece neighbor set.
 - `boxFormation` (function): function boxFormation(options: BoxFormationOptions): FormationSlotGenerator — A rectangular grid centered on the destination, front row toward `+forward` — a marching block or a phalanx. Rows fill front-to-back, left-to-right.
 - `boxRegion` (function): function boxRegion(min: Point3, max: Point3): SampleRegion<Point3> — An axis-aligned box `[min..max]` in 3D. Uniform density; draws x, y, z in order.
+- `budgetWarning` (function): function budgetWarning(coverage: ScatterCoverage): string — The shared clamp-and-warn clause every scatterable kind appends, worded identically: `""` when under budget, else ` · requested N, capped at M (budget)` when the pre-cap ask is known, or ` · capped at M (budget)` when only the ceiling is (city). This is the "surfaced, never silent" budget signal from #1112.
 - `buildContextMenu` (function): function buildContextMenu(input: BuildContextMenuInput): ContextMenu | null — Assemble a menu from a target's catalog verbs; null when the target lists none.
 - `buildRoadRibbon` (function): function buildRoadRibbon(path: readonly RoadPoint[], width: number, sampleHeight: (x: number, z: number) => number, options: RoadRibbonOptions = {}): RoadRibbon — Triangulate a road centerline into a ground-draped ribbon mesh: the polyline is subdivided, each vertex is offset half a `width` along the local perpendicular, and every vertex sits at `sampleHeight(x, z) + elevation`. Pure geometry — the shell (or any renderer) turns the result into a mesh, and tests can assert on it directly.
 - `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`.
@@ -1929,6 +1938,8 @@
 - `definePatrolOrder` (function): function definePatrolOrder<TCtx extends OrderMover>(config: OrderKindConfig & { arriveRadius?: number } = {}): OrderKind<TCtx, PatrolOrderPayload> — Patrol: walk a waypoint route, advancing the serialized `index` as each point is reached. Loops forever by default, or completes at the last waypoint when `loop` is `false`.
 - `defineStopOrder` (function): function defineStopOrder<TCtx extends OrderMover>(config: OrderKindConfig = {}): OrderKind<TCtx, EmptyOrderPayload> — Stop: halt immediately and complete the same tick — the interrupt that clears a unit's intent to standstill.
 - `defineTargetedOrder` (function): function defineTargetedOrder<TCtx extends OrderMover & OrderTargeting>(config: EngagementKindConfig = {}): OrderKind<TCtx, TargetedOrderPayload> — Targeted action: pursue one specific target until within `range`, writing the engagement intent into `order.state`. Completes when the target is gone (despawned/dead), so the game's effect loop runs while `inRange` is true.
+- `densityCoverage` (function): function densityCoverage(kind: "grass_field" | "scatter", area: number, density: number): ScatterCoverage — Coverage for a per-m² kind (`grass_field` / `scatter`): `requested = floor(density × area)`, clamped to the kind's budget. `capped` is true when the request exceeds the budget.
+- `describeScatterCoverage` (function): function describeScatterCoverage(coverage: ScatterCoverage): string — The full one-line coverage readout: `≈ N unit · A m²` plus the {@link budgetWarning} when capped.
 - `discRegion` (function): function discRegion(center: Vec2, radius: number, options: { distribution?: RadialDistribution } = {}): SampleRegion<Vec2> — A filled circle. `"area"` is area-uniform (√-corrected radius, even density); `"radial"` is radius-uniform (clumps toward the center). Angle is drawn first, then radius — matching the common `angle = rng()·2π; r = rng()·R` idiom so migrations keep their stream.
 - `distance` (function): function distance(a: Vec3, b: Vec3): number — ⚠ undocumented
 - `distance3` (function): function distance3(a: { x: number; y: number; z: number }, b: { x: number; y: number; z: number }): number — ⚠ undocumented
@@ -2002,6 +2013,7 @@
 - `placeAuthoredObjects` (function): function placeAuthoredObjects(store: AuthoredObjectPlaceTarget, objects: readonly AuthoredObject[], sampleHeight: (x: number, z: number) => number, options: PlaceAuthoredObjectsOptions = {}): string[] — Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus per-object and options vertical offsets. Returns the instance ids that were placed (or kept).
 - `placeAuthoredObjectsFromDocument` (function): function placeAuthoredObjectsFromDocument(store: AuthoredObjectPlaceTarget, document: AuthoredObjectsDocumentLike, sampleHeight: (x: number, z: number) => number, options: PlaceAuthoredObjectsOptions = {}): string[] — Convenience: resolve a document then place every authored catalog prop.
 - `placeFormation` (function): function placeFormation(destination: Vec2, facing: number, count: number, generator: FormationSlotGenerator): Vec2[] — Transform a generator's local slot offsets into world XZ positions around a `destination`, rotated by `facing` (engine yaw). Slot `i` in the returned array is `generator(count)[i]` mapped through the group frame, so it stays aligned with {@link assignFormationSlots}' slot indices. Pure and allocation- light: one array of `count` points, no per-call closures retained.
+- `placedCoverage` (function): function placedCoverage(kind: ScatterCoverageKind, area: number, placed: number): ScatterCoverage — Coverage for a kind whose placed `count` is already known from its generator (city, from its resolved lots). No pre-cap `requested` is available — the generator stops at the budget — so `capped` is inferred from the placed count reaching the ceiling.
 - `player` (function): function player(): PlayerBehavior — ⚠ undocumented
 - `plots` (function): function plots(config: PlotsWorldConfig = {}): WorldFeature — Declares a subdivided-plots world — farming, base-building, and other parcel-based layouts.
 - `pointGravity` (function): function pointGravity(options: PointGravityOptions): GravityField — Radial gravity toward one center, with optional inverse-square falloff for planetary worlds.
@@ -2057,6 +2069,8 @@
 - `sampleStratified` (function): function sampleStratified(options: StratifiedOptions): Vec2[] — Stratified 2D sampling: one jittered point per grid cell over `area`, in deterministic row-major order. Unlike pure rejection sampling this guarantees even coverage (no clumps, no gaps) — the distinct "stratified" distribution policy, kept separate from area-uniform draws.
 - `sanitizeGameTimeScale` (function): function sanitizeGameTimeScale(timeScale?: number | null): number — ⚠ undocumented
 - `scatter` (function): function scatter(config: ScatterConfig): ScatterPoint[] — ⚠ undocumented
+- `scatterCoverageSpec` (function): function scatterCoverageSpec(kind: string): ScatterCoverageSpec | null — The coverage spec for a scatterable kind, or `null` when the kind is not scatterable.
+- `scatterFootprintArea` (function): function scatterFootprintArea(object: { points?: readonly { x: number; z: number }[]; halfExtents?: { x: number; z: number }; radius?: number; }): number — Footprint area (m²) of a scatterable object: a closed path polygon (shoelace), a volume box (`halfExtents`), or a disc (`radius`). Structural so it accepts a `SceneKindObject`, an editor volume, or a scatter path without a hard type dependency.
 - `scatterItems` (function): function scatterItems<T>(field: RegionField<T>, area: Aabb, layersFor: (sample: RegionSample<T>) => readonly ScatterLayer[], options: { cell?: number; max?: number; saltKey?: number } = {}): ScatterInstance[] — Deterministically place opaque items across `area`, grounded on a region field. For each grid cell it asks `layersFor` which items may appear in that region and rolls one against their densities. The engine never interprets `item` — a game maps it to a mesh or entity. Content scatter (region-driven density) as opposed to `scatter` in `./scatter`, which is renderer-free geometric point distribution.
 - `scatterRegionEstimate` (function): function scatterRegionEstimate(path: ScenePathLike): { area: number; count: number } — Estimated placement count for a scatter path — density × polygon area, for a live UI readout.
 - `scatterRegionFromPath` (function): function scatterRegionFromPath(path: ScenePathLike): ScatterRegion | null — Builds a resolvable {@link ScatterRegion} from a scatter path (XZ polygon + rules), or null.
@@ -2750,6 +2764,21 @@
 - `scatter` (function): function scatter(config: ScatterConfig): ScatterPoint[] — ⚠ undocumented
 - `scatterAabb` (function): function scatterAabb(area: ScatterArea | Aabb): Aabb — ⚠ undocumented
 
+## @jgengine/core/world/scatterCoverage
+
+- `CITY_BUILDING_BUDGET` (const): const CITY_BUILDING_BUDGET: 2600 — Max buildings a single `city` district generates — the block/parcel pipeline's bounded lot cap.
+- `SCATTER_COVERAGE_SPECS` (const): const SCATTER_COVERAGE_SPECS: Record<ScatterCoverageKind, ScatterCoverageSpec> — The coverage spec per scatterable kind — the single source for its unit + budget.
+- `SCATTER_INSTANCE_BUDGET` (const): const SCATTER_INSTANCE_BUDGET: 250000 — Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never renders more than this many placements regardless of density × area.
+- `ScatterCoverage` (interface): interface ScatterCoverage — A resolved coverage readout: how many instances an authored patch WANTS (`requested`, when it can be computed cheaply from geometry × density), how many it will actually place after the budget clamp (`count`), the `budget` ceiling, and whether the request hit it (`capped`). `requested` is `null` for kinds whose pre-cap ask is not knowable without running the generator (city, where the count comes from the resolved street fabric).
+- `ScatterCoverageKind` (type): type ScatterCoverageKind = "grass_field" | "scatter" | "city" — The shared "how much stuff grows here" contract for scatterable scene kinds (`grass_field` / `scatter` / `city`). Every scatterable kind fills an authored AREA with instances at a DENSITY, and every kind caps the placed count at a bounded BUDGET so a huge or dense request can never generate unbounded work. Before this module each kind hand-rolled its own readout and clamp story (grass silently capped in the renderer, scatter never capped, city had no budget note); this is the one place that
+- `ScatterCoverageSpec` (interface): interface ScatterCoverageSpec — Per-kind coverage descriptor: the unit noun, whether density is per-m², and the placement budget.
+- `budgetWarning` (function): function budgetWarning(coverage: ScatterCoverage): string — The shared clamp-and-warn clause every scatterable kind appends, worded identically: `""` when under budget, else ` · requested N, capped at M (budget)` when the pre-cap ask is known, or ` · capped at M (budget)` when only the ceiling is (city). This is the "surfaced, never silent" budget signal from #1112.
+- `densityCoverage` (function): function densityCoverage(kind: "grass_field" | "scatter", area: number, density: number): ScatterCoverage — Coverage for a per-m² kind (`grass_field` / `scatter`): `requested = floor(density × area)`, clamped to the kind's budget. `capped` is true when the request exceeds the budget.
+- `describeScatterCoverage` (function): function describeScatterCoverage(coverage: ScatterCoverage): string — The full one-line coverage readout: `≈ N unit · A m²` plus the {@link budgetWarning} when capped.
+- `placedCoverage` (function): function placedCoverage(kind: ScatterCoverageKind, area: number, placed: number): ScatterCoverage — Coverage for a kind whose placed `count` is already known from its generator (city, from its resolved lots). No pre-cap `requested` is available — the generator stops at the budget — so `capped` is inferred from the placed count reaching the ceiling.
+- `scatterCoverageSpec` (function): function scatterCoverageSpec(kind: string): ScatterCoverageSpec | null — The coverage spec for a scatterable kind, or `null` when the kind is not scatterable.
+- `scatterFootprintArea` (function): function scatterFootprintArea(object: { points?: readonly { x: number; z: number }[]; halfExtents?: { x: number; z: number }; radius?: number; }): number — Footprint area (m²) of a scatterable object: a closed path polygon (shoelace), a volume box (`halfExtents`), or a disc (`radius`). Structural so it accepts a `SceneKindObject`, an editor volume, or a scatter path without a hard type dependency.
+
 ## @jgengine/core/world/scatterItems
 
 - `ScatterInstance` (interface): interface ScatterInstance — ⚠ undocumented

package/skills/jgengine-world/capabilities.md

@@ -355,6 +355,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `controlGroupKey` (function) · `import { controlGroupKey } from "@jgengine/core/world"`
 - `resolveControlGroupIntent` (function) · `import { resolveControlGroupIntent } from "@jgengine/core/world"`
 
+## scatter-coverage — shared density/budget semantics for scatterable kinds
+
+- `ScatterCoverageKind` (type) · `import { ScatterCoverageKind } from "@jgengine/core/world"`
+
 ## selection-bookmark-recall — fold a saved set into the active selection with stale-ref pruning and a caller focus hook
 
 - `recallSelectionBookmark` (function) · `import { recallSelectionBookmark } from "@jgengine/core/world"`