@jgengine/core 0.10.0 → 0.12.0

package/dist/scene/sceneOwnership.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+/** Where an editor-visible object comes from — its authorship provenance. */
+export type SceneProvenanceKind = "authored" | "generated" | "runtime" | "transient";
+/** A first-class entry in the scene document — the editor fully owns and persists it. */
+export interface AuthoredProvenance {
+    readonly kind: "authored";
+    /** Stable id of the object in the scene document. */
+    readonly documentId: string;
+}
+/**
+ * An object derived from an authored document object — instances scattered from a
+ * painted layer, walls extruded from an authored footprint. Edits belong on the
+ * source object, not the generated instance.
+ */
+export interface GeneratedProvenance {
+    readonly kind: "generated";
+    /** Document object this instance was generated from. */
+    readonly sourceDocumentId: string;
+    /** Stable id of the generated instance. */
+    readonly instanceId: string;
+}
+/**
+ * An object owned entirely by runtime or procedural code with no document entry.
+ * Not authorable unless its provider can bake it into schema-valid authored data.
+ */
+export interface RuntimeProvenance {
+    readonly kind: "runtime";
+    /** Stable id of the runtime provider that owns this object. */
+    readonly providerId: string;
+    /** Stable id of the object within the provider. */
+    readonly instanceId: string;
+}
+/** An ephemeral simulation object — a spawned agent, projectile, or particle that never persists. */
+export interface TransientProvenance {
+    readonly kind: "transient";
+    /** Stable id of the runtime provider that spawned this object. */
+    readonly providerId: string;
+    /** Stable id of the object within the provider. */
+    readonly instanceId: string;
+}
+/** The provenance of one editor-visible object — authored, generated, runtime, or transient. */
+export type SceneProvenance = AuthoredProvenance | GeneratedProvenance | RuntimeProvenance | TransientProvenance;
+/** What a provider lets the editor do with one of its objects. Absent flags default to `false`. */
+export interface ProviderCapabilities {
+    /** Editor may select the object. */
+    readonly select?: boolean;
+    /** Editor may focus/frame the camera on it. */
+    readonly focus?: boolean;
+    /** Editor may hide it from the viewport. */
+    readonly hide?: boolean;
+    /** Provider can emit schema-valid authored data (stable ids, undoable) to bake this object into the document. */
+    readonly bake?: boolean;
+}
+/** A provider's explicit ownership declaration for one editor-visible object. */
+export interface SceneOwnershipDeclaration {
+    /** Where the object comes from. */
+    readonly provenance: SceneProvenance;
+    /** What the provider lets the editor do with it. */
+    readonly capabilities?: ProviderCapabilities;
+    /**
+     * Human-readable justification for why this object is not an authored document
+     * object. Required for `runtime`/`transient` provenance without a `bake`
+     * capability — its absence is a boundary violation (unowned content
+     * masquerading as scene content).
+     */
+    readonly reason?: string;
+}
+/** The boundary's resolution for one object. */
+export type OwnershipDecision = "expose" | "bake" | "reject";
+/** The full verdict for one object: its decision plus the flags and diagnostic the editor needs to act on it. */
+export interface OwnershipVerdict {
+    /** `expose` (authorable), `bake` (offer import), or `reject` (read-only runtime content). */
+    readonly decision: OwnershipDecision;
+    /** The provenance kind that produced this decision. */
+    readonly provenance: SceneProvenanceKind;
+    /** The editor must present the object read-only — authoring edits are not accepted. */
+    readonly readOnly: boolean;
+    /** A "bake/import to document" action should be offered for this object. */
+    readonly bakeable: boolean;
+    /** Diagnostic string the editor can surface next to the object. */
+    readonly reason: string;
+    /** Set when the declaration breaks the ownership contract; the editor and content gate should flag it. */
+    readonly violation?: string;
+}
+/** One boundary problem found while auditing a set of declarations. */
+export interface OwnershipDiagnostic {
+    /** Key identifying the offending object (its provenance id when audited from a manifest). */
+    readonly key: string;
+    /** Provenance kind of the offending object. */
+    readonly provenance: SceneProvenanceKind;
+    /** The decision the object resolved to (always `reject` for a violation). */
+    readonly decision: OwnershipDecision;
+    /** Human-readable violation message. */
+    readonly message: string;
+}
+/** Serializable record of a world's ownership declarations — persisted next to the scene document or shipped by a game. */
+export interface SceneOwnershipManifest {
+    /** Schema version; currently {@link SCENE_OWNERSHIP_MANIFEST_VERSION}. */
+    readonly version: 1;
+    /** Optional label for the provider/world these declarations describe. */
+    readonly provider?: string;
+    /** The per-object ownership declarations. */
+    readonly declarations: readonly SceneOwnershipDeclaration[];
+}
+/** Current {@link SceneOwnershipManifest} schema version. */
+export declare 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 declare function classifyOwnership(declaration: SceneOwnershipDeclaration): OwnershipVerdict;
+/**
+ * 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 declare function ownershipKey(provenance: SceneProvenance): string;
+/**
+ * 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 declare function collectOwnershipDiagnostics(entries: Iterable<readonly [string, SceneOwnershipDeclaration]>): OwnershipDiagnostic[];
+/**
+ * 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 declare function auditManifest(manifest: SceneOwnershipManifest): OwnershipDiagnostic[];
+/**
+ * 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 declare function isSceneOwnershipManifest(value: unknown): value is SceneOwnershipManifest;

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/sceneRaycast.js

@@ -1,4 +1,5 @@
 import { colliderBounds, colliderWorldCenter, defaultEntityColliders, defaultObjectColliders, resolveColliders, } from "./colliders.js";
+import { raycastCollisionMesh } from "./collisionMesh.js";
 import { intersectAabb, normalizeDirection } from "./objectQuery.js";
 function excluded(exclude, id) {
     if (exclude === undefined)
@@ -54,6 +55,20 @@ function rayHitsCollider(origin, direction, maxDistance, collider, position, rot
             ],
         };
     }
+    if (collider.shape.kind === "mesh") {
+        const hit = raycastCollisionMesh(collider.shape.mesh, origin, direction, maxDistance, position, rotationY, collider.shape.meshScale, collider.shape.meshTranslate);
+        if (hit === null)
+            return null;
+        return {
+            distance: hit.distance,
+            normal: hit.normal,
+            point: [
+                origin[0] + direction[0] * hit.distance,
+                origin[1] + direction[1] * hit.distance,
+                origin[2] + direction[2] * hit.distance,
+            ],
+        };
+    }
     const bounds = colliderBounds(collider, position, rotationY);
     const hit = intersectAabb(origin, direction, bounds.min, bounds.max, maxDistance);
     if (hit === null)

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;