@jgengine/shell 0.13.0 → 0.15.0-next.0

package/dist/inputSink.js

@@ -77,6 +77,20 @@ export function inputFramesEqual(a, b) {
     for (let i = 0; i < a.held.length; i++)
         if (a.held[i] !== b.held[i])
             return false;
+    const aa = a.analog ?? null;
+    const ba = b.analog ?? null;
+    if (aa === null || ba === null) {
+        if (aa !== ba)
+            return false;
+    }
+    else {
+        const keys = Object.keys(aa);
+        if (keys.length !== Object.keys(ba).length)
+            return false;
+        for (const key of keys)
+            if (aa[key] !== ba[key])
+                return false;
+    }
     const pa = a.pointer;
     const pb = b.pointer;
     if (pa === null || pb === null)

package/dist/materialOverride.js

@@ -36,5 +36,35 @@ function overrideOne(material, override, clone, textures) {
         target.aoMap = textures.ao;
     if (textures !== undefined)
         target.needsUpdate = true;
+    if (override.rim !== undefined)
+        applyRimLight(target, override.rim);
     return target;
 }
+/**
+ * Adds a fresnel rim term to a standard material's outgoing light. Patched through
+ * `onBeforeCompile` rather than as a second pass so the rim shadows, fogs, and tonemaps with the
+ * body it belongs to instead of floating in front of it.
+ */
+function applyRimLight(target, rim) {
+    const color = new THREE.Color(rim.color ?? "#ffffff");
+    const strength = rim.strength ?? 0.6;
+    const power = rim.power ?? 2.5;
+    if (strength <= 0)
+        return;
+    target.onBeforeCompile = (shader) => {
+        shader.uniforms.uJgRimColor = { value: color };
+        shader.uniforms.uJgRimStrength = { value: strength };
+        shader.uniforms.uJgRimPower = { value: power };
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+uniform vec3 uJgRimColor;
+uniform float uJgRimStrength;
+uniform float uJgRimPower;`)
+            .replace("#include <opaque_fragment>", `float jgRim = pow(1.0 - clamp(dot(normalize(normal), normalize(vViewPosition)), 0.0, 1.0), uJgRimPower);
+outgoingLight += uJgRimColor * jgRim * uJgRimStrength;
+#include <opaque_fragment>`);
+    };
+    // Two materials differing only in rim tuning must not share a compiled program.
+    target.customProgramCacheKey = () => `jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
+    target.needsUpdate = true;
+}

package/dist/postfx/PostProcessing.d.ts

@@ -3,14 +3,15 @@ import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 /**
  * 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 declare function PostProcessing({ config, quality }: {
     config: PostProcessingConfig;

package/dist/postfx/PostProcessing.js

@@ -5,7 +5,33 @@ 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";
+/**
+ * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
+ * transparent overlay quads (additive VFX sprites, telegraphs, debug gizmos) into the AO
+ * buffers as opaque squares — the AO composite then multiplies them toward black. Hide
+ * marked overlay subtrees for the whole pass: the beauty buffer it composites over was
+ * already rendered with them in.
+ */
+class OverlayAwareGTAOPass extends GTAOPass {
+    hiddenOverlays = [];
+    render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
+        hidePostfxOverlays(this.scene, this.hiddenOverlays);
+        super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+        restorePostfxOverlays(this.hiddenOverlays);
+    }
+}
+/** DOF's depth prepass has the same `overrideMaterial` overlay-stamping problem as GTAO. */
+class OverlayAwareBokehPass extends BokehPass {
+    hiddenOverlays = [];
+    render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
+        hidePostfxOverlays(this.scene, this.hiddenOverlays);
+        super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+        restorePostfxOverlays(this.hiddenOverlays);
+    }
+}
 const TONE_MAPPING = {
     aces: THREE.ACESFilmicToneMapping,
     agx: THREE.AgXToneMapping,
@@ -34,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);
@@ -52,15 +79,17 @@ 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));
         const heavyPasses = quality === "high";
         if (heavyPasses && config.ao !== undefined && config.ao !== false) {
-            const ao = new GTAOPass(scene, camera, width, height);
+            const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
             ao.blendIntensity = config.ao.blend ?? 1;
             ao.updateGtaoMaterial({
                 radius: config.ao.radius ?? 1.8,
@@ -78,13 +107,17 @@ export function PostProcessing({ config, quality = "high" }) {
         let dof = null;
         if (heavyPasses && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
-            dof = new BokehPass(scene, camera, {
+            dof = new OverlayAwareBokehPass(scene, camera, {
                 focus: d.focus ?? 18,
                 aperture: d.aperture ?? 0.00025,
                 maxblur: d.maxBlur ?? 0.01,
             });
             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/postfx/postfxOverlay.d.ts

@@ -0,0 +1,24 @@
+import type * as THREE from "three";
+/**
+ * Spread onto a group's `userData` to mark its subtree as a screen/world overlay effect —
+ * additive glows, telegraphs, tracers, debug gizmos — that post-processing scene prepasses
+ * (GTAO's normal/depth render, DOF's depth render) must skip. Those prepasses render the
+ * scene with `overrideMaterial`, which turns transparent overlay quads into opaque stamps
+ * in the AO/DOF buffers (visible as black squares over hit sparks). The shell marks its own
+ * combat VFX and collision-debug mounts; games mark custom overlay effects the same way.
+ */
+export declare const POSTFX_OVERLAY_USERDATA: {
+    readonly jgPostfxOverlay: true;
+};
+/** True when the object opted out of postfx scene prepasses via {@link POSTFX_OVERLAY_USERDATA}. */
+export declare function isPostfxOverlay(object: {
+    userData?: Record<string, unknown>;
+}): boolean;
+/**
+ * Hide every currently visible marked object under `scene`, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
+ * undo exactly that set.
+ */
+export declare function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[]): void;
+/** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
+export declare function restorePostfxOverlays(hidden: THREE.Object3D[]): void;

package/dist/postfx/postfxOverlay.js

@@ -0,0 +1,35 @@
+/**
+ * Spread onto a group's `userData` to mark its subtree as a screen/world overlay effect —
+ * additive glows, telegraphs, tracers, debug gizmos — that post-processing scene prepasses
+ * (GTAO's normal/depth render, DOF's depth render) must skip. Those prepasses render the
+ * scene with `overrideMaterial`, which turns transparent overlay quads into opaque stamps
+ * in the AO/DOF buffers (visible as black squares over hit sparks). The shell marks its own
+ * combat VFX and collision-debug mounts; games mark custom overlay effects the same way.
+ */
+export const POSTFX_OVERLAY_USERDATA = {
+    jgPostfxOverlay: true,
+};
+/** True when the object opted out of postfx scene prepasses via {@link POSTFX_OVERLAY_USERDATA}. */
+export function isPostfxOverlay(object) {
+    return object.userData?.jgPostfxOverlay === true;
+}
+/**
+ * Hide every currently visible marked object under `scene`, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
+ * undo exactly that set.
+ */
+export function hidePostfxOverlays(scene, out) {
+    out.length = 0;
+    scene.traverse((object) => {
+        if (object.visible && isPostfxOverlay(object)) {
+            object.visible = false;
+            out.push(object);
+        }
+    });
+}
+/** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
+export function restorePostfxOverlays(hidden) {
+    for (const object of hidden)
+        object.visible = true;
+    hidden.length = 0;
+}

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/EntityPreview.d.ts

@@ -0,0 +1,53 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import { type StudioMood } from "../scene/StudioStage.js";
+/** Props for {@link EntityPreview}. */
+export interface EntityPreviewProps {
+    /**
+     * The rendered entity — the game's *own* `renderEntity` content (e.g. its procedural body component),
+     * which may call `useEntityRenderCues(id)` / `useGameContext()` internally to mirror the live game.
+     * Takes precedence over `model`. Omit both to render an empty lit stage.
+     */
+    children?: ReactNode;
+    /**
+     * Convenience for engine-native models: render this {@link ModelConfig} via `IsolatedEntityModel`.
+     * Pair with `instanceId` to bind it to a live entity so the preview walks / flinches / topples in
+     * sync with the world. Ignored when `children` is supplied.
+     */
+    model?: ModelConfig;
+    /** Live entity id driving motion cues for `model` (also lets a custom child resolve the same entity). */
+    instanceId?: string;
+    /** Lighting mood for the stage. Default `"studio"`. */
+    mood?: StudioMood;
+    /** Override the backdrop color (hex). Default: the mood's backdrop. */
+    backdrop?: string;
+    /** Turntable spin (rad/s). Default 0 — a still portrait that mirrors the live entity's own motion. */
+    turntable?: number;
+    /** Yaw the subject to face the camera each frame instead of spinning. Overrides `turntable`. */
+    faceCamera?: boolean;
+    /** The subject's declared forward axis for `faceCamera`. Default `[0, 0, 1]`. */
+    forward?: readonly [number, number, number];
+    /** Draw the backdrop + floor (true) or keep a transparent stage as a pure lighting rig (false). Default true. */
+    environment?: boolean;
+    /** Camera position framing the subject. Default `[0, 1, 3]`. */
+    cameraPosition?: [number, number, number];
+    /** Camera field of view. Default 35. */
+    fov?: number;
+    /** Device pixel ratio clamp. Default `[1, 2]`. */
+    dpr?: number | [number, number];
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Drop-in live 3D preview of a single entity — the character-screen portrait, unit inspector, or loadout
+ * viewer. It owns all the plumbing a game would otherwise re-derive by hand: a nested `<Canvas>`, the
+ * {@link GameContextBridge} that carries the running `GameContext` across the R3F reconciler boundary (so
+ * the subject's `useEntityRenderCues` / `useGameContext` hooks resolve and it mirrors the live game), a
+ * {@link StudioStage} 3-point lighting rig with optional turntable / face-camera, and a capture-friendly
+ * GL surface. The game keeps ownership of its `renderEntity`: pass it as `children`, or hand a native
+ * `model` (+ `instanceId`) for an engine-composed body. Bound to a live `instanceId`, the portrait walks,
+ * flinches, and topples in lockstep with the world instead of a canned spin.
+ *
+ * @capability entity-preview live 3D entity portrait — nested Canvas + context bridge + studio stage, driven by the game's own renderEntity
+ */
+export declare function EntityPreview({ children, model, instanceId, mood, backdrop, turntable, faceCamera, forward, environment, cameraPosition, fov, dpr, className, style, }: EntityPreviewProps): import("react").JSX.Element;

package/dist/render/EntityPreview.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Canvas } from "@react-three/fiber";
+import { GameContextBridge, useOptionalGameContext } from "@jgengine/react/provider";
+import { StudioStage } from "../scene/StudioStage.js";
+import { IsolatedEntityModel } from "./SceneModels.js";
+/**
+ * Drop-in live 3D preview of a single entity — the character-screen portrait, unit inspector, or loadout
+ * viewer. It owns all the plumbing a game would otherwise re-derive by hand: a nested `<Canvas>`, the
+ * {@link GameContextBridge} that carries the running `GameContext` across the R3F reconciler boundary (so
+ * the subject's `useEntityRenderCues` / `useGameContext` hooks resolve and it mirrors the live game), a
+ * {@link StudioStage} 3-point lighting rig with optional turntable / face-camera, and a capture-friendly
+ * GL surface. The game keeps ownership of its `renderEntity`: pass it as `children`, or hand a native
+ * `model` (+ `instanceId`) for an engine-composed body. Bound to a live `instanceId`, the portrait walks,
+ * flinches, and topples in lockstep with the world instead of a canned spin.
+ *
+ * @capability entity-preview live 3D entity portrait — nested Canvas + context bridge + studio stage, driven by the game's own renderEntity
+ */
+export function EntityPreview({ children, model, instanceId, mood = "studio", backdrop, turntable = 0, faceCamera = false, forward, environment = true, cameraPosition = [0, 1, 3], fov = 35, dpr = [1, 2], className, style, }) {
+    const ctx = useOptionalGameContext();
+    const subject = children ??
+        (model !== undefined ? _jsx(IsolatedEntityModel, { model: model, instanceId: instanceId }) : null);
+    return (_jsx("div", { "data-jg-entity-preview": "", className: className, style: { position: "relative", width: "100%", height: "100%", ...style }, children: _jsx(Canvas, { shadows: true, dpr: dpr, camera: { position: cameraPosition, fov }, gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: _jsx(GameContextBridge, { context: ctx, children: _jsx(StudioStage, { mood: mood, ...(backdrop === undefined ? {} : { backdrop }), turntable: turntable, faceCamera: faceCamera, ...(forward === undefined ? {} : { forward }), environment: environment, children: subject }) }) }) }));
+}

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;