@jgengine/shell 0.13.0 → 0.15.0-next.0

package/dist/environment/DayNightSky.js

@@ -0,0 +1,51 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef } from "react";
+import * as THREE from "three";
+import { SkyDome } from "./Daylight.js";
+import { daylightStateAt } from "./daylightCycle.js";
+const HEMI_GROUND = "#4c6b34";
+/**
+ * Binds a {@link DayNightCycle} to the engine's existing `SkyDome` shader and a pair of
+ * lights: each frame it reads `cycle.sample()` and writes the blended tint into the dome's
+ * top/horizon/sun uniforms while the sun's arc comes from the shared `daylightStateAt`
+ * geometry. This is the turnkey presentation seam — a game mounts this one component in its
+ * scene and gets a moving, color-graded day-night sky from the serializable model, with no
+ * hand-rolled per-frame lerp and no new renderer. The cycle's `phase`/color values are
+ * free-form and never interpreted here.
+ *
+ * @capability day-night-sky drop-in R3F presenter that drives the engine's existing sky dome and lights from a serializable day-night cycle for a moving, color-graded day-night look
+ */
+export function DayNightSky({ cycle, radius, hazeStrength, sunGlowStrength, lights = true, keyLightIntensity = 1.1, ambientIntensity = 0.6, }) {
+    const skyMaterialRef = useRef(null);
+    const sunRef = useRef(null);
+    const hemiRef = useRef(null);
+    const initial = useMemo(() => cycle.sample(), [cycle]);
+    const initialSun = useMemo(() => daylightStateAt(initial.dayFraction).sunPosition, [initial.dayFraction]);
+    useFrame(() => {
+        const sample = cycle.sample();
+        const geometry = daylightStateAt(sample.dayFraction);
+        const material = skyMaterialRef.current;
+        if (material !== null) {
+            material.uniforms.topColor.value.set(sample.lightColor);
+            material.uniforms.bottomColor.value.set(sample.color);
+            material.uniforms.uSunColor.value.set(sample.lightColor);
+            material.uniforms.uSunDirection.value
+                .set(geometry.sunPosition[0], geometry.sunPosition[1], geometry.sunPosition[2])
+                .normalize();
+            material.uniforms.uSunIntensity.value = sample.intensity;
+        }
+        const sun = sunRef.current;
+        if (sun !== null) {
+            sun.position.set(geometry.sunPosition[0], geometry.sunPosition[1], geometry.sunPosition[2]);
+            sun.intensity = sample.intensity * keyLightIntensity;
+            sun.color.set(sample.lightColor);
+        }
+        const hemi = hemiRef.current;
+        if (hemi !== null) {
+            hemi.intensity = sample.intensity * ambientIntensity;
+            hemi.color.set(sample.lightColor);
+        }
+    });
+    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.lightColor, horizonColor: initial.color, sunDirection: initialSun, sunColor: initial.lightColor, sunIntensity: initial.intensity, materialRef: skyMaterialRef, ...(radius === undefined ? {} : { radius }), ...(hazeStrength === undefined ? {} : { hazeStrength }), ...(sunGlowStrength === undefined ? {} : { sunGlowStrength }) }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [initial.lightColor, HEMI_GROUND, initial.intensity * ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initialSun, intensity: initial.intensity * keyLightIntensity, color: initial.lightColor, castShadow: true, "shadow-mapSize-width": 2048, "shadow-mapSize-height": 2048, "shadow-camera-left": -90, "shadow-camera-right": 90, "shadow-camera-top": 90, "shadow-camera-bottom": -90, "shadow-camera-near": 10, "shadow-camera-far": 520, "shadow-bias": -0.0004, "shadow-normalBias": 0.02 })] })) : null] }));
+}

package/dist/environment/Daylight.d.ts

@@ -16,13 +16,15 @@ export interface SkyDomeProps {
     sunIntensity?: number;
     /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
     hazeStrength?: number;
+    /** Procedural cloud-band opacity: 0 is a clear sky, 1 is heavy overcast. Default 0.35. */
+    cloudiness?: number;
     /** Sun-glow brightness multiplier around the sun disc. Default 1. */
     sunGlowStrength?: number;
     /** Exposes the created shader material so a time-of-day driver can mutate its uniforms per frame without recreating it. */
     materialRef?: MutableRefObject<THREE.ShaderMaterial | null>;
 }
 /** @internal */
-export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, hazeStrength, sunGlowStrength, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
+export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, hazeStrength, sunGlowStrength, cloudiness, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
 export interface DaylightProps {
     sky?: SkyDomeProps | false;
     fog?: {

package/dist/environment/Daylight.js

@@ -36,7 +36,7 @@ function ShadowCastingSun({ position, intensity, color, }) {
     return (_jsx("directionalLight", { ref: ref, position: [position[0], position[1], position[2]], intensity: intensity, color: color, castShadow: true, "shadow-mapSize-width": 2048, "shadow-mapSize-height": 2048, "shadow-camera-left": -90, "shadow-camera-right": 90, "shadow-camera-top": 90, "shadow-camera-bottom": -90, "shadow-camera-near": 10, "shadow-camera-far": 520, "shadow-bias": -0.0004, "shadow-normalBias": 0.02 }));
 }
 /** @internal */
-export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, sunDirection, sunColor = "#fff4d6", sunIntensity = 1, hazeStrength = 0.5, sunGlowStrength = 1, materialRef, } = {}) {
+export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, sunDirection, sunColor = "#fff4d6", sunIntensity = 1, hazeStrength = 0.5, sunGlowStrength = 1, cloudiness = 0.35, materialRef, } = {}) {
     const meshRef = useRef(null);
     const material = useMemo(() => {
         return new THREE.ShaderMaterial({
@@ -50,6 +50,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
                 uSunIntensity: { value: sunDirection === undefined ? 0 : sunIntensity },
                 uHazeStrength: { value: hazeStrength },
                 uSunGlow: { value: sunGlowStrength },
+                uCloudiness: { value: cloudiness },
             },
             vertexShader: `
         varying vec3 vWorldPosition;
@@ -67,6 +68,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
         uniform float uSunIntensity;
         uniform float uHazeStrength;
         uniform float uSunGlow;
+        uniform float uCloudiness;
         uniform float offset;
         uniform float exponent;
         varying vec3 vWorldPosition;
@@ -86,7 +88,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
           vec2 cuv = vd.xz / (max(vd.y, 0.06) + 0.15) * 1.2;
           float clouds = smoothstep(0.52, 0.82, sFbm(cuv));
           float band = smoothstep(0.08, 0.35, dir.y) * smoothstep(1.0, 0.35, dir.y);
-          col = mix(col, mix(topColor, vec3(1.0), 0.6), clouds * band * 0.35);
+          col = mix(col, mix(topColor, vec3(1.0), 0.6), clouds * band * uCloudiness);
           float sd = max(dot(vd, normalize(uSunDirection)), 0.0);
           float glow = pow(sd, 8.0) * 0.35 + pow(sd, 128.0) * 2.6;
           col += uSunColor * glow * uSunIntensity * uSunGlow;
@@ -97,7 +99,7 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
             depthWrite: false,
             fog: false,
         });
-    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, hazeStrength, sunGlowStrength]);
+    }, [topColor, horizonColor, offset, exponent, sunColor, sunDirection, sunIntensity, hazeStrength, sunGlowStrength, cloudiness]);
     useEffect(() => {
         if (materialRef !== undefined)
             materialRef.current = material;
@@ -139,6 +141,8 @@ function skyDomeShape(sky) {
         ...(sky.radius === undefined ? {} : { radius: sky.radius }),
         ...(sky.hazeStrength === undefined ? {} : { hazeStrength: sky.hazeStrength }),
         ...(sky.sunGlowStrength === undefined ? {} : { sunGlowStrength: sky.sunGlowStrength }),
+        ...(sky.gradientExponent === undefined ? {} : { exponent: sky.gradientExponent }),
+        ...(sky.cloudiness === undefined ? {} : { cloudiness: sky.cloudiness }),
     };
 }
 function StaticSkyDaylight({ sky, lights }) {

package/dist/environment/EnvironmentScene.js

@@ -6,11 +6,12 @@ import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
-import { findRoadJunctions, junctionExclusions } from "@jgengine/core/world/streets";
+import { findRoadJunctions } from "@jgengine/core/world/streets";
 import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
+import { useDisposable } from "../render/useDisposable.js";
 import { GroundPad } from "./GroundPad.js";
 import { RoadJunctions } from "./RoadJunctions.js";
-import { RoadRibbons } from "./RoadRibbons.js";
+import { buildAuthoredRoadNetwork, RoadRibbons } from "./RoadRibbons.js";
 import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
@@ -36,8 +37,7 @@ function TexturedTerrainGround({ detail, layout, }) {
             texture.needsUpdate = true;
         }
     }, [textures]);
-    const material = useMemo(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
-    useEffect(() => () => material.dispose(), [material]);
+    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
     return (_jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material }));
 }
 function TerrainGround({ terrain, field, center, }) {
@@ -158,6 +158,6 @@ export function EnvironmentScene({ feature }) {
     const islands = feature.islands ?? [];
     const roads = feature.roads ?? [];
     const junctions = useMemo(() => findRoadJunctions(roads), [roads]);
-    const exclusions = useMemo(() => junctionExclusions(junctions), [junctions]);
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, exclusions: exclusions }, `road-${index}`))), _jsx(RoadJunctions, { junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    const roadNetwork = useMemo(() => buildAuthoredRoadNetwork(roads, junctions, (x, z) => field.sampleHeight(x, z)), [roads, junctions, field]);
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/RoadJunctions.d.ts

@@ -1,12 +1,16 @@
 import { type RoadJunction } from "@jgengine/core/world/streets";
 import type { TerrainField } from "@jgengine/core/world/terrain";
+import type { JunctionSurface } from "./RoadRibbons.js";
 /**
- * Renders welded road intersections: one asphalt disc patch per junction (covering the crossing
- * ribbons so they read as one intersection instead of stacking/z-fighting), plus white stop lines
- * and crosswalk bars at each approach. Fed the junctions the scene already computed from its roads.
+ * Renders welded road intersections: one seam-shared asphalt surface per junction (built by
+ * {@link buildAuthoredRoadNetwork}, its boundary vertices welded onto the trimmed ribbon ends so
+ * there is no overlap and no floating disc), plus white stop lines and crosswalk bars at each
+ * approach. Markings ride the {@link GROUND_DECAL_LAYERS} marking layer above the surface, with
+ * `polygonOffset`/`renderOrder` so they win the depth test on sloped ground.
  * @internal
  */
-export declare function RoadJunctions({ junctions, field, }: {
+export declare function RoadJunctions({ surfaces, junctions, field, }: {
+    surfaces: readonly JunctionSurface[];
     junctions: readonly RoadJunction[];
     field: TerrainField;
 }): import("react").JSX.Element | null;

package/dist/environment/RoadJunctions.js

@@ -1,8 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { BufferAttribute, BufferGeometry, DoubleSide } from "three";
-import { buildJunctionPatch, buildRoadRibbon } from "@jgengine/core/world/roads";
+import { buildRoadRibbon, GROUND_DECAL_LAYERS } from "@jgengine/core/world/roads";
 import { junctionMarkings } from "@jgengine/core/world/streets";
+/** Lane paint sits the table's road→marking gap above the welded junction surface (also polygonOffset). */
+const MARKING_LIFT = GROUND_DECAL_LAYERS.marking - GROUND_DECAL_LAYERS.road;
 function toGeometry(positions, indices) {
     if (positions.length === 0)
         return null;
@@ -34,18 +36,17 @@ function mergedBars(bars, width, field, elevation) {
     return toGeometry(positions, indices);
 }
 /**
- * Renders welded road intersections: one asphalt disc patch per junction (covering the crossing
- * ribbons so they read as one intersection instead of stacking/z-fighting), plus white stop lines
- * and crosswalk bars at each approach. Fed the junctions the scene already computed from its roads.
+ * Renders welded road intersections: one seam-shared asphalt surface per junction (built by
+ * {@link buildAuthoredRoadNetwork}, its boundary vertices welded onto the trimmed ribbon ends so
+ * there is no overlap and no floating disc), plus white stop lines and crosswalk bars at each
+ * approach. Markings ride the {@link GROUND_DECAL_LAYERS} marking layer above the surface, with
+ * `polygonOffset`/`renderOrder` so they win the depth test on sloped ground.
  * @internal
  */
-export function RoadJunctions({ junctions, field, }) {
-    const patches = useMemo(() => junctions
-        .map((junction) => {
-        const patch = buildJunctionPatch(junction.center, junction.radius, (x, z) => field.sampleHeight(x, z), { elevation: junction.elevation + 0.02 });
-        return { color: junction.color, geometry: toGeometry(patch.positions, patch.indices) };
-    })
-        .filter((entry) => entry.geometry !== null), [junctions, field]);
+export function RoadJunctions({ surfaces, junctions, field, }) {
+    const patches = useMemo(() => surfaces
+        .map((surface) => ({ color: surface.color, geometry: toGeometry(surface.ribbon.positions, surface.ribbon.indices) }))
+        .filter((entry) => entry.geometry !== null), [surfaces]);
     const markings = useMemo(() => {
         const stopBars = [];
         const crossBars = [];
@@ -59,11 +60,11 @@ export function RoadJunctions({ junctions, field, }) {
                 crossBars.push(bar);
         }
         return {
-            stops: mergedBars(stopBars, 0.5, field, elevation + 0.05),
-            crosswalks: mergedBars(crossBars, 0.55, field, elevation + 0.05),
+            stops: mergedBars(stopBars, 0.5, field, elevation + MARKING_LIFT),
+            crosswalks: mergedBars(crossBars, 0.55, field, elevation + MARKING_LIFT),
         };
     }, [junctions, field]);
-    if (patches.length === 0)
+    if (patches.length === 0 && markings.stops === null && markings.crosswalks === null)
         return null;
-    return (_jsxs("group", { children: [patches.map((patch, index) => (_jsx("mesh", { geometry: patch.geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: patch.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }, `junction-${index}`))), markings.stops !== null ? (_jsx("mesh", { geometry: markings.stops, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide }) })) : null, markings.crosswalks !== null ? (_jsx("mesh", { geometry: markings.crosswalks, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide }) })) : null] }));
+    return (_jsxs("group", { children: [patches.map((patch, index) => (_jsx("mesh", { geometry: patch.geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: patch.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }, `junction-${index}`))), markings.stops !== null ? (_jsx("mesh", { geometry: markings.stops, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, markings.crosswalks !== null ? (_jsx("mesh", { geometry: markings.crosswalks, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null] }));
 }

package/dist/environment/RoadRibbons.d.ts

@@ -1,13 +1,49 @@
 import type { RoadEnvironmentDescriptor } from "@jgengine/core/world/features";
-import { type DashExclusion } from "@jgengine/core/world/roads";
+import { type RoadJunctionInput, type RoadPoint, type RoadRibbon } from "@jgengine/core/world/roads";
+import { type RoadJunction } from "@jgengine/core/world/streets";
 import type { TerrainField } from "@jgengine/core/world/terrain";
+/** Convert a detected {@link RoadJunction} into the structural {@link RoadJunctionInput} the trimmer wants. @internal */
+export declare function roadJunctionInput(junction: RoadJunction): RoadJunctionInput;
 /**
- * Renders one `road()` descriptor: an asphalt ribbon, a curb/edge strip along each border, plus an
- * optional dashed centerline (draped on the terrain, and interrupted through any `exclusions`
- * — the welded junction patches — so the center line does not paint across intersections).
+ * Split every path segment at the junction centers that fall on it, inserting the junction point as
+ * a real vertex so {@link trimPathAtJunctions} (which matches junctions to path vertices) can cut the
+ * ribbon back there. Authored road crossings from `findRoadJunctions` land mid-segment, not on the
+ * hand-authored vertices, so without this the trimmer would never see them.
+ * @internal
  */
-export declare function RoadRibbons({ road, field, exclusions, }: {
+export declare function insertJunctionNodes(path: readonly RoadPoint[], junctions: readonly RoadJunctionInput[], tolerance?: number): RoadPoint[];
+/** One welded asphalt junction surface plus the color it should render in. */
+export interface JunctionSurface {
+    color: string;
+    ribbon: RoadRibbon;
+}
+/** Trimmed ribbons for every road plus the welded surfaces that fill the crossings between them. */
+export interface AuthoredRoadNetwork {
+    /** Trimmed centerline sub-paths per input road (parallel to the `roads` array; empty for degenerate roads). */
+    roadPaths: RoadPoint[][][];
+    /** One welded surface per junction that at least one trimmed ribbon actually ends at. */
+    junctionSurfaces: JunctionSurface[];
+}
+/**
+ * Trim every authored road back to its junction boundaries and weld one surface into each crossing —
+ * the drop-in replacement for the old "full ribbons + floating disc" model. Each road's path gets its
+ * junction crossings inserted as vertices, is trimmed by {@link trimPathAtJunctions} (a through-road
+ * splits in two), and the terminal cross-section corners feed {@link buildJunctionSurface}. Ribbon
+ * corners drape at the road's own authored `elevation`, so each welded corner meets the ribbon end at
+ * the exact same height (seam-shared, per {@link GROUND_DECAL_LAYERS}); the surface interior drapes at
+ * the junction's representative elevation. Pure geometry, so the shell just meshes the result.
+ * @internal
+ */
+export declare function buildAuthoredRoadNetwork(roads: readonly RoadEnvironmentDescriptor[], junctions: readonly RoadJunction[], sampleHeight: (x: number, z: number) => number): AuthoredRoadNetwork;
+/**
+ * Renders one `road()` descriptor from its trimmed centerline sub-paths (cut back at every junction
+ * by {@link buildAuthoredRoadNetwork}): an asphalt ribbon, a curb/edge strip along each border, an
+ * optional dashed centerline, and optional sidewalks. Because the sub-paths already stop at the
+ * junction boundary, every layer naturally ends there — no ribbon ploughs through the crossing and
+ * the dashed line no longer needs exclusion circles to skip intersections.
+ */
+export declare function RoadRibbons({ road, field, paths, }: {
     road: RoadEnvironmentDescriptor;
     field: TerrainField;
-    exclusions?: readonly DashExclusion[];
+    paths: readonly (readonly RoadPoint[])[];
 }): import("react").JSX.Element | null;

package/dist/environment/RoadRibbons.js

@@ -1,8 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { BufferAttribute, BufferGeometry, Color, DoubleSide } from "three";
-import { buildRoadRibbon, dashSegments } from "@jgengine/core/world/roads";
-import { curbPaths, offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+import { buildJunctionSurface, buildRoadRibbon, dashSegments, GROUND_DECAL_LAYERS, trimPathAtJunctions, } from "@jgengine/core/world/roads";
+import { offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+/**
+ * Decal sub-layers as small lifts above each road's authored base `elevation`, spaced by the
+ * single-owner {@link GROUND_DECAL_LAYERS} table so the edge strip and lane paint never z-fight the
+ * asphalt they sit on. The asphalt ribbon and the welded junction surface stay on the authored base
+ * (they are seam-welded — never stacked); markings lift by the table's road→marking gap and ALSO get
+ * `polygonOffset`/`renderOrder` on the material. Curbs and sidewalks are their own surfaces beside
+ * the road edge (not table decal layers), so they carry documented offsets rather than a table entry.
+ */
+const MARKING_LIFT = GROUND_DECAL_LAYERS.marking - GROUND_DECAL_LAYERS.road;
+const CURB_LIFT = 0.02;
+const SIDEWALK_LIFT = 0.06;
 /** Darken an asphalt color toward black for a curb/edge strip (deterministic, no alloc churn). */
 function darken(hex, amount) {
     const c = new Color(hex);
@@ -18,13 +29,8 @@ function toGeometry(positions, indices) {
     geometry.computeVertexNormals();
     return geometry;
 }
-function ribbonGeometry(path, width, field, elevation) {
-    const ribbon = buildRoadRibbon(path, width, (x, z) => field.sampleHeight(x, z), { elevation });
-    return toGeometry(ribbon.positions, ribbon.indices);
-}
-function mergedDashGeometry(road, field, exclusions) {
-    const width = Math.max(0.25, road.width * 0.035);
-    const ribbons = dashSegments(road.path, 3.2, 4, exclusions).map((dash) => buildRoadRibbon(dash, width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + 0.04 }));
+/** Merge many ribbons into one buffer geometry (draws collapse to a single mesh). */
+function mergeRibbons(ribbons) {
     const vertexCount = ribbons.reduce((sum, r) => sum + r.positions.length, 0);
     const indexCount = ribbons.reduce((sum, r) => sum + r.indices.length, 0);
     if (vertexCount === 0)
@@ -36,40 +42,157 @@ function mergedDashGeometry(road, field, exclusions) {
     for (const ribbon of ribbons) {
         positions.set(ribbon.positions, vertexOffset);
         const base = vertexOffset / 3;
-        for (let i = 0; i < ribbon.indices.length; i += 1) {
+        for (let i = 0; i < ribbon.indices.length; i += 1)
             indices[indexOffset + i] = ribbon.indices[i] + base;
-        }
         vertexOffset += ribbon.positions.length;
         indexOffset += ribbon.indices.length;
     }
     return toGeometry(positions, indices);
 }
+/** Convert a detected {@link RoadJunction} into the structural {@link RoadJunctionInput} the trimmer wants. @internal */
+export function roadJunctionInput(junction) {
+    return {
+        x: junction.center[0],
+        z: junction.center[1],
+        // Arm direction `[dx, dz]` → angle `atan2(dx, dz)`, matching the generator convention the core uses.
+        arms: junction.approaches.map((approach) => ({
+            angle: Math.atan2(approach.direction[0], approach.direction[1]),
+            width: approach.width,
+        })),
+    };
+}
+/**
+ * Split every path segment at the junction centers that fall on it, inserting the junction point as
+ * a real vertex so {@link trimPathAtJunctions} (which matches junctions to path vertices) can cut the
+ * ribbon back there. Authored road crossings from `findRoadJunctions` land mid-segment, not on the
+ * hand-authored vertices, so without this the trimmer would never see them.
+ * @internal
+ */
+export function insertJunctionNodes(path, junctions, tolerance = 1e-3) {
+    if (path.length < 2)
+        return path.map((p) => [p[0], p[1]]);
+    const out = [[path[0][0], path[0][1]]];
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const lengthSq = abx * abx + abz * abz;
+        if (lengthSq > 1e-12) {
+            const hits = [];
+            for (const j of junctions) {
+                const t = ((j.x - a[0]) * abx + (j.z - a[1]) * abz) / lengthSq;
+                if (t <= 1e-6 || t >= 1 - 1e-6)
+                    continue; // coincident with an existing vertex — already covered
+                const px = a[0] + abx * t;
+                const pz = a[1] + abz * t;
+                if (Math.hypot(j.x - px, j.z - pz) <= tolerance)
+                    hits.push({ t, x: j.x, z: j.z });
+            }
+            hits.sort((u, v) => u.t - v.t);
+            for (const hit of hits) {
+                const prev = out[out.length - 1];
+                if (Math.hypot(prev[0] - hit.x, prev[1] - hit.z) > 1e-6)
+                    out.push([hit.x, hit.z]);
+            }
+        }
+        out.push([b[0], b[1]]);
+    }
+    return out;
+}
 /**
- * Renders one `road()` descriptor: an asphalt ribbon, a curb/edge strip along each border, plus an
- * optional dashed centerline (draped on the terrain, and interrupted through any `exclusions`
- * — the welded junction patches — so the center line does not paint across intersections).
+ * Trim every authored road back to its junction boundaries and weld one surface into each crossing —
+ * the drop-in replacement for the old "full ribbons + floating disc" model. Each road's path gets its
+ * junction crossings inserted as vertices, is trimmed by {@link trimPathAtJunctions} (a through-road
+ * splits in two), and the terminal cross-section corners feed {@link buildJunctionSurface}. Ribbon
+ * corners drape at the road's own authored `elevation`, so each welded corner meets the ribbon end at
+ * the exact same height (seam-shared, per {@link GROUND_DECAL_LAYERS}); the surface interior drapes at
+ * the junction's representative elevation. Pure geometry, so the shell just meshes the result.
+ * @internal
  */
-export function RoadRibbons({ road, field, exclusions = [], }) {
-    const asphalt = useMemo(() => ribbonGeometry(road.path, road.width, field, road.elevation), [road, field]);
-    const dashes = useMemo(() => (road.markings ? mergedDashGeometry(road, field, exclusions) : null), [road, field, exclusions]);
+export function buildAuthoredRoadNetwork(roads, junctions, sampleHeight) {
+    const inputs = junctions.map(roadJunctionInput);
+    const roadPaths = [];
+    const approachesByJunction = new Map();
+    for (const road of roads) {
+        if (road.path.length < 2 || road.width <= 0) {
+            roadPaths.push([]);
+            continue;
+        }
+        const noded = insertJunctionNodes(road.path, inputs);
+        const subs = trimPathAtJunctions(noded, road.width, inputs);
+        roadPaths.push(subs.map((sub) => sub.path));
+        for (const sub of subs) {
+            for (const cut of sub.cuts) {
+                const approach = {
+                    center: cut.center,
+                    left: [cut.left[0], sampleHeight(cut.left[0], cut.left[1]) + road.elevation, cut.left[1]],
+                    right: [cut.right[0], sampleHeight(cut.right[0], cut.right[1]) + road.elevation, cut.right[1]],
+                };
+                const list = approachesByJunction.get(cut.junctionIndex);
+                if (list)
+                    list.push(approach);
+                else
+                    approachesByJunction.set(cut.junctionIndex, [approach]);
+            }
+        }
+    }
+    const junctionSurfaces = [];
+    for (const ji of [...approachesByJunction.keys()].sort((p, q) => p - q)) {
+        const junction = junctions[ji];
+        const ribbon = buildJunctionSurface({ x: junction.center[0], z: junction.center[1] }, approachesByJunction.get(ji), sampleHeight, { elevation: junction.elevation });
+        junctionSurfaces.push({ color: junction.color, ribbon });
+    }
+    return { roadPaths, junctionSurfaces };
+}
+/**
+ * Renders one `road()` descriptor from its trimmed centerline sub-paths (cut back at every junction
+ * by {@link buildAuthoredRoadNetwork}): an asphalt ribbon, a curb/edge strip along each border, an
+ * optional dashed centerline, and optional sidewalks. Because the sub-paths already stop at the
+ * junction boundary, every layer naturally ends there — no ribbon ploughs through the crossing and
+ * the dashed line no longer needs exclusion circles to skip intersections.
+ */
+export function RoadRibbons({ road, field, paths, }) {
+    const asphalt = useMemo(() => mergeRibbons(paths.map((path) => buildRoadRibbon(path, road.width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation }))), [paths, road.width, road.elevation, field]);
+    const dashes = useMemo(() => {
+        if (!road.markings)
+            return null;
+        const width = Math.max(0.25, road.width * 0.035);
+        const ribbons = [];
+        for (const path of paths) {
+            for (const dash of dashSegments(path, 3.2, 4)) {
+                ribbons.push(buildRoadRibbon(dash, width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + MARKING_LIFT }));
+            }
+        }
+        return mergeRibbons(ribbons);
+    }, [paths, road.markings, road.width, road.elevation, field]);
     const curbColor = useMemo(() => darken(road.color, 0.45), [road.color]);
     const curbs = useMemo(() => {
         // A thin strip straddling each asphalt edge, lifted just above the ribbon.
         const strip = Math.max(0.4, road.width * 0.09);
-        return curbPaths(road, strip / 2)
-            .map((path) => ribbonGeometry(path, strip, field, road.elevation + 0.02))
-            .filter((geometry) => geometry !== null);
-    }, [road, field]);
+        const edge = road.width / 2 - strip / 2;
+        const ribbons = [];
+        for (const path of paths) {
+            for (const off of [edge, -edge]) {
+                ribbons.push(buildRoadRibbon(offsetPath(path, off), strip, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + CURB_LIFT }));
+            }
+        }
+        return mergeRibbons(ribbons);
+    }, [paths, road.width, road.elevation, field]);
     const sidewalks = useMemo(() => {
         const width = sidewalkWidthOf(road);
         if (width <= 0)
-            return [];
+            return null;
         const offset = road.width / 2 + width / 2;
-        return [offsetPath(road.path, offset), offsetPath(road.path, -offset)]
-            .map((path) => ribbonGeometry(path, width, field, road.elevation + 0.06))
-            .filter((geometry) => geometry !== null);
-    }, [road, field]);
+        const ribbons = [];
+        for (const path of paths) {
+            for (const off of [offset, -offset]) {
+                ribbons.push(buildRoadRibbon(offsetPath(path, off), width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + SIDEWALK_LIFT }));
+            }
+        }
+        return mergeRibbons(ribbons);
+    }, [paths, road, field]);
     if (asphalt === null)
         return null;
-    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }), curbs.map((geometry, index) => (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: curbColor, roughness: 0.9, metalness: 0, side: DoubleSide }) }, `curb-${index}`))), dashes !== null ? (_jsx("mesh", { geometry: dashes, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide }) })) : null, sidewalks.map((geometry, index) => (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.sidewalk === false ? "#a7adb8" : road.sidewalk.color, roughness: 0.9, metalness: 0, side: DoubleSide }) }, `walk-${index}`)))] }));
+    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }), curbs !== null ? (_jsx("mesh", { geometry: curbs, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: curbColor, roughness: 0.9, metalness: 0, side: DoubleSide }) })) : null, dashes !== null ? (_jsx("mesh", { geometry: dashes, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, sidewalks !== null ? (_jsx("mesh", { geometry: sidewalks, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.sidewalk === false ? "#a7adb8" : road.sidewalk.color, roughness: 0.9, metalness: 0, side: DoubleSide }) })) : null] }));
 }

package/dist/environment/VolumetricClouds.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
-import { useEffect, useMemo, useRef } from "react";
+import { useRef } from "react";
 import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
 /**
  * Camera-centered proxy dome radius. Must sit inside the default camera far plane
  * (`CAMERA_FRUSTUM_DEFAULTS.far` = 300) — a bigger sphere is clipped whole and renders nothing. The
@@ -161,7 +162,7 @@ void main() {
 export function VolumetricClouds({ rules, sunDirection }) {
     const meshRef = useRef(null);
     const timeRef = useRef(0);
-    const material = useMemo(() => {
+    const material = useDisposable(() => {
         return new THREE.ShaderMaterial({
             uniforms: {
                 uCameraPos: { value: new THREE.Vector3() },
@@ -186,7 +187,6 @@ export function VolumetricClouds({ rules, sunDirection }) {
             fog: false,
         });
     }, [rules, sunDirection]);
-    useEffect(() => () => material.dispose(), [material]);
     useFrame((state, delta) => {
         timeRef.current += delta;
         const mesh = meshRef.current;

package/dist/environment/index.d.ts

@@ -1,4 +1,5 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
+export { DayNightSky, type DayNightSkyProps } from "./DayNightSky.js";
 export { EnvironmentScene, type EnvironmentSceneProps } from "./EnvironmentScene.js";
 export { VolumetricClouds, type VolumetricCloudsProps } from "./VolumetricClouds.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, type DaylightCycleConfig, type DaylightState, } from "./daylightCycle.js";

package/dist/environment/index.js

@@ -1,4 +1,5 @@
 export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, } from "./Daylight.js";
+export { DayNightSky } from "./DayNightSky.js";
 export { EnvironmentScene } from "./EnvironmentScene.js";
 export { VolumetricClouds } from "./VolumetricClouds.js";
 export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, } from "./daylightCycle.js";

package/dist/gameKit.d.ts

@@ -1,8 +1,9 @@
 /**
- * The happy-path game kit — one import surface covering a whole simple game: authoring
- * (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
- * (`defineSystem`), the authored-scene document helpers, HUD primitives, and deterministic
- * randomness. Start here; reach for deep package paths only when a game outgrows the kit.
+ * **Start here for game code.** The sole happy-path import surface for a whole simple game:
+ * authoring (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
+ * (`defineSystem`), authored-scene helpers, HUD building blocks, and deterministic randomness.
+ * Reach for deep package paths only when a game outgrows the kit. Do not start from
+ * `@jgengine/core/authoring` — that module is a core-side helper barrel, not the game entrypoint.
  *
  * @capability game-kit one-stop happy-path import surface for authoring, mounting, state, systems, authored scenes, and HUD
  */
@@ -20,7 +21,9 @@ export { authoredSpawnPosition } from "@jgengine/core/world/authoredSpawn";
 export { collectAuthoredTriggers } from "@jgengine/core/scene/authoredTriggers";
 export { environmentContentFromDocument } from "@jgengine/core/editor/environment";
 export { environment } from "@jgengine/core/world/features";
+export { grounded } from "@jgengine/core/world/grounded";
 export type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+export { DEFAULT_WALK_CODES } from "./shellMovement.js";
 export { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react/hudLayout";
 export { StatBar, Hotbar, Clock, Coins } from "@jgengine/react/hud";
 export { seededRng } from "@jgengine/core/random/rng";

package/dist/gameKit.js

@@ -1,8 +1,9 @@
 /**
- * The happy-path game kit — one import surface covering a whole simple game: authoring
- * (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
- * (`defineSystem`), the authored-scene document helpers, HUD primitives, and deterministic
- * randomness. Start here; reach for deep package paths only when a game outgrows the kit.
+ * **Start here for game code.** The sole happy-path import surface for a whole simple game:
+ * authoring (`defineGame`), mounting (`GameHost`), serializable state (`defineStore`), behavior
+ * (`defineSystem`), authored-scene helpers, HUD building blocks, and deterministic randomness.
+ * Reach for deep package paths only when a game outgrows the kit. Do not start from
+ * `@jgengine/core/authoring` — that module is a core-side helper barrel, not the game entrypoint.
  *
  * @capability game-kit one-stop happy-path import surface for authoring, mounting, state, systems, authored scenes, and HUD
  */
@@ -20,7 +21,9 @@ export { collectAuthoredTriggers } from "@jgengine/core/scene/authoredTriggers";
 export { environmentContentFromDocument } from "@jgengine/core/editor/environment";
 // World + camera.
 export { environment } from "@jgengine/core/world/features";
-// HUD layout + optional building blocks — games own custom chrome (not a stock face).
+export { grounded } from "@jgengine/core/world/grounded";
+export { DEFAULT_WALK_CODES } from "./shellMovement.js";
+// HUD layout + drop-in building blocks — compose these, reskin with HudTheme; games own layout/terminology/art direction.
 export { HudCanvas, HudPanel, useHudLayout } from "@jgengine/react/hudLayout";
 export { StatBar, Hotbar, Clock, Coins } from "@jgengine/react/hud";
 // Deterministic randomness (inject seeds; never Math.random in game logic).