@jgengine/shell 0.13.0 → 0.15.0-next.0

package/dist/render/EnvironmentLighting.js

@@ -1,27 +1,28 @@
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
 import * as THREE from "three";
-import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
 /**
- * Sets a neutral, network-free image-based-lighting environment on the scene so every
- * `MeshStandardMaterial` — models and un-modeled primitive fallbacks alike — picks up soft
- * reflections and fill instead of rendering dead-flat. A game's own sky/lighting still layers on
- * top; this only supplies the reflective ambient the shell never had. Opt out with `look: "flat"`.
+ * 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
+ * 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({ intensity = 0.28 }) {
+export function EnvironmentLighting({ intensity = 0.35, skyColor = "#87b5e0", groundColor = "#3d4a38", sunDirection, sunColor = "#fff2d6", }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     useEffect(() => {
         const pmrem = new THREE.PMREMGenerator(gl);
-        const room = new RoomEnvironment();
-        const target = pmrem.fromScene(room, 0.04);
+        const probe = buildSkyProbeScene({ skyColor, groundColor, sunDirection, sunColor });
+        const target = pmrem.fromScene(probe, 0.04);
         const previous = scene.environment;
         scene.environment = target.texture;
         const sceneWithIntensity = scene;
         const previousIntensity = sceneWithIntensity.environmentIntensity;
         sceneWithIntensity.environmentIntensity = intensity;
-        room.dispose?.();
+        disposeScene(probe);
         pmrem.dispose();
         return () => {
             target.dispose();
@@ -29,6 +30,64 @@ export function EnvironmentLighting({ intensity = 0.28 }) {
             if (previousIntensity !== undefined)
                 sceneWithIntensity.environmentIntensity = previousIntensity;
         };
-    }, [gl, scene, intensity]);
+    }, [gl, scene, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
     return null;
 }
+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 mat = new THREE.ShaderMaterial({
+        side: THREE.BackSide,
+        depthWrite: false,
+        uniforms: {
+            sky: { value: new THREE.Color(options.skyColor) },
+            ground: { value: new THREE.Color(options.groundColor) },
+        },
+        vertexShader: /* glsl */ `
+      varying vec3 vDir;
+      void main() {
+        vDir = normalize(position);
+        gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+      }
+    `,
+        fragmentShader: /* glsl */ `
+      uniform vec3 sky;
+      uniform vec3 ground;
+      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);
+      }
+    `,
+    });
+    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) {
+    scene.traverse((obj) => {
+        const mesh = obj;
+        if (mesh.isMesh) {
+            mesh.geometry?.dispose();
+            const material = mesh.material;
+            if (Array.isArray(material))
+                material.forEach((m) => m.dispose());
+            else
+                material?.dispose();
+        }
+    });
+}

package/dist/render/PartMotion.js

@@ -3,7 +3,7 @@ import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { createPartPose, partMotionPhase, sampleBodyPose, samplePartPose, } from "@jgengine/core/game/partAnimation";
-import { useGameContext } from "@jgengine/react/provider";
+import { useOptionalGameContext } from "@jgengine/react/provider";
 const FLINCH_RELEASE_SEC = 0.35;
 const DEATH_RAMP_PER_SEC = 2.5;
 const SPEED_SMOOTHING = 12;
@@ -16,7 +16,7 @@ const SPEED_SMOOTHING = 12;
  * as static kit pieces. Children are the base model content (primitive, attachments).
  */
 export function PartMotionRig({ parts, model, instanceId, renderPart, children, }) {
-    const ctx = useGameContext();
+    const ctx = useOptionalGameContext();
     const rootRef = useRef(null);
     const partRefs = useRef([]);
     const motionRef = useRef({
@@ -27,7 +27,7 @@ export function PartMotionRig({ parts, model, instanceId, renderPart, children,
     });
     const phase = useMemo(() => partMotionPhase(instanceId ?? model.url), [instanceId, model.url]);
     useEffect(() => {
-        if (instanceId === undefined)
+        if (ctx === null || instanceId === undefined)
             return;
         const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
             if (event.instanceId === instanceId)
@@ -46,7 +46,7 @@ export function PartMotionRig({ parts, model, instanceId, renderPart, children,
     const pose = useMemo(() => createPartPose(), []);
     useFrame((frameState, delta) => {
         const motion = motionRef.current;
-        if (delta > 0 && instanceId !== undefined) {
+        if (delta > 0 && instanceId !== undefined && ctx !== null) {
             const entity = ctx.scene.entity.get(instanceId);
             if (entity !== null) {
                 const [x, , z] = entity.position;

package/dist/render/SceneLighting.js

@@ -1,6 +1,13 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CascadedShadows } from "./CascadedShadows.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
+function usesCascades(entry) {
+    return (entry.castShadow ?? false) && (entry.cascades ?? 1) > 1;
+}
 function DirectionalShadowLight({ entry }) {
+    if (usesCascades(entry)) {
+        return _jsx(CascadedShadows, { entry: entry });
+    }
     const size = entry.shadowCameraSize ?? 40;
     return (_jsx("directionalLight", { 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": entry.shadowMapSize ?? 1024, "shadow-mapSize-height": entry.shadowMapSize ?? 1024, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": Math.max(200, size * 6), "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
 }

package/dist/render/SceneModels.d.ts

@@ -1,8 +1,44 @@
-import { type ReactNode } from "react";
+import { Component, type ReactNode } from "react";
 import type { EntitySpriteConfig, ModelConfig } from "@jgengine/core/game/playableGame";
+import { type FallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
 export declare function EntitySprite({ sprite }: {
     sprite: EntitySpriteConfig;
 }): import("react").JSX.Element;
+/**
+ * Catches a render throw from a model subtree and swaps in `fallback` — but never silently: the
+ * failed state re-reports to the fallback-seam probe on every render (matching the per-seam frame
+ * boundary in `WorldScene`) and the catch warns once with the model url and the error. Without
+ * that, a throw anywhere in a composition erases the actor with an empty `probes.fallbacks`.
+ * @internal
+ */
+export declare class ModelFallbackBoundary extends Component<{
+    fallback: ReactNode;
+    children: ReactNode;
+    url: string;
+    seam?: FallbackSeam;
+}, {
+    failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(error: unknown): void;
+    render(): ReactNode;
+}
+/**
+ * One model subtree behind its own error boundary and Suspense boundary, so a throwing or
+ * still-loading piece cannot erase its siblings. Every nested piece of a composition — parts,
+ * attachments, material maps — mounts through this.
+ * @internal
+ */
+export declare function IsolatedModelPart({ model, seam, children, }: {
+    model: ModelConfig;
+    seam?: FallbackSeam;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function IsolatedEntityModel({ model, instanceId, measure, fallback, }: {
     model: ModelConfig;
     instanceId?: string;

package/dist/render/SceneModels.js

@@ -3,9 +3,11 @@ import { useFrame, useLoader } from "@react-three/fiber";
 import { useTexture } from "@react-three/drei";
 import { Component, Suspense, useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
-import { useGameContext } from "@jgengine/react/provider";
+import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
+import { useOptionalGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "./modelLoad.js";
 import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
+import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
 import { useModelAnimation } from "./useModelAnimation.js";
 import { PartMotionRig } from "./PartMotion.js";
 import { applyMaterialOverride } from "../materialOverride.js";
@@ -19,17 +21,42 @@ export function EntitySprite({ sprite }) {
     }, [texture]);
     return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: texture, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
 }
-class ModelFallbackBoundary extends Component {
+/**
+ * Catches a render throw from a model subtree and swaps in `fallback` — but never silently: the
+ * failed state re-reports to the fallback-seam probe on every render (matching the per-seam frame
+ * boundary in `WorldScene`) and the catch warns once with the model url and the error. Without
+ * that, a throw anywhere in a composition erases the actor with an empty `probes.fallbacks`.
+ * @internal
+ */
+export class ModelFallbackBoundary extends Component {
     state = { failed: false };
     static getDerivedStateFromError() {
         return { failed: true };
     }
+    componentDidCatch(error) {
+        if (typeof console === "undefined")
+            return;
+        console.warn(`[jgengine] model "${this.props.url}" threw while rendering and was replaced by its fallback ` +
+            `(nothing, unless one was supplied). Fix the throw below — the actor is invisible until then.`, error);
+    }
     render() {
-        return this.state.failed ? this.props.fallback : this.props.children;
+        if (!this.state.failed)
+            return this.props.children;
+        reportFallbackSeam(this.props.seam ?? "entity", "renderError");
+        return this.props.fallback;
     }
 }
+/**
+ * One model subtree behind its own error boundary and Suspense boundary, so a throwing or
+ * still-loading piece cannot erase its siblings. Every nested piece of a composition — parts,
+ * attachments, material maps — mounts through this.
+ * @internal
+ */
+export function IsolatedModelPart({ model, seam, children, }) {
+    return (_jsx(ModelFallbackBoundary, { fallback: null, url: model.url, seam: seam, children: _jsx(Suspense, { fallback: null, children: children }) }));
+}
 export function IsolatedEntityModel({ model, instanceId, measure, fallback, }) {
-    return (_jsx(ModelFallbackBoundary, { fallback: fallback ?? null, children: _jsx(Suspense, { fallback: null, children: _jsx(EntityModel, { model: model, instanceId: instanceId, measure: measure }) }) }));
+    return (_jsx(ModelFallbackBoundary, { fallback: fallback ?? null, url: model.url, seam: measure?.target, children: _jsx(Suspense, { fallback: null, children: _jsx(EntityModel, { model: model, instanceId: instanceId, measure: measure }) }) }));
 }
 function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
     const gltf = useLoader(sharedGltfLoader, model.url);
@@ -62,7 +89,7 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
 }
 /** Renders a static kit-of-parts child at a fixed local offset under the parent model — no bone/rig lookup, unlike `BoneAttachment`. The nested `EntityModel` still applies its own `dims`/anchor centering, so scale/pivot sanity carries over per part. */
 function ModelPartGroup({ model, position, rotation, scale, }) {
-    return (_jsx("group", { position: position ?? [0, 0, 0], rotation: rotation ?? [0, 0, 0], scale: scale ?? 1, children: _jsx(EntityModel, { model: model }) }));
+    return (_jsx("group", { position: position ?? [0, 0, 0], rotation: rotation ?? [0, 0, 0], scale: scale ?? 1, children: _jsx(IsolatedModelPart, { model: model, children: _jsx(EntityModel, { model: model }) }) }));
 }
 function ModelMaterialMapsApplier({ scene, maps }) {
     const entries = useMemo(() => {
@@ -87,7 +114,10 @@ function ModelMaterialMapsApplier({ scene, maps }) {
 }
 export function EntityModel({ model, instanceId, measure, }) {
     const gltf = useLoader(sharedGltfLoader, model.url);
-    const ctx = useGameContext();
+    // Optional, not required: measured bounds and paint strokes are live-world extras, and a model
+    // that threw without a running game could not be inspected outside one — which is how a broken
+    // composition stayed undiagnosable in `EntityPreview` (#1588).
+    const ctx = useOptionalGameContext();
     const material = model.material;
     const baseY = model.y ?? 0;
     const dims = model.dims;
@@ -129,7 +159,7 @@ export function EntityModel({ model, instanceId, measure, }) {
     const dimsMaxY = dims?.maxY;
     const [positionX, positionY, positionZ] = position;
     useEffect(() => {
-        if (measureTarget === undefined || measureKey === undefined || dimsMaxY !== undefined)
+        if (ctx === null || measureTarget === undefined || measureKey === undefined || dimsMaxY !== undefined)
             return;
         const raw = measureLocalBounds(scene);
         if (raw === null)
@@ -140,6 +170,18 @@ export function EntityModel({ model, instanceId, measure, }) {
             meshCount: raw.meshCount,
         });
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey, dimsMaxY]);
+    // Runs with or without index dims: the loaded geometry upgrades whatever box the kind resolved
+    // (fitted or measured) to a hitbox that raycasts the model's own triangles.
+    useEffect(() => {
+        if (ctx === null || measureTarget === undefined || measureKey === undefined)
+            return;
+        const triangles = measureLocalCollisionTriangles(scene, {
+            scale,
+            offset: [positionX, positionY, positionZ],
+        });
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, measureTarget, measureKey, triangles);
+    }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey]);
     useModelAnimation(scene, gltf.animations, model.animation, instanceId);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
@@ -155,7 +197,7 @@ export function EntityModel({ model, instanceId, measure, }) {
         materialCacheRef.current = null;
     }, [scene]);
     useFrame(() => {
-        if (instanceId === undefined)
+        if (ctx === null || instanceId === undefined)
             return;
         const paint = ctx.scene.entity.paint;
         const version = paint.version(instanceId);
@@ -177,12 +219,12 @@ export function EntityModel({ model, instanceId, measure, }) {
         }
         paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
     });
-    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }, `${attachment.slot}-${index}`)))] }));
+    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? (_jsx(IsolatedModelPart, { model: model, children: _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) })) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
     const parts = model.parts ?? [];
     // Any role-tagged part switches the composition onto the procedural part-motion rig:
     // root bob/flinch/topple plus per-role limb swing, driven from the entity's live state.
     if (parts.some((part) => part.role !== undefined)) {
-        return (_jsx(PartMotionRig, { parts: parts, model: model, instanceId: instanceId, renderPart: (part) => (typeof part.model === "string" ? null : _jsx(EntityModel, { model: part.model })), children: base }));
+        return (_jsx(PartMotionRig, { parts: parts, model: model, instanceId: instanceId, renderPart: (part) => typeof part.model === "string" ? null : (_jsx(IsolatedModelPart, { model: part.model, children: _jsx(EntityModel, { model: part.model }) })), children: base }));
     }
     return (_jsxs(_Fragment, { children: [base, parts.map((part, index) => typeof part.model === "string" ? null : (_jsx(ModelPartGroup, { model: part.model, position: part.position, rotation: part.rotation, scale: part.scale }, index)))] }));
 }

package/dist/render/measureBounds.js

@@ -3,6 +3,7 @@ import { useFrame } from "@react-three/fiber";
 import { useRef } from "react";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
 /** Subtrees flagged with this userData key are excluded from bounds measurement — debug gizmos,
  * selection quads, effect billboards that should not inflate the hitbox. Sprites and invisible
  * subtrees are always excluded. */
@@ -122,6 +123,9 @@ export function MeasuredBoundsGroup({ target, measureKey, children, }) {
             return;
         lastMeshCountRef.current = measured.meshCount;
         reportMeasuredBounds(ctx, target, measureKey, measured);
+        const triangles = measureLocalCollisionTriangles(group);
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, target, measureKey, triangles);
     });
     return _jsx("group", { ref: groupRef, children: children });
 }

package/dist/render/measureCollisionMesh.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from "three";
+import type { CollisionMeshSource } from "@jgengine/core/scene/collisionMesh";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/** Entity-local triangle soup of the meshes under a measured root, plus the contributing mesh count
+ * (same async fill-in detection as measured bounds). Satisfies {@link CollisionMeshSource}. */
+export interface MeasuredCollisionTriangles extends CollisionMeshSource {
+    positions: Float32Array;
+    indices: Uint32Array;
+    triangleCount: number;
+    meshCount: number;
+}
+/**
+ * Collect the triangle soup of the meshes under `root` in `root`'s own frame — the mesh-accurate
+ * counterpart to `measureLocalBounds`, with the same visibility/sprite/{@link MEASURE_EXCLUDE_KEY}
+ * exclusions (skinned meshes contribute their bind pose). An optional uniform `scale` + `offset`
+ * maps the result into entity-local space when the caller mounts the root scaled/translated (the
+ * model-primitive path). Returns `null` when nothing is measurable or the soup exceeds the
+ * triangle budget — callers keep their box fallback.
+ */
+export declare function measureLocalCollisionTriangles(root: THREE.Object3D, transform?: {
+    scale: number;
+    offset: readonly [number, number, number];
+}): MeasuredCollisionTriangles | null;
+/** Forward measured triangles into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same soup so remounts and multi-instance kinds don't rebuild the BVH. */
+export declare function reportMeasuredCollisionMesh(ctx: GameContext, target: "entity" | "object", key: string, triangles: MeasuredCollisionTriangles): void;

package/dist/render/measureCollisionMesh.js

@@ -0,0 +1,108 @@
+import * as THREE from "three";
+import { MEASURE_EXCLUDE_KEY } from "./measureBounds.js";
+/** Above this the model is too dense to double as its own hitbox — keep the fitted box instead of
+ * paying BVH build + per-ray traversal on a hero-detail mesh. Game-ready low-poly assets sit far under it. */
+const MAX_COLLISION_TRIANGLES = 60_000;
+const IDENTITY = new THREE.Matrix4();
+const tmpVec = new THREE.Vector3();
+function collectTriangles(object, parentMatrix, sink) {
+    if (sink.overflow)
+        return;
+    if (parentMatrix !== null) {
+        if (!object.visible)
+            return;
+        if (object.isSprite === true)
+            return;
+        if (object.userData[MEASURE_EXCLUDE_KEY] === true)
+            return;
+    }
+    let matrix = null;
+    if (parentMatrix !== null) {
+        if (object.matrixAutoUpdate)
+            object.updateMatrix();
+        matrix = new THREE.Matrix4().multiplyMatrices(parentMatrix, object.matrix);
+    }
+    const mesh = object;
+    if (mesh.isMesh === true && mesh.geometry !== undefined) {
+        const geometry = mesh.geometry;
+        const positionAttribute = geometry.getAttribute("position");
+        if (positionAttribute !== undefined && positionAttribute.itemSize === 3 && positionAttribute.count >= 3) {
+            const base = sink.positions.length / 3;
+            const applied = matrix ?? IDENTITY;
+            for (let v = 0; v < positionAttribute.count; v += 1) {
+                tmpVec.fromBufferAttribute(positionAttribute, v).applyMatrix4(applied);
+                sink.positions.push(tmpVec.x, tmpVec.y, tmpVec.z);
+            }
+            const index = geometry.getIndex();
+            const triangleCount = index !== null ? Math.floor(index.count / 3) : Math.floor(positionAttribute.count / 3);
+            if (sink.triangleCount + triangleCount > MAX_COLLISION_TRIANGLES) {
+                sink.overflow = true;
+                return;
+            }
+            if (index !== null) {
+                for (let i = 0; i + 2 < index.count; i += 3) {
+                    sink.indices.push(base + index.getX(i), base + index.getX(i + 1), base + index.getX(i + 2));
+                }
+            }
+            else {
+                for (let i = 0; i + 2 < positionAttribute.count; i += 3) {
+                    sink.indices.push(base + i, base + i + 1, base + i + 2);
+                }
+            }
+            sink.triangleCount += triangleCount;
+            sink.meshCount += 1;
+        }
+    }
+    const childMatrix = matrix ?? IDENTITY;
+    for (const child of object.children)
+        collectTriangles(child, childMatrix, sink);
+}
+/**
+ * Collect the triangle soup of the meshes under `root` in `root`'s own frame — the mesh-accurate
+ * counterpart to `measureLocalBounds`, with the same visibility/sprite/{@link MEASURE_EXCLUDE_KEY}
+ * exclusions (skinned meshes contribute their bind pose). An optional uniform `scale` + `offset`
+ * maps the result into entity-local space when the caller mounts the root scaled/translated (the
+ * model-primitive path). Returns `null` when nothing is measurable or the soup exceeds the
+ * triangle budget — callers keep their box fallback.
+ */
+export function measureLocalCollisionTriangles(root, transform) {
+    const sink = { positions: [], indices: [], meshCount: 0, triangleCount: 0, overflow: false };
+    collectTriangles(root, null, sink);
+    if (sink.overflow || sink.meshCount === 0 || sink.triangleCount === 0)
+        return null;
+    const positions = new Float32Array(sink.positions);
+    if (transform !== undefined) {
+        const { scale, offset } = transform;
+        for (let v = 0; v < positions.length; v += 3) {
+            positions[v] = positions[v] * scale + offset[0];
+            positions[v + 1] = positions[v + 1] * scale + offset[1];
+            positions[v + 2] = positions[v + 2] * scale + offset[2];
+        }
+    }
+    return {
+        positions,
+        indices: new Uint32Array(sink.indices),
+        triangleCount: sink.triangleCount,
+        meshCount: sink.meshCount,
+    };
+}
+const reportedByContext = new WeakMap();
+/** Forward measured triangles into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same soup so remounts and multi-instance kinds don't rebuild the BVH. */
+export function reportMeasuredCollisionMesh(ctx, target, key, triangles) {
+    let map = reportedByContext.get(ctx);
+    if (map === undefined) {
+        map = new Map();
+        reportedByContext.set(ctx, map);
+    }
+    const registryKey = `${target}:${key}`;
+    const prev = map.get(registryKey);
+    if (prev !== undefined && prev.meshCount === triangles.meshCount && prev.triangleCount === triangles.triangleCount) {
+        return;
+    }
+    const accepted = target === "entity"
+        ? ctx.scene.entity.reportCollisionMesh(key, triangles)
+        : ctx.scene.object.reportCollisionMesh(key, triangles);
+    if (accepted)
+        map.set(registryKey, { meshCount: triangles.meshCount, triangleCount: triangles.triangleCount });
+}

package/dist/render/modelLoad.d.ts

@@ -1,5 +1,14 @@
 import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
+/**
+ * The shared GLB {@link THREE.LoadingManager}'s `onError` sink. It fires for EVERY item the manager
+ * loads — the GLB container AND each texture/image a `GLTFLoader` fetches for it. The container's own
+ * failure is already surfaced by the model-fallback probe (it resolves to a placeholder), so this records
+ * only the sub-resource (texture) failures the fallback probe cannot see — a model that resolves but whose
+ * textures 404. Split out and exported so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export declare function recordManagerLoadError(url: string): void;
 /**
  * Re-fetch a model URL that just failed to load and classify what actually came
  * back — a 404, a dev-server HTML fallback, a corrupt or non-model body — so the
@@ -10,11 +19,38 @@ import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
  */
 export declare function probeModelUrl(url: string, logicalId?: string, fetchImpl?: typeof fetch): Promise<AssetLoadDiagnosis>;
 /**
- * A {@link GLTFLoader} whose success path is unchanged but whose failures are
- * enriched: when a load errors, it probes the URL and rejects with an
- * {@link AssetLoadDiagnosis}-derived message (missing / HTML fallback / corrupt /
- * unsupported) instead of the raw parse error. Drop-in for the shared loader, so
- * `useLoader(sharedGltfLoader, url)` benefits with no call-site change.
+ * Build a stand-in {@link GLTF} whose scene is a single magenta placeholder box,
+ * returned in place of a model that could not be loaded. Consumers clone and
+ * mount `gltf.scene` exactly as they would a real model, so one broken asset
+ * degrades to a visible primitive instead of taking down the scene. The optional
+ * `diagnosis` is stashed on `userData.jgengineDiagnosis` for debugging.
+ * @internal
+ */
+export declare function createFallbackModel(diagnosis?: AssetLoadDiagnosis): GLTF;
+/**
+ * The failure seam for {@link DiagnosticGLTFLoader}: re-probe the URL a load just
+ * failed on and decide what the loader should hand back. A diagnosed broken asset
+ * (missing / HTML dev-server fallback / corrupt / unsupported) resolves via
+ * `onLoad` to a {@link createFallbackModel} primitive so the failure is contained
+ * at the load seam for **every** consumer — no reliance on a React error boundary
+ * catching a rejected Suspense promise, which does not fire reliably for async
+ * loader rejections inside the react-three-fiber reconciler. Only a genuine parse
+ * error over bytes that still look like a valid model (`diagnosis.ok`) is surfaced
+ * through `onError`. Split out from the loader so it is unit-testable without a GL
+ * context; `overrides` inject the probe and warning sink in tests.
+ * @internal
+ */
+export declare function handleModelLoadFailure(resolvedUrl: string, originalEvent: unknown, onLoad: (gltf: GLTF) => void, onError: (event: unknown) => void, overrides?: {
+    probe?: typeof probeModelUrl;
+    warn?: (message: string) => void;
+}): Promise<void>;
+/**
+ * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
+ * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
+ * asset (missing / HTML fallback / corrupt / unsupported) — resolves to a
+ * {@link createFallbackModel} placeholder primitive instead of rejecting, so the
+ * one broken model never bubbles a throw past its mount. Drop-in for the shared
+ * loader, so `useLoader(sharedGltfLoader, url)` benefits with no call-site change.
  * @internal
  */
 export declare class DiagnosticGLTFLoader extends GLTFLoader {