@jgengine/shell 0.11.0 → 0.13.0

package/dist/render/assetBase.js

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+/**
+ * The app base URL every root-absolute asset path resolves under. `/` (the
+ * default) leaves URLs untouched — standalone game runners serve assets from
+ * the site root. The website serves the runner under `/play/`, where a game's
+ * `/models/…` or `/materials/…` must load from `/play/models/…`.
+ * @internal
+ */
+let assetBase = "/";
+/**
+ * Resolves a root-absolute asset URL (`/models/…`, `/materials/…`) against the
+ * installed app base. Relative, protocol-relative, absolute-scheme (`https:`,
+ * `blob:`, `data:`), and already-based URLs pass through unchanged. Installed
+ * as the URL modifier on THREE loading managers so every model and texture
+ * load resolves correctly wherever the app is mounted.
+ */
+export function resolveAssetBaseUrl(url) {
+    if (assetBase === "/" || !url.startsWith("/") || url.startsWith("//") || url.startsWith(assetBase)) {
+        return url;
+    }
+    return `${assetBase.replace(/\/+$/, "")}${url}`;
+}
+/**
+ * Installs the app base URL (pass `import.meta.env.BASE_URL`) so root-absolute
+ * asset paths load from under it. Call once at app startup, before any game
+ * loads. Bases that are not root-absolute (`/`, `./`) reset to the pass-through
+ * default. Also registers {@link resolveAssetBaseUrl} on
+ * `THREE.DefaultLoadingManager`, covering `TextureLoader`, drei's `useTexture`
+ * / `useGLTF`, and every other loader on the default manager.
+ */
+export function installAssetBase(base) {
+    const normalized = base.endsWith("/") ? base : `${base}/`;
+    assetBase = normalized.startsWith("/") && !normalized.startsWith("//") ? normalized : "/";
+    THREE.DefaultLoadingManager.setURLModifier(resolveAssetBaseUrl);
+}

package/dist/render/measureBounds.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import * as THREE from "three";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/** Subtrees flagged with this userData key are excluded from bounds measurement — debug gizmos,
+ * selection quads, effect billboards that should not inflate the hitbox. Sprites and invisible
+ * subtrees are always excluded. */
+export declare const MEASURE_EXCLUDE_KEY = "jgMeasureExclude";
+/** Entity-local AABB of the meshes under a measured root, plus how many meshes contributed — the
+ * count lets callers detect async subtree fill-in without diffing bounds. */
+export interface MeasuredLocalBounds {
+    min: [number, number, number];
+    max: [number, number, number];
+    meshCount: number;
+}
+/**
+ * Measure the meshes under `root` in `root`'s own frame (root's transform is the measuring frame,
+ * children compose their local matrices below it). Returns `null` when nothing measurable is
+ * mounted. Skinned meshes measure at bind pose — the standard engine approximation.
+ */
+export declare function measureLocalBounds(root: THREE.Object3D): MeasuredLocalBounds | null;
+/** Forward a measured result into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same shape so remounts and multi-instance kinds don't churn collider resolution. */
+export declare function reportMeasuredBounds(ctx: GameContext, target: "entity" | "object", key: string, bounds: MeasuredLocalBounds): void;
+/**
+ * Wraps custom-rendered actor content (`renderEntity` / `renderObject`) and reports its measured
+ * entity-local bounds into collider resolution, so the hitbox wraps what is actually on screen
+ * instead of the fixed-size fallback box. A successful measure re-reports only when the subtree
+ * gained or lost meshes (async fill-in), not when idle animation nudges the same meshes.
+ */
+export declare function MeasuredBoundsGroup({ target, measureKey, children, }: {
+    target: "entity" | "object";
+    measureKey: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/render/measureBounds.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useRef } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+/** Subtrees flagged with this userData key are excluded from bounds measurement — debug gizmos,
+ * selection quads, effect billboards that should not inflate the hitbox. Sprites and invisible
+ * subtrees are always excluded. */
+export const MEASURE_EXCLUDE_KEY = "jgMeasureExclude";
+const IDENTITY = new THREE.Matrix4();
+const tmpBox = new THREE.Box3();
+/**
+ * Measure the meshes under `root` in `root`'s own frame (root's transform is the measuring frame,
+ * children compose their local matrices below it). Returns `null` when nothing measurable is
+ * mounted. Skinned meshes measure at bind pose — the standard engine approximation.
+ */
+export function measureLocalBounds(root) {
+    const box = new THREE.Box3();
+    box.makeEmpty();
+    const meshCount = collectBounds(root, null, box);
+    if (meshCount === 0 || box.isEmpty())
+        return null;
+    return {
+        min: [box.min.x, box.min.y, box.min.z],
+        max: [box.max.x, box.max.y, box.max.z],
+        meshCount,
+    };
+}
+function collectBounds(object, parentMatrix, into) {
+    if (parentMatrix !== null) {
+        if (!object.visible)
+            return 0;
+        if (object.isSprite === true)
+            return 0;
+        if (object.userData[MEASURE_EXCLUDE_KEY] === true)
+            return 0;
+    }
+    let matrix = null;
+    if (parentMatrix !== null) {
+        if (object.matrixAutoUpdate)
+            object.updateMatrix();
+        matrix = new THREE.Matrix4().multiplyMatrices(parentMatrix, object.matrix);
+    }
+    let count = 0;
+    const mesh = object;
+    if (mesh.isMesh === true && mesh.geometry !== undefined) {
+        const geometry = mesh.geometry;
+        if (geometry.boundingBox === null)
+            geometry.computeBoundingBox();
+        const bounds = geometry.boundingBox;
+        if (bounds !== null && !bounds.isEmpty()) {
+            tmpBox.copy(bounds);
+            if (matrix !== null)
+                tmpBox.applyMatrix4(matrix);
+            into.union(tmpBox);
+            count += 1;
+        }
+    }
+    const childMatrix = matrix ?? IDENTITY;
+    for (const child of object.children)
+        count += collectBounds(child, childMatrix, into);
+    return count;
+}
+const reportedByContext = new WeakMap();
+const EPSILON = 0.01;
+function boundsClose(a, b) {
+    for (let axis = 0; axis < 3; axis += 1) {
+        if (Math.abs(a.min[axis] - b.min[axis]) > EPSILON)
+            return false;
+        if (Math.abs(a.max[axis] - b.max[axis]) > EPSILON)
+            return false;
+    }
+    return true;
+}
+/** Forward a measured result into the context (entity kind or object catalog id), deduping repeat
+ * reports of the same shape so remounts and multi-instance kinds don't churn collider resolution. */
+export function reportMeasuredBounds(ctx, target, key, bounds) {
+    let map = reportedByContext.get(ctx);
+    if (map === undefined) {
+        map = new Map();
+        reportedByContext.set(ctx, map);
+    }
+    const registryKey = `${target}:${key}`;
+    const prev = map.get(registryKey);
+    if (prev !== undefined && prev.meshCount === bounds.meshCount && boundsClose(prev, bounds))
+        return;
+    const accepted = target === "entity"
+        ? ctx.scene.entity.reportBounds(key, bounds)
+        : ctx.scene.object.reportBounds(key, bounds);
+    if (accepted)
+        map.set(registryKey, bounds);
+}
+/** Frames-since-mount at which a marker re-measures — bounded retries catch content that fills in
+ * asynchronously after first mount without paying a traversal every frame forever. */
+const MEASURE_FRAMES = [1, 15, 30, 60];
+/**
+ * Wraps custom-rendered actor content (`renderEntity` / `renderObject`) and reports its measured
+ * entity-local bounds into collider resolution, so the hitbox wraps what is actually on screen
+ * instead of the fixed-size fallback box. A successful measure re-reports only when the subtree
+ * gained or lost meshes (async fill-in), not when idle animation nudges the same meshes.
+ */
+export function MeasuredBoundsGroup({ target, measureKey, children, }) {
+    const ctx = useGameContext();
+    const groupRef = useRef(null);
+    const frameRef = useRef(0);
+    const attemptRef = useRef(0);
+    const lastMeshCountRef = useRef(null);
+    useFrame(() => {
+        if (attemptRef.current >= MEASURE_FRAMES.length)
+            return;
+        frameRef.current += 1;
+        if (frameRef.current < MEASURE_FRAMES[attemptRef.current])
+            return;
+        attemptRef.current += 1;
+        const group = groupRef.current;
+        if (group === null)
+            return;
+        const measured = measureLocalBounds(group);
+        if (measured === null)
+            return;
+        if (lastMeshCountRef.current === measured.meshCount)
+            return;
+        lastMeshCountRef.current = measured.meshCount;
+        reportMeasuredBounds(ctx, target, measureKey, measured);
+    });
+    return _jsx("group", { ref: groupRef, children: children });
+}

package/dist/render/modelLoad.js

@@ -2,6 +2,7 @@ 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 { resolveAssetBaseUrl } from "./assetBase.js";
 /**
  * Dedicated LoadingManager for every GLB load instead of THREE.DefaultLoadingManager.
  * The shared default manager is process-wide; under repeated dev-server navigations its
@@ -10,6 +11,7 @@ import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
  * @internal
  */
 const modelLoadingManager = new THREE.LoadingManager();
+modelLoadingManager.setURLModifier(resolveAssetBaseUrl);
 /** How many leading bytes to read when probing a failed model URL for its signature. @internal */
 const PROBE_BYTE_LIMIT = 64;
 /**
@@ -52,7 +54,8 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         super.load(url, onLoad, onProgress, (event) => {
             if (onError === undefined)
                 return;
-            void probeModelUrl(url)
+            // 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.

package/dist/render/resolveModel.d.ts

@@ -1,5 +1,6 @@
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { GameContextModels } from "@jgengine/core/runtime/gameContext";
 export interface ModelResolveContext {
     seam: "entityModels" | "objectModels" | "scatterModels";
     key: string;
@@ -40,6 +41,20 @@ export declare function pickModel(assets: AssetCatalog, pick: ModelPick): ModelC
  * @internal
  */
 export declare function resolveModelPlan(assets: AssetCatalog, plan: Record<string, ModelPick>): Record<string, ModelConfig>;
+/**
+ * The `createGameContext` `models` lookup derived from a playable's render maps: what each entity kind /
+ * object catalog id actually renders as, so colliders auto-fit the rendered mesh. Soft-resolves string
+ * ids (a missing catalog id keeps the default collider instead of throwing — the render path already
+ * reports it), passes inline configs through. `undefined` when the playable maps no models at all.
+ * @internal
+ */
+export declare function contextModels(playable: {
+    game: {
+        assets: AssetCatalog;
+    };
+    entityModels?: Record<string, string | ModelConfig>;
+    objectModels?: Record<string, string | ModelConfig>;
+}): GameContextModels | undefined;
 /**
  * Builds a `(key) => ModelConfig | null` override from a `seam`'s id/config map plus its catalog —
  * `undefined` when either half is missing so the caller can fall back to its own default renderer.

package/dist/render/resolveModel.js

@@ -1,3 +1,17 @@
+/**
+ * The `ModelConfig` a resolved catalog ref renders as. Stamps `animation: "auto"` so any rigged
+ * catalog asset animates by default — the shell derives idle/walk/run states and one-shots from
+ * the loaded GLB's clip names; clipless models are unaffected. An explicit `style.animation`
+ * (merged after resolve) or `"none"` overrides.
+ */
+function catalogModelConfig(ref) {
+    return {
+        url: ref.url,
+        ...(ref.dims === undefined ? {} : { dims: ref.dims }),
+        ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
+        animation: "auto",
+    };
+}
 /**
  * Resolve a string asset id or a direct ModelConfig. Missing/misspelled catalog
  * ids throw — silent generic-primitive fallback only happens when the mapping
@@ -14,7 +28,7 @@ export function resolveModel(value, assets, context) {
         const where = context === undefined ? `model asset "${value}"` : `${context.seam}["${context.key}"] → "${value}"`;
         throw new Error(`[jgengine] missing ${where} — not in the asset catalog. Fix the id, register it, or omit the mapping to keep the deliberate primitive/sprite fallback.`);
     }
-    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
+    return catalogModelConfig(ref);
 }
 /** Soft lookup used when an object catalog id may double as a model asset id.
  * @internal
@@ -23,7 +37,7 @@ export function tryResolveCatalogModel(id, assets) {
     const ref = assets.resolve(id);
     if (ref === null)
         return undefined;
-    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
+    return catalogModelConfig(ref);
 }
 /**
  * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog
@@ -82,6 +96,33 @@ export function resolveModelPlan(assets, plan) {
     }
     return out;
 }
+function softModelLookup(map, assets) {
+    if (map === undefined)
+        return undefined;
+    return (key) => {
+        const value = map[key];
+        if (value === undefined || typeof value !== "string")
+            return value;
+        return tryResolveCatalogModel(value, assets);
+    };
+}
+/**
+ * The `createGameContext` `models` lookup derived from a playable's render maps: what each entity kind /
+ * object catalog id actually renders as, so colliders auto-fit the rendered mesh. Soft-resolves string
+ * ids (a missing catalog id keeps the default collider instead of throwing — the render path already
+ * reports it), passes inline configs through. `undefined` when the playable maps no models at all.
+ * @internal
+ */
+export function contextModels(playable) {
+    const entity = softModelLookup(playable.entityModels, playable.game.assets);
+    const object = softModelLookup(playable.objectModels, playable.game.assets);
+    if (entity === undefined && object === undefined)
+        return undefined;
+    return {
+        ...(entity === undefined ? {} : { entity }),
+        ...(object === undefined ? {} : { object }),
+    };
+}
 /**
  * Builds a `(key) => ModelConfig | null` override from a `seam`'s id/config map plus its catalog —
  * `undefined` when either half is missing so the caller can fall back to its own default renderer.

package/dist/render/useModelAnimation.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from "three";
+import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
+/**
+ * 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).
+ * Handles `"auto"` derivation from the GLB's clip names, speed-driven idle/walk/run crossfades
+ * read from the entity's live position when `instanceId` is set, one-shots fired from
+ * `entity.animation` / `combat.hitReaction` / `entity.died`, held poses, and the death clamp.
+ */
+export declare function useModelAnimation(scene: THREE.Object3D, clips: THREE.AnimationClip[], animationInput: ModelAnimationConfig | "auto" | "none" | undefined, instanceId?: string): void;

package/dist/render/useModelAnimation.js

@@ -0,0 +1,198 @@
+import { useFrame } from "@react-three/fiber";
+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";
+/**
+ * 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).
+ * Handles `"auto"` derivation from the GLB's clip names, speed-driven idle/walk/run crossfades
+ * read from the entity's live position when `instanceId` is set, one-shots fired from
+ * `entity.animation` / `combat.hitReaction` / `entity.died`, held poses, and the death clamp.
+ */
+export function useModelAnimation(scene, clips, animationInput, instanceId) {
+    const ctx = useGameContext();
+    // "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]);
+    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 || clips.length === 0) {
+            mixerRef.current = null;
+            stateActionsRef.current = null;
+            return;
+        }
+        const mixer = new THREE.AnimationMixer(scene);
+        if (states !== undefined) {
+            const clipFor = (name) => THREE.AnimationClip.findByName(clips, name) ?? clips[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(clips, 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(clips, animation.clip) : undefined) ??
+            clips[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,
+        clips,
+        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]);
+    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);
+    });
+}

package/dist/scatter/InstancedScatter.js

@@ -5,6 +5,7 @@ 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 { chunkScatterInstances } from "@jgengine/core/world/scatterRegion";
+import { beginFallbackSeam, reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
 import { buildScatterProxy } from "./scatterProxies.js";
 import { buildScatterModelSources, disposeScatterModelSources } from "./scatterModels.js";
 /** Chunk edge (m): dense fields split into this-sized buckets, each frustum-culled independently. */
@@ -90,6 +91,9 @@ function ScatterModelSpecies({ model, batches }) {
 export function InstancedScatter({ instances, chunkSize = DEFAULT_CHUNK_SIZE, maxInstances = DEFAULT_MAX_INSTANCES, resolveItem, }) {
     const batches = useMemo(() => batchInstances(instances.length > maxInstances ? instances.slice(0, maxInstances) : instances, chunkSize), [instances, chunkSize, maxInstances]);
     const { proxyBatches, modelSpecies } = useMemo(() => {
+        // Dev diagnostic (no-op unless armed): re-zero the scatter seam before re-tallying which species
+        // fall to a stylized proxy (no resolveItem mapping / a null result). Reported once per species.
+        beginFallbackSeam("scatter");
         const proxy = [];
         const bySpecies = new Map();
         const knownProxy = new Set();
@@ -106,6 +110,7 @@ export function InstancedScatter({ instances, chunkSize = DEFAULT_CHUNK_SIZE, ma
             const resolved = resolveItem?.(batch.item) ?? null;
             if (resolved === null) {
                 knownProxy.add(batch.item);
+                reportFallbackSeam("scatter", "omittedMapping");
                 proxy.push(batch);
                 continue;
             }

package/dist/scatter/scatterProxies.js

@@ -6,6 +6,9 @@ const OAK = "#4a7a37";
 const BUSH = "#4d7d3a";
 const ROCK = "#82858c";
 const GRASS = "#5f9a3c";
+const PALM_BARK = "#8a7355";
+const PALM_FROND = "#4c8b3d";
+const CYPRESS = "#31502f";
 /** Concatenates part geometries into one vertex-colored buffer (position + normal + color). */
 function mergeParts(parts) {
     const geos = parts.map((part) => (part.geometry.index === null ? part.geometry : part.geometry.toNonIndexed()));
@@ -80,6 +83,27 @@ const BUILDERS = {
         { geometry: cone(0.08, 0.55, 0).translate(0.12, 0, 0.05), color: GRASS },
         { geometry: cone(0.08, 0.6, 0).translate(-0.1, 0, -0.06), color: GRASS },
     ]),
+    palm: () => {
+        // Tall bare trunk with a radial crown of drooping fronds — each frond a flattened cone laid
+        // near-horizontal, tips sagging below the crown.
+        const parts = [{ geometry: trunk(2.6, 0.09), color: PALM_BARK }];
+        for (let i = 0; i < 6; i += 1) {
+            const yaw = (i / 6) * Math.PI * 2;
+            const frond = new THREE.ConeGeometry(0.16, 1.35, 4);
+            frond.scale(1, 1, 0.35);
+            frond.rotateX(-Math.PI / 2 - 0.5);
+            frond.rotateY(yaw);
+            frond.translate(Math.sin(yaw) * 0.32, 2.62, Math.cos(yaw) * 0.32);
+            parts.push({ geometry: frond, color: PALM_FROND });
+        }
+        parts.push({ geometry: sphere(0.14, 2.56), color: PALM_BARK });
+        return mergeParts(parts);
+    },
+    cypress: () => mergeParts([
+        { geometry: trunk(0.5, 0.07), color: BARK },
+        { geometry: cone(0.34, 2.5, 0.35, 6), color: CYPRESS },
+        { geometry: cone(0.2, 0.7, 2.75, 5), color: CYPRESS },
+    ]),
 };
 function defaultProxy() {
     return mergeParts([{ geometry: cone(0.35, 1.2, 0), color: GRASS }]);

package/dist/scene/AuthoredScene.d.ts

@@ -68,6 +68,8 @@ export interface AuthoredSceneProps {
     placeObjects?: boolean | {
         verticalOffset?: number;
     };
+    /** Terrain surface color sampler forwarded to studio renderers (see `SceneKindRenderContext.groundColorAt`). */
+    groundColorAt?: (x: number, z: number) => string;
 }
 /**
  * Renders an editor document's scene content — draped paths plus GPU-instanced foliage — from one
@@ -79,4 +81,4 @@ export interface AuthoredSceneProps {
  * place markers with your own entity spawns. Pass `scatterModels`+`assets` to resolve palette items to
  * real catalog GLBs; unmapped items keep the stylized proxy.
  */
-export declare function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live, placeObjects, }: AuthoredSceneProps): import("react").JSX.Element;
+export declare function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live, placeObjects, groundColorAt, }: AuthoredSceneProps): import("react").JSX.Element;

package/dist/scene/AuthoredScene.js

@@ -163,11 +163,16 @@ export function AuthoredObjects({ document, field, verticalOffset = 0, onExistin
  * place markers with your own entity spawns. Pass `scatterModels`+`assets` to resolve palette items to
  * real catalog GLBs; unmapped items keep the stylized proxy.
  */
-export function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live = true, placeObjects, }) {
+export function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live = true, placeObjects, groundColorAt, }) {
     const liveDocument = useLiveEditorDocument(document, live);
     const instances = useMemo(() => resolveScatter(liveDocument, field), [liveDocument, field]);
     const resolveItem = useMemo(() => createModelMapResolver(scatterModels, assets, "scatterModels"), [scatterModels, assets]);
     const shouldPlaceObjects = placeObjects === true || (typeof placeObjects === "object" && placeObjects !== null);
     const objectVerticalOffset = typeof placeObjects === "object" && placeObjects !== null ? (placeObjects.verticalOffset ?? 0) : 0;
-    return (_jsxs(_Fragment, { children: [_jsx(AuthoredPaths, { document: liveDocument, field: field, ...(pathKinds === undefined ? {} : { kinds: pathKinds }) }), _jsx(InstancedScatter, { instances: instances, ...(resolveItem === undefined ? {} : { resolveItem }) }), _jsx(AuthoredStudios, { document: liveDocument, context: { document: liveDocument, field, ...(assets === undefined ? {} : { assets }) } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(AuthoredPaths, { document: liveDocument, field: field, ...(pathKinds === undefined ? {} : { kinds: pathKinds }) }), _jsx(InstancedScatter, { instances: instances, ...(resolveItem === undefined ? {} : { resolveItem }) }), _jsx(AuthoredStudios, { document: liveDocument, context: {
+                    document: liveDocument,
+                    field,
+                    ...(assets === undefined ? {} : { assets }),
+                    ...(groundColorAt === undefined ? {} : { groundColorAt }),
+                } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
 }

package/dist/scene/CityRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `city` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerCityRenderer(): void;