@jgengine/shell 0.7.0 → 0.9.0

package/dist/touch/TouchControlsOverlay.js

@@ -0,0 +1,279 @@
+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 };
+const BUTTON_SIZE = 56;
+const RING1_RADIUS = 112;
+const RING2_RADIUS = 178;
+const RING1_CAPACITY = 3;
+const RING2_CAPACITY = 5;
+const RING1_ANGLES = [[], [40], [16, 64], [12, 44, 76]];
+const DOCK_BASE_PADDING = 20;
+const UTILITY_ROW_HEIGHT = 28;
+function polar(radius, deg, buttonSize) {
+    const rad = (deg * Math.PI) / 180;
+    return {
+        right: radius * Math.cos(rad) - buttonSize / 2,
+        bottom: radius * Math.sin(rad) - buttonSize / 2,
+    };
+}
+function ringAngles(count, from, to) {
+    if (count === 1)
+        return [(from + to) / 2];
+    const step = (to - from) / (count - 1);
+    return Array.from({ length: count }, (_, index) => from + index * step);
+}
+/**
+ * Thumb-arc placement for primary buttons around the bottom-right corner:
+ * up to three on an inner ring, the rest on an outer ring. Null means too
+ * many buttons for an arc — the dock falls back to a wrapping grid.
+ */
+export function primaryButtonOffsets(count, scale = 1) {
+    if (count === 0)
+        return [];
+    if (count > RING1_CAPACITY + RING2_CAPACITY)
+        return null;
+    const button = BUTTON_SIZE * scale;
+    const ring1 = RING1_ANGLES[Math.min(count, RING1_CAPACITY)] ?? [];
+    const offsets = ring1.map((angle) => polar(RING1_RADIUS * scale, angle, button));
+    const rest = count - ring1.length;
+    if (rest > 0) {
+        for (const angle of ringAngles(rest, 10, 80))
+            offsets.push(polar(RING2_RADIUS * scale, angle, button));
+    }
+    return offsets;
+}
+function primaryClusterExtent(count, scale = 1) {
+    if (count === 0)
+        return 0;
+    if (count <= RING1_CAPACITY)
+        return (RING1_RADIUS + BUTTON_SIZE / 2) * scale;
+    if (count <= RING1_CAPACITY + RING2_CAPACITY)
+        return (RING2_RADIUS + BUTTON_SIZE / 2) * scale;
+    return Math.ceil(count / 4) * (BUTTON_SIZE + 12) * scale;
+}
+/**
+ * Vertical space (px, excluding device safe areas) the dock occupies above
+ * the bottom edge. The shell publishes it as `--jg-hud-dock-clearance` so
+ * `HudCanvas` regions never collide with touch controls.
+ */
+export function touchDockClearance(scheme, scale = 1) {
+    if (scheme === null)
+        return 0;
+    let primary = 0;
+    let utility = 0;
+    for (const button of scheme.buttons) {
+        if (button.kind === "utility")
+            utility += 1;
+        else
+            primary += 1;
+    }
+    const tallest = Math.max(scheme.joystick !== null ? JOYSTICK_SIZE * scale : 0, primaryClusterExtent(primary, scale), utility > 0 ? UTILITY_ROW_HEIGHT : 0);
+    if (tallest === 0)
+        return 0;
+    return tallest + DOCK_BASE_PADDING + 12;
+}
+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, scale = 1 }) {
+    const baseRef = useRef(null);
+    const thumbRef = useRef(null);
+    const pointerIdRef = useRef(null);
+    const activeRef = useRef(new Set());
+    const size = JOYSTICK_SIZE * scale;
+    const thumbSize = JOYSTICK_THUMB * scale;
+    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 - thumbSize / 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: size, height: 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: thumbSize, height: thumbSize } }) }));
+}
+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, scale = 1 }) {
+    const pointerIdRef = useRef(null);
+    const icon = touchButtonIcon(button);
+    const size = BUTTON_SIZE * scale;
+    const releaseIfHeld = () => {
+        if (pointerIdRef.current === null)
+            return;
+        pointerIdRef.current = null;
+        sink.onCodeUp(touchCode(button.action));
+    };
+    return (_jsx("button", { type: "button", "aria-label": button.label, style: { width: size, height: size }, className: "pointer-events-auto flex 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: Math.round(26 * scale) }) : _jsx("span", { className: "px-1", children: button.label }) }));
+}
+function TouchUtilityChip({ button, sink }) {
+    const pointerIdRef = useRef(null);
+    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-7 touch-none select-none items-center rounded-full border border-white/20 bg-black/40 px-3 text-[10px] font-semibold uppercase tracking-wide text-white/80 backdrop-blur-sm active:border-white/50 active:bg-white/25", 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: button.label }));
+}
+function PrimaryButtonCluster({ buttons, sink, scale = 1 }) {
+    const offsets = primaryButtonOffsets(buttons.length, scale);
+    if (offsets === null) {
+        return (_jsx("div", { className: "flex max-w-[60%] flex-wrap items-end justify-end gap-3", children: buttons.map((button) => (_jsx(TouchActionButton, { button: button, sink: sink, scale: scale }, button.action))) }));
+    }
+    const extent = primaryClusterExtent(buttons.length, scale);
+    return (_jsx("div", { className: "pointer-events-none relative", style: { width: extent, height: extent }, children: buttons.map((button, index) => {
+            const offset = offsets[index];
+            return (_jsx("div", { className: "absolute", style: { right: offset?.right ?? 0, bottom: offset?.bottom ?? 0 }, children: _jsx(TouchActionButton, { button: button, sink: sink, scale: scale }) }, button.action));
+        }) }));
+}
+export function TouchControlsDock({ scheme, sink, scale = 1 }) {
+    const primary = scheme.buttons.filter((button) => button.kind !== "utility");
+    const utility = scheme.buttons.filter((button) => button.kind === "utility");
+    return (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 z-40", style: { paddingBottom: `calc(env(safe-area-inset-bottom, 0px) + ${DOCK_BASE_PADDING}px)` }, children: [_jsxs("div", { className: "flex items-end justify-between gap-4 px-5", children: [_jsx("div", { children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, scale: scale }) : null }), _jsx(PrimaryButtonCluster, { buttons: primary, sink: sink, scale: scale })] }), utility.length > 0 ? (_jsx("div", { className: "pointer-events-none absolute inset-x-0 flex justify-center gap-2", style: { bottom: "calc(env(safe-area-inset-bottom, 0px) + 8px)" }, children: utility.map((button) => (_jsx(TouchUtilityChip, { button: button, sink: sink }, button.action))) })) : null] }));
+}

package/dist/visibility/CullingProvider.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode, type MutableRefObject } from "react";
+import type { VisibilityConfig } from "@jgengine/core/visibility/config";
+type VisiblePredicate = (id: string) => boolean;
+/**
+ * Read the current render-visibility predicate. Backward compatible: with no CullingProvider
+ * mounted (or culling disabled) it returns an always-visible ref, so a marker that consults it
+ * behaves exactly as before this feature existed.
+ */
+export declare function useRenderVisibility(): MutableRefObject<VisiblePredicate>;
+/**
+ * Drives automatic frustum + distance culling for every entity and placed object. It reads the
+ * live render camera each frame, updates the engine VisibilitySystem, and exposes a predicate the
+ * entity/object markers consult to toggle `group.visible` — objects fully outside the view (plus a
+ * conservative preload margin) are never submitted to the renderer, without unmounting them or
+ * touching gameplay. UI, sky, terrain, and environment live outside this subtree and are unaffected.
+ */
+export declare function CullingProvider({ config, children }: {
+    config: VisibilityConfig | undefined;
+    children: ReactNode;
+}): ReactNode;
+export {};

package/dist/visibility/CullingProvider.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useRef } from "react";
+import { useThree, useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { createVisibilitySystem } from "@jgengine/core/visibility/visibilitySystem";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/index.js";
+const ALWAYS_VISIBLE = () => true;
+const alwaysVisibleRef = { current: ALWAYS_VISIBLE };
+const CullingContext = createContext(null);
+/**
+ * Read the current render-visibility predicate. Backward compatible: with no CullingProvider
+ * mounted (or culling disabled) it returns an always-visible ref, so a marker that consults it
+ * behaves exactly as before this feature existed.
+ */
+export function useRenderVisibility() {
+    return useContext(CullingContext) ?? alwaysVisibleRef;
+}
+const ENTITY_BOUNDS = { kind: "sphere", radius: 2, offset: [0, 1, 0] };
+function objectRadius(scale) {
+    if (scale === undefined)
+        return 1;
+    const s = typeof scale === "number" ? scale : Math.max(scale[0], scale[1], scale[2]);
+    return Math.max(0.75, s);
+}
+function buildSystem(ctx, config) {
+    const versions = new Map();
+    let currentView = null;
+    const scratch = { id: "", position: [0, 0, 0], version: 0 };
+    const objectSpec = { kind: "sphere", radius: 1, offset: [0, 0.5, 0] };
+    function bump(id, position, rot) {
+        const prev = versions.get(id);
+        if (prev !== undefined && prev.x === position[0] && prev.y === position[1] && prev.z === position[2] && prev.rot === rot) {
+            return prev.version;
+        }
+        const version = (prev?.version ?? 0) + 1;
+        versions.set(id, { x: position[0], y: position[1], z: position[2], rot, version });
+        return version;
+    }
+    function* renderables() {
+        const entityOverrides = config?.entities;
+        for (const entity of ctx.scene.entity.list()) {
+            scratch.id = entity.id;
+            scratch.position = entity.position;
+            scratch.version = bump(entity.id, entity.position, entity.rotationY);
+            scratch.bounds = ENTITY_BOUNDS;
+            scratch.overrides = entityOverrides?.[entity.name];
+            scratch.layer = "entity";
+            yield scratch;
+        }
+        const objectOverrides = config?.objects;
+        for (const object of ctx.scene.object.list()) {
+            scratch.id = object.instanceId;
+            scratch.position = object.position;
+            scratch.version = bump(object.instanceId, object.position, object.rotationY);
+            objectSpec.radius = objectRadius(object.visual?.scale);
+            scratch.bounds = objectSpec;
+            scratch.overrides = objectOverrides?.[object.catalogId];
+            scratch.layer = "object";
+            yield scratch;
+        }
+    }
+    const cameras = () => (currentView === null ? EMPTY_CAMERAS : [{ id: "main", view: currentView }]);
+    const options = {
+        renderables,
+        cameras,
+        ...(config?.culling !== undefined ? { settings: config.culling } : {}),
+        ...(config?.scene !== undefined ? { sceneOverrides: config.scene } : {}),
+    };
+    const system = createVisibilitySystem(options);
+    return {
+        system,
+        setView(view) {
+            currentView = view;
+        },
+    };
+}
+const EMPTY_CAMERAS = [];
+const tmpDir = new THREE.Vector3();
+function viewFromCamera(camera) {
+    camera.getWorldDirection(tmpDir);
+    const p = camera.position;
+    const position = [p.x, p.y, p.z];
+    const target = [p.x + tmpDir.x, p.y + tmpDir.y, p.z + tmpDir.z];
+    const up = [camera.up.x, camera.up.y, camera.up.z];
+    if (camera.isPerspectiveCamera) {
+        const c = camera;
+        return { kind: "perspective", position, target, up, fovDeg: c.fov, aspect: c.aspect, near: c.near, far: c.far };
+    }
+    if (camera.isOrthographicCamera) {
+        const c = camera;
+        const zoom = c.zoom || 1;
+        return {
+            kind: "orthographic",
+            position,
+            target,
+            up,
+            halfWidth: Math.abs((c.right - c.left) / 2 / zoom),
+            halfHeight: Math.abs((c.top - c.bottom) / 2 / zoom),
+            near: c.near,
+            far: c.far,
+        };
+    }
+    return null;
+}
+/**
+ * Drives automatic frustum + distance culling for every entity and placed object. It reads the
+ * live render camera each frame, updates the engine VisibilitySystem, and exposes a predicate the
+ * entity/object markers consult to toggle `group.visible` — objects fully outside the view (plus a
+ * conservative preload margin) are never submitted to the renderer, without unmounting them or
+ * touching gameplay. UI, sky, terrain, and environment live outside this subtree and are unaffected.
+ */
+export function CullingProvider({ config, children }) {
+    const ctx = useGameContext();
+    const enabled = config?.enabled !== false;
+    const predicateRef = useRef(ALWAYS_VISIBLE);
+    const camera = useThree((state) => state.camera);
+    const driver = useMemo(() => (enabled ? buildSystem(ctx, config) : null), [ctx, config, enabled]);
+    useFrame(() => {
+        if (driver === null) {
+            predicateRef.current = ALWAYS_VISIBLE;
+            return;
+        }
+        const view = viewFromCamera(camera);
+        if (view === null) {
+            predicateRef.current = ALWAYS_VISIBLE;
+            return;
+        }
+        driver.setView(view);
+        const visible = driver.system.update().visible;
+        predicateRef.current = (id) => visible.has(id);
+    }, CAMERA_POST_FRAME_PRIORITY);
+    return _jsx(CullingContext.Provider, { value: predicateRef, children: children });
+}

package/dist/vision/FrustumSensorHud.d.ts

@@ -1,14 +1,9 @@
 import { type FramingConfig, type FrustumSample } from "@jgengine/core/sensor/frustumSensor";
+export { frustumSampleDisplayEqual } from "./frustumSampleEqual.js";
 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`)

package/dist/vision/FrustumSensorHud.js

@@ -5,21 +5,18 @@ import { useMemo, useRef, useState } from "react";
 import { PerspectiveCamera, Vector3 } from "three";
 import { createFrustumSensor, } from "@jgengine/core/sensor/frustumSensor";
 import { useSceneEntities } from "@jgengine/react/hooks";
+import { frustumSampleDisplayEqual } from "./frustumSampleEqual.js";
+export { frustumSampleDisplayEqual } from "./frustumSampleEqual.js";
 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 bestRef = useRef(null);
     const forward = useRef(new Vector3());
     useFrame((_, dt) => {
         const targets = [];
@@ -29,28 +26,29 @@ export function useFrustumSensor(options) {
                 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;
+        if (targets.length > 0) {
+            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);
+            for (const sample of samples) {
+                if (!sample.inView)
+                    continue;
+                if (leader === null || sample.framing > leader.framing)
+                    leader = sample;
+            }
         }
+        if (frustumSampleDisplayEqual(bestRef.current, leader))
+            return;
+        bestRef.current = leader;
         setBest(leader);
     });
     return best;
@@ -62,6 +60,6 @@ export function useFrustumSensor(options) {
  */
 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 ??
+    return (_jsx(Html, { fullscreen: true, calculatePosition: (_el, _camera, size) => [size.width / 2, size.height / 2], 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/frustumSampleEqual.d.ts

@@ -0,0 +1,2 @@
+import type { FrustumSample } from "@jgengine/core/sensor/frustumSensor";
+export declare function frustumSampleDisplayEqual(a: FrustumSample | null, b: FrustumSample | null): boolean;

package/dist/vision/frustumSampleEqual.js

@@ -0,0 +1,10 @@
+export function frustumSampleDisplayEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return (a.id === b.id &&
+        a.inView === b.inView &&
+        Math.round(a.framing * 100) === Math.round(b.framing * 100) &&
+        Math.round(a.dwellSeconds * 10) === Math.round(b.dwellSeconds * 10));
+}

package/dist/water/Ocean.js

@@ -5,7 +5,7 @@ import * as THREE from "three";
 import { createOceanConfig } from "./OceanConfig.js";
 import { createOceanMaterial, syncOceanMaterial } from "./OceanMaterial.js";
 function createOceanGeometry(config) {
-    const geometry = new THREE.PlaneGeometry(config.size, config.size, config.resolution, config.resolution);
+    const geometry = new THREE.PlaneGeometry(config.size, config.depth, config.resolution, config.resolution);
     geometry.rotateX(-Math.PI / 2);
     geometry.computeBoundingSphere();
     return geometry;

package/dist/water/OceanConfig.d.ts

@@ -30,7 +30,10 @@ export interface OceanFoamConfig {
 }
 export interface OceanConfig {
     quality?: OceanQualityPreset;
+    /** Ocean plane width in world units (X). When `depth` is omitted, also used for depth (square). */
     size?: number;
+    /** Ocean plane depth in world units (Z). Defaults to `size` for a square sheet. */
+    depth?: number;
     resolution?: number;
     amplitude?: number;
     speed?: number;
@@ -38,6 +41,12 @@ export interface OceanConfig {
     choppiness?: number;
     steepness?: number;
     timeScale?: number;
+    /**
+     * Primary Gerstner wavelength in world units — same unit as `@jgengine/core/world/water` `waveScale`
+     * (default 18). Scales the default wave set so the longest wave matches this value; explicit `waves`
+     * wavelengths are multiplied by `waveScale / 18`.
+     */
+    waveScale?: number;
     color?: OceanColorConfig;
     foam?: OceanFoamConfig;
     waves?: readonly OceanWaveConfig[];
@@ -67,6 +76,7 @@ export interface ResolvedOceanWaveConfig {
 export interface ResolvedOceanConfig {
     quality: OceanQualityPreset;
     size: number;
+    depth: number;
     resolution: number;
     amplitude: number;
     speed: number;
@@ -74,10 +84,13 @@ export interface ResolvedOceanConfig {
     choppiness: number;
     steepness: number;
     timeScale: number;
+    waveScale: number;
     color: ResolvedOceanColorConfig;
     foam: ResolvedOceanFoamConfig;
     waves: readonly ResolvedOceanWaveConfig[];
 }
+/** Shared with `@jgengine/core/world/water` — primary wavelength in world units. */
+export declare const DEFAULT_OCEAN_WAVE_SCALE = 18;
 export declare const OCEAN_QUALITY_PRESETS: Record<OceanQualityPreset, {
     size: number;
     resolution: number;