@jgengine/shell 0.6.0 → 0.8.0

package/dist/touch/TouchControlsOverlay.d.ts

@@ -0,0 +1,18 @@
+import { type MutableRefObject } from "react";
+import { type TouchScheme } from "@jgengine/core/input/touchScheme";
+export interface TouchCodeSink {
+    onCodeDown(code: string): void;
+    onCodeUp(code: string): void;
+}
+export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }: {
+    scheme: TouchScheme;
+    sink: TouchCodeSink;
+    yawRef: MutableRefObject<number>;
+    pitchRef: MutableRefObject<number>;
+    maxPitch: number;
+    onPrimaryTap: () => void;
+}): import("react").JSX.Element;
+export declare function TouchControlsDock({ scheme, sink }: {
+    scheme: TouchScheme;
+    sink: TouchCodeSink;
+}): import("react").JSX.Element;

package/dist/touch/TouchControlsOverlay.js

@@ -0,0 +1,173 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from "react";
+import { createGestureSurfaceTracker } from "@jgengine/core/input/gestureSurface";
+import { createTouchGestureTracker } from "@jgengine/core/input/touchGestures";
+import { touchCode } from "@jgengine/core/input/touchScheme";
+import { GameIcon, iconForAction, isGameIconName } from "@jgengine/react/gameIcons";
+const JOYSTICK_SIZE = 132;
+const JOYSTICK_THUMB = 52;
+const JOYSTICK_DEADZONE = 0.28;
+const JOYSTICK_AXIS_THRESHOLD = 0.42;
+const LOOK_TAP_TUNING = { tapMoveThresholdPx: 12, tapMaxMs: 280, longPressMs: 450 };
+function pressOnce(sink, action) {
+    const code = touchCode(action);
+    sink.onCodeDown(code);
+    sink.onCodeUp(code);
+}
+export function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }) {
+    const pointerIdRef = useRef(null);
+    const gestureTracker = useMemo(() => (scheme.gestures === null ? null : createGestureSurfaceTracker(scheme.gestures)), [scheme]);
+    const lookTracker = useMemo(() => (scheme.look ? createTouchGestureTracker(LOOK_TAP_TUNING) : null), [scheme]);
+    const release = (event) => {
+        if (event.pointerId !== pointerIdRef.current)
+            return;
+        pointerIdRef.current = null;
+    };
+    return (_jsx("div", { className: "absolute inset-0 touch-none", onPointerDown: (event) => {
+            if (event.pointerType !== "touch" || pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            if (lookTracker !== null)
+                lookTracker.begin(event.clientX, event.clientY, performance.now());
+            else
+                gestureTracker?.begin(event.clientX, event.clientY, performance.now());
+        }, onPointerMove: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            if (lookTracker !== null) {
+                const delta = lookTracker.move(event.clientX, event.clientY);
+                if (delta !== null) {
+                    yawRef.current -= delta.dx * scheme.lookSensitivity;
+                    pitchRef.current = Math.max(-maxPitch, Math.min(maxPitch, pitchRef.current - delta.dy * scheme.lookSensitivity));
+                }
+                return;
+            }
+            for (const action of gestureTracker?.move(event.clientX, event.clientY) ?? [])
+                pressOnce(sink, action);
+        }, onPointerUp: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            release(event);
+            if (lookTracker !== null) {
+                if (lookTracker.end(performance.now()) === "tap") {
+                    if (scheme.gestures?.tap !== undefined)
+                        pressOnce(sink, scheme.gestures.tap);
+                    else
+                        onPrimaryTap();
+                }
+                return;
+            }
+            for (const action of gestureTracker?.end(event.clientX, event.clientY, performance.now()) ?? []) {
+                pressOnce(sink, action);
+            }
+        }, onPointerCancel: (event) => {
+            release(event);
+            lookTracker?.cancel();
+            gestureTracker?.cancel();
+        } }));
+}
+function joystickDirections(joystick, nx, ny) {
+    const active = new Set();
+    if (Math.hypot(nx, ny) < JOYSTICK_DEADZONE)
+        return active;
+    if (joystick.up !== null && ny < -JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.up);
+    if (joystick.down !== null && ny > JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.down);
+    if (joystick.left !== null && nx < -JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.left);
+    if (joystick.right !== null && nx > JOYSTICK_AXIS_THRESHOLD)
+        active.add(joystick.right);
+    return active;
+}
+function VirtualJoystick({ joystick, sink }) {
+    const baseRef = useRef(null);
+    const thumbRef = useRef(null);
+    const pointerIdRef = useRef(null);
+    const activeRef = useRef(new Set());
+    const applyVector = (clientX, clientY) => {
+        const base = baseRef.current;
+        const thumb = thumbRef.current;
+        if (base === null || thumb === null)
+            return;
+        const rect = base.getBoundingClientRect();
+        const radius = rect.width / 2;
+        let nx = (clientX - rect.left - radius) / radius;
+        let ny = (clientY - rect.top - radius) / radius;
+        const length = Math.hypot(nx, ny);
+        if (length > 1) {
+            nx /= length;
+            ny /= length;
+        }
+        const travel = radius - JOYSTICK_THUMB / 2;
+        thumb.style.transform = `translate(${nx * travel}px, ${ny * travel}px)`;
+        const next = joystickDirections(joystick, nx, ny);
+        for (const action of activeRef.current) {
+            if (!next.has(action))
+                sink.onCodeUp(touchCode(action));
+        }
+        for (const action of next) {
+            if (!activeRef.current.has(action))
+                sink.onCodeDown(touchCode(action));
+        }
+        activeRef.current = next;
+    };
+    const releaseAll = () => {
+        pointerIdRef.current = null;
+        for (const action of activeRef.current)
+            sink.onCodeUp(touchCode(action));
+        activeRef.current = new Set();
+        if (thumbRef.current !== null)
+            thumbRef.current.style.transform = "translate(0px, 0px)";
+    };
+    return (_jsx("div", { ref: baseRef, className: "pointer-events-auto relative flex touch-none select-none items-center justify-center rounded-full border border-white/20 bg-white/10 backdrop-blur-sm", style: { width: JOYSTICK_SIZE, height: JOYSTICK_SIZE }, onPointerDown: (event) => {
+            if (pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            applyVector(event.clientX, event.clientY);
+        }, onPointerMove: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            applyVector(event.clientX, event.clientY);
+        }, onPointerUp: (event) => {
+            if (event.pointerId !== pointerIdRef.current)
+                return;
+            event.stopPropagation();
+            releaseAll();
+        }, onPointerCancel: () => releaseAll(), children: _jsx("div", { ref: thumbRef, className: "rounded-full border border-white/30 bg-white/25", style: { width: JOYSTICK_THUMB, height: JOYSTICK_THUMB } }) }));
+}
+function touchButtonIcon(button) {
+    if (button.icon === false)
+        return null;
+    if (button.icon !== null && isGameIconName(button.icon))
+        return button.icon;
+    return iconForAction(button.action);
+}
+function TouchActionButton({ button, sink }) {
+    const pointerIdRef = useRef(null);
+    const icon = touchButtonIcon(button);
+    const releaseIfHeld = () => {
+        if (pointerIdRef.current === null)
+            return;
+        pointerIdRef.current = null;
+        sink.onCodeUp(touchCode(button.action));
+    };
+    return (_jsx("button", { type: "button", "aria-label": button.label, className: "pointer-events-auto flex h-14 w-14 touch-none select-none items-center justify-center rounded-full border border-white/25 bg-white/10 text-center text-[10px] font-semibold uppercase leading-tight tracking-wide text-white/90 backdrop-blur-sm active:border-white/50 active:bg-white/30", onPointerDown: (event) => {
+            if (pointerIdRef.current !== null)
+                return;
+            pointerIdRef.current = event.pointerId;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            sink.onCodeDown(touchCode(button.action));
+        }, onPointerUp: (event) => {
+            event.stopPropagation();
+            releaseIfHeld();
+        }, onPointerCancel: () => releaseIfHeld(), onContextMenu: (event) => event.preventDefault(), children: icon !== null ? _jsx(GameIcon, { name: icon, size: 26 }) : _jsx("span", { className: "px-1", children: button.label }) }));
+}
+export function TouchControlsDock({ scheme, sink }) {
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 z-40 flex items-end justify-between gap-4 px-5", style: { paddingBottom: "calc(env(safe-area-inset-bottom, 0px) + 20px)" }, children: [_jsx("div", { children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink }) : null }), _jsx("div", { className: "flex max-w-[60%] flex-wrap items-end justify-end gap-3", children: scheme.buttons.map((button) => (_jsx(TouchActionButton, { button: button, sink: sink }, button.action))) })] }));
+}

package/dist/vision/FrustumSensorHud.d.ts

@@ -0,0 +1,21 @@
+import { type FramingConfig, type FrustumSample } from "@jgengine/core/sensor/frustumSensor";
+export interface FrustumSensorProbeOptions extends FramingConfig {
+    subjectIds: readonly string[];
+    subjectRadius?: number;
+}
+/**
+ * View-frustum sensor (#117) driven by the live render camera: which held-camera
+ * subjects are in frame, how well framed, and their dwell time on-screen
+ * (Content Warning-style "is this monster filmed well" scoring). Returns the
+ * best-framed in-view subject each frame for a photo-mode HUD readout.
+ */
+export declare function useFrustumSensor(options: FrustumSensorProbeOptions): FrustumSample | null;
+/**
+ * Renders inside the Canvas (needs the live camera via `useFrame`/`useThree`)
+ * but portals a real HTML readout via drei's `Html fullscreen` — a photo-mode
+ * "is this subject framed" HUD.
+ */
+export declare function FrustumSensorReadout(props: FrustumSensorProbeOptions & {
+    wrapperClassName?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/vision/FrustumSensorHud.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Html } from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useMemo, useRef, useState } from "react";
+import { PerspectiveCamera, Vector3 } from "three";
+import { createFrustumSensor, } from "@jgengine/core/sensor/frustumSensor";
+import { useSceneEntities } from "@jgengine/react/hooks";
+function isPerspective(camera) {
+    return camera.isPerspectiveCamera === true;
+}
+/**
+ * View-frustum sensor (#117) driven by the live render camera: which held-camera
+ * subjects are in frame, how well framed, and their dwell time on-screen
+ * (Content Warning-style "is this monster filmed well" scoring). Returns the
+ * best-framed in-view subject each frame for a photo-mode HUD readout.
+ */
+export function useFrustumSensor(options) {
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    const entities = useSceneEntities();
+    const sensor = useMemo(() => createFrustumSensor(options), []);
+    const [best, setBest] = useState(null);
+    const forward = useRef(new Vector3());
+    useFrame((_, dt) => {
+        const targets = [];
+        for (const id of options.subjectIds) {
+            const entity = entities.find((candidate) => candidate.id === id);
+            if (entity === undefined)
+                continue;
+            targets.push({ id, position: entity.position, radius: options.subjectRadius });
+        }
+        if (targets.length === 0) {
+            setBest(null);
+            return;
+        }
+        camera.getWorldDirection(forward.current);
+        const samples = sensor.tick({
+            position: [camera.position.x, camera.position.y, camera.position.z],
+            lookAt: [
+                camera.position.x + forward.current.x,
+                camera.position.y + forward.current.y,
+                camera.position.z + forward.current.z,
+            ],
+            fovDeg: isPerspective(camera) ? camera.fov : 55,
+            aspect: size.height === 0 ? 16 / 9 : size.width / size.height,
+        }, targets, dt);
+        let leader = null;
+        for (const sample of samples) {
+            if (!sample.inView)
+                continue;
+            if (leader === null || sample.framing > leader.framing)
+                leader = sample;
+        }
+        setBest(leader);
+    });
+    return best;
+}
+/**
+ * Renders inside the Canvas (needs the live camera via `useFrame`/`useThree`)
+ * but portals a real HTML readout via drei's `Html fullscreen` — a photo-mode
+ * "is this subject framed" HUD.
+ */
+export function FrustumSensorReadout(props) {
+    const sample = useFrustumSensor(props);
+    return (_jsx(Html, { fullscreen: true, children: _jsx("div", { className: props.wrapperClassName ?? "pointer-events-none absolute bottom-24 right-4", children: sample === null ? (_jsx("div", { className: props.className ?? "rounded border border-white/15 bg-black/60 px-3 py-1.5 text-xs text-white/50", children: "No subject framed" })) : (_jsxs("div", { className: props.className ??
+                    "rounded border border-amber-300/40 bg-black/70 px-3 py-1.5 text-xs text-amber-200 shadow-lg", children: [_jsx("span", { className: "font-semibold uppercase tracking-wide", children: sample.id }), _jsxs("span", { className: "ml-2 tabular-nums", children: ["framing ", Math.round(sample.framing * 100), "%"] }), _jsxs("span", { className: "ml-2 tabular-nums", children: ["dwell ", sample.dwellSeconds.toFixed(1), "s"] })] })) }) }));
+}

package/dist/vision/HiddenStateProbeHud.d.ts

@@ -0,0 +1,11 @@
+import { probeHiddenState, type HiddenStateSource, type SensorProbeOptions } from "@jgengine/core/sensor/hiddenStateProbe";
+import type { EntityPosition } from "@jgengine/core/scene/entityStore";
+/** Reads a hidden zone/entity state variable in range (EMF / thermometer / geiger style sensor verb, #116). */
+export declare function useHiddenStateProbe(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): import("@jgengine/core/sensor/hiddenStateProbe").SensorReading | null;
+export interface SensorReadoutMeterProps {
+    label: string;
+    reading: ReturnType<typeof probeHiddenState>;
+    className?: string;
+}
+/** A handheld-sensor readout: needle strength bar + the raw reading, or a "no signal" idle state. */
+export declare function SensorReadoutMeter({ label, reading, className }: SensorReadoutMeterProps): import("react").JSX.Element;

package/dist/vision/HiddenStateProbeHud.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { probeHiddenState } from "@jgengine/core/sensor/hiddenStateProbe";
+/** Reads a hidden zone/entity state variable in range (EMF / thermometer / geiger style sensor verb, #116). */
+export function useHiddenStateProbe(origin, sources, options) {
+    return probeHiddenState(origin, sources, options);
+}
+/** A handheld-sensor readout: needle strength bar + the raw reading, or a "no signal" idle state. */
+export function SensorReadoutMeter({ label, reading, className }) {
+    const percent = reading === null ? 0 : Math.round(reading.strength * 100);
+    return (_jsxs("div", { className: className ?? "w-44 rounded border border-emerald-400/30 bg-black/70 p-2 text-xs text-emerald-200 shadow-lg", children: [_jsxs("div", { className: "mb-1 flex items-center justify-between uppercase tracking-wide", children: [_jsx("span", { children: label }), _jsx("span", { className: "tabular-nums", children: reading === null ? "—" : `${percent}%` })] }), _jsx("div", { className: "h-1.5 overflow-hidden rounded bg-white/10", children: _jsx("div", { className: "h-full bg-emerald-400 transition-[width]", style: { width: `${percent}%` } }) }), _jsx("div", { className: "mt-1 text-[10px] text-emerald-300/70", children: reading === null ? "no signal" : String(reading.value) })] }));
+}

package/dist/vision/RevealVision.d.ts

@@ -0,0 +1,28 @@
+import { type RevealHit } from "@jgengine/core/sensor/revealQuery";
+import type { SceneEntity } from "@jgengine/core/scene/entityStore";
+export interface RevealVisionOptions {
+    originEntityId?: string;
+    radius: number;
+    tags: readonly string[];
+    resolveTags: (entity: SceneEntity) => readonly string[];
+}
+/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene. */
+export declare function useRevealHits(options: RevealVisionOptions): readonly RevealHit[];
+export interface RevealHighlightsProps extends RevealVisionOptions {
+    enabled: boolean;
+    color?: string;
+}
+/**
+ * Screen-space reveal effect (#115) — highlights tagged entities through
+ * occluders (Dark Sight / detective-vision / wallhack style). Renders with
+ * `depthTest: false` so the highlight draws over any wall standing between
+ * the origin and the revealed entity, rather than the usual depth-sorted scene.
+ */
+export declare function RevealHighlights(props: RevealHighlightsProps): import("react").JSX.Element | null;
+export interface RevealScreenTintProps {
+    enabled: boolean;
+    color?: string;
+    className?: string;
+}
+/** Full-screen desaturating tint that reads as "vision mode is on" (Dark Sight / thermal / detective vision). */
+export declare function RevealScreenTint({ enabled, color, className }: RevealScreenTintProps): import("react").JSX.Element | null;

package/dist/vision/RevealVision.js

@@ -0,0 +1,53 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { DoubleSide } from "three";
+import { createRevealQuery } from "@jgengine/core/sensor/revealQuery";
+import { usePlayer, useSceneEntities } from "@jgengine/react/hooks";
+/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene. */
+export function useRevealHits(options) {
+    const entities = useSceneEntities();
+    const player = usePlayer();
+    const originId = options.originEntityId ?? player.userId;
+    const tagsKey = options.tags.join("|");
+    return useMemo(() => {
+        const byId = new Map(entities.map((entity) => [entity.id, entity]));
+        const query = createRevealQuery({
+            resolvePosition: (id) => byId.get(id)?.position,
+            resolveTags: (id) => {
+                const entity = byId.get(id);
+                return entity === undefined ? [] : options.resolveTags(entity);
+            },
+            candidates: () => entities.map((entity) => entity.id),
+        });
+        return query.inRadius(originId, options.radius, options.tags);
+    }, [entities, originId, options.radius, tagsKey, options.tags, options.resolveTags]);
+}
+/**
+ * Screen-space reveal effect (#115) — highlights tagged entities through
+ * occluders (Dark Sight / detective-vision / wallhack style). Renders with
+ * `depthTest: false` so the highlight draws over any wall standing between
+ * the origin and the revealed entity, rather than the usual depth-sorted scene.
+ */
+export function RevealHighlights(props) {
+    const { enabled, color = "#7dd3fc" } = props;
+    const hits = useRevealHits(props);
+    const entities = useSceneEntities();
+    if (!enabled)
+        return null;
+    return (_jsx(_Fragment, { children: hits.map((hit) => {
+            const entity = entities.find((candidate) => candidate.id === hit.instanceId);
+            if (entity === undefined)
+                return null;
+            const pulse = Math.max(0.25, 1 - hit.distance / Math.max(props.radius, 1));
+            return (_jsxs("group", { position: [entity.position[0], entity.position[1], entity.position[2]], children: [_jsxs("mesh", { "position-y": 0.95, renderOrder: 999, children: [_jsx("capsuleGeometry", { args: [0.42, 1.2, 6, 14] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.55 + pulse * 0.35, depthTest: false })] }), _jsxs("mesh", { "position-y": 2.6, renderOrder: 999, children: [_jsx("coneGeometry", { args: [0.14, 0.3, 12] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85, depthTest: false })] }), _jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.04, renderOrder: 999, children: [_jsx("ringGeometry", { args: [0.55, 0.85, 32] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.9, depthTest: false, side: DoubleSide })] })] }, hit.instanceId));
+        }) }));
+}
+/** Full-screen desaturating tint that reads as "vision mode is on" (Dark Sight / thermal / detective vision). */
+export function RevealScreenTint({ enabled, color = "rgba(56, 189, 248, 0.16)", className }) {
+    if (!enabled)
+        return null;
+    return (_jsx("div", { className: className ?? "pointer-events-none absolute inset-0 z-10 mix-blend-screen", style: {
+            background: `radial-gradient(circle at 50% 50%, transparent 25%, ${color} 100%)`,
+            filter: "saturate(0.55) contrast(1.15) brightness(0.92)",
+        } }));
+}

package/dist/water/OceanShader.d.ts

@@ -1,2 +1,2 @@
-export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float common = horizontal * k * sine;\n    tangent += vec3(-common * direction.x * direction.x, amplitude * k * direction.x * cosine, -common * direction.x * direction.y);\n    bitangent += vec3(-common * direction.x * direction.y, amplitude * k * direction.y * cosine, -common * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
+export declare const oceanVertexShader = "\nuniform float uTime;\nuniform vec2 uWaveDirections[6];\nuniform vec4 uWaveParams[6];\nuniform float uChoppiness;\nuniform float uFoamThreshold;\nuniform float uFoamSoftness;\nuniform float uFoamCoverage;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 displaced = position;\n  vec3 tangent = vec3(1.0, 0.0, 0.0);\n  vec3 bitangent = vec3(0.0, 0.0, 1.0);\n  float crest = 0.0;\n\n  for (int i = 0; i < 6; i++) {\n    vec2 direction = normalize(uWaveDirections[i]);\n    vec4 wave = uWaveParams[i];\n    float k = wave.x;\n    float amplitude = wave.y;\n    float steepness = wave.z;\n    float omega = wave.w;\n    float phase = k * dot(direction, position.xz) - omega * uTime;\n    float sine = sin(phase);\n    float cosine = cos(phase);\n    float horizontal = steepness * amplitude * uChoppiness;\n    displaced.x += horizontal * direction.x * cosine;\n    displaced.z += horizontal * direction.y * cosine;\n    displaced.y += amplitude * sine;\n    float slopeTerm = horizontal * k * sine;\n    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);\n    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);\n    crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));\n  }\n\n  vNormal = normalize(cross(bitangent, tangent));\n  vCrest = crest;\n  vWaveHeight = displaced.y;\n  vec4 worldPosition = modelMatrix * vec4(displaced, 1.0);\n  vWorldPosition = worldPosition.xyz;\n  gl_Position = projectionMatrix * viewMatrix * worldPosition;\n}\n";
 export declare const oceanFragmentShader = "\nuniform vec3 uShallowColor;\nuniform vec3 uDeepColor;\nuniform vec3 uCrestColor;\nuniform vec3 uFoamColor;\nuniform float uOpacity;\nuniform float uFresnelStrength;\nuniform float uHorizonBlend;\nuniform float uFoamIntensity;\n\nvarying vec3 vWorldPosition;\nvarying vec3 vNormal;\nvarying float vCrest;\nvarying float vWaveHeight;\n\nvoid main() {\n  vec3 normal = normalize(vNormal);\n  vec3 viewDirection = normalize(cameraPosition - vWorldPosition);\n  float fresnel = pow(1.0 - max(dot(normal, viewDirection), 0.0), 4.5);\n  float depthMix = smoothstep(-1.8, 1.6, vWaveHeight);\n  vec3 waterColor = mix(uDeepColor, uShallowColor, depthMix);\n  waterColor = mix(waterColor, uCrestColor, smoothstep(0.15, 1.2, vWaveHeight) * 0.28);\n  waterColor = mix(waterColor, vec3(0.86, 0.95, 1.0), fresnel * uFresnelStrength);\n  float horizon = smoothstep(0.0, 1.0, 1.0 - abs(normal.y));\n  waterColor = mix(waterColor, uShallowColor, horizon * uHorizonBlend);\n  float foam = clamp(vCrest * uFoamIntensity, 0.0, 1.0);\n  vec3 color = mix(waterColor, uFoamColor, foam);\n  gl_FragColor = vec4(color, uOpacity);\n}\n";

package/dist/water/OceanShader.js

@@ -32,9 +32,9 @@ void main() {
     displaced.x += horizontal * direction.x * cosine;
     displaced.z += horizontal * direction.y * cosine;
     displaced.y += amplitude * sine;
-    float common = horizontal * k * sine;
-    tangent += vec3(-common * direction.x * direction.x, amplitude * k * direction.x * cosine, -common * direction.x * direction.y);
-    bitangent += vec3(-common * direction.x * direction.y, amplitude * k * direction.y * cosine, -common * direction.y * direction.y);
+    float slopeTerm = horizontal * k * sine;
+    tangent += vec3(-slopeTerm * direction.x * direction.x, amplitude * k * direction.x * cosine, -slopeTerm * direction.x * direction.y);
+    bitangent += vec3(-slopeTerm * direction.x * direction.y, amplitude * k * direction.y * cosine, -slopeTerm * direction.y * direction.y);
     crest = max(crest, smoothstep(uFoamThreshold, uFoamThreshold + uFoamSoftness, sine * steepness + uFoamCoverage * 0.35));
   }
 

package/dist/weather/FireSpreadLayer.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from "three";
+import type { FireGrid } from "@jgengine/core/world/weather";
+export interface FireSpreadLayerProps {
+    grid: FireGrid;
+    cellSize: number;
+    origin?: readonly [number, number];
+    /** Sample ground height so flames sit on terrain; defaults to y=0. */
+    heightAt?: (x: number, z: number) => number;
+    /** Flame quad height. Default 1.6. */
+    flameHeight?: number;
+    burningColor?: THREE.ColorRepresentation;
+    emberColor?: THREE.ColorRepresentation;
+}
+export declare function FireSpreadLayer({ grid, cellSize, origin, heightAt, flameHeight, burningColor, emberColor, }: FireSpreadLayerProps): import("react").JSX.Element;

package/dist/weather/FireSpreadLayer.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+const HIDDEN = new THREE.Matrix4().makeScale(0, 0, 0);
+export function FireSpreadLayer({ grid, cellSize, origin = [0, 0], heightAt, flameHeight = 1.6, burningColor = "#ff6a1a", emberColor = "#4a1206", }) {
+    const flames = useRef(null);
+    const scorch = useRef(null);
+    const capacity = grid.cols * grid.rows;
+    const flameGeometry = useMemo(() => new THREE.PlaneGeometry(cellSize * 0.9, flameHeight), [cellSize, flameHeight]);
+    const scorchGeometry = useMemo(() => {
+        const geometry = new THREE.PlaneGeometry(cellSize, cellSize);
+        geometry.rotateX(-Math.PI / 2);
+        return geometry;
+    }, [cellSize]);
+    const flameMaterial = useMemo(() => new THREE.MeshBasicMaterial({ color: burningColor, transparent: true, opacity: 0.85, depthWrite: false, side: THREE.DoubleSide }), [burningColor]);
+    const scorchMaterial = useMemo(() => new THREE.MeshBasicMaterial({ color: emberColor, transparent: true, opacity: 0.7, depthWrite: false }), [emberColor]);
+    useEffect(() => () => {
+        flameGeometry.dispose();
+        scorchGeometry.dispose();
+        flameMaterial.dispose();
+        scorchMaterial.dispose();
+    }, [flameGeometry, scorchGeometry, flameMaterial, scorchMaterial]);
+    const matrix = useMemo(() => new THREE.Matrix4(), []);
+    const position = useMemo(() => new THREE.Vector3(), []);
+    const quaternion = useMemo(() => new THREE.Quaternion(), []);
+    const scale = useMemo(() => new THREE.Vector3(1, 1, 1), []);
+    useFrame((state) => {
+        const flameMesh = flames.current;
+        const scorchMesh = scorch.current;
+        if (flameMesh === null || scorchMesh === null)
+            return;
+        const cells = grid.snapshot();
+        const flicker = 0.85 + 0.15 * Math.sin(state.clock.elapsedTime * 12);
+        let flameIndex = 0;
+        let scorchIndex = 0;
+        for (let row = 0; row < grid.rows; row += 1) {
+            for (let col = 0; col < grid.cols; col += 1) {
+                const cell = cells[row * grid.cols + col];
+                const x = origin[0] + col * cellSize;
+                const z = origin[1] + row * cellSize;
+                const groundY = heightAt?.(x, z) ?? 0;
+                if (cell.state === "burning") {
+                    position.set(x, groundY + flameHeight * 0.5, z);
+                    quaternion.setFromEuler(new THREE.Euler(0, state.camera.rotation.y, 0));
+                    scale.set(1, flicker, 1);
+                    matrix.compose(position, quaternion, scale);
+                    flameMesh.setMatrixAt(flameIndex, matrix);
+                    flameIndex += 1;
+                }
+                else if (cell.state === "burnt") {
+                    position.set(x, groundY + 0.05, z);
+                    scorchMesh.setMatrixAt(scorchIndex, matrix.compose(position, new THREE.Quaternion(), scale.set(1, 1, 1)));
+                    scorchIndex += 1;
+                }
+            }
+        }
+        for (let i = flameIndex; i < capacity; i += 1)
+            flameMesh.setMatrixAt(i, HIDDEN);
+        for (let i = scorchIndex; i < capacity; i += 1)
+            scorchMesh.setMatrixAt(i, HIDDEN);
+        flameMesh.count = capacity;
+        scorchMesh.count = capacity;
+        flameMesh.instanceMatrix.needsUpdate = true;
+        scorchMesh.instanceMatrix.needsUpdate = true;
+    });
+    return (_jsxs("group", { children: [_jsx("instancedMesh", { ref: scorch, args: [scorchGeometry, scorchMaterial, capacity], frustumCulled: false, renderOrder: 5 }), _jsx("instancedMesh", { ref: flames, args: [flameGeometry, flameMaterial, capacity], frustumCulled: false, renderOrder: 11 })] }));
+}

package/dist/weather/index.d.ts

@@ -1,3 +1,4 @@
+export { FireSpreadLayer, type FireSpreadLayerProps } from "./FireSpreadLayer.js";
 export { LightningStrike, type LightningStrikeProps } from "./LightningStrike.js";
 export { RainField, type RainFieldProps } from "./RainField.js";
 export { SnowField, type SnowFieldProps } from "./SnowField.js";

package/dist/weather/index.js

@@ -1,3 +1,4 @@
+export { FireSpreadLayer } from "./FireSpreadLayer.js";
 export { LightningStrike } from "./LightningStrike.js";
 export { RainField } from "./RainField.js";
 export { SnowField } from "./SnowField.js";

package/dist/world/DataObjects.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from "react";
+import * as THREE from "three";
+/**
+ * Renders one placed 3D object per data item — a 3D bar chart, a heatmap, a city
+ * of buildings, a crowd. By default each item is an extruded box (all boxes share
+ * one `InstancedMesh`, so hundreds cost one draw call), sized and colored from the
+ * item; `renderItem` swaps the box for arbitrary content (a sprite, a GLB, a full
+ * entity). Genre-agnostic: the caller owns the data `T`, this owns the placement.
+ */
+export interface DataObjectsProps<T> {
+    data: readonly T[];
+    /** World `[x, z]` for an item (placed on the ground plane). */
+    position: (item: T, index: number) => readonly [number, number];
+    /** Box height (Y-scale) for an item. */
+    height: (item: T, index: number) => number;
+    /** Box color for an item (any CSS/hex/THREE color). */
+    color: (item: T, index: number) => THREE.ColorRepresentation;
+    /** Footprint on X and Z. Default 0.28. */
+    cellSize?: number;
+    /** Index of the highlighted item, painted with `hoverColor`. */
+    hovered?: number | null;
+    hoverColor?: THREE.ColorRepresentation;
+    /** Called with the item index under the pointer, or null on exit. */
+    onHover?: (index: number | null) => void;
+    /** Staggered grow-in; restarts whenever `data` identity changes. */
+    grow?: {
+        duration?: number;
+        delay?: (item: T, index: number) => number;
+    };
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+    /**
+     * Render arbitrary content per item instead of an instanced box — a sprite, a
+     * GLB, a full entity. The layout positions each on the ground at its `[x, z]`
+     * and hands you the resolved `height` to size against (e.g. one walking figure
+     * per unit of value). When set, the instanced-box path is bypassed.
+     */
+    renderItem?: (item: T, index: number, info: {
+        x: number;
+        z: number;
+        height: number;
+    }) => ReactNode;
+}
+export declare function DataObjects<T>({ data, position, height, color, cellSize, hovered, hoverColor, onHover, grow, castShadow, receiveShadow, renderItem, }: DataObjectsProps<T>): import("react").JSX.Element;

package/dist/world/DataObjects.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+export function DataObjects({ data, position, height, color, cellSize = 0.28, hovered = null, hoverColor = "#ffffff", onHover, grow, castShadow = true, receiveShadow = true, renderItem, }) {
+    const meshRef = useRef(null);
+    const dummy = useMemo(() => new THREE.Object3D(), []);
+    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ roughness: 0.62, metalness: 0.04 }), []);
+    const hover = useMemo(() => new THREE.Color(hoverColor), [hoverColor]);
+    const startRef = useRef(null);
+    const capacity = data.length;
+    const layout = useMemo(() => {
+        const positions = new Float32Array(capacity * 2);
+        const targets = new Float32Array(capacity);
+        const delays = new Float32Array(capacity);
+        const colors = [];
+        data.forEach((item, i) => {
+            const [x, z] = position(item, i);
+            positions[i * 2] = x;
+            positions[i * 2 + 1] = z;
+            targets[i] = height(item, i);
+            delays[i] = grow?.delay?.(item, i) ?? 0;
+            colors.push(new THREE.Color(color(item, i)));
+        });
+        return { positions, targets, delays, colors };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [data]);
+    useEffect(() => {
+        startRef.current = null;
+    }, [data]);
+    useEffect(() => () => {
+        geometry.dispose();
+        material.dispose();
+    }, [geometry, material]);
+    const duration = grow?.duration ?? 0;
+    useFrame((state) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        if (startRef.current === null)
+            startRef.current = state.clock.elapsedTime;
+        const elapsed = state.clock.elapsedTime - startRef.current;
+        const { positions, targets, delays, colors } = layout;
+        for (let i = 0; i < capacity; i += 1) {
+            const grown = duration <= 0 ? 1 : clamp01((elapsed - delays[i]) / duration);
+            const eased = 1 - Math.pow(1 - grown, 3);
+            const h = Math.max(targets[i] * eased, 0.001);
+            dummy.position.set(positions[i * 2], h / 2, positions[i * 2 + 1]);
+            dummy.scale.set(cellSize, h, cellSize);
+            dummy.updateMatrix();
+            mesh.setMatrixAt(i, dummy.matrix);
+            mesh.setColorAt(i, i === hovered ? hover : colors[i]);
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+        if (mesh.instanceColor !== null)
+            mesh.instanceColor.needsUpdate = true;
+    });
+    function handleMove(event) {
+        if (onHover === undefined)
+            return;
+        event.stopPropagation();
+        onHover(event.instanceId ?? null);
+    }
+    if (renderItem !== undefined) {
+        return (_jsx("group", { children: data.map((item, i) => {
+                const [x, z] = position(item, i);
+                return (_jsx("group", { position: [x, 0, z], children: renderItem(item, i, { x, z, height: height(item, i) }) }, i));
+            }) }));
+    }
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, Math.max(capacity, 1)], castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: false, onPointerMove: onHover === undefined ? undefined : handleMove, onPointerOut: onHover === undefined ? undefined : () => onHover(null) }, capacity));
+}

package/dist/world/GridWorldScene.d.ts

@@ -0,0 +1,10 @@
+import type { WorldFeature } from "@jgengine/core/world/features";
+export interface GridWorldSceneProps {
+    feature: WorldFeature;
+}
+/**
+ * Data-driven renderer for the `biomes()`/`voxel()`/`plots()`/`tilemap()` world-feature kinds
+ * (#207.1): one `InstancedMesh` of extruded, colored boxes built from each feature's declared
+ * `cells`, following the same direct-buffer pattern as `InstancedBodies`.
+ */
+export declare function GridWorldScene({ feature }: GridWorldSceneProps): import("react").JSX.Element | null;