@jgengine/shell 0.14.0 → 0.15.0

package/dist/postfx/PostProcessing.js

@@ -5,6 +5,7 @@ import { EffectComposer, RenderPass, UnrealBloomPass } from "three-stdlib";
 import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
+import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
 import { createGradePass } from "./gradeShader.js";
 import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
 /**
@@ -59,14 +60,15 @@ function syncSize(built, width, height, pixelRatio) {
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → OutputPass → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
  * `quality` (the player's graphics-quality setting) gates the passes whose cost
  * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
  * the whole scene for depth/normals and runs a multi-sample full-screen pass,
  * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
- * tone mapping, and grade stay on every tier.
+ * SMAA, tone mapping, and grade stay on every tier (SMAA is the cheap edge fix
+ * for alpha-tested foliage that MSAA samples alone leave crawling).
  */
 export function PostProcessing({ config, quality = "high" }) {
     const gl = useThree((s) => s.gl);
@@ -77,9 +79,11 @@ export function PostProcessing({ config, quality = "high" }) {
     useEffect(() => {
         const width = Math.max(1, size.width);
         const height = Math.max(1, size.height);
+        const aa = config.aa === undefined ? "smaa" : config.aa;
+        const msaaSamples = aa === false ? 0 : 2;
         const target = new THREE.WebGLRenderTarget(width, height, {
             type: THREE.HalfFloatType,
-            samples: 2,
+            samples: msaaSamples,
         });
         const composer = new EffectComposer(gl, target);
         composer.addPass(new RenderPass(scene, camera));
@@ -110,6 +114,10 @@ export function PostProcessing({ config, quality = "high" }) {
             });
             composer.addPass(dof);
         }
+        // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
+        if (aa === "smaa") {
+            composer.addPass(new SMAAPass());
+        }
         composer.addPass(new OutputPass());
         let grade = null;
         if (config.grade !== false) {

package/dist/postfx/ScreenEffectsOverlay.d.ts

@@ -0,0 +1,32 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ScreenEffectsController } from "@jgengine/core/vfx/screenEffects";
+/** Reskin tokens for {@link ScreenEffectsOverlay}. */
+export interface ScreenEffectsOverlayProps {
+    /** The model to render. */
+    controller: ScreenEffectsController;
+    /**
+     * CSS blend mode for the tint layers. Default `"normal"` (straight alpha
+     * composite). `"screen"` or `"multiply"` read as more filmic color grades.
+     */
+    blendMode?: CSSProperties["mixBlendMode"];
+    /** Extra `z-index` for the overlay root. Default `40`. */
+    zIndex?: number;
+    /**
+     * Drive `advance()` on an animation frame. Default `true`. Turn off if the game
+     * already advances the controller from its own tick.
+     */
+    animate?: boolean;
+}
+/**
+ * A DOM overlay that renders a {@link ScreenEffectsController} as full-screen
+ * color-grade layers over the game canvas — damage vignettes, heal flashes, a
+ * sustained low-health pulse — through the shell's postfx overlay layer, so a game
+ * gets screen feedback without hand-rolling shader or overlay timing. It subscribes
+ * to the model, drives `advance()` on an animation frame (unless the game ticks it),
+ * and paints one absolutely-positioned, pointer-transparent layer per active effect
+ * at its eased opacity. Presentation only: all timing and state live in the core
+ * model, and `kind` is never interpreted here.
+ *
+ * @capability screen-effects-overlay shell DOM overlay that renders a core screen-effects controller as full-screen flash / edge-vignette / low-health-pulse color-grade layers
+ */
+export declare function ScreenEffectsOverlay({ controller, blendMode, zIndex, animate, }: ScreenEffectsOverlayProps): ReactNode;

package/dist/postfx/ScreenEffectsOverlay.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+/**
+ * Build the CSS `background` for one effect at its current eased opacity. A
+ * `"full"` effect tints the whole frame; a `"vignette"` effect tints only the
+ * edges via a radial gradient that stays transparent in the center. Genre-blind —
+ * it reads `color`/`shape`/`intensity` off the model and nothing else.
+ */
+function effectBackground(effect) {
+    if (effect.shape === "vignette") {
+        // Transparent core → the effect color at the corners, scaled by opacity.
+        return `radial-gradient(ellipse at center, transparent 40%, ${effect.color} 140%)`;
+    }
+    return effect.color;
+}
+/** Per-effect fill layer opacity, so `color` can stay a plain CSS color string. */
+function effectOpacity(effect) {
+    const a = effect.intensity;
+    return a < 0 ? 0 : a > 1 ? 1 : a;
+}
+/**
+ * A DOM overlay that renders a {@link ScreenEffectsController} as full-screen
+ * color-grade layers over the game canvas — damage vignettes, heal flashes, a
+ * sustained low-health pulse — through the shell's postfx overlay layer, so a game
+ * gets screen feedback without hand-rolling shader or overlay timing. It subscribes
+ * to the model, drives `advance()` on an animation frame (unless the game ticks it),
+ * and paints one absolutely-positioned, pointer-transparent layer per active effect
+ * at its eased opacity. Presentation only: all timing and state live in the core
+ * model, and `kind` is never interpreted here.
+ *
+ * @capability screen-effects-overlay shell DOM overlay that renders a core screen-effects controller as full-screen flash / edge-vignette / low-health-pulse color-grade layers
+ */
+export function ScreenEffectsOverlay({ controller, blendMode = "normal", zIndex = 40, animate = true, }) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const rafRef = useRef(0);
+    useEffect(() => controller.subscribe(bump), [controller]);
+    useEffect(() => {
+        if (!animate)
+            return;
+        let running = true;
+        const loop = () => {
+            if (!running)
+                return;
+            controller.advance();
+            rafRef.current = requestAnimationFrame(loop);
+        };
+        rafRef.current = requestAnimationFrame(loop);
+        return () => {
+            running = false;
+            cancelAnimationFrame(rafRef.current);
+        };
+    }, [controller, animate]);
+    const composite = controller.composite();
+    if (composite.length === 0)
+        return null;
+    const root = {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+        zIndex,
+    };
+    return (_jsx("div", { style: root, "aria-hidden": "true", "data-jg-screen-effects": "", children: composite.map((effect) => (_jsx("div", { style: {
+                position: "absolute",
+                inset: 0,
+                background: effectBackground(effect),
+                opacity: effectOpacity(effect),
+                mixBlendMode: blendMode,
+            } }, effect.id))) }));
+}

package/dist/presentationResolve.d.ts

@@ -31,9 +31,10 @@ export interface ResolvedPresentationEffects {
 }
 /**
  * Resolve `presentationEffects` for the 3D shell.
- * - `undefined` / `true` → all channels on (historical default).
+ * - `undefined` / `true` → default channels (telegraphs, vfx, floatText, shake on; tracers off).
  * - `false` → none.
- * - object → per-channel; missing keys default to on so games can disable one channel.
+ * - object → per-channel; missing keys default on, EXCEPT `tracers`, which is opt-in and only
+ *   enabled by an explicit `tracers: true`.
  * @internal
  */
 export declare function resolvePresentationEffects(config: boolean | PresentationEffectsConfig | undefined): ResolvedPresentationEffects;

package/dist/presentationResolve.js

@@ -17,11 +17,15 @@ export function resolveWorldOverlayBars(config) {
         ...(config.showHealth === undefined ? {} : { showHealth: config.showHealth }),
     };
 }
-const ALL_ON = {
+// Every channel defaults on EXCEPT tracers. `fireProjectile` is a generic seam (bullets,
+// bolts, grenades, launchers), so a muzzle→impact tracer line is only ever right for a subset
+// of shots — it must never appear in a game that never asked for it. Tracers are therefore
+// opt-in: a game turns them on with `presentationEffects: { tracers: true }`.
+const DEFAULTS = {
     telegraphs: true,
     vfx: true,
     floatText: true,
-    tracers: true,
+    tracers: false,
     shake: true,
 };
 const ALL_OFF = {
@@ -33,21 +37,22 @@ const ALL_OFF = {
 };
 /**
  * Resolve `presentationEffects` for the 3D shell.
- * - `undefined` / `true` → all channels on (historical default).
+ * - `undefined` / `true` → default channels (telegraphs, vfx, floatText, shake on; tracers off).
  * - `false` → none.
- * - object → per-channel; missing keys default to on so games can disable one channel.
+ * - object → per-channel; missing keys default on, EXCEPT `tracers`, which is opt-in and only
+ *   enabled by an explicit `tracers: true`.
  * @internal
  */
 export function resolvePresentationEffects(config) {
     if (config === false)
         return ALL_OFF;
     if (config === undefined || config === true)
-        return ALL_ON;
+        return { ...DEFAULTS };
     return {
         telegraphs: config.telegraphs !== false,
         vfx: config.vfx !== false,
         floatText: config.floatText !== false,
-        tracers: config.tracers !== false,
+        tracers: config.tracers === true,
         shake: config.shake !== false,
     };
 }

package/dist/render/CascadedShadows.d.ts

@@ -0,0 +1,13 @@
+import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
+/**
+ * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
+ * single 40-unit ortho frustum. Uses three.js `CSM` (shader injection on standard materials).
+ *
+ * Mount when `entry.cascades > 1` and `castShadow`. Replaces the single R3F directional
+ * shadow light for that entry.
+ *
+ * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
+ */
+export declare function CascadedShadows({ entry }: {
+    entry: DirectionalLightingConfig;
+}): null;

package/dist/render/CascadedShadows.js

@@ -0,0 +1,96 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+import * as THREE from "three";
+import { CSM } from "three/examples/jsm/csm/CSM.js";
+function isStandardMaterial(mat) {
+    return mat instanceof THREE.MeshStandardMaterial || mat instanceof THREE.MeshPhysicalMaterial;
+}
+/**
+ * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
+ * single 40-unit ortho frustum. Uses three.js `CSM` (shader injection on standard materials).
+ *
+ * Mount when `entry.cascades > 1` and `castShadow`. Replaces the single R3F directional
+ * shadow light for that entry.
+ *
+ * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
+ */
+export function CascadedShadows({ entry }) {
+    const camera = useThree((s) => s.camera);
+    const scene = useThree((s) => s.scene);
+    const csmRef = useRef(null);
+    const patchedRef = useRef(new WeakSet());
+    const frameRef = useRef(0);
+    useEffect(() => {
+        const cascades = Math.max(2, Math.min(4, Math.floor(entry.cascades ?? 3)));
+        const lightDirection = new THREE.Vector3(-entry.position[0], -entry.position[1], -entry.position[2]);
+        if (lightDirection.lengthSq() < 1e-8)
+            lightDirection.set(-1, -1, -1);
+        lightDirection.normalize();
+        const csm = new CSM({
+            camera,
+            parent: scene,
+            cascades,
+            maxFar: entry.shadowMaxFar ?? 200,
+            mode: "practical",
+            shadowMapSize: entry.shadowMapSize ?? 1024,
+            shadowBias: entry.shadowBias ?? -0.0004,
+            lightDirection,
+            lightIntensity: entry.intensity ?? 1.3,
+            lightNear: 0.5,
+            lightFar: Math.max(200, (entry.shadowCameraSize ?? 40) * 6),
+            lightMargin: entry.shadowCameraSize ?? 40,
+        });
+        for (const light of csm.lights) {
+            light.color = new THREE.Color(entry.color ?? "#ffffff");
+            light.castShadow = true;
+        }
+        patchedRef.current = new WeakSet();
+        patchSceneMaterials(scene, csm, patchedRef.current);
+        csmRef.current = csm;
+        frameRef.current = 0;
+        return () => {
+            csm.dispose();
+            csmRef.current = null;
+        };
+    }, [
+        camera,
+        scene,
+        entry.cascades,
+        entry.color,
+        entry.intensity,
+        entry.position[0],
+        entry.position[1],
+        entry.position[2],
+        entry.shadowBias,
+        entry.shadowCameraSize,
+        entry.shadowMapSize,
+        entry.shadowMaxFar,
+    ]);
+    useFrame(() => {
+        const csm = csmRef.current;
+        if (csm === null)
+            return;
+        csm.camera = camera;
+        frameRef.current += 1;
+        // Async model mounts need setupMaterial — re-scan every 30 frames after the first.
+        if (frameRef.current === 1 || frameRef.current % 30 === 0) {
+            patchSceneMaterials(scene, csm, patchedRef.current);
+        }
+        csm.update();
+    });
+    return null;
+}
+function patchSceneMaterials(scene, csm, patched) {
+    scene.traverse((obj) => {
+        const mesh = obj;
+        if (!mesh.isMesh)
+            return;
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const mat of materials) {
+            if (!isStandardMaterial(mat) || patched.has(mat))
+                continue;
+            csm.setupMaterial(mat);
+            patched.add(mat);
+        }
+    });
+}

package/dist/render/EnvironmentLighting.d.ts

@@ -1,10 +1,26 @@
+/** @internal Props for shell {@link EnvironmentLighting}. */
+export interface EnvironmentLightingProps {
+    /** IBL intensity. Default 0.35. */
+    intensity?: number;
+    /** Upper-hemisphere tint for the procedural sky probe. Default cool daylight. */
+    skyColor?: string;
+    /** Ground / lower-hemisphere tint. Default soft earth. */
+    groundColor?: string;
+    /**
+     * Optional sun direction (world space, not normalized). When set, a bright disc
+     * is baked into the probe so metals pick up a real sun glint that tracks daylight.
+     */
+    sunDirection?: readonly [number, number, number];
+    /** Sun disc tint. Default warm white. */
+    sunColor?: string;
+}
 /**
- * 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 declare function EnvironmentLighting({ intensity }: {
-    intensity?: number;
-}): null;
+export declare function EnvironmentLighting({ intensity, skyColor, groundColor, sunDirection, sunColor, }: EnvironmentLightingProps): null;

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;