@jgengine/shell 0.14.0 → 0.15.0-next.0

package/dist/render/SceneModels.js

@@ -3,7 +3,8 @@ 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";
@@ -20,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);
@@ -63,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(() => {
@@ -88,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;
@@ -130,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)
@@ -144,7 +173,7 @@ export function EntityModel({ model, instanceId, measure, }) {
     // 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 (measureTarget === undefined || measureKey === undefined)
+        if (ctx === null || measureTarget === undefined || measureKey === undefined)
             return;
         const triangles = measureLocalCollisionTriangles(scene, {
             scale,
@@ -168,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);
@@ -190,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/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 {

package/dist/render/modelLoad.js

@@ -2,7 +2,23 @@ import * as THREE from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
+import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
 import { resolveAssetBaseUrl } from "./assetBase.js";
+/** Model containers already covered by the whole-model fallback probe; not "texture" errors. @internal */
+const MODEL_URL_RE = /\.(glb|gltf)(\?|#|$)/i;
+/**
+ * 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 function recordManagerLoadError(url) {
+    if (MODEL_URL_RE.test(url))
+        return;
+    reportTextureLoadError(url);
+}
 /**
  * Dedicated LoadingManager for every GLB load instead of THREE.DefaultLoadingManager.
  * The shared default manager is process-wide; under repeated dev-server navigations its
@@ -12,6 +28,9 @@ import { resolveAssetBaseUrl } from "./assetBase.js";
  */
 const modelLoadingManager = new THREE.LoadingManager();
 modelLoadingManager.setURLModifier(resolveAssetBaseUrl);
+// Capture GLTF texture/image load failures that never reach the top-level model onError (the model still
+// resolves). Feeds the `textureErrors` probe so a texture-404'd scene is visible in debug_snapshot.
+modelLoadingManager.onError = recordManagerLoadError;
 /** How many leading bytes to read when probing a failed model URL for its signature. @internal */
 const PROBE_BYTE_LIMIT = 64;
 /**
@@ -42,11 +61,71 @@ export async function probeModelUrl(url, logicalId, fetchImpl = fetch) {
     }
 }
 /**
- * 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 function createFallbackModel(diagnosis) {
+    const scene = new THREE.Group();
+    scene.name = "jgengine-missing-model";
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial({ color: 0xd63384, roughness: 0.7, metalness: 0 }));
+    mesh.name = "jgengine-missing-model-box";
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    scene.add(mesh);
+    const userData = { jgengineFallback: true };
+    if (diagnosis !== undefined)
+        userData.jgengineDiagnosis = diagnosis;
+    return {
+        scene,
+        scenes: [scene],
+        animations: [],
+        cameras: [],
+        asset: { generator: "jgengine-fallback-model" },
+        // The fallback never runs a GLTF parser; consumers only read `scene`/`animations`.
+        parser: undefined,
+        userData,
+    };
+}
+function warnMissingModel(message) {
+    if (typeof console !== "undefined") {
+        console.warn(`[jgengine] ${message} Rendering a placeholder primitive in its place.`);
+    }
+}
+/**
+ * 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 async function handleModelLoadFailure(resolvedUrl, originalEvent, onLoad, onError, overrides = {}) {
+    const probe = overrides.probe ?? probeModelUrl;
+    const diagnosis = await probe(resolvedUrl);
+    if (diagnosis.ok) {
+        // The bytes look like a real model on re-fetch — surface the original parse error unchanged.
+        onError(originalEvent);
+        return;
+    }
+    (overrides.warn ?? warnMissingModel)(diagnosis.message);
+    onLoad(createFallbackModel(diagnosis));
+}
+/**
+ * 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 class DiagnosticGLTFLoader extends GLTFLoader {
@@ -55,19 +134,7 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
             if (onError === undefined)
                 return;
             // Probe the URL the loader actually fetched (base-resolved), not the raw input.
-            void probeModelUrl(this.manager.resolveURL(url))
-                .then((diagnosis) => {
-                if (diagnosis.ok) {
-                    // The bytes look fine on re-fetch — surface the original parse error unchanged.
-                    onError(event);
-                    return;
-                }
-                const enriched = new Error(`[jgengine] ${diagnosis.message}`);
-                enriched.diagnosis = diagnosis;
-                enriched.cause = event;
-                onError(enriched);
-            })
-                .catch(() => onError(event));
+            void handleModelLoadFailure(this.manager.resolveURL(url), event, onLoad, onError).catch(() => onError(event));
         });
     }
 }

package/dist/render/sceneCapture.d.ts

@@ -0,0 +1,27 @@
+/** The bit of a WebGL renderer scene capture needs — its backing `<canvas>`. */
+export interface CaptureRenderer {
+    domElement: {
+        toDataURL(type?: string): string;
+    };
+}
+/**
+ * Read the current frame to a PNG data URL. Requires the R3F `<Canvas>` to have
+ * been created with `gl={{ preserveDrawingBuffer: true }}` (the shell's game
+ * canvas already is); returns null if the backing canvas can't be read.
+ *
+ * @capability capture-canvas read the live R3F frame to a PNG data URL (needs preserveDrawingBuffer)
+ */
+export declare function captureCanvas(gl: CaptureRenderer): string | null;
+/** Trigger a browser download of an image data URL (the photo-mode "save" action). */
+export declare function downloadImage(dataUrl: string, filename?: string): void;
+/**
+ * In-`<Canvas>` binder that hands the scene-capture function out to HUD code
+ * living outside the reconciler (a photo-mode Capture button). Mount it inside
+ * the game's `WorldOverlay`; call `bind` receives a `() => string | null` that
+ * grabs the current frame. Renders nothing.
+ *
+ * @capability scene-capture-binding expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode)
+ */
+export declare function SceneCaptureBinding({ bind }: {
+    bind: (capture: () => string | null) => void;
+}): null;

package/dist/render/sceneCapture.js

@@ -0,0 +1,43 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+/**
+ * Read the current frame to a PNG data URL. Requires the R3F `<Canvas>` to have
+ * been created with `gl={{ preserveDrawingBuffer: true }}` (the shell's game
+ * canvas already is); returns null if the backing canvas can't be read.
+ *
+ * @capability capture-canvas read the live R3F frame to a PNG data URL (needs preserveDrawingBuffer)
+ */
+export function captureCanvas(gl) {
+    try {
+        const url = gl.domElement.toDataURL("image/png");
+        return url.startsWith("data:image/png") ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Trigger a browser download of an image data URL (the photo-mode "save" action). */
+export function downloadImage(dataUrl, filename = "screenshot.png") {
+    if (typeof document === "undefined")
+        return;
+    const anchor = document.createElement("a");
+    anchor.href = dataUrl;
+    anchor.download = filename;
+    anchor.click();
+}
+/**
+ * In-`<Canvas>` binder that hands the scene-capture function out to HUD code
+ * living outside the reconciler (a photo-mode Capture button). Mount it inside
+ * the game's `WorldOverlay`; call `bind` receives a `() => string | null` that
+ * grabs the current frame. Renders nothing.
+ *
+ * @capability scene-capture-binding expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode)
+ */
+export function SceneCaptureBinding({ bind }) {
+    const gl = useThree((state) => state.gl);
+    useEffect(() => {
+        bind(() => captureCanvas(gl));
+        return () => bind(() => null);
+    }, [gl, bind]);
+    return null;
+}

package/dist/render/useDisposable.d.ts

@@ -0,0 +1,16 @@
+import { type DependencyList } from "react";
+/** Anything exposing dispose() — three.js geometries, materials, textures, render targets. */
+export interface Disposable {
+    dispose(): void;
+}
+/** Dispose a single resource or every resource in a tuple. */
+export declare function disposeAll(value: Disposable | readonly Disposable[]): void;
+/**
+ * Memoize a three.js resource (or tuple of resources) and dispose it when `deps` change or the
+ * component unmounts. Owns the useMemo + dispose-effect pair that otherwise repeats at every
+ * GPU-resource call site. The factory must return objects exposing `dispose()` (geometries,
+ * materials, textures, render targets).
+ *
+ * @capability disposable-resource memoize a three.js GPU resource (or tuple) with automatic dispose on change/unmount — no hand-rolled useMemo + dispose-effect pairs
+ */
+export declare function useDisposable<T extends Disposable | readonly Disposable[]>(create: () => T, deps: DependencyList): T;

package/dist/render/useDisposable.js

@@ -0,0 +1,24 @@
+import { useEffect, useMemo } from "react";
+/** Dispose a single resource or every resource in a tuple. */
+export function disposeAll(value) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            item.dispose();
+        return;
+    }
+    value.dispose();
+}
+/**
+ * Memoize a three.js resource (or tuple of resources) and dispose it when `deps` change or the
+ * component unmounts. Owns the useMemo + dispose-effect pair that otherwise repeats at every
+ * GPU-resource call site. The factory must return objects exposing `dispose()` (geometries,
+ * materials, textures, render targets).
+ *
+ * @capability disposable-resource memoize a three.js GPU resource (or tuple) with automatic dispose on change/unmount — no hand-rolled useMemo + dispose-effect pairs
+ */
+export function useDisposable(create, deps) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const value = useMemo(create, deps);
+    useEffect(() => () => disposeAll(value), [value]);
+    return value;
+}

package/dist/render/useModelAnimation.js

@@ -3,7 +3,46 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
 import { resolveOneShotClip } from "@jgengine/core/game/modelAnimation";
-import { useGameContext } from "@jgengine/react/provider";
+import { useOptionalGameContext } from "@jgengine/react/provider";
+/**
+ * An explicit `animation` config always wins over `"auto"`, and both the state machine and the
+ * one-shot table degrade quietly when a named clip is absent: states fall back to `clips[0]` (often
+ * an attack clip, so an actor "idles" mid-swing) and one-shots are dropped, so deaths and attacks
+ * never play. Neither leaves a trace, which makes a mistyped or wrong-pack clip name one of the
+ * hardest render bugs to see — the model loads, animates, and is simply wrong forever.
+ *
+ * Warn once per mount with the names that missed and the names the rig actually has, so the fix
+ * (usually deleting the hand-written config and letting `"auto"` derive it) is obvious.
+ */
+function warnMissingClips(animation, clips) {
+    if (typeof console === "undefined")
+        return;
+    const available = new Set(clips.map((clip) => clip.name));
+    const missing = new Set();
+    const { states, oneShots } = animation;
+    if (states !== undefined) {
+        for (const name of [states.idle, states.walk, states.run]) {
+            if (name !== undefined && !available.has(name))
+                missing.add(name);
+        }
+    }
+    if (oneShots !== undefined) {
+        for (const spec of Object.values(oneShots)) {
+            for (const name of typeof spec === "string" ? [spec] : spec) {
+                if (!available.has(name))
+                    missing.add(name);
+            }
+        }
+    }
+    if (animation.clip !== undefined && !available.has(animation.clip))
+        missing.add(animation.clip);
+    if (missing.size === 0)
+        return;
+    console.warn(`[jgengine] model animation: clip(s) ${[...missing].map((name) => `"${name}"`).join(", ")} ` +
+        `not found on this rig. Available: ${clips.map((clip) => clip.name).join(", ")}. ` +
+        `States fall back to the first clip and one-shots are skipped — set animation: "auto" to ` +
+        `derive states/one-shots from the rig's own clip names.`);
+}
 /**
  * The engine's model animation driver as a standalone hook — the same mixer `EntityModel` runs,
  * for games that render a cloned scene themselves (custom materials, procedural composition).
@@ -12,7 +51,10 @@ import { useGameContext } from "@jgengine/react/provider";
  * `entity.animation` / `combat.hitReaction` / `entity.died`, held poses, and the death clamp.
  */
 export function useModelAnimation(scene, clips, animationInput, instanceId) {
-    const ctx = useGameContext();
+    // Optional: a model must still animate its bind pose / auto clip in a preview or inspector that
+    // has no running game — a hard context requirement made every part composition unviewable outside
+    // the world, which is half of why #1588 took a session to see.
+    const ctx = useOptionalGameContext();
     // "auto" (stamped by catalog resolution, or set inline) derives states/one-shots from the
     // loaded GLB's actual clip names; "none" and absent render the bind pose.
     const animation = useMemo(() => resolveAnimationConfig(animationInput, clips.map((clip) => clip.name)), [animationInput, clips]);
@@ -29,6 +71,7 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             stateActionsRef.current = null;
             return;
         }
+        warnMissingClips(animation, clips);
         const mixer = new THREE.AnimationMixer(scene);
         if (states !== undefined) {
             const clipFor = (name) => THREE.AnimationClip.findByName(clips, name) ?? clips[0];
@@ -138,7 +181,7 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
         oneShots,
     ]);
     useEffect(() => {
-        if (instanceId === undefined || oneShots === undefined)
+        if (ctx === null || instanceId === undefined || oneShots === undefined)
             return;
         const fire = (event) => oneShotPlayRef.current?.(event);
         const offAnimation = ctx.game.events.on("entity.animation", (event) => {
@@ -161,7 +204,7 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
     }, [ctx, instanceId, oneShots]);
     useFrame((_state, delta) => {
         const stateMachine = stateActionsRef.current;
-        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0) {
+        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0 && ctx !== null) {
             const entity = ctx.scene.entity.get(instanceId);
             if (entity !== null) {
                 const [x, , z] = entity.position;

package/dist/scene/AuthoredScene.js

@@ -1,9 +1,9 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useEffect, useMemo, useState } from "react";
+import { Fragment, useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
 import * as THREE from "three";
 import { getDocumentLiveSync, subscribeDocumentLiveSyncInstall, } from "@jgengine/core/editor/index";
 import { placeAuthoredObjects, resolveAuthoredObjects, } from "@jgengine/core/world/authoredObjects";
-import { buildRoadRibbon, roundPathCorners } from "@jgengine/core/world/roads";
+import { buildRoadRibbon, GROUND_DECAL_LAYERS, roundPathCorners } from "@jgengine/core/world/roads";
 import { isScatterPath, resolveScatter } from "@jgengine/core/world/scatterRegion";
 import { getAssetGenerator } from "@jgengine/core/scene/assetGenerator";
 import { useGameContext } from "@jgengine/react/provider";
@@ -12,6 +12,7 @@ import { InstancedScatter } from "../scatter/InstancedScatter.js";
 import { GeneratedAssetInstance } from "./GeneratedAssetRenderer.js";
 import { registerBuiltinSceneKindRenderers } from "./builtinSceneKindRenderers.js";
 import { getSceneKindRenderer } from "./sceneKindRenderers.js";
+const noopSubscribe = () => () => undefined;
 /**
  * Resolves the document AuthoredScene renders: when a {@link getDocumentLiveSync} bus is
  * installed (editor host live), subscribe to document patches; otherwise use the prop.
@@ -19,32 +20,20 @@ import { getSceneKindRenderer } from "./sceneKindRenderers.js";
  * @internal
  */
 export function useLiveEditorDocument(document, live = true) {
-    const [resolved, setResolved] = useState(document);
-    useEffect(() => {
-        if (!live) {
-            setResolved(document);
-            return;
-        }
-        let unsubDoc;
-        const attach = () => {
+    const subscribeLive = useCallback((onStoreChange) => {
+        let unsubDoc = getDocumentLiveSync()?.subscribeDocument(onStoreChange);
+        const unsubInstall = subscribeDocumentLiveSyncInstall(() => {
             unsubDoc?.();
-            unsubDoc = undefined;
-            const sync = getDocumentLiveSync();
-            if (sync === null) {
-                setResolved(document);
-                return;
-            }
-            setResolved(sync.getDocument());
-            unsubDoc = sync.subscribeDocument((event) => setResolved(event.document));
-        };
-        attach();
-        const unsubInstall = subscribeDocumentLiveSyncInstall(attach);
+            unsubDoc = getDocumentLiveSync()?.subscribeDocument(onStoreChange);
+            onStoreChange();
+        });
         return () => {
             unsubInstall();
             unsubDoc?.();
         };
-    }, [document, live]);
-    return live ? resolved : document;
+    }, []);
+    const getDocument = useCallback(() => (live ? (getDocumentLiveSync()?.getDocument() ?? document) : document), [live, document]);
+    return useSyncExternalStore(live ? subscribeLive : noopSubscribe, getDocument, getDocument);
 }
 registerBuiltinSceneKindRenderers();
 function markerToKindObject(marker) {
@@ -106,7 +95,8 @@ function DrapedPath({ points, width, color, field, }) {
         // Fillet sharp turns first so bends read as smooth arcs, not overlapping rectangles.
         const rounded = roundPathCorners(points, Math.max(1.5, width * 0.9), 6);
         const ribbon = buildRoadRibbon(rounded, width, (x, z) => field.sampleHeight(x, z), {
-            elevation: 0.18,
+            // Generic authored paths (dirt roads, routes, corridors) drape on the shared road decal layer.
+            elevation: GROUND_DECAL_LAYERS.road,
             maxSegmentLength: 1,
         });
         const geo = new THREE.BufferGeometry();