@jgengine/shell 0.21.0 → 0.23.0

package/dist/environment/RoadRibbons.js

@@ -3,6 +3,8 @@ import { useMemo } from "react";
 import { BufferAttribute, BufferGeometry, Color, DoubleSide } from "three";
 import { buildJunctionSurface, buildRoadRibbon, dashSegments, GROUND_DECAL_LAYERS, trimPathAtJunctions, } from "@jgengine/core/world/roads";
 import { offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+import { resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonSurfaceFrame, useSurfaceRibbonMaterial, } from "../terrain/surfaceRibbonMaterial.js";
+import { useTerrainQuality } from "../terrain/terrainQuality.js";
 /**
  * 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
@@ -47,7 +49,9 @@ function mergeRibbons(ribbons) {
         vertexOffset += ribbon.positions.length;
         indexOffset += ribbon.indices.length;
     }
-    return toGeometry(positions, indices);
+    const geometry = toGeometry(positions, indices);
+    geometry?.setAttribute(RIBBON_FRAME_ATTRIBUTE, new BufferAttribute(ribbonSurfaceFrame(ribbons.map((r) => r.positions)), 3));
+    return geometry;
 }
 /** Convert a detected {@link RoadJunction} into the structural {@link RoadJunctionInput} the trimmer wants. @internal */
 export function roadJunctionInput(junction) {
@@ -150,7 +154,9 @@ export function buildAuthoredRoadNetwork(roads, junctions, sampleHeight) {
  * 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.
+ * the dashed line no longer needs exclusion circles to skip intersections. The carriageway, curbs and
+ * sidewalks shade with the terrain's procedural surfaces (`road.surface`, default asphalt with tyre
+ * wear); `surface: false` keeps them flat.
  */
 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]);
@@ -192,7 +198,14 @@ export function RoadRibbons({ road, field, paths, }) {
         }
         return mergeRibbons(ribbons);
     }, [paths, road, field]);
+    const quality = useTerrainQuality();
+    const detailed = road.surface !== false;
+    const style = detailed ? resolvePathSurface("road", road.width, { surface: road.surface ?? "road" }) : null;
+    const asphaltMaterial = useSurfaceRibbonMaterial(style === null ? null : { surface: style.surface, wear: style.wear, color: road.color, halfWidth: road.width / 2, quality });
+    const curbMaterial = useSurfaceRibbonMaterial(detailed ? { surface: "concrete", color: curbColor, halfWidth: road.width / 2, roughness: 0.9, quality } : null);
+    const sidewalkColor = road.sidewalk === false ? "#a7adb8" : road.sidewalk.color;
+    const sidewalkMaterial = useSurfaceRibbonMaterial(detailed && sidewalks !== null ? { surface: "pavement", color: sidewalkColor, halfWidth: road.width / 2, roughness: 0.9, scale: 1.6, quality } : null);
     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 !== 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] }));
+    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, ...(asphaltMaterial === null ? {} : { material: asphaltMaterial }), children: asphaltMaterial === null ? _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) : null }), curbs !== null ? (_jsx("mesh", { geometry: curbs, receiveShadow: true, ...(curbMaterial === null ? {} : { material: curbMaterial }), children: curbMaterial === null ? _jsx("meshStandardMaterial", { color: curbColor, roughness: 0.9, metalness: 0, side: DoubleSide }) : null })) : 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, ...(sidewalkMaterial === null ? {} : { material: sidewalkMaterial }), children: sidewalkMaterial === null ? _jsx("meshStandardMaterial", { color: sidewalkColor, roughness: 0.9, metalness: 0, side: DoubleSide }) : null })) : null] }));
 }

package/dist/environment/terrainGroundColor.d.ts

@@ -1,9 +1,10 @@
 import type { TerrainEnvironmentDescriptor } from "@jgengine/core/world/features";
 import { type TerrainField } from "@jgengine/core/world/terrain";
+import { type TerraformSnapshot } from "@jgengine/core/world/terraform";
 /**
- * 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.
+ * Terrain base color at a world XZ — authored paint first, otherwise the regional palette lerped
+ * by ground height. Grass roots and soil-patch borders share the painted color with ground vertices.
+ * Descriptor surface mottling and fragment detail are presentation overlays, not sampled here.
  * @internal
  */
-export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField): ((x: number, z: number) => string) | undefined;
+export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField, sculpt?: TerraformSnapshot): ((x: number, z: number) => string) | undefined;

package/dist/environment/terrainGroundColor.js

@@ -1,22 +1,33 @@
 import * as THREE from "three";
-import { resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { createTerrainPaletteSampler, resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+import { createTerrainPaintColorSampler } from "../terrain/terrainPaintColor.js";
 /**
- * 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.
+ * Terrain base color at a world XZ — authored paint first, otherwise the regional palette lerped
+ * by ground height. Grass roots and soil-patch borders share the painted color with ground vertices.
+ * Descriptor surface mottling and fragment detail are presentation overlays, not sampled here.
  * @internal
  */
-export function terrainGroundColorSampler(terrain, field) {
-    if (terrain === undefined)
+export function terrainGroundColorSampler(terrain, field, sculpt) {
+    if (terrain === undefined && sculpt === undefined)
         return undefined;
     const palette = resolveTerrainPalette(terrain);
+    const paletteAt = terrain === undefined ? undefined : createTerrainPaletteSampler(terrain);
+    const paintColorAt = sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt));
     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 base = terrain?.baseHeight ?? 0;
+    const swing = (terrain?.height ?? 0) * 1.2;
     const scratch = new THREE.Color();
     return (x, z) => {
+        const regional = paletteAt?.(x, z);
+        if (regional !== undefined) {
+            low.set(regional.low);
+            high.set(regional.high);
+        }
         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()}`;
+        scratch.copy(low).lerp(high, t);
+        paintColorAt?.(x, z, scratch);
+        return `#${scratch.getHexString()}`;
     };
 }

package/dist/materialOverride.js

@@ -117,7 +117,8 @@ function applyRimLight(target, rim) {
     if (strength <= 0)
         return;
     const previousCompile = target.onBeforeCompile;
-    const previousKey = target.customProgramCacheKey();
+    const previousKey = target.customProgramCacheKey;
+    previousKey.call(target);
     target.onBeforeCompile = (shader, renderer) => {
         previousCompile.call(target, shader, renderer);
         shader.uniforms.uJgRimColor = { value: color };
@@ -133,6 +134,7 @@ outgoingLight += uJgRimColor * jgRim * uJgRimStrength;
 #include <opaque_fragment>`);
     };
     // Two materials differing only in rim tuning must not share a compiled program.
-    target.customProgramCacheKey = () => `${previousKey}|jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
+    // Read the chained key lazily: the default surface's key follows the live graphics tier.
+    target.customProgramCacheKey = () => `${previousKey.call(target)}|jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
     target.needsUpdate = true;
 }

package/dist/playSurfaceFocus.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Focus recovery for the play surface. Gameplay keys are read on the shell's focusable wrapper, so
+ * when a focused menu button unmounts (a start screen's "Play", a closed panel's last control) the
+ * browser drops focus to `<body>` and WASD silently does nothing until the player clicks the canvas.
+ * The one decision: reclaim only when the clicked element is gone from the document and
+ * nothing else took focus — a deliberate click elsewhere on the page keeps its focus.
+ * @internal
+ */
+export declare function shouldReclaimPlayFocus(lost: Element | null, active: Element | null, body: Element | null): boolean;
+/**
+ * Watches clicks (pointer, Enter or Space on a button) and, right after the click's update commits, returns focus to `surface()` if the clicked control unmounted and focus fell to the body.
+ * Chromium moves focus to `<body>` on removal without a `focusout`, so the click is the hook.
+ * Returns the cleanup.
+ * @internal
+ */
+export declare function installPlayFocusReclaim(doc: Document, surface: () => HTMLElement | null): () => void;

package/dist/playSurfaceFocus.js

@@ -0,0 +1,42 @@
+/**
+ * Focus recovery for the play surface. Gameplay keys are read on the shell's focusable wrapper, so
+ * when a focused menu button unmounts (a start screen's "Play", a closed panel's last control) the
+ * browser drops focus to `<body>` and WASD silently does nothing until the player clicks the canvas.
+ * The one decision: reclaim only when the clicked element is gone from the document and
+ * nothing else took focus — a deliberate click elsewhere on the page keeps its focus.
+ * @internal
+ */
+export function shouldReclaimPlayFocus(lost, active, body) {
+    if (lost === null || lost.isConnected)
+        return false;
+    return active === null || active === body;
+}
+/**
+ * Watches clicks (pointer, Enter or Space on a button) and, right after the click's update commits, returns focus to `surface()` if the clicked control unmounted and focus fell to the body.
+ * Chromium moves focus to `<body>` on removal without a `focusout`, so the click is the hook.
+ * Returns the cleanup.
+ * @internal
+ */
+export function installPlayFocusReclaim(doc, surface) {
+    let timer;
+    const onClick = (event) => {
+        const clicked = event.target instanceof Element ? event.target : null;
+        if (clicked === null)
+            return;
+        clearTimeout(timer);
+        // React commits a click's update synchronously at the end of the event; a macrotask is enough and,
+        // unlike a frame callback, does not stall when the page renders slowly.
+        timer = setTimeout(() => {
+            const target = surface();
+            if (target === null || !target.isConnected)
+                return;
+            if (shouldReclaimPlayFocus(clicked, doc.activeElement, doc.body))
+                target.focus({ preventScroll: true });
+        });
+    };
+    doc.addEventListener("click", onClick, true);
+    return () => {
+        clearTimeout(timer);
+        doc.removeEventListener("click", onClick, true);
+    };
+}

package/dist/postfx/PostProcessing.d.ts

@@ -1,5 +1,5 @@
 import { EffectComposer, type ShaderPass } from "three-stdlib";
-import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
+import { type AoConfig, type PostProcessingConfig } from "@jgengine/core/render/postProcessing";
 import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 interface BuiltGraph {
     composer: EffectComposer;
@@ -9,6 +9,8 @@ interface BuiltGraph {
 export declare function disposeGraph(built: BuiltGraph): void;
 /** Resize the composer and its passes at the renderer's pixel ratio. @internal */
 export declare function syncSize(built: BuiltGraph, width: number, height: number, pixelRatio: number): void;
+/** AO the chain runs: authored config, {@link DEFAULT_AO} when unset, null when off or the tier skips it. @internal */
+export declare function resolveAoStage(ao: PostProcessingConfig["ao"], tierAllowsAo: boolean): AoConfig | null;
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured

package/dist/postfx/PostProcessing.js

@@ -6,6 +6,7 @@ import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
+import { DEFAULT_AO } from "@jgengine/core/render/postProcessing";
 import { createGradePass } from "./gradeShader.js";
 import { StylizePass } from "./stylizePass.js";
 import { renderShadowlessPrepass } from "./shadowPrepass.js";
@@ -48,6 +49,12 @@ export function syncSize(built, width, height, pixelRatio) {
     built.composer.setPixelRatio(pixelRatio);
     built.composer.setSize(width, height);
 }
+/** AO the chain runs: authored config, {@link DEFAULT_AO} when unset, null when off or the tier skips it. @internal */
+export function resolveAoStage(ao, tierAllowsAo) {
+    if (!tierAllowsAo || ao === false)
+        return null;
+    return ao ?? DEFAULT_AO;
+}
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
@@ -76,15 +83,16 @@ export function PostProcessing({ config, quality = "high", stages }) {
         const composer = new EffectComposer(gl, target);
         composer.addPass(new RenderPass(scene, camera));
         const resolvedStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
-        if (resolvedStages.ao && config.ao !== undefined && config.ao !== false) {
+        const aoStage = resolveAoStage(config.ao, resolvedStages.ao);
+        if (aoStage !== null) {
             const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
-            ao.blendIntensity = config.ao.blend ?? 1;
+            ao.blendIntensity = aoStage.blend ?? 1;
             ao.updateGtaoMaterial({
-                radius: config.ao.radius ?? 1.8,
+                radius: aoStage.radius ?? 1.8,
                 distanceExponent: 1,
-                thickness: config.ao.distanceFalloff ?? 3.6,
-                scale: config.ao.intensity ?? 2.4,
-                samples: quality === "high" ? 16 : 8,
+                thickness: aoStage.distanceFalloff ?? 3.6,
+                scale: aoStage.intensity ?? 2.4,
+                samples: quality === "ultra" ? 16 : quality === "high" ? 12 : 8,
             });
             composer.addPass(ao);
         }

package/dist/registry.d.ts

@@ -2,10 +2,14 @@ import type { ComponentType, ReactNode } from "react";
 import type { PlayableGame as EnginePlayableGame, WorldOverlayProps } from "@jgengine/core/game/playableGame";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { HudTheme } from "@jgengine/react/hudTheme";
 import type { ViewmodelProps } from "./camera/GameFirstPersonCamera.js";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
 export type RenderObject = (object: SceneObject) => ReactNode;
 /** The concrete React-bound playable a shell `defineGame` returns and `GameHost` mounts — the one PlayableGame games handle. */
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps>>;
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject, ComponentType<ViewmodelProps>, ComponentType<WorldOverlayProps>> & {
+    /** HUD theme the shell applies at the `GameUI` root. Unset uses `defaultHudTheme`; `false` opts out of the default theme and the engine's generic HUD control styling. A theme the game sets inside `GameUI` still wins. */
+    hudTheme?: HudTheme | false;
+};
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
 export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/render/CascadedShadows.d.ts

@@ -1,6 +1,8 @@
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
+/** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
+export declare const DEFAULT_SHADOW_RADIUS = 1.25;
 /**
  * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
  * single 40-unit ortho frustum. Uses three.js `CSM` (shader injection on standard materials).

package/dist/render/CascadedShadows.js

@@ -2,6 +2,8 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
+/** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
+export const DEFAULT_SHADOW_RADIUS = 1.25;
 function isStandardMaterial(mat) {
     return mat instanceof THREE.MeshStandardMaterial || mat instanceof THREE.MeshPhysicalMaterial;
 }
@@ -41,6 +43,7 @@ export function CascadedShadows({ entry }) {
         for (const light of csm.lights) {
             light.color = new THREE.Color(entry.color ?? "#ffffff");
             light.castShadow = true;
+            light.shadow.radius = entry.shadowRadius ?? DEFAULT_SHADOW_RADIUS;
         }
         const unbind = bindCsmMaterials(scene, csm);
         csmRef.current = csm;
@@ -62,6 +65,7 @@ export function CascadedShadows({ entry }) {
         entry.shadowCameraSize,
         entry.shadowMapSize,
         entry.shadowMaxFar,
+        entry.shadowRadius,
     ]);
     useFrame(() => {
         const csm = csmRef.current;

package/dist/render/EntityPreview.js

@@ -19,5 +19,5 @@ export function EntityPreview({ children, model, instanceId, mood = "studio", ba
     const ctx = useOptionalGameContext();
     const subject = children ??
         (model !== undefined ? _jsx(IsolatedEntityModel, { model: model, instanceId: instanceId }) : null);
-    return (_jsx("div", { "data-jg-entity-preview": "", className: className, style: { position: "relative", width: "100%", height: "100%", ...style }, children: _jsx(Canvas, { shadows: true, dpr: dpr, camera: { position: cameraPosition, fov }, gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: _jsx(GameContextBridge, { context: ctx, children: _jsx(StudioStage, { mood: mood, ...(backdrop === undefined ? {} : { backdrop }), turntable: turntable, faceCamera: faceCamera, ...(forward === undefined ? {} : { forward }), environment: environment, children: subject }) }) }) }));
+    return (_jsx("div", { "data-jg-entity-preview": "", className: className, style: { position: "relative", width: "100%", height: "100%", ...style }, children: _jsx(Canvas, { shadows: "percentage", dpr: dpr, camera: { position: cameraPosition, fov }, gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: _jsx(GameContextBridge, { context: ctx, children: _jsx(StudioStage, { mood: mood, ...(backdrop === undefined ? {} : { backdrop }), turntable: turntable, faceCamera: faceCamera, ...(forward === undefined ? {} : { forward }), environment: environment, children: subject }) }) }) }));
 }

package/dist/render/EnvironmentLighting.d.ts

@@ -1,29 +1,48 @@
+import * as THREE from "three";
 import type { EnvironmentSource } from "@jgengine/core/render/environment";
 /** @internal Props for shell {@link EnvironmentLighting}. */
 export interface EnvironmentLightingProps {
     /** Optional authored environment map; absent or `gradient` uses the procedural probe. */
     source?: EnvironmentSource;
-    /** IBL intensity. Default 0.35. */
+    /** IBL intensity. Default {@link DEFAULT_IBL_INTENSITY}. */
     intensity?: number;
     /** Upper-hemisphere tint for the procedural sky probe. Default cool daylight. */
     skyColor?: string;
     /** Ground / lower-hemisphere tint. Default soft earth. */
     groundColor?: string;
+    /** Tint the horizon band leans toward, usually the scene's ambient colour so IBL keeps its warmth. Default white. */
+    horizonTint?: string;
     /**
-     * Optional sun direction (world space, not normalized). When set, a bright disc
-     * is baked into the probe so metals pick up a real sun glint that tracks daylight.
+     * Sun direction (world space, not normalized) baked into the probe as an HDR disc plus a broad
+     * lobe, so metals glint and diffuse IBL has a lit side. Default {@link DEFAULT_PROBE_SUN}.
      */
     sunDirection?: readonly [number, number, number];
     /** Sun disc tint. Default warm white. */
     sunColor?: string;
 }
 /**
- * Image-based lighting from a procedural sky/ground probe (not three's stock
- * RoomEnvironment gray studio box). Metals and dielectrics pick up sky color and
- * an optional sun glint; re-render when sky/sun props change so a daylight cycle
+ * Image-based lighting from a procedural sky/horizon/ground probe with an HDR sun (not three's stock
+ * RoomEnvironment gray studio box). Metals and dielectrics pick up sky color, a sun glint and a
+ * directional sky fill; re-render when sky/sun props change so a daylight cycle
  * regenerates the environment map with the authored world.
  *
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, sunDirection, sunColor, }: EnvironmentLightingProps): null;
+export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, horizonTint, sunDirection, sunColor, }: EnvironmentLightingProps): null;
+/** @internal Default IBL strength for the procedural probe: enough sky fill and sun lobe to model forms. */
+export declare const DEFAULT_IBL_INTENSITY = 0.45;
+/** @internal Fallback probe sun when no directional light is authored: high and off to one side. */
+export declare const DEFAULT_PROBE_SUN: readonly [number, number, number];
+/**
+ * @internal Procedural sky probe: zenith → brighter horizon → ground bounce, plus an HDR sun disc and
+ * a wide glow lobe. After PMREM the lobe becomes a directional diffuse term, so the IBL alone gives
+ * forms a lit and a shaded side instead of a uniform two-tone wash.
+ */
+export declare function buildSkyProbeScene(options: {
+    skyColor: string;
+    groundColor: string;
+    horizonTint?: string;
+    sunDirection?: readonly [number, number, number];
+    sunColor: string;
+}): THREE.Scene;

package/dist/render/EnvironmentLighting.js

@@ -5,15 +5,15 @@ import * as THREE from "three";
 import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
 import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
 /**
- * Image-based lighting from a procedural sky/ground probe (not three's stock
- * RoomEnvironment gray studio box). Metals and dielectrics pick up sky color and
- * an optional sun glint; re-render when sky/sun props change so a daylight cycle
+ * Image-based lighting from a procedural sky/horizon/ground probe with an HDR sun (not three's stock
+ * RoomEnvironment gray studio box). Metals and dielectrics pick up sky color, a sun glint and a
+ * directional sky fill; re-render when sky/sun props change so a daylight cycle
  * regenerates the environment map with the authored world.
  *
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b5e0", groundColor = "#3d4a38", sunDirection, sunColor = "#fff2d6", }) {
+export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY, skyColor = "#87b5e0", groundColor = "#3d4a38", horizonTint = "#ffffff", sunDirection, sunColor = "#fff2d6", }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     useEffect(() => {
@@ -91,7 +91,7 @@ export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b
                 });
             }
             else {
-                const probe = buildSkyProbeScene({ skyColor: effective?.sky ?? skyColor, groundColor: effective?.ground ?? groundColor, sunDirection, sunColor: effective?.sun ?? sunColor });
+                const probe = buildSkyProbeScene({ skyColor: effective?.sky ?? skyColor, groundColor: effective?.ground ?? groundColor, horizonTint, sunDirection, sunColor: effective?.sun ?? sunColor });
                 try {
                     apply(pmrem.fromScene(probe, 0.04));
                 }
@@ -105,19 +105,36 @@ export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b
             throw error;
         }
         return release;
-    }, [gl, scene, source, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
+    }, [gl, scene, source, intensity, skyColor, groundColor, horizonTint, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
     return null;
 }
-function buildSkyProbeScene(options) {
+/** @internal Default IBL strength for the procedural probe: enough sky fill and sun lobe to model forms. */
+export const DEFAULT_IBL_INTENSITY = 0.45;
+/** @internal Fallback probe sun when no directional light is authored: high and off to one side. */
+export const DEFAULT_PROBE_SUN = [-0.45, 0.8, 0.35];
+/**
+ * @internal Procedural sky probe: zenith → brighter horizon → ground bounce, plus an HDR sun disc and
+ * a wide glow lobe. After PMREM the lobe becomes a directional diffuse term, so the IBL alone gives
+ * forms a lit and a shaded side instead of a uniform two-tone wash.
+ */
+export function buildSkyProbeScene(options) {
     const probe = new THREE.Scene();
-    // Inward-facing sphere: sky above, ground below, so PMREM samples a sky dome not a studio box.
-    const geo = new THREE.SphereGeometry(50, 32, 16);
+    const sun = new THREE.Vector3(...(options.sunDirection ?? DEFAULT_PROBE_SUN));
+    if (sun.lengthSq() < 1e-8)
+        sun.set(...DEFAULT_PROBE_SUN);
+    sun.normalize();
+    const sky = new THREE.Color(options.skyColor);
+    const horizon = sky.clone().lerp(new THREE.Color(options.horizonTint ?? "#ffffff"), 0.35);
+    const geo = new THREE.SphereGeometry(50, 48, 24);
     const mat = new THREE.ShaderMaterial({
         side: THREE.BackSide,
         depthWrite: false,
         uniforms: {
-            sky: { value: new THREE.Color(options.skyColor) },
+            zenith: { value: sky.clone().multiplyScalar(0.85) },
+            horizon: { value: horizon },
             ground: { value: new THREE.Color(options.groundColor) },
+            sunDir: { value: sun },
+            sunColor: { value: new THREE.Color(options.sunColor) },
         },
         vertexShader: /* glsl */ `
       varying vec3 vDir;
@@ -127,30 +144,26 @@ function buildSkyProbeScene(options) {
       }
     `,
         fragmentShader: /* glsl */ `
-      uniform vec3 sky;
+      uniform vec3 zenith;
+      uniform vec3 horizon;
       uniform vec3 ground;
+      uniform vec3 sunDir;
+      uniform vec3 sunColor;
       varying vec3 vDir;
       void main() {
-        float t = clamp(vDir.y * 0.5 + 0.5, 0.0, 1.0);
-        // Soft horizon blend so the equator is not a hard band.
-        float w = smoothstep(0.0, 1.0, t);
-        gl_FragColor = vec4(mix(ground, sky, w), 1.0);
+        vec3 d = normalize(vDir);
+        float up = clamp(d.y, -1.0, 1.0);
+        vec3 col = up >= 0.0
+          ? mix(horizon, zenith, pow(up, 0.6))
+          : mix(horizon * 0.55 + ground * 0.45, ground * 0.7, smoothstep(0.0, 0.5, -up));
+        float facing = max(dot(d, sunDir), 0.0);
+        // Disc for specular glints; the broad lobe is what survives PMREM into the diffuse term.
+        col += sunColor * (pow(facing, 900.0) * 24.0 + pow(facing, 6.0) * 0.6 + pow(facing, 2.0) * 0.1);
+        gl_FragColor = vec4(col, 1.0);
       }
     `,
     });
     probe.add(new THREE.Mesh(geo, mat));
-    if (options.sunDirection !== undefined) {
-        const dir = new THREE.Vector3(options.sunDirection[0], options.sunDirection[1], options.sunDirection[2]);
-        if (dir.lengthSq() > 1e-8) {
-            dir.normalize();
-            const sunGeo = new THREE.SphereGeometry(3.5, 16, 12);
-            const sunMat = new THREE.MeshBasicMaterial({ color: options.sunColor });
-            const sun = new THREE.Mesh(sunGeo, sunMat);
-            // Place the disc outside the sky sphere sample so it stays a compact highlight.
-            sun.position.copy(dir.multiplyScalar(42));
-            probe.add(sun);
-        }
-    }
     return probe;
 }
 function disposeScene(scene) {

package/dist/render/SceneLighting.js

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useRef } from "react";
-import { CascadedShadows } from "./CascadedShadows.js";
+import { CascadedShadows, DEFAULT_SHADOW_RADIUS } from "./CascadedShadows.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
 /** Default cap for combined dynamic point and spot lights. */
 export const POINT_LIGHT_BUDGET = 8;
@@ -58,7 +58,7 @@ function SingleShadowLight({ entry }) {
         light.shadow.map.dispose();
         light.shadow.map = null;
     }, [mapSize]);
-    return (_jsx("directionalLight", { ref: lightRef, position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": mapSize, "shadow-mapSize-height": mapSize, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": far, "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
+    return (_jsx("directionalLight", { ref: lightRef, position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": mapSize, "shadow-mapSize-height": mapSize, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": far, "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02, "shadow-radius": entry.shadowRadius ?? DEFAULT_SHADOW_RADIUS }));
 }
 export function ConfiguredLighting({ lighting, profile }) {
     const dynamic = resolveDynamicLights(lighting);

package/dist/render/modelLoad.d.ts

@@ -122,5 +122,12 @@ export declare function materialKtx2Loader(): KTX2Loader;
  * @capability model-load-idle how long the shared GLB loader has been idle, for capture settle waits
  */
 export declare function modelLoadIdleMs(): number;
+/**
+ * How many times the shared GLB loader has gone from idle to busy since boot. A capture host
+ * compares two readings around a rendered frame to tell whether that frame started new model
+ * streaming, which an idle reading alone cannot show.
+ * @capability model-load-starts count of model streaming bursts, for capture quiescence checks
+ */
+export declare function modelLoadStarts(): number;
 /** Shared GLTF loader used by shell entity/object model mounts. @internal */
 export declare const sharedGltfLoader: DiagnosticGLTFLoader;

package/dist/render/modelLoad.js

@@ -6,6 +6,7 @@ import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.j
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
 import { resolveAssetBaseUrl } from "./assetBase.js";
+import { applyModelSurface } from "./modelSurface.js";
 /** Model containers already covered by the whole-model fallback probe; not "texture" errors. @internal */
 const MODEL_URL_RE = /\.(glb|gltf)(\?|#|$)/i;
 /**
@@ -210,6 +211,7 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
     load(url, onLoad, onProgress, onError) {
         super.load(url, (gltf) => {
             recordModelTriangles(url, countSceneTriangles(gltf.scene));
+            applyModelSurface(gltf.scene);
             onLoad(gltf);
         }, onProgress, (event) => {
             if (onError === undefined)
@@ -258,9 +260,11 @@ export function materialKtx2Loader() {
 // a drain timestamp is the whole state.
 let modelQueueBusy = false;
 let modelQueueDrainedAt = 0;
+let modelQueueStarts = 0;
 const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
 modelLoadingManager.onStart = () => {
     modelQueueBusy = true;
+    modelQueueStarts += 1;
 };
 modelLoadingManager.onLoad = () => {
     modelQueueBusy = false;
@@ -280,6 +284,15 @@ export function modelLoadIdleMs() {
         return Number.POSITIVE_INFINITY;
     return now() - modelQueueDrainedAt;
 }
+/**
+ * How many times the shared GLB loader has gone from idle to busy since boot. A capture host
+ * compares two readings around a rendered frame to tell whether that frame started new model
+ * streaming, which an idle reading alone cannot show.
+ * @capability model-load-starts count of model streaming bursts, for capture quiescence checks
+ */
+export function modelLoadStarts() {
+    return modelQueueStarts;
+}
 /** Shared GLTF loader used by shell entity/object model mounts. @internal */
 export const sharedGltfLoader = new DiagnosticGLTFLoader(modelLoadingManager);
 sharedGltfLoader.setMeshoptDecoder(MeshoptDecoder);

package/dist/render/modelRender.d.ts

@@ -19,6 +19,7 @@ export declare function modelPlacementTransform(root: THREE.Object3D, model: Mod
 export declare function cloneModelScene(source: THREE.Object3D, options?: {
     cloneMaterials?: boolean;
     shadows?: ModelShadowMode;
+    surfaceDetail?: boolean;
 }): THREE.Object3D;
 /**
  * Release materials and bone textures owned by `cloneModelScene`; shared assets and attached models remain owned by their callers.

package/dist/render/modelRender.js

@@ -2,6 +2,7 @@ import * as THREE from "three";
 import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
 import { measureLocalBounds } from "./measureBounds.js";
 import { copyModelBindPose } from "./modelBindPose.js";
+import { optOutModelSurface } from "./modelSurface.js";
 export const PAINT_TEXTURE_SIZE = 512;
 const modelResources = new WeakMap();
 /** Register an instance replacement without transferring borrowed geometry or textures. @internal */
@@ -56,6 +57,8 @@ export function cloneModelScene(source, options) {
             material = source.clone();
             material.onBeforeCompile = source.onBeforeCompile;
             material.customProgramCacheKey = source.customProgramCacheKey;
+            if (options?.surfaceDetail === false)
+                optOutModelSurface(material);
             materials.set(source, material);
         }
         return material;