@jgengine/shell 0.9.0 → 0.11.0

package/dist/render/SceneModels.js

@@ -0,0 +1,337 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { resolveOneShotClip } from "@jgengine/core/game/modelAnimation";
+import { useGameContext } from "@jgengine/react/provider";
+import { sharedGltfLoader } from "./modelLoad.js";
+import { applyMaterialOverride } from "../materialOverride.js";
+import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
+export function EntitySprite({ sprite }) {
+    const texture = useLoader(THREE.TextureLoader, sprite.url);
+    useEffect(() => {
+        texture.colorSpace = THREE.SRGBColorSpace;
+        texture.anisotropy = 4;
+        texture.needsUpdate = true;
+    }, [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 {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+export function IsolatedEntityModel({ model, instanceId, fallback, }) {
+    return (_jsx(ModelFallbackBoundary, { fallback: fallback ?? null, children: _jsx(Suspense, { fallback: null, children: _jsx(EntityModel, { model: model, instanceId: instanceId }) }) }));
+}
+function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
+    const gltf = useLoader(sharedGltfLoader, model.url);
+    const weaponScene = useMemo(() => cloneModelScene(gltf.scene), [gltf]);
+    const px = position?.[0] ?? 0;
+    const py = position?.[1] ?? 0;
+    const pz = position?.[2] ?? 0;
+    const rx = rotation?.[0] ?? 0;
+    const ry = rotation?.[1] ?? 0;
+    const rz = rotation?.[2] ?? 0;
+    const s = scale ?? 1;
+    useEffect(() => {
+        const bone = rig.getObjectByName(slot);
+        if (bone === undefined) {
+            if (typeof console !== "undefined") {
+                console.warn(`[jgengine] entityModels attachment: bone/slot "${slot}" not found on the rig`);
+            }
+            return;
+        }
+        weaponScene.position.set(px, py, pz);
+        weaponScene.rotation.set(rx, ry, rz);
+        weaponScene.scale.setScalar(s);
+        bone.add(weaponScene);
+        return () => {
+            bone.remove(weaponScene);
+        };
+    }, [rig, weaponScene, slot, px, py, pz, rx, ry, rz, s]);
+    useEffect(() => () => disposeClonedMaterials(weaponScene), [weaponScene]);
+    return null;
+}
+/** 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 }) }));
+}
+function ModelMaterialMapsApplier({ scene, maps }) {
+    const entries = useMemo(() => {
+        const record = {};
+        if (maps.color !== undefined)
+            record.color = maps.color;
+        if (maps.normal !== undefined)
+            record.normal = maps.normal;
+        if (maps.roughness !== undefined)
+            record.roughness = maps.roughness;
+        if (maps.ao !== undefined)
+            record.ao = maps.ao;
+        return record;
+    }, [maps.color, maps.normal, maps.roughness, maps.ao]);
+    const textures = useTexture(entries);
+    useEffect(() => {
+        if (textures.color !== undefined)
+            textures.color.colorSpace = THREE.SRGBColorSpace;
+        applyMaterialOverride(scene, {}, { clone: false, textures });
+    }, [scene, textures]);
+    return null;
+}
+export function EntityModel({ model, instanceId }) {
+    const gltf = useLoader(sharedGltfLoader, model.url);
+    const ctx = useGameContext();
+    const material = model.material;
+    const baseY = model.y ?? 0;
+    const dims = model.dims;
+    const scene = useMemo(() => {
+        const cloned = cloneModelScene(gltf.scene);
+        if (material !== undefined)
+            applyMaterialOverride(cloned, material, { clone: false });
+        return cloned;
+    }, [gltf, material]);
+    const measured = useMemo(() => {
+        if (model.targetHeight === undefined)
+            return null;
+        const box = new THREE.Box3().setFromObject(scene);
+        const height = box.max.y - box.min.y;
+        if (!Number.isFinite(height) || height <= 0)
+            return null;
+        return {
+            normalize: model.targetHeight / height,
+            minY: box.min.y,
+            centerX: (box.min.x + box.max.x) / 2,
+            centerZ: (box.min.z + box.max.z) / 2,
+        };
+    }, [scene, model.targetHeight]);
+    const scale = (model.scale ?? 1) * (measured?.normalize ?? 1);
+    const centered = (model.anchor ?? "center") === "center" && dims !== undefined;
+    const position = measured !== null
+        ? [-scale * measured.centerX, baseY - scale * measured.minY, -scale * measured.centerZ]
+        : centered
+            ? [-scale * dims.center.x, baseY - scale * dims.minY, -scale * dims.center.z]
+            : [0, baseY, 0];
+    useEffect(() => () => {
+        disposeClonedMaterials(scene);
+    }, [scene]);
+    const animation = model.animation;
+    const mixerRef = useRef(null);
+    const animationPausedRef = useRef(false);
+    const stateActionsRef = useRef(null);
+    const states = animation?.states;
+    const oneShots = animation?.oneShots;
+    const oneShotPlayRef = useRef(null);
+    const activeOneShotRef = useRef(null);
+    useEffect(() => {
+        if (animation === undefined || gltf.animations.length === 0) {
+            mixerRef.current = null;
+            stateActionsRef.current = null;
+            return;
+        }
+        const mixer = new THREE.AnimationMixer(scene);
+        if (states !== undefined) {
+            const clipFor = (name) => THREE.AnimationClip.findByName(gltf.animations, name) ?? gltf.animations[0];
+            const actions = {
+                idle: mixer.clipAction(clipFor(states.idle)),
+                walk: mixer.clipAction(clipFor(states.walk)),
+                ...(states.run === undefined ? {} : { run: mixer.clipAction(clipFor(states.run)) }),
+            };
+            for (const action of Object.values(actions)) {
+                action.setLoop(THREE.LoopRepeat, Infinity);
+                action.timeScale = animation.timeScale ?? 1;
+                action.enabled = true;
+            }
+            actions.idle.play();
+            mixer.update(0);
+            mixerRef.current = mixer;
+            stateActionsRef.current = { actions, active: "idle", lastPos: null, smoothedSpeed: 0 };
+            animationPausedRef.current = false;
+            let onOneShotFinished = null;
+            if (oneShots !== undefined) {
+                const clipNames = new Set();
+                for (const spec of Object.values(oneShots)) {
+                    if (typeof spec === "string")
+                        clipNames.add(spec);
+                    else
+                        for (const name of spec)
+                            clipNames.add(name);
+                }
+                const oneShotActions = new Map();
+                for (const name of clipNames) {
+                    const found = THREE.AnimationClip.findByName(gltf.animations, name);
+                    if (found === null)
+                        continue;
+                    const oneShotAction = mixer.clipAction(found);
+                    oneShotAction.setLoop(THREE.LoopOnce, 1);
+                    oneShotAction.enabled = true;
+                    oneShotActions.set(name, oneShotAction);
+                }
+                onOneShotFinished = ({ action }) => {
+                    const active = activeOneShotRef.current;
+                    if (active === null || action !== active.action || active.isDeath)
+                        return;
+                    const machine = stateActionsRef.current;
+                    const back = machine?.actions[machine.active];
+                    action.fadeOut(0.15);
+                    if (back !== undefined)
+                        back.reset().fadeIn(0.15).play();
+                    activeOneShotRef.current = null;
+                };
+                mixer.addEventListener("finished", onOneShotFinished);
+                oneShotPlayRef.current = (event) => {
+                    const active = activeOneShotRef.current;
+                    if (active !== null && active.isDeath)
+                        return;
+                    const clipName = resolveOneShotClip(oneShots, event, Math.random());
+                    if (clipName === null)
+                        return;
+                    const oneShotAction = oneShotActions.get(clipName);
+                    if (oneShotAction === undefined)
+                        return;
+                    const machine = stateActionsRef.current;
+                    machine?.actions[machine.active]?.fadeOut(0.1);
+                    if (active !== null && active.action !== oneShotAction)
+                        active.action.stop();
+                    oneShotAction.clampWhenFinished = event === "death";
+                    oneShotAction.reset().fadeIn(0.1).play();
+                    activeOneShotRef.current = { action: oneShotAction, isDeath: event === "death" };
+                };
+            }
+            return () => {
+                if (onOneShotFinished !== null)
+                    mixer.removeEventListener("finished", onOneShotFinished);
+                oneShotPlayRef.current = null;
+                activeOneShotRef.current = null;
+                mixer.stopAllAction();
+                mixerRef.current = null;
+                stateActionsRef.current = null;
+            };
+        }
+        const clip = (animation.clip !== undefined ? THREE.AnimationClip.findByName(gltf.animations, animation.clip) : undefined) ??
+            gltf.animations[0];
+        const action = mixer.clipAction(clip);
+        action.setLoop(animation.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Infinity);
+        action.clampWhenFinished = animation.loop === false;
+        action.timeScale = animation.timeScale ?? 1;
+        action.enabled = true;
+        action.paused = animation.paused === true;
+        action.play();
+        if (animation.time !== undefined)
+            action.time = animation.time;
+        mixer.update(0);
+        mixerRef.current = mixer;
+        animationPausedRef.current = animation.paused === true;
+        return () => {
+            mixer.stopAllAction();
+            mixerRef.current = null;
+        };
+    }, [
+        scene,
+        gltf,
+        animation?.clip,
+        animation?.loop,
+        animation?.timeScale,
+        animation?.paused,
+        animation?.time,
+        states,
+        oneShots,
+    ]);
+    useEffect(() => {
+        if (instanceId === undefined || oneShots === undefined)
+            return;
+        const fire = (event) => oneShotPlayRef.current?.(event);
+        const offAnimation = ctx.game.events.on("entity.animation", (event) => {
+            if (event.instanceId === instanceId)
+                fire(event.event);
+        });
+        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
+            if (event.instanceId === instanceId)
+                fire("hit");
+        });
+        const offDied = ctx.game.events.on("entity.died", (event) => {
+            if (event.instanceId === instanceId)
+                fire("death");
+        });
+        return () => {
+            offAnimation();
+            offHit();
+            offDied();
+        };
+    }, [ctx, instanceId, oneShots]);
+    const paintCanvasRef = useRef(null);
+    const paintDrawnCountRef = useRef(0);
+    const paintVersionRef = useRef(-1);
+    const materialCacheRef = useRef(null);
+    useEffect(() => () => {
+        if (paintCanvasRef.current !== null) {
+            disposePaintCanvas(paintCanvasRef.current);
+            paintCanvasRef.current = null;
+        }
+        paintDrawnCountRef.current = 0;
+        paintVersionRef.current = -1;
+        materialCacheRef.current = null;
+    }, [scene]);
+    useFrame((_state, delta) => {
+        const stateMachine = stateActionsRef.current;
+        if (stateMachine !== null && states !== undefined && instanceId !== undefined && delta > 0) {
+            const entity = ctx.scene.entity.get(instanceId);
+            if (entity !== null) {
+                const [x, , z] = entity.position;
+                if (stateMachine.lastPos !== null) {
+                    const instantSpeed = Math.hypot(x - stateMachine.lastPos[0], z - stateMachine.lastPos[2]) / delta;
+                    stateMachine.smoothedSpeed +=
+                        (instantSpeed - stateMachine.smoothedSpeed) * Math.min(1, delta * 12);
+                }
+                stateMachine.lastPos = [x, entity.position[1], z];
+                const walkSpeed = states.walkSpeed ?? 0.5;
+                const runSpeed = states.runSpeed ?? 6;
+                const next = stateMachine.smoothedSpeed < walkSpeed
+                    ? "idle"
+                    : stateMachine.actions.run !== undefined && stateMachine.smoothedSpeed >= runSpeed
+                        ? "run"
+                        : "walk";
+                if (next !== stateMachine.active) {
+                    if (activeOneShotRef.current === null) {
+                        const fade = states.fadeSec ?? 0.2;
+                        const from = stateMachine.actions[stateMachine.active];
+                        const to = stateMachine.actions[next];
+                        if (from !== undefined && to !== undefined) {
+                            to.reset().fadeIn(fade).play();
+                            from.fadeOut(fade);
+                        }
+                    }
+                    stateMachine.active = next;
+                }
+            }
+        }
+        if (mixerRef.current !== null && !animationPausedRef.current)
+            mixerRef.current.update(delta);
+        if (instanceId === undefined)
+            return;
+        const paint = ctx.scene.entity.paint;
+        const version = paint.version(instanceId);
+        if (version === paintVersionRef.current)
+            return;
+        paintVersionRef.current = version;
+        const strokes = paint.strokes(instanceId);
+        const cache = cacheStandardMaterials(scene, materialCacheRef.current);
+        materialCacheRef.current = cache;
+        if (paintCanvasRef.current === null) {
+            if (strokes.length === 0)
+                return;
+            const seed = cache.materials[0];
+            if (seed === undefined)
+                return;
+            const paintCanvas = createPaintCanvas(seed);
+            paintCanvasRef.current = paintCanvas;
+            applyPaintTextureToMaterials(cache.materials, paintCanvas);
+        }
+        paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
+    });
+    return (_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}`))), (model.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/defaultSurface.d.ts

@@ -0,0 +1,29 @@
+import { type ThreeElements } from "@react-three/fiber";
+import * as THREE from "three";
+/**
+ * Shared, lazily-built procedural detail maps (a subtle tangent-space normal map plus a
+ * roughness-variation map) used by every un-modeled primitive so a flat colored box reads as a
+ * surface, not plastic. Pure JS `DataTexture` — no canvas/DOM, so it imports safely under `bun test`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export declare function detailMaps(): {
+    normal: THREE.DataTexture;
+    roughness: THREE.DataTexture;
+};
+/**
+ * Props for {@link DefaultSurface}: a required base `color` plus optional PBR overrides.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export interface DefaultSurfaceProps extends Omit<ThreeElements["meshStandardMaterial"], "args" | "normalMap" | "roughnessMap"> {
+    color: THREE.ColorRepresentation;
+    roughness?: number;
+    metalness?: number;
+    detail?: boolean;
+}
+/**
+ * The upgraded default material for un-modeled entities/objects: tuned PBR roughness/metalness plus
+ * the shared procedural detail maps, so primitive fallbacks catch light and image-based reflections
+ * instead of reading as flat plastic. Drop-in replacement for a bare `<meshStandardMaterial color>`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export declare function DefaultSurface({ color, roughness, metalness, detail, ...rest }: DefaultSurfaceProps): import("react").JSX.Element;

package/dist/render/defaultSurface.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "@react-three/fiber";
+import { useMemo } from "react";
+import * as THREE from "three";
+const DETAIL_SIZE = 64;
+const DETAIL_REPEAT = 3;
+const NORMAL_STRENGTH = 2.2;
+const ROUGHNESS_SPREAD = 0.14;
+function periodicValueNoise(size, cells, seed) {
+    const lattice = new Float32Array(cells * cells);
+    for (let index = 0; index < lattice.length; index += 1) {
+        const h = Math.sin((index + 1) * 12.9898 + seed * 78.233) * 43758.5453;
+        lattice[index] = h - Math.floor(h);
+    }
+    const at = (cx, cy) => lattice[((cy % cells) + cells) % cells * cells + (((cx % cells) + cells) % cells)];
+    const field = new Float32Array(size * size);
+    const step = cells / size;
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const fx = x * step;
+            const fy = y * step;
+            const x0 = Math.floor(fx);
+            const y0 = Math.floor(fy);
+            const tx = fx - x0;
+            const ty = fy - y0;
+            const sx = tx * tx * (3 - 2 * tx);
+            const sy = ty * ty * (3 - 2 * ty);
+            const top = at(x0, y0) * (1 - sx) + at(x0 + 1, y0) * sx;
+            const bottom = at(x0, y0 + 1) * (1 - sx) + at(x0 + 1, y0 + 1) * sx;
+            field[y * size + x] = top * (1 - sy) + bottom * sy;
+        }
+    }
+    return field;
+}
+function heightField(size) {
+    const coarse = periodicValueNoise(size, 4, 1);
+    const medium = periodicValueNoise(size, 8, 7);
+    const fine = periodicValueNoise(size, 16, 13);
+    const field = new Float32Array(size * size);
+    for (let index = 0; index < field.length; index += 1) {
+        field[index] = coarse[index] * 0.55 + medium[index] * 0.3 + fine[index] * 0.15;
+    }
+    return field;
+}
+let cached = null;
+/**
+ * Shared, lazily-built procedural detail maps (a subtle tangent-space normal map plus a
+ * roughness-variation map) used by every un-modeled primitive so a flat colored box reads as a
+ * surface, not plastic. Pure JS `DataTexture` — no canvas/DOM, so it imports safely under `bun test`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export function detailMaps() {
+    if (cached !== null)
+        return cached;
+    const size = DETAIL_SIZE;
+    const height = heightField(size);
+    const sample = (x, y) => height[(((y % size) + size) % size) * size + (((x % size) + size) % size)];
+    const normalData = new Uint8Array(size * size * 4);
+    const roughnessData = new Uint8Array(size * size * 4);
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const dx = (sample(x - 1, y) - sample(x + 1, y)) * NORMAL_STRENGTH;
+            const dy = (sample(x, y - 1) - sample(x, y + 1)) * NORMAL_STRENGTH;
+            const length = Math.hypot(dx, dy, 1);
+            const offset = (y * size + x) * 4;
+            normalData[offset] = Math.round((dx / length * 0.5 + 0.5) * 255);
+            normalData[offset + 1] = Math.round((dy / length * 0.5 + 0.5) * 255);
+            normalData[offset + 2] = Math.round((1 / length * 0.5 + 0.5) * 255);
+            normalData[offset + 3] = 255;
+            const rough = Math.round((0.5 + (sample(x, y) - 0.5) * 2 * ROUGHNESS_SPREAD * 0.5) * 255);
+            roughnessData[offset] = rough;
+            roughnessData[offset + 1] = rough;
+            roughnessData[offset + 2] = rough;
+            roughnessData[offset + 3] = 255;
+        }
+    }
+    const build = (data) => {
+        const texture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+        texture.wrapS = THREE.RepeatWrapping;
+        texture.wrapT = THREE.RepeatWrapping;
+        texture.repeat.set(DETAIL_REPEAT, DETAIL_REPEAT);
+        texture.minFilter = THREE.LinearMipmapLinearFilter;
+        texture.magFilter = THREE.LinearFilter;
+        texture.generateMipmaps = true;
+        texture.anisotropy = 4;
+        texture.needsUpdate = true;
+        return texture;
+    };
+    cached = { normal: build(normalData), roughness: build(roughnessData) };
+    return cached;
+}
+/**
+ * The upgraded default material for un-modeled entities/objects: tuned PBR roughness/metalness plus
+ * the shared procedural detail maps, so primitive fallbacks catch light and image-based reflections
+ * instead of reading as flat plastic. Drop-in replacement for a bare `<meshStandardMaterial color>`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export function DefaultSurface({ color, roughness = 0.72, metalness = 0.04, detail = true, ...rest }) {
+    const maps = useMemo(() => (detail ? detailMaps() : null), [detail]);
+    return (_jsx("meshStandardMaterial", { color: color, roughness: roughness, metalness: metalness, envMapIntensity: 0.6, normalMap: maps?.normal ?? null, normalScale: maps === null ? undefined : new THREE.Vector2(0.6, 0.6), roughnessMap: maps?.roughness ?? null, ...rest }));
+}

package/dist/render/modelLoad.d.ts

@@ -0,0 +1,24 @@
+import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
+/**
+ * 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
+ * runtime can replace an opaque GLTF parse error with a diagnosis naming the
+ * broken asset contract. Runs only on the error path (loads rarely fail), and
+ * never throws: a failed probe returns a `missing` diagnosis instead.
+ * @internal
+ */
+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.
+ * @internal
+ */
+export declare class DiagnosticGLTFLoader extends GLTFLoader {
+    load(url: string, onLoad: (gltf: GLTF) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: unknown) => void): void;
+}
+/** Shared GLTF loader used by shell entity/object model mounts. @internal */
+export declare const sharedGltfLoader: DiagnosticGLTFLoader;

package/dist/render/modelLoad.js

@@ -0,0 +1,73 @@
+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";
+/**
+ * Dedicated LoadingManager for every GLB load instead of THREE.DefaultLoadingManager.
+ * The shared default manager is process-wide; under repeated dev-server navigations its
+ * AbortController can already be aborted, which silently stalls GLTFLoader.fetch forever
+ * with no thrown error. A private manager sidesteps that (ported from the duet-keys ship).
+ * @internal
+ */
+const modelLoadingManager = new THREE.LoadingManager();
+/** How many leading bytes to read when probing a failed model URL for its signature. @internal */
+const PROBE_BYTE_LIMIT = 64;
+/**
+ * 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
+ * runtime can replace an opaque GLTF parse error with a diagnosis naming the
+ * broken asset contract. Runs only on the error path (loads rarely fail), and
+ * never throws: a failed probe returns a `missing` diagnosis instead.
+ * @internal
+ */
+export async function probeModelUrl(url, logicalId, fetchImpl = fetch) {
+    const base = logicalId === undefined ? { url } : { url, logicalId };
+    try {
+        const response = await fetchImpl(url);
+        const buffer = await response.arrayBuffer();
+        const bytes = new Uint8Array(buffer.slice(0, PROBE_BYTE_LIMIT));
+        return classifyAssetResponse({
+            ...base,
+            status: response.status,
+            statusText: response.statusText,
+            contentType: response.headers.get("content-type") ?? undefined,
+            bytes,
+        });
+    }
+    catch {
+        // The probe fetch itself failed (network/CORS) — the file is effectively unreachable.
+        return classifyAssetResponse({ ...base, status: 0 });
+    }
+}
+/**
+ * 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.
+ * @internal
+ */
+export class DiagnosticGLTFLoader extends GLTFLoader {
+    load(url, onLoad, onProgress, onError) {
+        super.load(url, onLoad, onProgress, (event) => {
+            if (onError === undefined)
+                return;
+            void probeModelUrl(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));
+        });
+    }
+}
+/** 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

@@ -1,23 +1,34 @@
 import * as THREE from "three";
 import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
 export declare const PAINT_TEXTURE_SIZE = 512;
+/** @internal */
 export declare function cloneModelScene(source: THREE.Object3D, options?: {
     cloneMaterials?: boolean;
 }): THREE.Object3D;
+/** @internal */
 export declare function disposeClonedMaterials(root: THREE.Object3D): void;
+/** @internal */
 export declare function standardMaterialsOf(root: THREE.Object3D): THREE.MeshStandardMaterial[];
 export interface MaterialCache {
     materials: THREE.MeshStandardMaterial[];
     seedColor: THREE.Color;
 }
+/** @internal */
 export declare function cacheStandardMaterials(root: THREE.Object3D, into?: MaterialCache | null): MaterialCache;
+/** @internal */
 export declare function applyPaintTextureToMaterials(materials: readonly THREE.MeshStandardMaterial[], paint: PaintCanvas): void;
 export interface PaintCanvas {
     canvas: HTMLCanvasElement;
     context: CanvasRenderingContext2D;
     texture: THREE.CanvasTexture;
 }
+/** @internal */
 export declare function createPaintCanvas(seed: THREE.MeshStandardMaterial, size?: number): PaintCanvas;
+/** @internal */
+export declare function disposePaintCanvas(paint: PaintCanvas): void;
+/** @internal */
 export declare function drawPaintStrokes(paint: PaintCanvas, strokes: readonly PaintStroke[]): void;
+/** @internal */
 export declare function applyPaintTexture(root: THREE.Object3D, paint: PaintCanvas): void;
+/** @internal */
 export declare function syncPaintCanvas(paint: PaintCanvas, seedColor: THREE.Color, strokes: readonly PaintStroke[], drawnCount: number): number;

package/dist/render/modelRender.js

@@ -1,6 +1,7 @@
 import * as THREE from "three";
 import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
 export const PAINT_TEXTURE_SIZE = 512;
+/** @internal */
 export function cloneModelScene(source, options) {
     const clone = cloneSkinned(source);
     if (options?.cloneMaterials === false)
@@ -15,6 +16,7 @@ export function cloneModelScene(source, options) {
     });
     return clone;
 }
+/** @internal */
 export function disposeClonedMaterials(root) {
     const seen = new Set();
     root.traverse((node) => {
@@ -33,6 +35,7 @@ export function disposeClonedMaterials(root) {
 function isMeshStandardMaterial(material) {
     return material.isMeshStandardMaterial === true;
 }
+/** @internal */
 export function standardMaterialsOf(root) {
     const materials = [];
     root.traverse((node) => {
@@ -46,6 +49,7 @@ export function standardMaterialsOf(root) {
     });
     return materials;
 }
+/** @internal */
 export function cacheStandardMaterials(root, into) {
     if (into !== null && into !== undefined)
         return into;
@@ -53,12 +57,14 @@ export function cacheStandardMaterials(root, into) {
     const seedColor = materials[0]?.color.clone() ?? new THREE.Color("#ffffff");
     return { materials, seedColor };
 }
+/** @internal */
 export function applyPaintTextureToMaterials(materials, paint) {
     for (const material of materials) {
         material.map = paint.texture;
         material.needsUpdate = true;
     }
 }
+/** @internal */
 export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
     const canvas = document.createElement("canvas");
     canvas.width = size;
@@ -76,6 +82,13 @@ export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
     texture.colorSpace = seed.map?.colorSpace ?? THREE.SRGBColorSpace;
     return { canvas, context, texture };
 }
+/** @internal */
+export function disposePaintCanvas(paint) {
+    paint.texture.dispose();
+    paint.canvas.width = 0;
+    paint.canvas.height = 0;
+}
+/** @internal */
 export function drawPaintStrokes(paint, strokes) {
     const { canvas, context, texture } = paint;
     for (const stroke of strokes) {
@@ -86,9 +99,11 @@ export function drawPaintStrokes(paint, strokes) {
     }
     texture.needsUpdate = true;
 }
+/** @internal */
 export function applyPaintTexture(root, paint) {
     applyPaintTextureToMaterials(standardMaterialsOf(root), paint);
 }
+/** @internal */
 export function syncPaintCanvas(paint, seedColor, strokes, drawnCount) {
     if (strokes.length < drawnCount) {
         const { canvas, context } = paint;