@jgengine/shell 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -26,6 +26,20 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.24.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.24.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.21.0`; `@jgengine/github` is `0.11.0`.
+
+### Added
+
+- `buildGroundCoverageMask`, `createGroundEdgeFade` and `applyGroundEdgeFade` (`@jgengine/shell/terrain`) fade any ground material out at the outer edge of a merged mesh footprint, leaving seams between layers inside it crisp.
+
+### Changed
+
+- City studio ground (roads, junctions, block land, sidewalks, medians, drives, parks, crops, curbs, markings) now fades into the terrain where the town's ground ends instead of stopping at a hard edge. `meta.edgeFade: false` on the city volume keeps the old hard edge.
+
 ## 0.23.0
 
 ### Migrate

package/dist/scene/CityRenderer.js

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

package/dist/terrain/groundEdgeFade.d.ts

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

package/dist/terrain/groundEdgeFade.js

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

package/dist/terrain/index.d.ts

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

package/dist/terrain/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.23.0",
-    "@jgengine/react": "^0.23.0",
-    "@jgengine/ws": "^0.23.0"
+    "@jgengine/core": "^0.24.0",
+    "@jgengine/react": "^0.24.0",
+    "@jgengine/ws": "^0.24.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.23.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.24.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -232,7 +232,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.23.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.24.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/api.md

@@ -2828,6 +2828,9 @@
 - `GrassRange` (type): type GrassRange = number | readonly [min: number, max: number] — ⚠ undocumented
 - `GrassShaderUniforms` (interface): interface GrassShaderUniforms { uTime: THREE.IUniform<number>; uWindDirection: THREE.IUniform<THREE.Vector2>; uWindStrength: THREE.IUniform<number>; uWindSpeed: THREE.IUniform<number>; uWindGustScale: THREE.IUniform<number>; uWindFlutter: THREE.IUniform<number>; uColorB… — ⚠ undocumented
 - `GrassWindOptions` (interface): interface GrassWindOptions { direction?: readonly [x: number, z: number]; strength?: number; speed?: number; gustScale?: number; flutter?: number; layered?: boolean } — ⚠ undocumented
+- `GroundCoverageMask` (interface): interface GroundCoverageMask — How far each point of a merged ground footprint lies inside its outer edge, as a grid over world XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+- `GroundCoverageOptions` (interface): interface GroundCoverageOptions — Options for {@link buildGroundCoverageMask}.
+- `GroundEdgeFade` (interface): interface GroundEdgeFade — Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile.
 - `HeightfieldColorFn` (type): type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void — Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`.
 - `HeightfieldDisplaceOptions` (interface): interface HeightfieldDisplaceOptions — Options for {@link displaceHeightfieldGeometry}.
 - `HeightfieldRect` (interface): interface HeightfieldRect — XZ rectangle in world units — matches the shape of a terraform snapshot's `bounds`.
@@ -2861,6 +2864,9 @@
 - `TerrainSurfaceClass` (type): type TerrainSurfaceClass = "ground" | "grass" | "dirt" | "gravel" | "rock" | "sand" | "mud" | "snow" | "road" — Procedural ground response the terrain shader renders for a painted surface id.
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
+- `applyGroundEdgeFade` (function): function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M — Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge, opaque `width` metres inside, with a noise-broken line. Seams between layers inside the footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+- `buildGroundCoverageMask` (function): function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null — Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+- `createGroundEdgeFade` (function): function createGroundEdgeFade(): GroundEdgeFade — Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
 - `createSurfaceRibbonMaterial` (function): function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial — A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own procedural surface functions, so a dirt track or asphalt strip matches painted ground: the authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
 - `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground. Paint lives on a coarse cell grid; when the source exposes that grid, each sample smoothly blends the four surrounding cell centres (unpainted cells contribute the caller's base color in `out`), so painted paths and clearings get soft edges instead of grid-aligned stair steps.
 - `createTerrainPaintTextures` (function): function createTerrainPaintTextures(weights: TerrainPaintWeights): TerrainPaintTextures — Uploads packed paint coverage ({@link packTerrainPaintWeights}) as two linear-filtered RGBA textures plus per-slot hue, surface class, roughness and pattern scale for the terrain surface material.
@@ -2893,6 +2899,9 @@
 - `GrassRange` (type): type GrassRange = number | readonly [min: number, max: number] — ⚠ undocumented
 - `GrassShaderUniforms` (interface): interface GrassShaderUniforms { uTime: THREE.IUniform<number>; uWindDirection: THREE.IUniform<THREE.Vector2>; uWindStrength: THREE.IUniform<number>; uWindSpeed: THREE.IUniform<number>; uWindGustScale: THREE.IUniform<number>; uWindFlutter: THREE.IUniform<number>; uColorB… — ⚠ undocumented
 - `GrassWindOptions` (interface): interface GrassWindOptions { direction?: readonly [x: number, z: number]; strength?: number; speed?: number; gustScale?: number; flutter?: number; layered?: boolean } — ⚠ undocumented
+- `GroundCoverageMask` (interface): interface GroundCoverageMask — How far each point of a merged ground footprint lies inside its outer edge, as a grid over world XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+- `GroundCoverageOptions` (interface): interface GroundCoverageOptions — Options for {@link buildGroundCoverageMask}.
+- `GroundEdgeFade` (interface): interface GroundEdgeFade — Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile.
 - `HeightfieldColorFn` (type): type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void — Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`.
 - `HeightfieldDisplaceOptions` (interface): interface HeightfieldDisplaceOptions — Options for {@link displaceHeightfieldGeometry}.
 - `HeightfieldRect` (interface): interface HeightfieldRect — XZ rectangle in world units — matches the shape of a terraform snapshot's `bounds`.
@@ -2926,6 +2935,9 @@
 - `TerrainSurfaceClass` (type): type TerrainSurfaceClass = "ground" | "grass" | "dirt" | "gravel" | "rock" | "sand" | "mud" | "snow" | "road" — Procedural ground response the terrain shader renders for a painted surface id.
 - `TerrainSurfaceColorOptions` (interface): interface TerrainSurfaceColorOptions — Slope/noise surface shading laid over the height lerp so untextured ground reads like terrain instead of a smooth two-tone gradient. All knobs are optional with sane defaults; every field is a pure function of vertex position (+ `seed`), so the coloring is stable across rebuilds and tests.
 - `TerrainVertexColorOptions` (interface): interface TerrainVertexColorOptions { low?: THREE.ColorRepresentation; high?: THREE.ColorRepresentation; waterline?: THREE.ColorRepresentation; waterlineHeight?: number } — ⚠ undocumented
+- `applyGroundEdgeFade` (function): function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M — Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge, opaque `width` metres inside, with a noise-broken line. Seams between layers inside the footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+- `buildGroundCoverageMask` (function): function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null — Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+- `createGroundEdgeFade` (function): function createGroundEdgeFade(): GroundEdgeFade — Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
 - `createSurfaceRibbonMaterial` (function): function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial — A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own procedural surface functions, so a dirt track or asphalt strip matches painted ground: the authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
 - `createTerrainPaintColorSampler` (function): function createTerrainPaintColorSampler(terrain: TerrainPaintSource): TerrainPaintColorSampler — Shares layer tint, opacity and linear weighted-color blending between editor and runtime ground. Paint lives on a coarse cell grid; when the source exposes that grid, each sample smoothly blends the four surrounding cell centres (unpainted cells contribute the caller's base color in `out`), so painted paths and clearings get soft edges instead of grid-aligned stair steps.
 - `createTerrainPaintTextures` (function): function createTerrainPaintTextures(weights: TerrainPaintWeights): TerrainPaintTextures — Uploads packed paint coverage ({@link packTerrainPaintWeights}) as two linear-filtered RGBA textures plus per-slot hue, surface class, roughness and pattern scale for the terrain surface material.
@@ -2991,6 +3003,15 @@
 - `GrassShaderUniforms` (interface): interface GrassShaderUniforms { uTime: THREE.IUniform<number>; uWindDirection: THREE.IUniform<THREE.Vector2>; uWindStrength: THREE.IUniform<number>; uWindSpeed: THREE.IUniform<number>; uWindGustScale: THREE.IUniform<number>; uWindFlutter: THREE.IUniform<number>; uColorB… — ⚠ undocumented
 - `GrassWindOptions` (interface): interface GrassWindOptions { direction?: readonly [x: number, z: number]; strength?: number; speed?: number; gustScale?: number; flutter?: number; layered?: boolean } — ⚠ undocumented
 
+## @jgengine/shell/terrain/groundEdgeFade
+
+- `GroundCoverageMask` (interface): interface GroundCoverageMask — How far each point of a merged ground footprint lies inside its outer edge, as a grid over world XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+- `GroundCoverageOptions` (interface): interface GroundCoverageOptions — Options for {@link buildGroundCoverageMask}.
+- `GroundEdgeFade` (interface): interface GroundEdgeFade — Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile.
+- `applyGroundEdgeFade` (function): function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M — Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge, opaque `width` metres inside, with a noise-broken line. Seams between layers inside the footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+- `buildGroundCoverageMask` (function): function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null — Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+- `createGroundEdgeFade` (function): function createGroundEdgeFade(): GroundEdgeFade — Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
+
 ## @jgengine/shell/terrain/heightfieldGeometry
 
 - `HeightfieldColorFn` (type): type HeightfieldColorFn = (x: number, z: number, height: number, out: THREE.Color) => void — Per-vertex color hook for {@link displaceHeightfieldGeometry}; write the tone into `out`.

package/skills/jgengine-ui/capabilities.md

@@ -266,6 +266,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `GameContextBridge` (function) · `import { GameContextBridge } from "@jgengine/react"`
 
+## ground-edge-fade — fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+
+- `applyGroundEdgeFade` (function) · `import { applyGroundEdgeFade } from "@jgengine/shell/terrain"`
+- `buildGroundCoverageMask` (function) · `import { buildGroundCoverageMask } from "@jgengine/shell/terrain"`
+- `createGroundEdgeFade` (function) · `import { createGroundEdgeFade } from "@jgengine/shell/terrain"`
+
 ## heavy-models — models over the per-model triangle budget, for perf probes and smoke assertions
 
 - `heavyModels` (function) · `import { heavyModels } from "@jgengine/shell/render/modelLoad"`

package/skills/jgengine-world/reference.md

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