@jgengine/shell 0.6.0 → 0.7.0

package/dist/pointer/pointerService.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from "three";
+import type { PointerHit, PointerVec3 } from "@jgengine/core/input/pointer";
+export declare const POINTER_ENTITY_KEY = "jgEntityId";
+export declare const POINTER_OBJECT_KEY = "jgObjectId";
+interface PointerDeps {
+    camera: THREE.Camera;
+    scene: THREE.Scene;
+    width: number;
+    height: number;
+}
+export interface PointerService {
+    /** Cast the current cursor into the world; null when the cursor is off-canvas. */
+    worldHit(): PointerHit | null;
+    /** Project a world point to CSS pixels for the marquee / HUD; null before the probe binds. */
+    screenOf(world: PointerVec3): {
+        x: number;
+        y: number;
+    } | null;
+    hasCursor(): boolean;
+    bind(deps: PointerDeps | null): void;
+    setCursor(ndcX: number, ndcY: number, present: boolean): void;
+}
+export declare function createPointerService(): PointerService;
+export {};

package/dist/pointer/pointerService.js

@@ -0,0 +1,68 @@
+import * as THREE from "three";
+export const POINTER_ENTITY_KEY = "jgEntityId";
+export const POINTER_OBJECT_KEY = "jgObjectId";
+function tagOf(object, key) {
+    let cursor = object;
+    while (cursor !== null) {
+        const value = cursor.userData[key];
+        if (typeof value === "string")
+            return value;
+        cursor = cursor.parent;
+    }
+    return null;
+}
+export function createPointerService() {
+    const raycaster = new THREE.Raycaster();
+    const ndc = new THREE.Vector2();
+    const scratch = new THREE.Vector3();
+    const normalMatrix = new THREE.Matrix3();
+    const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+    let deps = null;
+    let cursorPresent = false;
+    return {
+        hasCursor: () => cursorPresent,
+        bind: (next) => {
+            deps = next;
+        },
+        setCursor: (ndcX, ndcY, present) => {
+            ndc.set(ndcX, ndcY);
+            cursorPresent = present;
+        },
+        worldHit() {
+            if (deps === null || !cursorPresent)
+                return null;
+            raycaster.setFromCamera(ndc, deps.camera);
+            const intersects = raycaster.intersectObjects(deps.scene.children, true);
+            for (const hit of intersects) {
+                if (!hit.object.isMesh)
+                    continue;
+                const point = [hit.point.x, hit.point.y, hit.point.z];
+                let normal = [0, 1, 0];
+                if (hit.face !== null && hit.face !== undefined) {
+                    normalMatrix.getNormalMatrix(hit.object.matrixWorld);
+                    scratch.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
+                    normal = [scratch.x, scratch.y, scratch.z];
+                }
+                return {
+                    point,
+                    normal,
+                    entity: tagOf(hit.object, POINTER_ENTITY_KEY),
+                    object: tagOf(hit.object, POINTER_OBJECT_KEY),
+                };
+            }
+            const grounded = raycaster.ray.intersectPlane(groundPlane, scratch);
+            if (grounded === null)
+                return null;
+            return { point: [grounded.x, grounded.y, grounded.z], normal: [0, 1, 0], entity: null, object: null };
+        },
+        screenOf(world) {
+            if (deps === null)
+                return null;
+            scratch.set(world[0], world[1], world[2]).project(deps.camera);
+            return {
+                x: (scratch.x * 0.5 + 0.5) * deps.width,
+                y: (-scratch.y * 0.5 + 0.5) * deps.height,
+            };
+        },
+    };
+}

package/dist/replay/useSessionRecorder.d.ts

@@ -0,0 +1,14 @@
+import { type RecordingBuffer, type RecordingBufferOptions } from "@jgengine/core/sensor/recordingBuffer";
+import type { EntityPosition } from "@jgengine/core/scene/entityStore";
+export interface RecordedPose {
+    position: EntityPosition;
+    rotationY: number;
+}
+/**
+ * Session-recording buffer (#120) for replay / photo mode / kill-cam: records
+ * an entity's pose on game-time every frame into a `RecordingBuffer`, which a
+ * game can then `seek()` to scrub, drive an observer cam ghost, or export a
+ * kill-cam clip. Recording rides on `ctx.time.now()`, so pause/fast-forward
+ * scrub the recording exactly like the live sim.
+ */
+export declare function useSessionRecorder(entityId: string, options?: RecordingBufferOptions): RecordingBuffer<RecordedPose>;

package/dist/replay/useSessionRecorder.js

@@ -0,0 +1,22 @@
+import { useFrame } from "@react-three/fiber";
+import { useMemo } from "react";
+import { createRecordingBuffer } from "@jgengine/core/sensor/recordingBuffer";
+import { useGameContext } from "@jgengine/react/provider";
+/**
+ * Session-recording buffer (#120) for replay / photo mode / kill-cam: records
+ * an entity's pose on game-time every frame into a `RecordingBuffer`, which a
+ * game can then `seek()` to scrub, drive an observer cam ghost, or export a
+ * kill-cam clip. Recording rides on `ctx.time.now()`, so pause/fast-forward
+ * scrub the recording exactly like the live sim.
+ */
+export function useSessionRecorder(entityId, options) {
+    const ctx = useGameContext();
+    const buffer = useMemo(() => createRecordingBuffer(options), []);
+    useFrame(() => {
+        const entity = ctx.scene.entity.get(entityId);
+        if (entity === null)
+            return;
+        buffer.append(ctx.time.now(), { position: entity.position, rotationY: entity.rotationY });
+    });
+    return buffer;
+}

package/dist/structures/PlacementGhost.d.ts

@@ -0,0 +1,8 @@
+import type { PlacementPreview } from "@jgengine/core/world/placementController";
+export interface PlacementGhostProps {
+    preview: PlacementPreview | null;
+    height?: number;
+    validColor?: string;
+    invalidColor?: string;
+}
+export declare function PlacementGhost({ preview, height, validColor, invalidColor, }: PlacementGhostProps): import("react").JSX.Element | null;

package/dist/structures/PlacementGhost.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { quarterTurnsToRotationY } from "@jgengine/core/world/placementController";
+export function PlacementGhost({ preview, height = 1, validColor = "#34d399", invalidColor = "#f87171", }) {
+    const footprint = preview?.footprint;
+    const size = useMemo(() => [footprint?.w ?? 1, height, footprint?.d ?? 1], [footprint?.w, footprint?.d, height]);
+    if (preview === null)
+        return null;
+    const color = preview.valid ? validColor : invalidColor;
+    return (_jsxs("group", { position: [preview.center[0], preview.y, preview.center[1]], "rotation-y": quarterTurnsToRotationY(preview.quarterTurns), children: [_jsxs("mesh", { "position-y": height / 2, children: [_jsx("boxGeometry", { args: size }), _jsx("meshStandardMaterial", { color: color, transparent: true, opacity: 0.35, depthWrite: false, emissive: color, emissiveIntensity: 0.4 })] }), _jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [Math.max(size[0], size[2]) * 0.5, Math.max(size[0], size[2]) * 0.5 + 0.12, 40] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85 })] })] }));
+}

package/dist/structures/index.d.ts

@@ -0,0 +1,2 @@
+export { BuildingBlock, GeneratedBuilding, type BuildingBlockProps, type GeneratedBuildingProps, } from "./GeneratedBuilding.js";
+export { PlacementGhost, type PlacementGhostProps } from "./PlacementGhost.js";

package/dist/structures/index.js

@@ -0,0 +1,2 @@
+export { BuildingBlock, GeneratedBuilding, } from "./GeneratedBuilding.js";
+export { PlacementGhost } from "./PlacementGhost.js";

package/dist/structures.d.ts

@@ -0,0 +1 @@
+export * from "./structures/index.js";

package/dist/structures.js

@@ -0,0 +1 @@
+export * from "./structures/index.js";

package/dist/terrain/CarvedTerrain.d.ts

@@ -0,0 +1,22 @@
+import { type ThreeElements } from "@react-three/fiber";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+import { type FieldGroundOptions } from "./terrainMath.js";
+export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
+    /** The terrain field to mesh — a `CarvableField` renders its craters and mounds. */
+    field: TerrainField;
+    size?: FieldGroundOptions["size"];
+    segments?: FieldGroundOptions["segments"];
+    center?: FieldGroundOptions["center"];
+    colors?: FieldGroundOptions["colors"];
+    heightRange?: FieldGroundOptions["heightRange"];
+    roughness?: number;
+    metalness?: number;
+    /** Bump after a runtime carve/deposit to re-mesh the deformed surface. */
+    epoch?: number;
+}
+/**
+ * Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
+ * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
+ * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+ */
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, roughness, metalness, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { createFieldGroundGeometry } from "./terrainMath.js";
+/**
+ * Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
+ * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
+ * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+ */
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, roughness = 0.95, metalness = 0, receiveShadow = true, epoch = 0, ...meshProps }) {
+    const geometry = useMemo(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [field, size, segments, center, colors, heightRange, epoch]);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    useEffect(() => () => material.dispose(), [material]);
+    return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
+}

package/dist/terrain/EditableGround.d.ts

@@ -0,0 +1,11 @@
+import type { Aabb } from "@jgengine/core/world/geometry";
+import type { EditableTerrain } from "@jgengine/core/world/terraform";
+export interface EditableGroundProps {
+    terrain: Pick<EditableTerrain, "sampleHeight" | "surfaceAt">;
+    bounds: Aabb;
+    segments?: number;
+    version?: number;
+    baseColor?: string;
+    surfaceColors?: Record<string, string>;
+}
+export declare function EditableGround({ terrain, bounds, segments, version, baseColor, surfaceColors, }: EditableGroundProps): import("react").JSX.Element;

package/dist/terrain/EditableGround.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+const DEFAULT_SURFACE_COLORS = {
+    path: "#b8a06a",
+    gravel: "#8d8d84",
+    stone: "#7c7f86",
+    grass: "#4b7f3f",
+};
+export function EditableGround({ terrain, bounds, segments = 96, version = 0, baseColor = "#3f6b3a", surfaceColors = DEFAULT_SURFACE_COLORS, }) {
+    const geometry = useMemo(() => {
+        void version;
+        const width = bounds.maxX - bounds.minX;
+        const depth = bounds.maxZ - bounds.minZ;
+        const geo = new THREE.PlaneGeometry(width, depth, segments, segments);
+        geo.rotateX(-Math.PI / 2);
+        const position = geo.attributes.position;
+        const base = new THREE.Color(baseColor);
+        const colors = new Float32Array(position.count * 3);
+        const cx = (bounds.minX + bounds.maxX) / 2;
+        const cz = (bounds.minZ + bounds.maxZ) / 2;
+        for (let index = 0; index < position.count; index += 1) {
+            const x = position.getX(index) + cx;
+            const z = position.getZ(index) + cz;
+            position.setY(index, terrain.sampleHeight(x, z));
+            const surface = terrain.surfaceAt(x, z);
+            const color = surface !== null && surfaceColors[surface] !== undefined ? new THREE.Color(surfaceColors[surface]) : base;
+            colors[index * 3] = color.r;
+            colors[index * 3 + 1] = color.g;
+            colors[index * 3 + 2] = color.b;
+        }
+        geo.setAttribute("color", new THREE.BufferAttribute(colors, 3));
+        geo.computeVertexNormals();
+        return geo;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [terrain, bounds, segments, version, baseColor, surfaceColors]);
+    return (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 0.95, metalness: 0 }) }));
+}

package/dist/terrain/TerraformBrushCursor.d.ts

@@ -0,0 +1,8 @@
+import type { TerraformMode } from "@jgengine/core/world/terraform";
+export interface TerraformBrushCursorProps {
+    center: readonly [number, number] | null;
+    y?: number;
+    radius: number;
+    mode: TerraformMode;
+}
+export declare function TerraformBrushCursor({ center, y, radius, mode }: TerraformBrushCursorProps): import("react").JSX.Element | null;

package/dist/terrain/TerraformBrushCursor.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const MODE_COLOR = {
+    raise: "#38bdf8",
+    lower: "#fb923c",
+    flatten: "#a3e635",
+    paint: "#e879f9",
+};
+export function TerraformBrushCursor({ center, y = 0.05, radius, mode }) {
+    if (center === null)
+        return null;
+    const color = MODE_COLOR[mode];
+    return (_jsxs("group", { position: [center[0], y, center[1]], children: [_jsxs("mesh", { "rotation-x": -Math.PI / 2, children: [_jsx("ringGeometry", { args: [radius - 0.15, radius, 48] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.9 })] }), _jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": -0.02, children: [_jsx("circleGeometry", { args: [radius, 48] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.14, depthWrite: false })] })] }));
+}

package/dist/terrain/index.d.ts

@@ -1,7 +1,10 @@
+export { CarvedTerrain, type CarvedTerrainProps } from "./CarvedTerrain.js";
 export { GrassField, type GrassFieldProps } from "./GrassField.js";
 export { ProceduralGround, type ProceduralGroundProps } from "./ProceduralGround.js";
+export { EditableGround, type EditableGroundProps } from "./EditableGround.js";
+export { TerraformBrushCursor, type TerraformBrushCursorProps } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, type GrassBladeGeometryOptions, type GrassRange, type ResolvedGrassBladeGeometryOptions, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMaterialHandle, type GrassMaterialOptions, type GrassShaderUniforms, type GrassWindOptions, } from "./grassMaterial.js";
 export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "./random.js";
-export { createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
+export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, type FractalNoiseConfig, type NoiseFieldConfig, type TerrainField, type TerrainNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/index.js

@@ -1,7 +1,10 @@
+export { CarvedTerrain } from "./CarvedTerrain.js";
 export { GrassField } from "./GrassField.js";
 export { ProceduralGround } from "./ProceduralGround.js";
+export { EditableGround } from "./EditableGround.js";
+export { TerraformBrushCursor } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./grassMaterial.js";
 export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
-export { createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
+export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/terrainMath.d.ts

@@ -1,4 +1,4 @@
-import { type NoiseFieldConfig } from "@jgengine/core/world/terrain";
+import { type NoiseFieldConfig, type TerrainField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
 import { type TerrainSeed } from "./random.js";
 export type TerrainArea = number | readonly [width: number, depth: number];
@@ -31,4 +31,17 @@ export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainS
 export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
 export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;
 export declare function createProceduralTerrainSampler(config?: ProceduralTerrainConfig): TerrainHeightSampler;
+export interface FieldGroundOptions {
+    size?: TerrainArea;
+    segments?: number | readonly [x: number, z: number];
+    center?: readonly [x: number, z: number];
+    colors?: TerrainVertexColorOptions;
+    heightRange?: readonly [min: number, max: number];
+}
+/**
+ * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
+ * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
+ * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
+ */
+export declare function createFieldGroundGeometry(field: TerrainField, options?: FieldGroundOptions): THREE.BufferGeometry;
 export declare function createProceduralGroundGeometry(config?: ProceduralTerrainConfig, colors?: TerrainVertexColorOptions): THREE.BufferGeometry;

package/dist/terrain/terrainMath.js

@@ -23,6 +23,86 @@ export function toNoiseFieldConfig(config = {}) {
 export function createProceduralTerrainSampler(config = {}) {
     return noiseField(toNoiseFieldConfig(config)).sampleHeight;
 }
+/**
+ * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
+ * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
+ * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
+ */
+export function createFieldGroundGeometry(field, options = {}) {
+    const size = resolveTerrainSize(options.size);
+    const segments = resolveTerrainSegments(options.segments);
+    const [cx, cz] = options.center ?? [0, 0];
+    return buildGroundGeometry(size, segments, (x, z) => field.sampleHeight(x, z), {
+        colors: options.colors ?? {},
+        center: [cx, cz],
+        heightRange: options.heightRange,
+    });
+}
+function buildGroundGeometry(size, segments, sampler, opts) {
+    const colors = opts.colors;
+    const vertexCountX = segments.x + 1;
+    const vertexCountZ = segments.z + 1;
+    const positions = new Float32Array(vertexCountX * vertexCountZ * 3);
+    const uvs = new Float32Array(vertexCountX * vertexCountZ * 2);
+    const colorValues = new Float32Array(vertexCountX * vertexCountZ * 3);
+    const indices = new Uint32Array(segments.x * segments.z * 6);
+    const low = new THREE.Color(colors.low ?? "#30402c");
+    const high = new THREE.Color(colors.high ?? "#7f8b50");
+    const waterline = colors.waterline === undefined ? null : new THREE.Color(colors.waterline);
+    const minHeight = opts.heightRange?.[0] ?? -3;
+    const maxHeight = opts.heightRange?.[1] ?? 3;
+    let index = 0;
+    let uvIndex = 0;
+    let colorIndex = 0;
+    for (let zIndex = 0; zIndex < vertexCountZ; zIndex += 1) {
+        const v = zIndex / segments.z;
+        const z = opts.center[1] + (v - 0.5) * size.depth;
+        for (let xIndex = 0; xIndex < vertexCountX; xIndex += 1) {
+            const u = xIndex / segments.x;
+            const x = opts.center[0] + (u - 0.5) * size.width;
+            const y = sampler(x, z);
+            positions[index] = x;
+            positions[index + 1] = y;
+            positions[index + 2] = z;
+            uvs[uvIndex] = u;
+            uvs[uvIndex + 1] = v;
+            const blend = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            const color = low.clone().lerp(high, blend);
+            if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
+                color.lerp(waterline, 0.65);
+            colorValues[colorIndex] = color.r;
+            colorValues[colorIndex + 1] = color.g;
+            colorValues[colorIndex + 2] = color.b;
+            index += 3;
+            uvIndex += 2;
+            colorIndex += 3;
+        }
+    }
+    let triangleIndex = 0;
+    for (let zIndex = 0; zIndex < segments.z; zIndex += 1) {
+        for (let xIndex = 0; xIndex < segments.x; xIndex += 1) {
+            const a = zIndex * vertexCountX + xIndex;
+            const b = a + 1;
+            const c = a + vertexCountX;
+            const d = c + 1;
+            indices[triangleIndex] = a;
+            indices[triangleIndex + 1] = c;
+            indices[triangleIndex + 2] = b;
+            indices[triangleIndex + 3] = b;
+            indices[triangleIndex + 4] = c;
+            indices[triangleIndex + 5] = d;
+            triangleIndex += 6;
+        }
+    }
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+    geometry.setAttribute("uv", new THREE.BufferAttribute(uvs, 2));
+    geometry.setAttribute("color", new THREE.BufferAttribute(colorValues, 3));
+    geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+    return geometry;
+}
 export function createProceduralGroundGeometry(config = {}, colors = {}) {
     const size = resolveTerrainSize(config.size);
     const segments = resolveTerrainSegments(config.segments);

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)",
+        } }));
+}