@jgengine/core 0.10.0 → 0.12.0

package/dist/editor/runtimeInspector.d.ts

@@ -0,0 +1,88 @@
+import type { EditorCommand } from "./commands.js";
+import type { EditorDocument } from "./types.js";
+import { type RuntimeEntityState, type RuntimeStateSnapshot } from "./liveSync.js";
+/** Play-mode sim gate held by the editor host — pause freezes ticks; step runs N frames then re-pauses. */
+export interface RuntimePlayControl {
+    paused: boolean;
+    pendingSteps: number;
+}
+/** Compact reverse-channel view for the play-mode inspector and `runtime_summary` RPC. */
+export interface RuntimeInspectorSummary {
+    seq: number;
+    entityCount: number;
+    entities: readonly {
+        id: string;
+        hasPosition: boolean;
+        rotationY?: number;
+        valueKeys: readonly string[];
+    }[];
+    tunableKeys: readonly string[];
+    overrideIds: readonly string[];
+    play: RuntimePlayControl;
+}
+/** One resolved runtime field returned by `runtime_get`. */
+export interface RuntimeInspectorGetResult {
+    id: string;
+    kind: "entity" | "tunable" | "missing";
+    entity?: RuntimeEntityState;
+    path?: string;
+    value?: unknown;
+    override?: RuntimeEntityState;
+}
+/** Desired mutation from `runtime_set` before the host applies it. */
+export interface RuntimeInspectorSetPlan {
+    entity?: RuntimeEntityState;
+    tunable?: {
+        key: string;
+        value: unknown;
+    };
+    writeBackCommands: readonly EditorCommand[];
+    error?: string;
+}
+/**
+ * Builds the compact reverse-channel summary used by the play-mode inspector panel and the
+ * `runtime_summary` bridge RPC.
+ * @capability editor-runtime-inspector summarize live runtime entities and tunables for play mode
+ */
+export declare function summarizeRuntimeInspector(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, play: RuntimePlayControl): RuntimeInspectorSummary;
+/**
+ * Resolves one entity, entity field, or tunable from the reverse-channel snapshot (with overrides
+ * layered on top for entity rows).
+ * @capability editor-runtime-inspector read one live runtime entity field or tunable
+ */
+export declare function getRuntimeInspectorValue(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, id: string, path?: string): RuntimeInspectorGetResult;
+/**
+ * Plans a play-mode poke: builds the ephemeral entity/tunable override and, when `writeBack` is
+ * true, the undoable document commands that promote it into the scene document.
+ * @capability editor-runtime-inspector plan a play-mode runtime_set with optional document write-back
+ */
+export declare function planRuntimeInspectorSet(document: EditorDocument, input: {
+    id: string;
+    path?: string;
+    value?: unknown;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY?: number;
+    values?: Record<string, unknown>;
+    writeBack?: boolean;
+}): RuntimeInspectorSetPlan;
+/**
+ * Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object.
+ * Returns null when the id is not in the document or there are no values.
+ * @capability editor-runtime-inspector promote runtime entity values into a document meta write-back
+ */
+export declare function runtimeEntityMetaWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null;
+/**
+ * Advances the play-control step counter: when paused with pending steps, consumes one and reports
+ * whether the sim should run this frame. When not paused, always runs.
+ * @capability editor-runtime-inspector gate a play-mode frame against pause/step control
+ */
+export declare function consumeRuntimePlayStep(play: RuntimePlayControl): {
+    runFrame: boolean;
+    next: RuntimePlayControl;
+};
+/** Default play-control state when entering play mode (running). */
+export declare function createRuntimePlayControl(paused?: boolean): RuntimePlayControl;

package/dist/editor/runtimeInspector.js

@@ -0,0 +1,239 @@
+import { runtimeEntityWriteBackCommand, } from "./liveSync.js";
+/**
+ * Builds the compact reverse-channel summary used by the play-mode inspector panel and the
+ * `runtime_summary` bridge RPC.
+ * @capability editor-runtime-inspector summarize live runtime entities and tunables for play mode
+ */
+export function summarizeRuntimeInspector(snapshot, overrides, play) {
+    const entities = Object.values(snapshot.entities)
+        .map((entity) => ({
+        id: entity.id,
+        hasPosition: entity.position !== undefined,
+        ...(entity.rotationY === undefined ? {} : { rotationY: entity.rotationY }),
+        valueKeys: entity.values === undefined ? [] : Object.keys(entity.values).sort(),
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        seq: snapshot.seq,
+        entityCount: entities.length,
+        entities,
+        tunableKeys: Object.keys(snapshot.tunables).sort(),
+        overrideIds: Object.keys(overrides).sort(),
+        play: { paused: play.paused, pendingSteps: play.pendingSteps },
+    };
+}
+/**
+ * Resolves one entity, entity field, or tunable from the reverse-channel snapshot (with overrides
+ * layered on top for entity rows).
+ * @capability editor-runtime-inspector read one live runtime entity field or tunable
+ */
+export function getRuntimeInspectorValue(snapshot, overrides, id, path) {
+    if (id.startsWith("tunable:")) {
+        const key = id.slice("tunable:".length);
+        if (key.length === 0)
+            return { id, kind: "missing" };
+        if (!(key in snapshot.tunables) && path === undefined)
+            return { id, kind: "missing", path: key };
+        return {
+            id,
+            kind: "tunable",
+            path: key,
+            value: snapshot.tunables[key],
+        };
+    }
+    const base = snapshot.entities[id];
+    const override = overrides[id];
+    if (base === undefined && override === undefined) {
+        if (path !== undefined && path in snapshot.tunables) {
+            return { id: `tunable:${path}`, kind: "tunable", path, value: snapshot.tunables[path] };
+        }
+        return { id, kind: "missing", path };
+    }
+    const entity = {
+        id,
+        position: override?.position ?? base?.position,
+        rotationY: override?.rotationY ?? base?.rotationY,
+        values: override?.values === undefined && base?.values === undefined
+            ? undefined
+            : { ...base?.values, ...override?.values },
+    };
+    if (path === undefined || path === "") {
+        return { id, kind: "entity", entity, ...(override === undefined ? {} : { override }) };
+    }
+    if (path === "position") {
+        return { id, kind: "entity", entity, path, value: entity.position, ...(override === undefined ? {} : { override }) };
+    }
+    if (path === "rotationY") {
+        return { id, kind: "entity", entity, path, value: entity.rotationY, ...(override === undefined ? {} : { override }) };
+    }
+    if (path.startsWith("values.")) {
+        const key = path.slice("values.".length);
+        return {
+            id,
+            kind: "entity",
+            entity,
+            path,
+            value: entity.values?.[key],
+            ...(override === undefined ? {} : { override }),
+        };
+    }
+    return {
+        id,
+        kind: "entity",
+        entity,
+        path,
+        value: entity.values?.[path],
+        ...(override === undefined ? {} : { override }),
+    };
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function asPosition(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!isFiniteNumber(record.x) || !isFiniteNumber(record.y) || !isFiniteNumber(record.z))
+        return null;
+    return { x: record.x, y: record.y, z: record.z };
+}
+/**
+ * Plans a play-mode poke: builds the ephemeral entity/tunable override and, when `writeBack` is
+ * true, the undoable document commands that promote it into the scene document.
+ * @capability editor-runtime-inspector plan a play-mode runtime_set with optional document write-back
+ */
+export function planRuntimeInspectorSet(document, input) {
+    const writeBack = input.writeBack !== false;
+    const writeBackCommands = [];
+    if (input.id.startsWith("tunable:")) {
+        const key = input.id.slice("tunable:".length);
+        if (key.length === 0)
+            return { writeBackCommands, error: "tunable id is empty" };
+        if (input.value === undefined)
+            return { writeBackCommands, error: "tunable set requires value" };
+        return { tunable: { key, value: input.value }, writeBackCommands };
+    }
+    if (input.path !== undefined && input.path.startsWith("tunable:")) {
+        const key = input.path.slice("tunable:".length);
+        if (key.length === 0)
+            return { writeBackCommands, error: "tunable path is empty" };
+        if (input.value === undefined)
+            return { writeBackCommands, error: "tunable set requires value" };
+        return { tunable: { key, value: input.value }, writeBackCommands };
+    }
+    const entity = { id: input.id };
+    let touched = false;
+    if (input.position !== undefined) {
+        entity.position = { ...input.position };
+        touched = true;
+    }
+    if (input.rotationY !== undefined) {
+        if (!isFiniteNumber(input.rotationY))
+            return { writeBackCommands, error: "rotationY must be finite" };
+        entity.rotationY = input.rotationY;
+        touched = true;
+    }
+    if (input.values !== undefined) {
+        entity.values = { ...input.values };
+        touched = true;
+    }
+    if (input.path === "position") {
+        const position = asPosition(input.value);
+        if (position === null)
+            return { writeBackCommands, error: "position value must be {x,y,z}" };
+        entity.position = position;
+        touched = true;
+    }
+    else if (input.path === "rotationY") {
+        if (!isFiniteNumber(input.value))
+            return { writeBackCommands, error: "rotationY value must be finite" };
+        entity.rotationY = input.value;
+        touched = true;
+    }
+    else if (input.path !== undefined && input.path.startsWith("values.")) {
+        const key = input.path.slice("values.".length);
+        if (key.length === 0)
+            return { writeBackCommands, error: "values path is empty" };
+        entity.values = { [key]: input.value };
+        touched = true;
+    }
+    else if (input.path !== undefined && input.path.length > 0 && input.value !== undefined) {
+        entity.values = { [input.path]: input.value };
+        touched = true;
+    }
+    if (!touched) {
+        return { writeBackCommands, error: `runtime_set "${input.id}" has no position, rotationY, values, or path` };
+    }
+    if (writeBack) {
+        const transform = runtimeEntityWriteBackCommand(document, entity);
+        if (transform !== null)
+            writeBackCommands.push(transform);
+        if (entity.values !== undefined) {
+            const metaCommand = runtimeEntityMetaWriteBackCommand(document, entity);
+            if (metaCommand !== null)
+                writeBackCommands.push(metaCommand);
+        }
+    }
+    return { entity, writeBackCommands };
+}
+/**
+ * Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object.
+ * Returns null when the id is not in the document or there are no values.
+ * @capability editor-runtime-inspector promote runtime entity values into a document meta write-back
+ */
+export function runtimeEntityMetaWriteBackCommand(document, entity) {
+    if (entity.values === undefined || Object.keys(entity.values).length === 0)
+        return null;
+    const marker = document.markers.find((entry) => entry.id === entity.id);
+    if (marker !== undefined) {
+        return {
+            type: "setMarker",
+            id: entity.id,
+            patch: { meta: { ...marker.meta, ...entity.values } },
+        };
+    }
+    const volume = document.volumes.find((entry) => entry.id === entity.id);
+    if (volume !== undefined) {
+        return {
+            type: "setVolume",
+            id: entity.id,
+            patch: { meta: { ...volume.meta, ...entity.values } },
+        };
+    }
+    const path = document.paths.find((entry) => entry.id === entity.id);
+    if (path !== undefined) {
+        return {
+            type: "setPath",
+            id: entity.id,
+            patch: { meta: { ...path.meta, ...entity.values } },
+        };
+    }
+    const note = document.annotations.find((entry) => entry.id === entity.id);
+    if (note !== undefined) {
+        return {
+            type: "setNote",
+            id: entity.id,
+            patch: { meta: { ...note.meta, ...entity.values } },
+        };
+    }
+    return null;
+}
+/**
+ * Advances the play-control step counter: when paused with pending steps, consumes one and reports
+ * whether the sim should run this frame. When not paused, always runs.
+ * @capability editor-runtime-inspector gate a play-mode frame against pause/step control
+ */
+export function consumeRuntimePlayStep(play) {
+    if (!play.paused)
+        return { runFrame: true, next: play };
+    if (play.pendingSteps <= 0)
+        return { runFrame: false, next: play };
+    return {
+        runFrame: true,
+        next: { paused: true, pendingSteps: play.pendingSteps - 1 },
+    };
+}
+/** Default play-control state when entering play mode (running). */
+export function createRuntimePlayControl(paused = false) {
+    return { paused, pendingSteps: 0 };
+}

package/dist/editor/streamer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides,
+ * as the camera moves, which shards enter and leave residency. It is pure scheduling — actually
+ * reading/merging the shard documents stays the caller's job (compose with
+ * `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has
+ * no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a
+ * shard on a boundary from thrashing load/unload every frame.
+ */
+/** The minimal shard shape the streamer schedules on — any world-manifest shard satisfies it. */
+export interface StreamerShard {
+    /** Stable shard id (the load/unload unit). */
+    id: string;
+    /** XZ footprint `[minX, minZ]`..`[maxX, maxZ]`; absent = always resident. */
+    bounds?: {
+        min: [number, number];
+        max: [number, number];
+    };
+    /** `"always"` keeps the shard resident regardless of distance; default `"streamed"` when bounded. */
+    residency?: "always" | "streamed";
+}
+/** Configuration for {@link createWorldStreamer}. */
+export interface WorldStreamerConfig {
+    shards: readonly StreamerShard[];
+    /** Load a shard when the camera comes within this distance (m) of its footprint. */
+    loadRadius: number;
+    /** Keep a loaded shard resident until the camera is farther than this (m) — hysteresis band. */
+    keepRadius: number;
+}
+/** The residency change produced by one {@link WorldStreamer.update}. */
+export interface StreamUpdate {
+    /** Shard ids that became resident on this update. */
+    load: string[];
+    /** Shard ids that left residency on this update. */
+    unload: string[];
+    /** The full resident shard-id set after this update (sorted, stable order). */
+    resident: string[];
+}
+/** A stateful proximity streamer over a fixed shard set. */
+export interface WorldStreamer {
+    /** Advances the streamer to a new camera position, returning the residency delta. */
+    update(center: {
+        x: number;
+        z: number;
+    }): StreamUpdate;
+    /** The current resident shard-id set (sorted). */
+    resident(): string[];
+    /** Clears all residency (next update reloads from scratch). */
+    reset(): void;
+}
+/**
+ * Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
+ * @capability world-streaming distance from a camera to a shard footprint
+ */
+export declare function shardDistance(shard: StreamerShard, center: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Creates a proximity streamer over a world's shards. Always-resident shards are resident from the
+ * first update onward; each bounded shard loads when the camera comes within `loadRadius` of its
+ * footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up),
+ * giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the
+ * caller wires each delta to `loadWorldDocument`.
+ * @capability world-streaming schedule shard load/unload by camera proximity
+ */
+export declare function createWorldStreamer(config: WorldStreamerConfig): WorldStreamer;

package/dist/editor/streamer.js

@@ -0,0 +1,68 @@
+/**
+ * The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides,
+ * as the camera moves, which shards enter and leave residency. It is pure scheduling — actually
+ * reading/merging the shard documents stays the caller's job (compose with
+ * `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has
+ * no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a
+ * shard on a boundary from thrashing load/unload every frame.
+ */
+function isAlwaysResident(shard) {
+    return shard.residency === "always" || shard.bounds === undefined;
+}
+/**
+ * Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
+ * @capability world-streaming distance from a camera to a shard footprint
+ */
+export function shardDistance(shard, center) {
+    if (shard.bounds === undefined)
+        return 0;
+    const { min, max } = shard.bounds;
+    const qx = Math.max(min[0], Math.min(center.x, max[0]));
+    const qz = Math.max(min[1], Math.min(center.z, max[1]));
+    return Math.hypot(center.x - qx, center.z - qz);
+}
+/**
+ * Creates a proximity streamer over a world's shards. Always-resident shards are resident from the
+ * first update onward; each bounded shard loads when the camera comes within `loadRadius` of its
+ * footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up),
+ * giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the
+ * caller wires each delta to `loadWorldDocument`.
+ * @capability world-streaming schedule shard load/unload by camera proximity
+ */
+export function createWorldStreamer(config) {
+    const loadRadius = Math.max(0, config.loadRadius);
+    const keepRadius = Math.max(loadRadius, config.keepRadius);
+    const shards = [...config.shards];
+    const resident = new Set();
+    const residentSorted = () => [...resident].sort();
+    return {
+        update(center) {
+            const load = [];
+            const unload = [];
+            for (const shard of shards) {
+                if (isAlwaysResident(shard)) {
+                    if (!resident.has(shard.id)) {
+                        resident.add(shard.id);
+                        load.push(shard.id);
+                    }
+                    continue;
+                }
+                const distance = shardDistance(shard, center);
+                const isResident = resident.has(shard.id);
+                if (!isResident && distance <= loadRadius) {
+                    resident.add(shard.id);
+                    load.push(shard.id);
+                }
+                else if (isResident && distance > keepRadius) {
+                    resident.delete(shard.id);
+                    unload.push(shard.id);
+                }
+            }
+            return { load: load.sort(), unload: unload.sort(), resident: residentSorted() };
+        },
+        resident: residentSorted,
+        reset() {
+            resident.clear();
+        },
+    };
+}