@jgengine/shell 0.11.0 → 0.13.0

package/dist/camera/rigMath.js

@@ -74,6 +74,22 @@ export function topDownPose(follow, resolved, fov) {
         fov,
     };
 }
+/**
+ * World-space direction for RTS pan input: `panX` slides along screen-right,
+ * `panZ` along the camera's ground-plane forward, for a camera posed by
+ * `topDownPose` at the same yaw. Normalized; zero input returns zero.
+ * @internal
+ */
+export function rtsPanWorldDir(panX, panZ, yaw) {
+    const forward = forwardVector(yaw);
+    const right = rightVector(yaw);
+    const x = panX * right.x + panZ * forward.x;
+    const z = panX * right.z + panZ * forward.z;
+    const len = Math.hypot(x, z);
+    if (len === 0)
+        return { x: 0, y: 0, z: 0 };
+    return { x: x / len, y: 0, z: z / len };
+}
 /** Exponential spring-arm approach toward a desired point (frame-rate independent).
  * @internal
  */
@@ -242,6 +258,9 @@ export function resolveChase(config) {
         bankPerYawRate: config?.bank?.perYawRate ?? 0,
         bankMax: config?.bank?.max ?? 0.35,
         bankDamping: config?.bank?.damping ?? 8,
+        velocityYawBlend: config?.velocityYaw === undefined ? 0 : config.velocityYaw.blend ?? 0.65,
+        velocityYawMinSpeed: config?.velocityYaw?.minSpeed ?? 4,
+        velocityYawResponse: config?.velocityYaw?.response ?? 6,
     };
 }
 /** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
@@ -323,6 +342,32 @@ export function chaseLookAt(follow, yaw, resolved) {
         z: follow.z + forward.z * 2,
     };
 }
+/**
+ * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
+ * smoothing. When the target slides, its planar `velocity` diverges from its
+ * `heading`; this rotates the anchor from heading partway toward the velocity
+ * direction so the camera reveals the car's side while travel stays framed. The
+ * traversed fraction is `velocityYawBlend` scaled by how far the slip angle has
+ * opened (0 at straight-line travel, full at a 90° slide), so ordinary driving
+ * is untouched. Returns the raw heading — no swing — when the feature is off,
+ * when planar speed is below `velocityYawMinSpeed`, or when the target is
+ * reversing (velocity opposed to heading forward). Blending is shortest-arc, so
+ * it stays correct across the ±PI wrap seam.
+ * @internal
+ */
+export function velocityYawTarget(heading, velocity, resolved) {
+    if (resolved.velocityYawBlend <= 0)
+        return heading;
+    const speed = Math.hypot(velocity.x, velocity.z);
+    if (speed < resolved.velocityYawMinSpeed)
+        return heading;
+    const forward = forwardVector(heading);
+    if (forward.x * velocity.x + forward.z * velocity.z < 0)
+        return heading;
+    const slip = angleDelta(heading, Math.atan2(velocity.x, velocity.z));
+    const slipFraction = clamp(Math.abs(slip) / (Math.PI / 2), 0, 1);
+    return heading + slip * resolved.velocityYawBlend * slipFraction;
+}
 /** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle.
  * @internal
  */

package/dist/defineGame.d.ts

@@ -1,7 +1,8 @@
-import type { ComponentType } from "react";
+import { type ComponentType } from "react";
 import { type GameDefinitionConfig, type GameLoop } from "@jgengine/core/game/defineGame";
 import type { GameContext, GameContextContent } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import type { PlayableGame } from "./registry.js";
 type EngineFields<TAssetRef extends ModelAssetRef> = Omit<GameDefinitionConfig<TAssetRef>, "loop" | "ui" | "multiplayer"> & {
     multiplayer?: GameDefinitionConfig<TAssetRef>["multiplayer"];
@@ -10,7 +11,20 @@ type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "Game
     content?: GameContextContent;
     loop?: Partial<GameLoop<GameContext>>;
     GameUI?: ComponentType;
+    /** Tunes how the auto-mounted `AuthoredScene` places the document's catalog-id markers into the object store. Default `true`; pass `false` when the game spawns its placed content as entities itself (`placeAuthoredObjects`) to avoid a double render. */
+    scenePlacement?: boolean | {
+        verticalOffset?: number;
+    };
+    /** GLB models for the auto-mounted scene's scatter palette items, keyed by palette item id; string ids resolve through the game's asset catalog. Unmatched items keep the built-in proxy meshes. */
+    sceneScatterModels?: Record<string, string | ModelConfig>;
 };
 export type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields;
+/**
+ * The one public authoring entry point: compose engine fields (systems, world, physics, input) and
+ * presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`.
+ * Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+ */
 export declare function defineGame<TAssetRef extends ModelAssetRef = ModelAssetRef>(config: GameConfig<TAssetRef>): PlayableGame;
 export {};

package/dist/defineGame.js

@@ -1,17 +1,34 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { defineGame as defineEngineGame, } from "@jgengine/core/game/defineGame";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { defineGameDefinition as defineEngineGame, } from "@jgengine/core/game/defineGame";
 import { syncLifecyclePhase } from "@jgengine/core/game/gamePhase";
 import { offline } from "@jgengine/core/runtime/adapter";
 import { EnvironmentScene } from "./environment.js";
+import { terrainGroundColorSampler } from "./environment/terrainGroundColor.js";
+import { AuthoredScene } from "./scene/AuthoredScene.js";
 const noop = () => { };
 function worldBackdrop(feature) {
     return function WorldBackdrop() {
         return _jsx(EnvironmentScene, { feature: feature });
     };
 }
+function authoredSceneOverlay(document, placement, scatterModels, assets, world, Vfx) {
+    const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
+    return function AuthoredSceneOverlay(props) {
+        const groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground), [props.ctx.world.ground]);
+        return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, field: props.ctx.world.ground, placeObjects: placement, ...(scatterModels === undefined ? {} : { scatterModels, assets }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
+    };
+}
 const emptyUi = () => null;
+/**
+ * The one public authoring entry point: compose engine fields (systems, world, physics, input) and
+ * presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`.
+ * Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+ */
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
         multiplayer: multiplayer ?? offline(),
@@ -39,7 +56,11 @@ export function defineGame(config) {
         environment: environment ??
             (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
         camera: camera ?? { perspective: "third" },
-        WorldOverlay,
+        editorLayers,
+        editorCatalogs,
+        WorldOverlay: editorLayers === undefined
+            ? WorldOverlay
+            : authoredSceneOverlay(editorLayers, scenePlacement ?? true, sceneScatterModels, game.assets, game.world, WorldOverlay),
         viewmodel,
         renderEntity,
         renderObject,
@@ -53,6 +74,7 @@ export function defineGame(config) {
         orientation,
         worldHealthBars,
         nameplates,
+        presentationEffects,
         audio,
         entitySounds,
         objectSounds,

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -30,8 +30,8 @@ export declare function buildLeanReport(playable: PlayableGame): {
             pctOfSim: number;
         }[];
     } | null;
-    render: import("@jgengine/core/devtools/devtools").RenderSample | null;
-    latency: import("@jgengine/core/devtools/devtools").LatencyStats | null;
+    render: import("@jgengine/core/devtools/types").RenderSample | null;
+    latency: import("@jgengine/core/devtools/types").LatencyStats | null;
     longFrameSummary: {
         count: number;
         culprits: {
@@ -54,10 +54,10 @@ export declare function buildLeanReport(playable: PlayableGame): {
             ms: number;
         }[];
         probes: Record<string, unknown>;
-        render: import("@jgengine/core/devtools/devtools").RenderSample | null;
+        render: import("@jgengine/core/devtools/types").RenderSample | null;
     }[];
     probes: Record<string, unknown>;
-    logs: import("@jgengine/core/devtools/devtools").DevtoolsLogEntry[] | undefined;
+    logs: import("@jgengine/core/devtools/types").DevtoolsLogEntry[] | undefined;
     controls: {
         name: string;
         value: unknown;

package/dist/devtools/DevtoolsOverlay.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame } from "@react-three/fiber";
+import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { devtools, instrumentLatency, } from "@jgengine/core/devtools/devtools";
+import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams";
 import { MOVEMENT_TUNING } from "@jgengine/core/movement/movementModel";
 import { collisionDebug } from "./collisionDebug.js";
 import { readStoredOverrides } from "./devtoolsOverrides.js";
@@ -24,21 +25,35 @@ export function withDevtoolsLatency(multiplayer) {
         },
     };
 }
+const RENDER_SAMPLE_MS = 500;
+const RENDER_PROBE_FRAME_PRIORITY = -10;
 /** @internal */
 export function DevtoolsRendererProbe() {
-    const frameCounter = useRef(0);
+    const gl = useThree((state) => state.gl);
+    const lastSampleAt = useRef(0);
+    useEffect(() => {
+        // three resets gl.info after every render() call, so with a multi-pass
+        // composer the counters only ever hold the last fullscreen pass. Own the
+        // reset instead: accumulate across the whole frame, reset at frame start.
+        gl.info.autoReset = false;
+        return () => {
+            gl.info.autoReset = true;
+        };
+    }, [gl]);
     useFrame((state) => {
-        frameCounter.current += 1;
-        if (frameCounter.current % 30 !== 0)
-            return;
         const info = state.gl.info;
-        devtools.render.record({
-            drawCalls: info.render.calls,
-            triangles: info.render.triangles,
-            geometries: info.memory.geometries,
-            textures: info.memory.textures,
-        });
-    });
+        const now = performance.now();
+        if (now - lastSampleAt.current >= RENDER_SAMPLE_MS) {
+            lastSampleAt.current = now;
+            devtools.render.record({
+                drawCalls: info.render.calls,
+                triangles: info.render.triangles,
+                geometries: info.memory.geometries,
+                textures: info.memory.textures,
+            });
+        }
+        info.reset();
+    }, RENDER_PROBE_FRAME_PRIORITY);
     return null;
 }
 const TABS = [
@@ -194,6 +209,7 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
         const disposers = [
             devtools.probes.register("entities", () => ctx.scene.entity.list().length),
             devtools.probes.register("objects", () => ctx.scene.object.list().length),
+            devtools.probes.register("fallbacks", () => fallbackSeamsSnapshot()),
         ];
         return () => {
             for (const dispose of disposers)

package/dist/devtools/agentBridge.js

@@ -1,3 +1,4 @@
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
@@ -104,6 +105,9 @@ export function installAgentBridge(options) {
                 return { ok: true, snapshot: buildLeanReport(playable) };
             case "debug_report":
                 return { ok: true, report: buildFullReport(playable) };
+            case "debug_perf_reset":
+                devtools.frame.reset();
+                return { ok: true };
             case "canvas_state":
                 return { ok: true, layouts: canvasPanels() };
             case "canvas_set_editing": {

package/dist/devtools/perfDiagnose.js

@@ -1,7 +1,7 @@
 import { devtools, LONG_FRAME_MS } from "@jgengine/core/devtools/devtools";
 import { ms } from "./panelAtoms.js";
 const CULPRIT_HINTS = {
-    "outside-sim": "Cost is outside the sim driver — three.js render, React commit, GPU, GC, or tab throttle.",
+    "outside-sim": "Cost is outside the sim driver — three.js render, React commit, GPU, GC, or tab throttle. Check the render sample: high draw calls/triangles mean scene cost (instancing, culling, terrain density); moderate counts with slow frames mean fill cost (dpr, AO/DOF passes, bloom) — try Quality low/medium.",
     sim: "Sim is slow but no named phase stands out — wrap hot onTick work with measure(\"name\", fn).",
     onTick: "Game loop.onTick is the hotspot — profile inside it with measure(\"physics\"|\"ai\"|…, fn).",
     pose: "Shell movement / collision / voxel step is expensive.",

package/dist/diagnostics/RuntimeDiagnostics.d.ts

@@ -23,6 +23,13 @@ export declare class GameUiErrorBoundary extends Component<{
     componentDidCatch(error: unknown, info: ErrorInfo): void;
     render(): ReactNode;
 }
+/** Standalone error footer text (page, browser, engine) shared by every error surface. */
+export declare function errorReportContext(): string;
+/** "Copy error" + "File issue" buttons for any error surface. `report` is the full text to copy / prefill. */
+export declare function ErrorReportActions({ report, issueTitle }: {
+    report: string;
+    issueTitle: string;
+}): import("react").JSX.Element;
 export declare function DiagnosticOverlay({ diagnostics, gameName }: {
     diagnostics: RuntimeDiagnostic[];
     gameName: string;

package/dist/diagnostics/RuntimeDiagnostics.js

@@ -32,16 +32,35 @@ function expandedReactError(message) {
         ? "Maximum update depth exceeded. A component is repeatedly updating state during render or after every update."
         : null;
 }
+const ISSUES_NEW_URL = "https://github.com/Noisemaker111/jgengine/issues/new";
+/** Standalone error footer text (page, browser, engine) shared by every error surface. */
+export function errorReportContext() {
+    return [
+        `Engine: ${VERSION}`,
+        `Page: ${window.location.origin}${window.location.pathname}`,
+        `Browser: ${navigator.userAgent}`,
+    ].join("\n");
+}
+/** "Copy error" + "File issue" buttons for any error surface. `report` is the full text to copy / prefill. */
+export function ErrorReportActions({ report, issueTitle }) {
+    const [copied, setCopied] = useState(false);
+    const issueBody = report.length > 8000 ? `${report.slice(0, 8000)}\n\n[Report truncated; use Copy error for the full report.]` : report;
+    const issueUrl = `${ISSUES_NEW_URL}?title=${encodeURIComponent(`[BUG] ${issueTitle.slice(0, 120)}`)}&body=${encodeURIComponent(issueBody)}`;
+    return (_jsxs("div", { className: "flex gap-2", children: [_jsx("button", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 text-xs font-semibold text-red-50 hover:bg-red-800", type: "button", onClick: () => {
+                    void navigator.clipboard.writeText(report).then(() => {
+                        setCopied(true);
+                        window.setTimeout(() => setCopied(false), 2000);
+                    });
+                }, children: copied ? "Copied" : "Copy error" }), _jsx("a", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 text-xs font-semibold text-red-50 hover:bg-red-800", href: issueUrl, rel: "noreferrer", target: "_blank", children: "File issue" })] }));
+}
 function diagnosticReport(diagnostic, gameName) {
     const explanation = expandedReactError(diagnostic.message);
     return [
         "JGengine runtime error",
         `Game: ${gameName}`,
-        `Engine: ${VERSION}`,
         `Phase: ${diagnostic.phase}`,
         `Time: ${diagnostic.capturedAt}`,
-        `Page: ${window.location.origin}${window.location.pathname}`,
-        `Browser: ${navigator.userAgent}`,
+        errorReportContext(),
         explanation === null ? null : `Explanation: ${explanation}`,
         "",
         `Message: ${diagnostic.message}`,
@@ -52,18 +71,10 @@ function diagnosticReport(diagnostic, gameName) {
         .join("\n");
 }
 export function DiagnosticOverlay({ diagnostics, gameName }) {
-    const [copied, setCopied] = useState(false);
     if (diagnostics.length === 0)
         return null;
     const latest = diagnostics[diagnostics.length - 1];
     const explanation = expandedReactError(latest.message);
     const report = diagnosticReport(latest, gameName);
-    const issueBody = report.length > 8000 ? `${report.slice(0, 8000)}\n\n[Report truncated; use Copy error for the full report.]` : report;
-    const issueUrl = `https://github.com/Noisemaker111/jgengine/issues/new?title=${encodeURIComponent(`[BUG] ${latest.phase}: ${latest.message.slice(0, 100)}`)}&body=${encodeURIComponent(issueBody)}`;
-    return (_jsxs("div", { className: "pointer-events-auto absolute right-4 top-4 z-50 max-w-lg rounded border border-red-400/60 bg-red-950/95 p-3 text-xs text-red-50 shadow-2xl", children: [_jsx("div", { className: "mb-1 font-semibold uppercase tracking-wide text-red-200", children: "JG engine error" }), _jsxs("div", { className: "font-mono text-[11px] text-red-100", children: ["[", latest.phase, "] ", latest.message] }), explanation !== null ? _jsx("div", { className: "mt-2 text-red-100", children: explanation }) : null, latest.stack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.stack })) : null, latest.componentStack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.componentStack })) : null, _jsxs("div", { className: "mt-3 flex gap-2", children: [_jsx("button", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 font-semibold hover:bg-red-800", type: "button", onClick: () => {
-                            void navigator.clipboard.writeText(report).then(() => {
-                                setCopied(true);
-                                window.setTimeout(() => setCopied(false), 2000);
-                            });
-                        }, children: copied ? "Copied" : "Copy error" }), _jsx("a", { className: "rounded border border-red-300/50 bg-red-900 px-2 py-1 font-semibold hover:bg-red-800", href: issueUrl, rel: "noreferrer", target: "_blank", children: "File issue" })] })] }));
+    return (_jsxs("div", { className: "pointer-events-auto absolute right-4 top-4 z-50 max-w-lg select-text rounded border border-red-400/60 bg-red-950/95 p-3 text-xs text-red-50 shadow-2xl", children: [_jsx("div", { className: "mb-1 font-semibold uppercase tracking-wide text-red-200", children: "JG engine error" }), _jsxs("div", { className: "font-mono text-[11px] text-red-100", children: ["[", latest.phase, "] ", latest.message] }), explanation !== null ? _jsx("div", { className: "mt-2 text-red-100", children: explanation }) : null, latest.stack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.stack })) : null, latest.componentStack !== undefined ? (_jsx("pre", { className: "mt-2 max-h-36 overflow-auto whitespace-pre-wrap text-[10px] text-red-200/80", children: latest.componentStack })) : null, _jsx("div", { className: "mt-3", children: _jsx(ErrorReportActions, { report: report, issueTitle: `${latest.phase}: ${latest.message.slice(0, 100)}` }) })] }));
 }

package/dist/environment/EnvironmentScene.js

@@ -6,9 +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 { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
+import { RoadJunctions } from "./RoadJunctions.js";
 import { RoadRibbons } from "./RoadRibbons.js";
+import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
@@ -73,7 +76,7 @@ function TerrainGround({ terrain, field, center, }) {
 function areaCenter(area) {
     return area.position ?? [0, 0];
 }
-function Vegetation({ grass, field }) {
+function Vegetation({ grass, field, groundColor, }) {
     const [cx, cz] = areaCenter(grass.area);
     const heightAt = useMemo(() => cx === 0 && cz === 0
         ? field.sampleHeight
@@ -82,7 +85,15 @@ function Vegetation({ grass, field }) {
     const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
     const colorBase = grass.colors[0];
     const colorTip = grass.colors[grass.colors.length - 1];
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, wind: wind, frustumCulled: true }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
+}
+/** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
+function vegetationGroundColor(terrain, field, grass) {
+    const sampler = terrainGroundColorSampler(terrain, field);
+    if (sampler === undefined)
+        return undefined;
+    const [cx, cz] = areaCenter(grass.area);
+    return sampler(cx, cz);
 }
 function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
@@ -133,6 +144,7 @@ function Structures({ structures, field }) {
     const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({
         building,
         position: [0, field.sampleHeight(building.center[0], building.center[1]), 0],
+        ...(building.rotationY === undefined ? {} : { rotationY: building.rotationY, pivot: building.center }),
     })), [structures, field]);
     const palette = useMemo(() => resolveBuildingPalette(structures.style, structures.palette), [structures.style, structures.palette]);
     return _jsx(InstancedBuildings, { buildings: placements, palette: palette });
@@ -145,5 +157,7 @@ export function EnvironmentScene({ feature }) {
     const pads = feature.pads ?? [];
     const islands = feature.islands ?? [];
     const roads = feature.roads ?? [];
-    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 }, `road-${index}`))), 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 }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    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] }));
 }

package/dist/environment/RoadJunctions.d.ts

@@ -0,0 +1,12 @@
+import { type RoadJunction } from "@jgengine/core/world/streets";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/**
+ * 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.
+ * @internal
+ */
+export declare function RoadJunctions({ junctions, field, }: {
+    junctions: readonly RoadJunction[];
+    field: TerrainField;
+}): import("react").JSX.Element | null;

package/dist/environment/RoadJunctions.js

@@ -0,0 +1,69 @@
+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 { junctionMarkings } from "@jgengine/core/world/streets";
+function toGeometry(positions, indices) {
+    if (positions.length === 0)
+        return null;
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new BufferAttribute(positions, 3));
+    geometry.setIndex(new BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    return geometry;
+}
+/** Merge many thin marking ribbons (stop lines + crosswalk bars) into one buffer geometry. */
+function mergedBars(bars, width, field, elevation) {
+    const ribbons = bars.map((bar) => buildRoadRibbon(bar, width, (x, z) => field.sampleHeight(x, z), { elevation }));
+    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)
+        return null;
+    const positions = new Float32Array(vertexCount);
+    const indices = new Uint32Array(indexCount);
+    let vertexOffset = 0;
+    let indexOffset = 0;
+    for (const ribbon of ribbons) {
+        positions.set(ribbon.positions, vertexOffset);
+        const base = vertexOffset / 3;
+        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);
+}
+/**
+ * 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.
+ * @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]);
+    const markings = useMemo(() => {
+        const stopBars = [];
+        const crossBars = [];
+        let elevation = 0;
+        for (const junction of junctions) {
+            elevation = Math.max(elevation, junction.elevation);
+            const marks = junctionMarkings(junction);
+            for (const bar of marks.stopLines)
+                stopBars.push(bar);
+            for (const bar of marks.crosswalkBars)
+                crossBars.push(bar);
+        }
+        return {
+            stops: mergedBars(stopBars, 0.5, field, elevation + 0.05),
+            crosswalks: mergedBars(crossBars, 0.55, field, elevation + 0.05),
+        };
+    }, [junctions, field]);
+    if (patches.length === 0)
+        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] }));
+}

package/dist/environment/RoadRibbons.d.ts

@@ -1,7 +1,13 @@
 import type { RoadEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type DashExclusion } from "@jgengine/core/world/roads";
 import type { TerrainField } from "@jgengine/core/world/terrain";
-/** Renders one `road()` descriptor: an asphalt ribbon plus optional dashed centerline, draped on the terrain. */
-export declare function RoadRibbons({ road, field }: {
+/**
+ * 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).
+ */
+export declare function RoadRibbons({ road, field, exclusions, }: {
     road: RoadEnvironmentDescriptor;
     field: TerrainField;
+    exclusions?: readonly DashExclusion[];
 }): import("react").JSX.Element | null;

package/dist/environment/RoadRibbons.js

@@ -1,8 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
-import { BufferAttribute, BufferGeometry, DoubleSide } from "three";
+import { BufferAttribute, BufferGeometry, Color, DoubleSide } from "three";
 import { buildRoadRibbon, dashSegments } from "@jgengine/core/world/roads";
-import { offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+import { curbPaths, offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+/** Darken an asphalt color toward black for a curb/edge strip (deterministic, no alloc churn). */
+function darken(hex, amount) {
+    const c = new Color(hex);
+    c.multiplyScalar(1 - amount);
+    return `#${c.getHexString()}`;
+}
 function toGeometry(positions, indices) {
     if (positions.length === 0)
         return null;
@@ -16,9 +22,9 @@ 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) {
+function mergedDashGeometry(road, field, exclusions) {
     const width = Math.max(0.25, road.width * 0.035);
-    const ribbons = dashSegments(road.path, 3.2, 4).map((dash) => buildRoadRibbon(dash, width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation + 0.04 }));
+    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 }));
     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)
@@ -38,10 +44,22 @@ function mergedDashGeometry(road, field) {
     }
     return toGeometry(positions, indices);
 }
-/** Renders one `road()` descriptor: an asphalt ribbon plus optional dashed centerline, draped on the terrain. */
-export function RoadRibbons({ road, field }) {
+/**
+ * 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).
+ */
+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) : null), [road, field]);
+    const dashes = useMemo(() => (road.markings ? mergedDashGeometry(road, field, exclusions) : null), [road, field, exclusions]);
+    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 sidewalks = useMemo(() => {
         const width = sidewalkWidthOf(road);
         if (width <= 0)
@@ -53,5 +71,5 @@ export function RoadRibbons({ road, field }) {
     }, [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 }) }), 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.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}`)))] }));
 }

package/dist/environment/terrainGroundColor.d.ts

@@ -0,0 +1,9 @@
+import type { TerrainEnvironmentDescriptor } from "@jgengine/core/world/features";
+import { type TerrainField } from "@jgengine/core/world/terrain";
+/**
+ * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
+ * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
+ * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * @internal
+ */
+export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField): ((x: number, z: number) => string) | undefined;

package/dist/environment/terrainGroundColor.js

@@ -0,0 +1,22 @@
+import * as THREE from "three";
+import { resolveTerrainPalette } from "@jgengine/core/world/terrain";
+/**
+ * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
+ * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
+ * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * @internal
+ */
+export function terrainGroundColorSampler(terrain, field) {
+    if (terrain === undefined)
+        return undefined;
+    const palette = resolveTerrainPalette(terrain);
+    const low = new THREE.Color(palette.low);
+    const high = new THREE.Color(palette.high);
+    const base = terrain.baseHeight ?? 0;
+    const swing = terrain.height * 1.2;
+    const scratch = new THREE.Color();
+    return (x, z) => {
+        const t = swing <= 0 ? 0.5 : THREE.MathUtils.clamp((field.sampleHeight(x, z) - (base - swing)) / (swing * 2), 0, 1);
+        return `#${scratch.copy(low).lerp(high, t).getHexString()}`;
+    };
+}