@jgengine/shell 0.13.0 → 0.15.0-next.0

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();