@jgengine/core 0.10.0 → 0.11.0

package/dist/scene/sceneOwnership.js

@@ -0,0 +1,179 @@
+/**
+ * Scene ownership boundary — gives every editor-visible object an explicit
+ * provenance and a single verdict (expose / bake / reject) so the editor never
+ * presents unauthored content as broken authored content.
+ *
+ * The product invariant is "author world content in the editor": the scene
+ * document is the source of truth. Runtime code, procedural generators, and
+ * simulation still put objects in front of the player that the document never
+ * described. This module classifies each such object by where it comes from and
+ * decides whether the editor may author it, may offer to bake it into the
+ * document, or must reject it as read-only runtime content — with a diagnostic
+ * that explains the decision. Genuinely runtime-only content is then declared
+ * with a reason rather than silently tolerated or exempted by game name.
+ *
+ * Everything here is plain serializable data and pure functions, so a
+ * {@link SceneOwnershipManifest} round-trips through JSON and the verdict for an
+ * object is deterministic given its declaration.
+ */
+/** Current {@link SceneOwnershipManifest} schema version. */
+export const SCENE_OWNERSHIP_MANIFEST_VERSION = 1;
+/**
+ * Resolve one declaration into a single boundary verdict.
+ *
+ * - `authored` and `generated` provenance -> **expose** (generated objects are
+ *   read-only; edit their source document object).
+ * - `runtime`/`transient` with a `bake` capability -> **bake** (offer import).
+ * - `runtime`/`transient` without `bake` -> **reject** (read-only); a missing
+ *   `reason` marks it a boundary violation — content bypassing the document with
+ *   no authored home, no way to bake, and no declared justification.
+ *
+ * @capability scene-ownership classify an editor-visible object as expose/bake/reject with a diagnostic
+ */
+export function classifyOwnership(declaration) {
+    const { provenance, capabilities, reason } = declaration;
+    const kind = provenance.kind;
+    if (kind === "authored") {
+        return {
+            decision: "expose",
+            provenance: kind,
+            readOnly: false,
+            bakeable: false,
+            reason: `authored document object "${provenance.documentId}"`,
+        };
+    }
+    if (kind === "generated") {
+        return {
+            decision: "expose",
+            provenance: kind,
+            readOnly: true,
+            bakeable: false,
+            reason: `generated from authored object "${provenance.sourceDocumentId}"; edit the source`,
+        };
+    }
+    const canBake = capabilities?.bake === true;
+    if (canBake) {
+        return {
+            decision: "bake",
+            provenance: kind,
+            readOnly: true,
+            bakeable: true,
+            reason: reason ?? `runtime provider "${provenance.providerId}" can bake this into the document`,
+        };
+    }
+    const hasReason = reason !== undefined && reason.trim() !== "";
+    const violation = hasReason
+        ? undefined
+        : `${kind} object "${provenance.instanceId}" from provider "${provenance.providerId}" has no authored ` +
+            `document entry, no bake capability, and no declared reason — it bypasses the scene-ownership boundary`;
+    return {
+        decision: "reject",
+        provenance: kind,
+        readOnly: true,
+        bakeable: false,
+        reason: hasReason ? reason : `runtime-only content owned by provider "${provenance.providerId}"`,
+        violation,
+    };
+}
+/** Stable id string for a provenance — used to key diagnostics deterministically. */
+function provenanceKey(provenance) {
+    switch (provenance.kind) {
+        case "authored":
+            return `authored:${provenance.documentId}`;
+        case "generated":
+            return `generated:${provenance.sourceDocumentId}/${provenance.instanceId}`;
+        default:
+            return `${provenance.kind}:${provenance.providerId}/${provenance.instanceId}`;
+    }
+}
+/**
+ * Stable identity string for a provenance (e.g. `runtime:town/building-3`), suitable
+ * for keying an object in an editor tree or a diagnostics table.
+ *
+ * @capability scene-ownership derive a stable object key from its provenance
+ */
+export function ownershipKey(provenance) {
+    return provenanceKey(provenance);
+}
+/**
+ * Audit a keyed set of declarations and return one diagnostic per object that
+ * breaks the boundary contract (a `reject` verdict carrying a `violation`).
+ * Deterministic: diagnostics come back in the iteration order of `entries`.
+ *
+ * @capability scene-ownership audit editor-visible objects and report boundary violations
+ */
+export function collectOwnershipDiagnostics(entries) {
+    const out = [];
+    for (const [key, declaration] of entries) {
+        const verdict = classifyOwnership(declaration);
+        if (verdict.violation !== undefined) {
+            out.push({
+                key,
+                provenance: verdict.provenance,
+                decision: verdict.decision,
+                message: `${key}: ${verdict.violation}`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Audit every declaration in a manifest, keying diagnostics by each object's
+ * provenance id. An empty result means the manifest declares all of its content
+ * cleanly — every object is authored, generated, bakeable, or a reasoned
+ * runtime/transient object.
+ *
+ * @capability scene-ownership audit a whole ownership manifest for boundary violations
+ */
+export function auditManifest(manifest) {
+    return collectOwnershipDiagnostics(manifest.declarations.map((declaration) => [provenanceKey(declaration.provenance), declaration]));
+}
+function isProvenance(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    switch (record.kind) {
+        case "authored":
+            return typeof record.documentId === "string";
+        case "generated":
+            return typeof record.sourceDocumentId === "string" && typeof record.instanceId === "string";
+        case "runtime":
+        case "transient":
+            return typeof record.providerId === "string" && typeof record.instanceId === "string";
+        default:
+            return false;
+    }
+}
+function isDeclaration(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (!isProvenance(record.provenance))
+        return false;
+    if (record.reason !== undefined && typeof record.reason !== "string")
+        return false;
+    if (record.capabilities !== undefined && (typeof record.capabilities !== "object" || record.capabilities === null)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Narrow unknown parsed JSON to a {@link SceneOwnershipManifest}. Structural only —
+ * verifies the version, the declarations array, and each declaration's provenance
+ * shape; it does not judge whether declarations satisfy the boundary (use
+ * {@link auditManifest} for that).
+ *
+ * @capability scene-ownership validate a serialized ownership manifest loaded from disk
+ */
+export function isSceneOwnershipManifest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (record.version !== SCENE_OWNERSHIP_MANIFEST_VERSION)
+        return false;
+    if (record.provider !== undefined && typeof record.provider !== "string")
+        return false;
+    if (!Array.isArray(record.declarations))
+        return false;
+    return record.declarations.every(isDeclaration);
+}

package/dist/scene/selectionBookmarks.d.ts

@@ -0,0 +1,93 @@
+import type { SelectionSet } from "./selection.js";
+/**
+ * The serializable shape of a {@link SelectionBookmarks} store: each key maps to
+ * its ordered, deduplicated id list. Plain data — safe to persist in a save file
+ * or replicate over the wire, and the exact input {@link createSelectionBookmarks}
+ * restores.
+ */
+export interface SelectionBookmarkSnapshot {
+    bookmarks: Record<string, readonly string[]>;
+}
+/** Outcome of a {@link SelectionBookmarks.prune} pass — what the validity predicate removed. */
+export interface SelectionPruneResult {
+    /** Ids dropped from at least one bookmark because the predicate rejected them. */
+    removedIds: string[];
+    /** Bookmark keys deleted because pruning emptied them. */
+    clearedKeys: string[];
+}
+/**
+ * A generic, keyed store of saved id sets ("bookmarks") over stable string ids —
+ * the reusable layer under RTS control groups, camera bookmarks, saved squads,
+ * editor selection presets, and accessibility recall. It owns storage only:
+ * binding, recall, enumeration, pruning, and serialization. It never touches the
+ * active {@link SelectionSet} or the camera — replacement/merge and focus stay
+ * caller hooks (see {@link recallSelectionBookmark}) so one store serves any
+ * genre, input scheme, or focus policy.
+ *
+ * Keys are opaque strings, so numbered control groups (`"1"`…`"9"`), named
+ * bookmarks (`"home"`, `"base"`), or per-owner namespaces all coexist. Each
+ * bookmark preserves insertion order and dedupes, matching {@link SelectionSet}.
+ */
+export interface SelectionBookmarks {
+    /** Replace the set under `key` with `ids` (ordered, deduped). Binding an empty set removes the key, so `has(key)` is then false and it drops out of {@link serialize}. */
+    bind(key: string, ids: Iterable<string>): void;
+    /** Add `ids` to the set under `key` (creating it if absent), skipping ones already present so order is stable. */
+    append(key: string, ids: Iterable<string>): void;
+    /** Remove `ids` from the set under `key`; if that empties the set, the key is deleted. No-op when the key is absent. */
+    remove(key: string, ids: Iterable<string>): void;
+    /** The ordered ids saved under `key`, or an empty array when the key is absent. The returned array is a fresh copy — mutating it never touches the store. */
+    recall(key: string): string[];
+    /** True when `key` holds a non-empty set. */
+    has(key: string): boolean;
+    /** Delete `key`; returns true when a set was removed. */
+    clear(key: string): boolean;
+    /** Delete every bookmark. */
+    clearAll(): void;
+    /** All bookmark keys in insertion order. */
+    keys(): string[];
+    /** Count of ids saved under `key`, or 0 when absent. */
+    size(key: string): number;
+    /**
+     * Drop every id the `isValid` predicate rejects from all bookmarks — the seam
+     * for destroyed entities, cross-scene ids, and ownership changes: the caller
+     * supplies validity, the store applies it. Bookmarks emptied by pruning are
+     * removed. Returns what was removed so callers can surface it.
+     */
+    prune(isValid: (id: string) => boolean): SelectionPruneResult;
+    /** A plain-data copy of every bookmark — the exact input {@link createSelectionBookmarks} restores. */
+    serialize(): SelectionBookmarkSnapshot;
+}
+/**
+ * Create a keyed bookmark store, optionally restored from a {@link serialize}
+ * snapshot. Restoration re-dedupes and drops empty sets, so a hand-authored or
+ * migrated snapshot always normalizes to the same invariants a live store holds.
+ *
+ * @capability selection-bookmarks keyed saved-set store (RTS control groups, camera bookmarks, saved squads) with prune + serialize
+ */
+export declare function createSelectionBookmarks(snapshot?: SelectionBookmarkSnapshot): SelectionBookmarks;
+/** How a recalled bookmark folds into the active selection. */
+export type BookmarkRecallMode = "replace" | "merge";
+/** Caller hooks for {@link recallSelectionBookmark} — kept out of the store so focus and validity stay genre-owned. */
+export interface RecallBookmarkOptions {
+    /** `"replace"` (default) swaps the active selection for the bookmark; `"merge"` unions it in. */
+    mode?: BookmarkRecallMode;
+    /**
+     * Validity predicate applied to the bookmark before it reaches the selection —
+     * stale ids (destroyed entities, wrong scene, lost ownership) are pruned from
+     * the stored bookmark in place, so recall self-heals. Omit to recall verbatim.
+     */
+    isValid?: (id: string) => boolean;
+    /** Focus hook fired with the surviving ids (e.g. center/follow the camera). Never called when recall yields nothing. */
+    onFocus?: (ids: readonly string[]) => void;
+}
+/**
+ * Compose a bookmark recall onto an active {@link SelectionSet}: optionally prune
+ * stale ids (updating the stored bookmark), fold the survivors into the selection
+ * by `mode`, then fire the caller's focus hook. This is the one place the store,
+ * the selection, and the camera meet — kept as an explicit helper, not a store
+ * side effect, so games opt into the exact replacement/merge and focus policy
+ * they want. Returns the surviving ids that were applied.
+ *
+ * @capability selection-bookmark-recall fold a saved set into the active selection with stale-ref pruning and a caller focus hook
+ */
+export declare function recallSelectionBookmark(bookmarks: SelectionBookmarks, key: string, selection: SelectionSet, options?: RecallBookmarkOptions): string[];

package/dist/scene/selectionBookmarks.js

@@ -0,0 +1,122 @@
+function dedupe(ids) {
+    const out = [];
+    const seen = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Create a keyed bookmark store, optionally restored from a {@link serialize}
+ * snapshot. Restoration re-dedupes and drops empty sets, so a hand-authored or
+ * migrated snapshot always normalizes to the same invariants a live store holds.
+ *
+ * @capability selection-bookmarks keyed saved-set store (RTS control groups, camera bookmarks, saved squads) with prune + serialize
+ */
+export function createSelectionBookmarks(snapshot) {
+    const groups = new Map();
+    if (snapshot !== undefined) {
+        for (const [key, ids] of Object.entries(snapshot.bookmarks)) {
+            const list = dedupe(ids);
+            if (list.length > 0)
+                groups.set(key, list);
+        }
+    }
+    return {
+        bind(key, ids) {
+            const list = dedupe(ids);
+            if (list.length === 0)
+                groups.delete(key);
+            else
+                groups.set(key, list);
+        },
+        append(key, ids) {
+            const existing = groups.get(key);
+            if (existing === undefined) {
+                const list = dedupe(ids);
+                if (list.length > 0)
+                    groups.set(key, list);
+                return;
+            }
+            const seen = new Set(existing);
+            for (const id of ids) {
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                existing.push(id);
+            }
+        },
+        remove(key, ids) {
+            const existing = groups.get(key);
+            if (existing === undefined)
+                return;
+            const drop = new Set(ids);
+            const next = existing.filter((id) => !drop.has(id));
+            if (next.length === 0)
+                groups.delete(key);
+            else
+                groups.set(key, next);
+        },
+        recall(key) {
+            const existing = groups.get(key);
+            return existing === undefined ? [] : [...existing];
+        },
+        has: (key) => (groups.get(key)?.length ?? 0) > 0,
+        clear: (key) => groups.delete(key),
+        clearAll: () => groups.clear(),
+        keys: () => [...groups.keys()],
+        size: (key) => groups.get(key)?.length ?? 0,
+        prune(isValid) {
+            const removedIds = new Set();
+            const clearedKeys = [];
+            for (const [key, list] of [...groups]) {
+                const next = list.filter((id) => {
+                    const keep = isValid(id);
+                    if (!keep)
+                        removedIds.add(id);
+                    return keep;
+                });
+                if (next.length === list.length)
+                    continue;
+                if (next.length === 0) {
+                    groups.delete(key);
+                    clearedKeys.push(key);
+                }
+                else {
+                    groups.set(key, next);
+                }
+            }
+            return { removedIds: [...removedIds], clearedKeys };
+        },
+        serialize: () => ({
+            bookmarks: Object.fromEntries([...groups].map(([key, list]) => [key, [...list]])),
+        }),
+    };
+}
+/**
+ * Compose a bookmark recall onto an active {@link SelectionSet}: optionally prune
+ * stale ids (updating the stored bookmark), fold the survivors into the selection
+ * by `mode`, then fire the caller's focus hook. This is the one place the store,
+ * the selection, and the camera meet — kept as an explicit helper, not a store
+ * side effect, so games opt into the exact replacement/merge and focus policy
+ * they want. Returns the surviving ids that were applied.
+ *
+ * @capability selection-bookmark-recall fold a saved set into the active selection with stale-ref pruning and a caller focus hook
+ */
+export function recallSelectionBookmark(bookmarks, key, selection, options = {}) {
+    const { mode = "replace", isValid, onFocus } = options;
+    if (isValid !== undefined)
+        bookmarks.prune(isValid);
+    const ids = bookmarks.recall(key);
+    if (mode === "replace")
+        selection.replace(ids);
+    else
+        for (const id of ids)
+            selection.add(id);
+    if (ids.length > 0)
+        onFocus?.(ids);
+    return ids;
+}

package/dist/scene/vehicleSeat.d.ts

@@ -0,0 +1,68 @@
+import { MountController, type MountSeat, type RideableConfig } from "./mount.js";
+/** World-space `[x, y, z]` for a vehicle's current position. */
+export type VehiclePosition = readonly [number, number, number];
+/** A vehicle's world-space position and heading, used for {@link VehicleSeats.exit}'s dismount placement math. */
+export interface VehiclePose {
+    position: VehiclePosition;
+    rotationY: number;
+}
+/** Options for {@link VehicleSeats.enter}. */
+export interface EnterVehicleOptions {
+    /** Specific seat to board; omit to take the first free control seat, else the first free seat. */
+    seatId?: string;
+}
+/** Movement-lock patch for `entities.update(riderId, { movement: { ...current, ...patch } })` (#286.gameplay `movement.frozen`). */
+export interface RiderMovementPatch {
+    frozen: boolean;
+}
+/** Result of {@link VehicleSeats.enter} — the resolved seat plus the camera/drive/movement patches to apply. */
+export type EnterVehicleResult = {
+    ok: true;
+    seat: MountSeat;
+    /** Feed straight into `ctx.camera.follow(...)` — the vehicle while a control seat is taken, else the rider's own id. */
+    cameraTarget: string;
+    /** Entity this rider's axis input should now drive (`scene/mount`'s `driveTarget`); `null` for a passenger seat. */
+    driveTarget: string | null;
+    riderMovementPatch: RiderMovementPatch;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Result of {@link VehicleSeats.exit} — the side-door placement plus the camera/movement patches to apply. */
+export type ExitVehicleResult = {
+    ok: true;
+    vehicleId: string;
+    /** Where to `setPose` the rider — alongside the vehicle's side door, facing its heading. */
+    placement: VehiclePose;
+    cameraTarget: string;
+    riderMovementPatch: RiderMovementPatch;
+} | {
+    ok: false;
+    reason: "not_seated";
+};
+/** Where {@link VehicleSeats.exit} steps the rider out, relative to the vehicle's heading. */
+export interface DismountOffset {
+    /** Lateral distance from the vehicle's centerline; default 2.2. */
+    distance?: number;
+    /** Which side of the vehicle to step out on, relative to its heading; default `"right"`. */
+    side?: "left" | "right";
+}
+/**
+ * Composes `scene/mount`'s control-transfer bookkeeping with the seat/camera/movement-mode transition
+ * every enter/exit-vehicle flow needs (#533.2): boarding resolves a free seat and reports the camera
+ * target, drive target, and rider movement-lock patch in one call; leaving computes a side-door
+ * placement next to the vehicle and reports the same triad in reverse. Pure — no entity/camera side
+ * effects — the caller applies `riderMovementPatch`/`placement`/`cameraTarget` via its own `ctx`.
+ */
+export declare class VehicleSeats {
+    private readonly controller;
+    constructor(controller?: MountController);
+    register(config: RideableConfig): void;
+    enter(riderId: string, vehicleId: string, options?: EnterVehicleOptions): EnterVehicleResult;
+    exit(riderId: string, vehiclePose: VehiclePose, offset?: DismountOffset): ExitVehicleResult;
+    isSeated(riderId: string): boolean;
+    driverOf(vehicleId: string): string | null;
+    get mounts(): MountController;
+}
+/** Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy. */
+export declare function createVehicleSeats(controller?: MountController): VehicleSeats;

package/dist/scene/vehicleSeat.js

@@ -0,0 +1,59 @@
+import { createMountController, MountController } from "./mount.js";
+/**
+ * Composes `scene/mount`'s control-transfer bookkeeping with the seat/camera/movement-mode transition
+ * every enter/exit-vehicle flow needs (#533.2): boarding resolves a free seat and reports the camera
+ * target, drive target, and rider movement-lock patch in one call; leaving computes a side-door
+ * placement next to the vehicle and reports the same triad in reverse. Pure — no entity/camera side
+ * effects — the caller applies `riderMovementPatch`/`placement`/`cameraTarget` via its own `ctx`.
+ */
+export class VehicleSeats {
+    controller;
+    constructor(controller) {
+        this.controller = controller ?? createMountController();
+    }
+    register(config) {
+        this.controller.register(config);
+    }
+    enter(riderId, vehicleId, options = {}) {
+        const result = this.controller.mount(riderId, vehicleId, options.seatId);
+        if (!result.ok)
+            return { ok: false, reason: result.reason };
+        return {
+            ok: true,
+            seat: result.seat,
+            cameraTarget: this.controller.cameraTarget(riderId),
+            driveTarget: this.controller.driveTarget(riderId),
+            riderMovementPatch: { frozen: true },
+        };
+    }
+    exit(riderId, vehiclePose, offset = {}) {
+        const vehicleId = this.controller.dismount(riderId);
+        if (vehicleId === null)
+            return { ok: false, reason: "not_seated" };
+        const distance = offset.distance ?? 2.2;
+        const sign = offset.side === "left" ? -1 : 1;
+        const side = vehiclePose.rotationY + (Math.PI / 2) * sign;
+        const x = vehiclePose.position[0] + Math.sin(side) * distance;
+        const z = vehiclePose.position[2] + Math.cos(side) * distance;
+        return {
+            ok: true,
+            vehicleId,
+            placement: { position: [x, vehiclePose.position[1], z], rotationY: vehiclePose.rotationY },
+            cameraTarget: riderId,
+            riderMovementPatch: { frozen: false },
+        };
+    }
+    isSeated(riderId) {
+        return this.controller.isSeated(riderId);
+    }
+    driverOf(vehicleId) {
+        return this.controller.driver(vehicleId);
+    }
+    get mounts() {
+        return this.controller;
+    }
+}
+/** Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy. */
+export function createVehicleSeats(controller) {
+    return new VehicleSeats(controller);
+}

package/dist/sensor/concealment.d.ts

@@ -1,5 +1,7 @@
 export type ColorHex = string;
+/** @internal */
 export declare function colorDistance(a: ColorHex, b: ColorHex): number;
+/** @internal */
 export declare function concealmentScore(entityColors: readonly ColorHex[], backgroundColors: readonly ColorHex[]): number;
 export interface ConcealmentTarget {
     id: string;
@@ -16,6 +18,7 @@ export interface ConcealmentSensor {
     tick(targets: readonly ConcealmentTarget[], dt: number): ConcealmentSample[];
     reset(id?: string): void;
 }
+/** @internal */
 export declare function createConcealmentSensor(config?: {
     threshold?: number;
 }): ConcealmentSensor;

package/dist/sensor/concealment.js

@@ -13,10 +13,12 @@ function redmean(a, b) {
     return Math.sqrt((2 + rmean / 256) * dr * dr + 4 * dg * dg + (2 + (255 - rmean) / 256) * db * db);
 }
 const REDMEAN_MAX = redmean([0, 0, 0], [255, 255, 255]);
+/** @internal */
 export function colorDistance(a, b) {
     const distance = redmean(parseHex(a), parseHex(b));
     return REDMEAN_MAX === 0 ? 0 : Math.min(1, distance / REDMEAN_MAX);
 }
+/** @internal */
 export function concealmentScore(entityColors, backgroundColors) {
     if (entityColors.length === 0 || backgroundColors.length === 0)
         return 0;
@@ -32,6 +34,7 @@ export function concealmentScore(entityColors, backgroundColors) {
     }
     return 1 - total / entityColors.length;
 }
+/** @internal */
 export function createConcealmentSensor(config) {
     const threshold = config?.threshold ?? 0.7;
     const dwell = new Map();

package/dist/sensor/freezeMonitor.d.ts

@@ -11,6 +11,7 @@ export interface FreezeMonitor {
     tick(subjects: readonly FreezeSubject[], frozenIds: ReadonlySet<string>, dt: number): FreezeViolation[];
     reset(id?: string): void;
 }
+/** @internal */
 export declare function createFreezeMonitor(config?: {
     toleranceSpeed?: number;
     graceSeconds?: number;

package/dist/sensor/freezeMonitor.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createFreezeMonitor(config) {
     const toleranceSpeed = config?.toleranceSpeed ?? 0.05;
     const graceSeconds = config?.graceSeconds ?? 0;

package/dist/sensor/frustumSensor.d.ts

@@ -26,7 +26,8 @@ export interface FrustumProjection {
  * Project a world point into the camera's view. Pure geometry — no three.js —
  * so a game can run "is this framed?" checks headlessly (photo-mode scoring,
  * server-side kill-cam validation) as well as from the live render camera.
- */
+  * @internal
+  */
 export declare function projectToView(camera: FrustumCamera, point: EntityPosition): FrustumProjection;
 export interface FramingConfig {
     /** World-unit distance from camera that reads as "ideally framed" size. Default 6. */
@@ -36,7 +37,9 @@ export interface FramingConfig {
     /** Weight of subject size (distance-to-ideal) in the framing score. Default 0.4. */
     sizeWeight?: number;
 }
-/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection. */
+/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection.
+ * @internal
+ */
 export declare function framingScore(projection: FrustumProjection, config?: FramingConfig): number;
 export interface FrustumSample {
     id: string;
@@ -56,5 +59,6 @@ export interface FrustumSensor {
  * A view-frustum sensor on a held camera object: which entities are in frame,
  * how well framed they are, and how long they've stayed on-screen (photo-mode
  * "is this subject framed", Content Warning-style monster-filming scoring).
- */
+  * @internal
+  */
 export declare function createFrustumSensor(config?: FramingConfig): FrustumSensor;

package/dist/sensor/frustumSensor.js

@@ -19,7 +19,8 @@ const WORLD_UP = [0, 1, 0];
  * Project a world point into the camera's view. Pure geometry — no three.js —
  * so a game can run "is this framed?" checks headlessly (photo-mode scoring,
  * server-side kill-cam validation) as well as from the live render camera.
- */
+  * @internal
+  */
 export function projectToView(camera, point) {
     const forward = normalize(subtract(camera.lookAt, camera.position));
     const relative = subtract(point, camera.position);
@@ -47,7 +48,9 @@ export function projectToView(camera, point) {
     const inView = Math.abs(screenX) <= 1 && Math.abs(screenY) <= 1;
     return { inView, distance, screenX, screenY };
 }
-/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection. */
+/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection.
+ * @internal
+ */
 export function framingScore(projection, config) {
     if (!projection.inView)
         return 0;
@@ -65,7 +68,8 @@ export function framingScore(projection, config) {
  * A view-frustum sensor on a held camera object: which entities are in frame,
  * how well framed they are, and how long they've stayed on-screen (photo-mode
  * "is this subject framed", Content Warning-style monster-filming scoring).
- */
+  * @internal
+  */
 export function createFrustumSensor(config) {
     const dwell = new Map();
     return {

package/dist/sensor/hiddenStateProbe.d.ts

@@ -25,7 +25,10 @@ export interface SensorReading {
  * `proximityPrompt` (a UI affordance), this reads world state the player has no
  * other way to see — the strongest in-range reading wins, mirroring how a real
  * handheld sensor needle settles on the loudest nearby source.
- */
+  * @internal
+  */
 export declare function probeHiddenState(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading | null;
-/** All in-range readings for `variableId`, strongest first. */
+/** All in-range readings for `variableId`, strongest first.
+ * @internal
+ */
 export declare function probeHiddenStateAll(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading[];

package/dist/sensor/hiddenStateProbe.js

@@ -12,12 +12,15 @@ function strengthAt(distance, range, falloff) {
  * `proximityPrompt` (a UI affordance), this reads world state the player has no
  * other way to see — the strongest in-range reading wins, mirroring how a real
  * handheld sensor needle settles on the loudest nearby source.
- */
+  * @internal
+  */
 export function probeHiddenState(origin, sources, options) {
     const readings = probeHiddenStateAll(origin, sources, options);
     return readings.length === 0 ? null : readings[0];
 }
-/** All in-range readings for `variableId`, strongest first. */
+/** All in-range readings for `variableId`, strongest first.
+ * @internal
+ */
 export function probeHiddenStateAll(origin, sources, options) {
     const { range, variableId, falloff = "linear" } = options;
     const readings = [];