@jgengine/shell 0.21.0 → 0.23.0

package/dist/scene/GrassFieldRenderer.js

@@ -1,6 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useMemo } from "react";
 import { resolveGrassObject } from "@jgengine/core/world/grassKind";
+import { clearanceMasksFrom, DEFAULT_CLEARANCE_KINDS } from "@jgengine/core/world/scatterRegion";
+import { masksInfluence } from "@jgengine/core/world/geometry";
 import { GrassField } from "../terrain/GrassField.js";
 import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
 /** Volume kinds turf yields to — blades never grow through cracked soil or out of open water. */
@@ -47,9 +49,25 @@ function sampleHeight(field, x, z) {
  */
 function OneGrass({ object, context }) {
     const resolved = useMemo(() => resolveGrassObject(object), [object]);
-    const heightAt = useCallback((x, z) => sampleHeight(context.field, x, z), [context.field]);
+    const heightAt = useCallback((x, z) => resolved === null ? 0 :
+        sampleHeight(context.field, x + resolved.center[0], z + resolved.center[2]) - resolved.center[1], [context.field, resolved]);
     const area = useMemo(() => (resolved === null ? null : [resolved.size[0], resolved.size[1]]), [resolved]);
     const bladeHeight = useMemo(() => (resolved === null ? null : [resolved.rules.bladeHeight * 0.7, resolved.rules.bladeHeight]), [resolved]);
+    const bladeWidth = useMemo(() => resolved === null ? undefined : [resolved.rules.bladeWidthMin, resolved.rules.bladeWidthMax], [resolved]);
+    const bladeBend = useMemo(() => resolved === null ? undefined : [resolved.rules.bladeBendMin, resolved.rules.bladeBendMax], [resolved]);
+    const { markers, paths } = context.document;
+    const masks = useMemo(() => {
+        const authored = clearanceMasksFrom(context.document, {
+            kinds: [...DEFAULT_CLEARANCE_KINDS, "road", "walkway", "route", "path"],
+        });
+        // Keep the entire authored footing clear; feather regrowth outside its edge.
+        return {
+            discs: authored.discs.map(zone => ({ ...zone, radius: zone.radius + (zone.feather ?? 0) })),
+            corridors: authored.corridors.map(zone => ({ ...zone, halfWidth: zone.halfWidth + (zone.feather ?? 0) })),
+        };
+    }, [markers, paths, context.document.volumes]);
+    const coverageAt = useCallback((x, z) => resolved === null ? 0 :
+        1 - masksInfluence(x + resolved.center[0], z + resolved.center[2], masks), [resolved, masks]);
     const wind = useMemo(() => resolved === null
         ? null
         : { strength: resolved.rules.windStrength, speed: resolved.rules.windSpeed, gustScale: resolved.rules.windGust }, [resolved]);
@@ -68,7 +86,7 @@ function OneGrass({ object, context }) {
     // footprint, and the fade only thins how many *draw* at range in the vertex shader — so a deeper
     // meadow reads expansive without raising the instance ceiling.
     const instanceCount = Math.max(1500, Math.min(250000, Math.ceil(rules.density * area[0] * area[1])));
-    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, wind: wind, edgeFeather: 2.2, exclude: exclude }));
+    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude }));
 }
 /** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
 export function registerGrassFieldRenderer() {

package/dist/scene/cityJunctionSurface.d.ts

@@ -0,0 +1,7 @@
+import type { CityIntersection, CityStreet } from "@jgengine/core/world/cityKind";
+/**
+ * Surface for a crossing's welded patch: gravel only when every street running through the crossing
+ * is gravel, so an unpaved hamlet's junctions stay gravel while a lane meeting a paved main stays asphalt.
+ * @internal
+ */
+export declare function junctionSurface(cross: Pick<CityIntersection, "x" | "z" | "radius">, streets: readonly Pick<CityStreet, "points" | "width" | "surface">[]): CityStreet["surface"];

package/dist/scene/cityJunctionSurface.js

@@ -0,0 +1,34 @@
+/**
+ * Surface for a crossing's welded patch: gravel only when every street running through the crossing
+ * is gravel, so an unpaved hamlet's junctions stay gravel while a lane meeting a paved main stays asphalt.
+ * @internal
+ */
+export function junctionSurface(cross, streets) {
+    let touched = false;
+    for (const street of streets) {
+        const reach = cross.radius + street.width * 0.5 + 0.5;
+        if (distanceToPath(cross.x, cross.z, street.points) > reach)
+            continue;
+        if (street.surface !== "gravel")
+            return "asphalt";
+        touched = true;
+    }
+    return touched ? "gravel" : "asphalt";
+}
+function distanceToPath(x, z, points) {
+    if (points.length === 0)
+        return Infinity;
+    if (points.length === 1)
+        return Math.hypot(x - points[0][0], z - points[0][1]);
+    let best = Infinity;
+    for (let i = 1; i < points.length; i += 1) {
+        const [ax, az] = points[i - 1];
+        const [bx, bz] = points[i];
+        const dx = bx - ax;
+        const dz = bz - az;
+        const len2 = dx * dx + dz * dz;
+        const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((x - ax) * dx + (z - az) * dz) / len2));
+        best = Math.min(best, Math.hypot(x - (ax + dx * t), z - (az + dz * t)));
+    }
+    return best;
+}

package/dist/settings/settingsController.js

@@ -51,7 +51,7 @@ export function useSettingsCategories(config) {
             const id = busVolumeSettingId(bus.id);
             return {
                 id,
-                label: `${bus.id.charAt(0).toUpperCase()}${bus.id.slice(1)} volume`,
+                label: bus.id === "ui" ? "UI volume" : `${bus.id.charAt(0).toUpperCase()}${bus.id.slice(1)} volume`,
                 kind: "slider",
                 value: store.get(id, bus.gain ?? 1),
                 min: 0,

package/dist/terrain/CarvedTerrain.d.ts

@@ -11,6 +11,7 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
     colors?: FieldGroundOptions["colors"];
     heightRange?: FieldGroundOptions["heightRange"];
     paletteAt?: FieldGroundOptions["paletteAt"];
+    paintColorAt?: FieldGroundOptions["paintColorAt"];
     roughness?: number;
     metalness?: number;
     /** Override the default vertex-colour material (e.g. a procedural detail material). The caller owns its lifecycle; it is not disposed here. */
@@ -23,4 +24,4 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -8,8 +8,8 @@ import { createFieldGroundGeometry } from "./terrainMath.js";
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
-    const geometry = useDisposable(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt }), [field, size, segments, center, colors, heightRange, paletteAt, epoch]);
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
+    const geometry = useDisposable(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt, paintColorAt }), [field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, epoch]);
     const defaultMaterial = useDisposable(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
     const material = surfaceMaterial ?? defaultMaterial;
     return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });

package/dist/terrain/GrassField.d.ts

@@ -19,6 +19,7 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     edgeFeather?: number;
     exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
+    coverageAt?: TerrainHeightSampler;
     colorBase?: GrassMaterialOptions["colorBase"];
     colorTip?: GrassMaterialOptions["colorTip"];
     colorGround?: GrassMaterialOptions["colorGround"];
@@ -29,4 +30,4 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     roughness?: number;
 }
 /** Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades. */
-export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }: GrassFieldProps): import("react").JSX.Element;
+export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, coverageAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }: GrassFieldProps): import("react").JSX.Element;

package/dist/terrain/GrassField.js

@@ -9,7 +9,7 @@ import { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget,
 export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
 export { GRASS_TUFT_BLADES } from "./grassGeometry.js";
 /** Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades. */
-export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, tuftBlades = GRASS_TUFT_BLADES, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }) {
+export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, tuftBlades = GRASS_TUFT_BLADES, tuftRadius, edgeFeather, exclude, heightAt, coverageAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }) {
     const chunks = useMemo(() => createGrassGeometryChunks({
         count,
         area,
@@ -23,7 +23,8 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         ...(edgeFeather === undefined ? {} : { edgeFeather }),
         ...(exclude === undefined ? {} : { exclude }),
         heightAt,
-    }), [area, bladeBend, bladeHeight, bladeWidth, count, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
+        coverageAt,
+    }), [area, bladeBend, bladeHeight, bladeWidth, count, coverageAt, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
     useDisposable(() => chunks.map((chunk) => chunk.geometry), [chunks]);
     const handle = useMemo(() => createGrassMaterial({
         colorBase,

package/dist/terrain/grassGeometry.d.ts

@@ -31,6 +31,8 @@ export interface GrassBladeGeometryOptions {
     /** Patch-local rectangles kept clear of blades (soil patches, water) with a soft regrow ramp. */
     exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
+    /** Patch-local coverage, 0..1, composed with explicit rectangular exclusions. */
+    coverageAt?: TerrainHeightSampler;
 }
 export interface ResolvedGrassBladeGeometryOptions {
     count: number;
@@ -45,6 +47,7 @@ export interface ResolvedGrassBladeGeometryOptions {
     edgeFeather: number;
     exclude: readonly GrassExclusion[];
     heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
 }
 /** @internal */
 export declare function resolveGrassRange(value: GrassRange | undefined, fallback: readonly [number, number]): readonly [number, number];

package/dist/terrain/grassGeometry.js

@@ -24,6 +24,7 @@ export function resolveGrassBladeGeometryOptions(options = {}) {
         edgeFeather: Math.max(0, options.edgeFeather ?? 1.5),
         exclude: options.exclude ?? [],
         heightAt: options.heightAt ?? (() => 0),
+        coverageAt: options.coverageAt ?? (() => 1),
     };
 }
 /** Tuft instances needed to carry `bladeCount` blades at `tuftBlades` blades per tuft. @internal */
@@ -123,7 +124,7 @@ export function createGrassBladeGeometry(options = {}) {
             const d = Math.max(Math.abs(x - zone.center[0]) - zone.half[0], Math.abs(z - zone.center[1]) - zone.half[1]);
             heightScale *= Math.min(1, Math.max(0, d / Math.max(0.001, zone.feather ?? 1.5)));
         }
-        heights[index] = heightScale;
+        heights[index] = heightScale * Math.max(0, Math.min(1, resolved.coverageAt(x, z)));
         widths[index] = randomRange(random, resolved.width);
         bend[index] = randomRange(random, resolved.bend);
         phase[index] = random() * Math.PI * 2;

package/dist/terrain/index.d.ts

@@ -9,3 +9,8 @@ export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMa
 export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "./random.js";
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainSurfaceColorOptions, type TerrainVertexColorOptions, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, type FractalNoiseConfig, type NoiseFieldConfig, type TerrainField, type TerrainNormal, } from "@jgengine/core/world/terrain";
+export { createTerrainPaintColorSampler, type TerrainPaintColorSampler, type TerrainPaintSource } from "./terrainPaintColor.js";
+export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, type TerrainDetailMaterialHandle, type TerrainDetailMaterialOptions, type TerrainDetailMaterialTextures, } from "./terrainDetailMaterial.js";
+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";

package/dist/terrain/index.js

@@ -9,3 +9,8 @@ export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./gr
 export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";
+export { createTerrainPaintColorSampler } from "./terrainPaintColor.js";
+export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, } from "./terrainDetailMaterial.js";
+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";

package/dist/terrain/surfaceRibbonMaterial.d.ts

@@ -0,0 +1,62 @@
+import * as THREE from "three";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+/** Vertex attribute {@link ribbonSurfaceFrame} fills: metres along the ribbon, signed metres across it, metres to its far end. */
+export declare const RIBBON_FRAME_ATTRIBUTE = "jgRibbon";
+/** How a ground ribbon (path, road, sidewalk) shades: procedural surface, edge blend and wear. */
+export interface RibbonSurfaceStyle {
+    /** Surface id classified like terrain paint (`"dirt"`, `"gravel"`, `"asphalt"`, …). */
+    surface: string;
+    /** Width of the edge fade in metres, centred on the authored edge. 0 keeps a hard opaque edge. */
+    feather: number;
+    /** How far noise pushes the edge in or out, in metres. */
+    warp: number;
+    /** Wheel ruts on soft ground, polished tyre lanes on pavement, 0..1. */
+    wear: number;
+}
+/** Options for {@link createSurfaceRibbonMaterial}. */
+export interface SurfaceRibbonMaterialOptions extends Partial<RibbonSurfaceStyle> {
+    /** Authored hue; the procedural surface varies around it. */
+    color: string;
+    /** Authored half width in metres; the edge fade is centred on it. */
+    halfWidth: number;
+    /** Override the surface class's default roughness. */
+    roughness?: number;
+    /** Pattern frequency multiplier. Default 1. */
+    scale?: number;
+    /** Graphics tier, from `useTerrainQuality()`. `low` drops micro-normals and fine octaves. Default `high`. */
+    quality?: GraphicsQuality;
+    /** Pull the ribbon toward the camera in depth so it wins over a coplanar layer beneath. */
+    polygonOffset?: boolean;
+    /** Multiply by the geometry's `color` attribute, as city ground meshes carry per-vertex tints. */
+    vertexColors?: boolean;
+}
+/**
+ * Default ribbon look for an authored path: the surface comes from `meta.surface`, else the path
+ * kind (`"road"` paves, `"gravel-track"` gravels), else dirt. Soft ground gets a noise-warped edge
+ * that fades into the terrain and wheel ruts; pavement keeps a near-hard edge and faint tyre lanes.
+ * `meta.surfaceDetail: false` (or `meta.surface: false`) returns `null` for the old flat ribbon;
+ * `meta.edgeSoftness` scales the fade (0 = hard) and `meta.wear` sets wear 0..1.
+ */
+export declare function resolvePathSurface(kind: string, width: number, meta: Readonly<Record<string, unknown>> | undefined): RibbonSurfaceStyle | null;
+/** Extra ribbon width (metres, both sides together) a style needs so its fade straddles the authored edge. */
+export declare function ribbonEdgeMargin(style: Pick<RibbonSurfaceStyle, "feather" | "warp">): number;
+/**
+ * Per-vertex `(along, across, toEnd)` for a ribbon in `buildRoadRibbon`'s layout (left/right vertex
+ * pairs down the centreline). Pass several ribbons' position arrays to get one concatenated frame
+ * for a merged mesh; each ribbon's distances restart at its own start.
+ */
+export declare function ribbonSurfaceFrame(ribbons: readonly Float32Array[]): Float32Array;
+/**
+ * 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.
+ */
+export declare function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial;
+/**
+ * {@link createSurfaceRibbonMaterial} for a React mesh: rebuilt only when an option changes and
+ * disposed on unmount. Pass `null` to get `null` (the caller falls back to a flat material).
+ */
+export declare function useSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions | null): THREE.MeshStandardMaterial | null;

package/dist/terrain/surfaceRibbonMaterial.js

@@ -0,0 +1,227 @@
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { NOISE_GLSL, SURFACE_BUMP_NORMAL_GLSL, SURFACE_FUNCTIONS_GLSL } from "./terrainSurfaceShader.js";
+import { terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness } from "./terrainSurfaces.js";
+/** Vertex attribute {@link ribbonSurfaceFrame} fills: metres along the ribbon, signed metres across it, metres to its far end. */
+export const RIBBON_FRAME_ATTRIBUTE = "jgRibbon";
+const SOFT_GROUND = new Set(["dirt", "mud", "sand", "gravel", "grass", "ground", "snow"]);
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * Default ribbon look for an authored path: the surface comes from `meta.surface`, else the path
+ * kind (`"road"` paves, `"gravel-track"` gravels), else dirt. Soft ground gets a noise-warped edge
+ * that fades into the terrain and wheel ruts; pavement keeps a near-hard edge and faint tyre lanes.
+ * `meta.surfaceDetail: false` (or `meta.surface: false`) returns `null` for the old flat ribbon;
+ * `meta.edgeSoftness` scales the fade (0 = hard) and `meta.wear` sets wear 0..1.
+ */
+export function resolvePathSurface(kind, width, meta) {
+    if (meta?.["surfaceDetail"] === false || meta?.["surface"] === false)
+        return null;
+    const id = typeof meta?.["surface"] === "string" ? meta["surface"] : kind;
+    const classified = terrainSurfaceClass(id);
+    const cls = classified === "ground" ? "dirt" : classified;
+    const surface = classified === "ground" ? "dirt" : id;
+    const soft = SOFT_GROUND.has(cls);
+    const softness = typeof meta?.["edgeSoftness"] === "number" ? Math.max(0, meta["edgeSoftness"]) : 1;
+    const feather = (soft ? clamp(width * 0.18, 0.35, 1.6) : clamp(width * 0.04, 0.08, 0.3)) * softness;
+    const warp = (soft ? clamp(width * 0.08, 0.15, 0.6) : 0.03) * softness;
+    const wear = typeof meta?.["wear"] === "number" ? clamp(meta["wear"], 0, 1) : soft ? 1 : 0.6;
+    return { surface, feather, warp, wear };
+}
+/** Extra ribbon width (metres, both sides together) a style needs so its fade straddles the authored edge. */
+export function ribbonEdgeMargin(style) {
+    return style.feather + style.warp * 2;
+}
+/**
+ * Per-vertex `(along, across, toEnd)` for a ribbon in `buildRoadRibbon`'s layout (left/right vertex
+ * pairs down the centreline). Pass several ribbons' position arrays to get one concatenated frame
+ * for a merged mesh; each ribbon's distances restart at its own start.
+ */
+export function ribbonSurfaceFrame(ribbons) {
+    const total = ribbons.reduce((sum, positions) => sum + positions.length, 0);
+    const out = new Float32Array(total);
+    let offset = 0;
+    for (const p of ribbons) {
+        const pairs = Math.floor(p.length / 6);
+        let along = 0;
+        let px = 0;
+        let pz = 0;
+        for (let i = 0; i < pairs; i++) {
+            const b = i * 6;
+            const cx = (p[b] + p[b + 3]) / 2;
+            const cz = (p[b + 2] + p[b + 5]) / 2;
+            if (i > 0)
+                along += Math.hypot(cx - px, cz - pz);
+            px = cx;
+            pz = cz;
+            const half = Math.hypot(p[b] - p[b + 3], p[b + 2] - p[b + 5]) / 2;
+            out[offset + b] = along;
+            out[offset + b + 1] = half;
+            out[offset + b + 3] = along;
+            out[offset + b + 4] = -half;
+        }
+        for (let i = 0; i < pairs; i++) {
+            const b = offset + i * 6;
+            out[b + 2] = along - out[b];
+            out[b + 5] = along - out[b + 3];
+        }
+        offset += p.length;
+    }
+    return out;
+}
+const RIBBON_FRAGMENT_GLSL = /* glsl */ `
+vec2 jgWp = vJgWorldPos.xz;
+jgFootprint = max(length(dFdx(vJgWorldPos)), length(dFdy(vJgWorldPos)));
+JgSurf jgS = jgSurface(JG_RIBBON_CLASS, diffuseColor.rgb, uJgRough, uJgScale, vJgWorldPos);
+vec3 jgCol = jgS.albedo;
+float jgRough = jgS.rough;
+float jgBumpH = jgS.bump;
+float jgAcross = vJgRibbon.y;
+jgCol *= 1.0 + (jgFbm2(jgWp / 14.0 + vec2(3.7, 61.2)) - 0.5) * 0.24;
+#if defined(JG_RIBBON_PAVED) && !defined(JG_SURFACE_LOW)
+{
+  // Weathered pavement: resurfaced patches, exposed aggregate and a partial crack network.
+  jgCol *= 1.0 + (jgFbm3o(jgWp / 5.0 + 11.0) - 0.5) * 0.34;
+  jgCol *= 1.0 + (jgVNoise(jgWp * 16.0) - 0.5) * 0.26 * jgBand(16.0);
+  vec3 jgCell = jgVoronoi(jgWp * 0.32 + 5.1);
+  float jgCrack = (1.0 - smoothstep(0.0, 0.03, jgCell.y)) * smoothstep(0.45, 0.6, jgVNoise(jgWp * 0.45 + 3.3)) * jgBand(2.0);
+  jgCol *= 1.0 - 0.4 * jgCrack;
+  jgRough += 0.05 * jgCrack;
+  jgBumpH -= jgCrack * 0.004;
+}
+#endif
+#ifdef JG_RIBBON_WEAR
+{
+  // Two wheel tracks a cart-axle apart, wandering together along the ribbon.
+  float jgWob = (jgVNoise(vec2(vJgRibbon.x * 0.09, 4.7)) - 0.5) * uJgHalfWidth * 0.35;
+  float jgRutD = abs(abs(jgAcross - jgWob) - uJgHalfWidth * 0.45);
+  float jgRutW = max(0.15, uJgHalfWidth * 0.14);
+  float jgRut = exp(-(jgRutD * jgRutD) / (jgRutW * jgRutW)) * (0.55 + 0.45 * jgVNoise(vec2(vJgRibbon.x * 0.4, 9.1))) * uJgWear;
+#ifdef JG_RIBBON_PAVED
+  jgCol *= 1.0 - 0.22 * jgRut;
+  jgRough -= 0.16 * jgRut;
+#else
+  // Trodden band: packed flat, fewer loose grains and a little dustier, so the track reads against
+  // painted dirt of the same hue; then darker ruts and loose soil heaped toward the shoulders.
+  float jgTrod = (1.0 - smoothstep(uJgHalfWidth * 0.5, uJgHalfWidth * 0.95, abs(jgAcross))) * uJgWear;
+  jgCol = mix(jgCol, diffuseColor.rgb * (0.96 + 0.12 * jgFbm2(jgWp * 0.7 + 2.9)), 0.5 * jgTrod);
+  jgCol *= 1.0 + 0.08 * jgTrod;
+  jgBumpH *= 1.0 - 0.6 * jgTrod;
+  jgCol *= 1.0 - 0.32 * jgRut;
+  jgRough -= 0.12 * jgRut;
+  jgBumpH -= jgRut * 0.03;
+  float jgShoulder = smoothstep(uJgHalfWidth * 0.6, uJgHalfWidth, abs(jgAcross)) * uJgWear;
+  jgCol *= 1.0 - 0.16 * jgShoulder;
+  jgBumpH += jgShoulder * 0.014;
+#endif
+}
+#endif
+#ifdef JG_RIBBON_EDGE
+{
+  float jgEdgeN = (jgFbm2(jgWp * 0.55 + 7.3) - 0.5) * 2.0 + (jgVNoise(jgWp * 2.3 + 1.7) - 0.5) * 0.6;
+  float jgEdge = uJgHalfWidth + jgEdgeN * uJgWarp;
+  float jgAlpha = 1.0 - smoothstep(jgEdge - uJgFeather * 0.5, jgEdge + uJgFeather * 0.5, abs(jgAcross));
+  jgAlpha *= smoothstep(0.0, uJgFeather, min(vJgRibbon.x, vJgRibbon.z) + jgEdgeN * uJgWarp);
+  // Taller grains (pebbles, clods) hold on longer, so the edge breaks up instead of fading evenly.
+  jgAlpha = clamp(jgAlpha + (jgS.height - 0.4) * 2.4 * jgAlpha * (1.0 - jgAlpha), 0.0, 1.0);
+  diffuseColor.a *= jgAlpha;
+  jgBumpH *= jgAlpha;
+}
+#endif
+#ifdef USE_COLOR_ALPHA
+{
+  // A per-vertex fade interpolated across big triangles draws straight iso-lines; warp it with noise
+  // so it breaks up like painted terrain. Fully opaque or fully clear vertices are left alone.
+  float jgA = diffuseColor.a;
+  float jgMid = min(jgA, 1.0 - jgA);
+  float jgFadeN = jgFbm2(jgWp * 0.35 + 21.7) - 0.5 + (jgVNoise(jgWp * 1.7 + 5.3) - 0.5) * 0.4;
+  diffuseColor.a = clamp(jgA + jgFadeN * min(1.0, jgMid * 4.0) * 1.1, 0.0, 1.0);
+  diffuseColor.a = smoothstep(0.08, 0.92, diffuseColor.a);
+}
+#endif
+diffuseColor.rgb = jgCol;
+`;
+/**
+ * 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.
+ */
+export function createSurfaceRibbonMaterial(options) {
+    const cls = terrainSurfaceClass(options.surface ?? "road");
+    const classIndex = terrainSurfaceClassIndex(cls);
+    const low = options.quality === "low";
+    const feather = Math.max(0, options.feather ?? 0);
+    const edge = feather > 0;
+    const wear = clamp(options.wear ?? 0, 0, 1);
+    const paved = cls === "road" || cls === "rock";
+    const roughness = options.roughness ?? terrainSurfaceRoughness(cls);
+    const material = new THREE.MeshStandardMaterial({
+        color: options.color,
+        roughness,
+        metalness: 0,
+        side: THREE.DoubleSide,
+        transparent: edge,
+        vertexColors: options.vertexColors === true,
+        ...(options.polygonOffset === true ? { polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 } : {}),
+    });
+    const uniforms = {
+        uJgRough: { value: roughness },
+        uJgScale: { value: options.scale ?? 1 },
+        uJgHalfWidth: { value: Math.max(0.01, options.halfWidth) },
+        uJgFeather: { value: Math.max(1e-3, feather) },
+        uJgWarp: { value: Math.max(0, options.warp ?? 0) },
+        uJgWear: { value: wear },
+    };
+    material.defines = {
+        JG_RIBBON_CLASS: String(classIndex),
+        JG_SURFACE_CLASSES: String(1 << classIndex),
+        ...(low ? { JG_SURFACE_LOW: "" } : {}),
+        ...(edge ? { JG_RIBBON_EDGE: "" } : {}),
+        ...(wear > 0 ? { JG_RIBBON_WEAR: "" } : {}),
+        ...(paved ? { JG_RIBBON_PAVED: "" } : {}),
+    };
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+attribute vec3 ${RIBBON_FRAME_ATTRIBUTE};
+varying vec3 vJgWorldPos;
+varying vec3 vJgRibbon;`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;
+vJgRibbon = ${RIBBON_FRAME_ATTRIBUTE};`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgRibbon;
+uniform float uJgRough;
+uniform float uJgScale;
+uniform float uJgHalfWidth;
+uniform float uJgFeather;
+uniform float uJgWarp;
+uniform float uJgWear;
+${NOISE_GLSL}
+${SURFACE_FUNCTIONS_GLSL}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>\n${RIBBON_FRAGMENT_GLSL}`)
+            .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+roughnessFactor = clamp(jgRough, 0.04, 1.0);`)
+            .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+${SURFACE_BUMP_NORMAL_GLSL}`);
+    };
+    material.customProgramCacheKey = () => `jgengine-surface-ribbon-${classIndex}-${low ? "low" : "full"}-${edge ? "edge" : "hard"}-${wear > 0 ? "wear" : "clean"}`;
+    return material;
+}
+/**
+ * {@link createSurfaceRibbonMaterial} for a React mesh: rebuilt only when an option changes and
+ * disposed on unmount. Pass `null` to get `null` (the caller falls back to a flat material).
+ */
+export function useSurfaceRibbonMaterial(options) {
+    const o = options;
+    const material = useMemo(() => (o === null ? null : createSurfaceRibbonMaterial(o)), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [o === null, o?.color, o?.halfWidth, o?.surface, o?.feather, o?.warp, o?.wear, o?.roughness, o?.scale, o?.quality, o?.polygonOffset, o?.vertexColors]);
+    useEffect(() => () => material?.dispose(), [material]);
+    return material;
+}

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -1,8 +1,14 @@
 import * as THREE from "three";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 import type { ResolvedTerrainDetail } from "@jgengine/core/world/terrain";
+import type { TerrainPaintTextures } from "./terrainSurfaces.js";
 /** The built procedural detail terrain material, ready to mount on the ground mesh. */
 export interface TerrainDetailMaterialHandle {
     material: THREE.MeshStandardMaterial;
+    /** Editor relief-contour strength 0..1 (0 in play); write `.value` to retune without recompiling. */
+    contour: {
+        value: number;
+    };
 }
 /**
  * Loaded PBR textures matching a resolved `ResolvedTerrainDetailMaterial.maps`' roles. The caller
@@ -15,17 +21,34 @@ export interface TerrainDetailMaterialTextures {
     roughness?: THREE.Texture;
     ao?: THREE.Texture;
 }
+/** Surface-pass inputs beyond the resolved detail config. */
+export interface TerrainDetailMaterialOptions {
+    /** Authored paint coverage from {@link createTerrainPaintTextures}; omit for unpainted ground. */
+    paint?: TerrainPaintTextures;
+    /** Graphics tier. `low` draws one cheap mottle per surface and skips micro-normals. Default `high`. */
+    quality?: GraphicsQuality;
+    /**
+     * Surface classes to compile (bit `1 << classIndex`); defaults to the paint's own classes. An
+     * editor that can paint any surface passes {@link ALL_TERRAIN_SURFACE_CLASSES}.
+     */
+    classMask?: number;
+    /** Initial editor relief-contour strength. Default 0. */
+    contour?: number;
+}
+/** Compile every surface response, for an editor viewport whose paint can change to any surface. */
+export declare const ALL_TERRAIN_SURFACE_CLASSES = 511;
 /**
- * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
- * colour as the base ground and blends procedural, noise-broken rock (by slope),
- * sand (by waterline), and snow (by height) over it — textured-reading terrain
- * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
- * material, so it composes with the post-processing chain.
+ * A `MeshStandardMaterial` that renders terrain as ground rather than flat colour. Each painted
+ * layer draws its surface type's procedural response (grass clumps and blades, dirt clods and
+ * pebbles, gravel stones, cracked rock, rippled sand, wet mud, snow, road grain) in the layer's
+ * authored hue, with albedo, roughness and a micro-normal. Layers meet along noise-warped,
+ * height-aware edges instead of paint-cell blobs; steep slopes turn to rock; macro sweeps break up
+ * tiling. Unpainted ground keeps the biome-tinted vertex colour with procedural detail, plus the
+ * waterline sand and altitude snow bands. Full PBR: lit, shadowed and fogged like any standard material.
  *
  * When `detail.material` is set, pass the matching loaded `textures` (color/normal/roughness/ao):
  * they tile by world position at `detail.material.repeat` world units per tile and blend over the
- * procedural result at `detail.material.strength` — the real-texture seam layers onto the existing
- * look instead of replacing it.
-  * @internal
-  */
-export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail, textures?: TerrainDetailMaterialTextures): TerrainDetailMaterialHandle;
+ * procedural result at `detail.material.strength`.
+ * @internal
+ */
+export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail, textures?: TerrainDetailMaterialTextures, options?: TerrainDetailMaterialOptions): TerrainDetailMaterialHandle;