@jgengine/shell 0.8.0 → 0.9.0

package/dist/touch/TouchControlsOverlay.js

@@ -9,6 +9,77 @@ 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);
@@ -83,11 +154,13 @@ function joystickDirections(joystick, nx, ny) {
         active.add(joystick.right);
     return active;
 }
-function VirtualJoystick({ joystick, sink }) {
+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;
@@ -102,7 +175,7 @@ function VirtualJoystick({ joystick, sink }) {
             nx /= length;
             ny /= length;
         }
-        const travel = radius - JOYSTICK_THUMB / 2;
+        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) {
@@ -123,7 +196,7 @@ function VirtualJoystick({ joystick, sink }) {
         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) => {
+    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;
@@ -139,7 +212,7 @@ function VirtualJoystick({ joystick, sink }) {
                 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 } }) }));
+        }, 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)
@@ -148,16 +221,36 @@ function touchButtonIcon(button) {
         return button.icon;
     return iconForAction(button.action);
 }
-function TouchActionButton({ button, sink }) {
+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-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) => {
+    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;
@@ -166,8 +259,21 @@ function TouchActionButton({ button, sink }) {
         }, 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 }) }));
+        }, 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 }) {
-    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))) })] }));
+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;

package/dist/water/OceanConfig.js

@@ -1,5 +1,7 @@
 import * as THREE from "three";
 export const MAX_OCEAN_WAVES = 6;
+/** Shared with `@jgengine/core/world/water` — primary wavelength in world units. */
+export const DEFAULT_OCEAN_WAVE_SCALE = 18;
 export const OCEAN_QUALITY_PRESETS = {
     low: { size: 220, resolution: 80 },
     medium: { size: 360, resolution: 128 },
@@ -9,6 +11,7 @@ export const OCEAN_QUALITY_PRESETS = {
 export const DEFAULT_OCEAN_CONFIG = {
     quality: "medium",
     size: OCEAN_QUALITY_PRESETS.medium.size,
+    depth: OCEAN_QUALITY_PRESETS.medium.size,
     resolution: OCEAN_QUALITY_PRESETS.medium.resolution,
     amplitude: 1,
     speed: 1,
@@ -16,6 +19,7 @@ export const DEFAULT_OCEAN_CONFIG = {
     choppiness: 1,
     steepness: 0.72,
     timeScale: 1,
+    waveScale: DEFAULT_OCEAN_WAVE_SCALE,
     color: {
         shallow: "#2dc5d3",
         deep: "#064468",
@@ -33,14 +37,10 @@ export const DEFAULT_OCEAN_CONFIG = {
     },
     waves: [],
 };
-const DEFAULT_WAVE_SHAPE = [
-    { amplitude: 1.15, wavelength: 44, speed: 1, steepness: 0.68 },
-    { amplitude: 0.72, wavelength: 28, speed: 1.08, steepness: 0.58 },
-    { amplitude: 0.44, wavelength: 17, speed: 1.18, steepness: 0.48 },
-    { amplitude: 0.28, wavelength: 10, speed: 1.34, steepness: 0.38 },
-    { amplitude: 0.18, wavelength: 6.5, speed: 1.52, steepness: 0.28 },
-    { amplitude: 0.11, wavelength: 3.8, speed: 1.75, steepness: 0.18 },
-];
+const WAVE_WAVELENGTH_FALLOFF = 0.65;
+const WAVE_AMPLITUDE_SHAPE = [1.15, 0.72, 0.44, 0.28, 0.18, 0.11];
+const WAVE_SPEED_SHAPE = [1, 1.08, 1.18, 1.34, 1.52, 1.75];
+const WAVE_STEEPNESS_SHAPE = [0.68, 0.58, 0.48, 0.38, 0.28, 0.18];
 const DEFAULT_DIRECTION_OFFSETS = [-8, 7, 21, -31, 46, -58];
 function finiteOr(value, fallback) {
     return value === undefined || !Number.isFinite(value) ? fallback : value;
@@ -67,18 +67,21 @@ function normalizeDirection(direction, fallback) {
 }
 function createDefaultWaves(config) {
     const baseAngle = directionAngle(config.direction);
-    return DEFAULT_WAVE_SHAPE.map((wave, index) => ({
-        amplitude: wave.amplitude,
-        wavelength: wave.wavelength,
-        speed: wave.speed,
+    return WAVE_AMPLITUDE_SHAPE.map((amplitude, index) => ({
+        amplitude,
+        wavelength: Math.max(0.1, config.waveScale * WAVE_WAVELENGTH_FALLOFF ** index),
+        speed: WAVE_SPEED_SHAPE[index],
         direction: directionFromAngle(baseAngle + DEFAULT_DIRECTION_OFFSETS[index]),
-        steepness: wave.steepness,
+        steepness: WAVE_STEEPNESS_SHAPE[index],
     }));
 }
-function resolveWave(wave, fallback, config) {
+function resolveWave(wave, fallback, config, customWaves) {
+    const wavelength = customWaves && wave?.wavelength !== undefined
+        ? wave.wavelength * (config.waveScale / DEFAULT_OCEAN_WAVE_SCALE)
+        : finiteOr(wave?.wavelength, fallback.wavelength);
     return {
         amplitude: Math.max(0, finiteOr(wave?.amplitude, fallback.amplitude) * config.amplitude),
-        wavelength: Math.max(0.1, finiteOr(wave?.wavelength, fallback.wavelength)),
+        wavelength: Math.max(0.1, wavelength),
         speed: finiteOr(wave?.speed, fallback.speed) * config.speed,
         direction: normalizeDirection(wave?.direction, fallback.direction),
         steepness: clamp(finiteOr(wave?.steepness, fallback.steepness) * config.steepness, 0, 1.2),
@@ -87,9 +90,12 @@ function resolveWave(wave, fallback, config) {
 export function createOceanConfig(patch = {}) {
     const quality = patch.quality ?? DEFAULT_OCEAN_CONFIG.quality;
     const preset = OCEAN_QUALITY_PRESETS[quality];
+    const size = Math.max(1, finiteOr(patch.size, preset.size));
+    const depth = Math.max(1, finiteOr(patch.depth, size));
     const withoutWaves = {
         quality,
-        size: Math.max(1, Math.floor(finiteOr(patch.size, preset.size))),
+        size,
+        depth,
         resolution: Math.max(1, Math.floor(finiteOr(patch.resolution, preset.resolution))),
         amplitude: Math.max(0, finiteOr(patch.amplitude, DEFAULT_OCEAN_CONFIG.amplitude)),
         speed: finiteOr(patch.speed, DEFAULT_OCEAN_CONFIG.speed),
@@ -97,6 +103,7 @@ export function createOceanConfig(patch = {}) {
         choppiness: Math.max(0, finiteOr(patch.choppiness, DEFAULT_OCEAN_CONFIG.choppiness)),
         steepness: Math.max(0, finiteOr(patch.steepness, DEFAULT_OCEAN_CONFIG.steepness)),
         timeScale: finiteOr(patch.timeScale, DEFAULT_OCEAN_CONFIG.timeScale),
+        waveScale: Math.max(0.1, finiteOr(patch.waveScale, DEFAULT_OCEAN_CONFIG.waveScale)),
         color: {
             ...DEFAULT_OCEAN_CONFIG.color,
             ...patch.color,
@@ -114,8 +121,9 @@ export function createOceanConfig(patch = {}) {
         },
     };
     const defaultWaves = createDefaultWaves(withoutWaves);
+    const customWaves = patch.waves !== undefined;
     const inputWaves = patch.waves ?? defaultWaves;
-    const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves));
+    const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves, customWaves));
     return { ...withoutWaves, waves };
 }
 export function buildOceanWaveUniforms(config) {

package/dist/water/index.d.ts

@@ -1,3 +1,3 @@
 export { Ocean, type OceanProps } from "./Ocean.js";
-export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, type OceanColorConfig, type OceanConfig, type OceanDirectionVector, type OceanFoamConfig, type OceanQualityPreset, type OceanWaveConfig, type OceanWaveDirection, type ResolvedOceanColorConfig, type ResolvedOceanConfig, type ResolvedOceanFoamConfig, type ResolvedOceanWaveConfig, } from "./OceanConfig.js";
+export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, DEFAULT_OCEAN_WAVE_SCALE, type OceanColorConfig, type OceanConfig, type OceanDirectionVector, type OceanFoamConfig, type OceanQualityPreset, type OceanWaveConfig, type OceanWaveDirection, type ResolvedOceanColorConfig, type ResolvedOceanConfig, type ResolvedOceanFoamConfig, type ResolvedOceanWaveConfig, } from "./OceanConfig.js";
 export { createOceanMaterial, syncOceanMaterial, type OceanMaterialUniforms, type OceanShaderMaterial, } from "./OceanMaterial.js";

package/dist/water/index.js

@@ -1,3 +1,3 @@
 export { Ocean } from "./Ocean.js";
-export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, } from "./OceanConfig.js";
+export { DEFAULT_OCEAN_CONFIG, MAX_OCEAN_WAVES, OCEAN_QUALITY_PRESETS, buildOceanWaveUniforms, createOceanConfig, DEFAULT_OCEAN_WAVE_SCALE, } from "./OceanConfig.js";
 export { createOceanMaterial, syncOceanMaterial, } from "./OceanMaterial.js";