@jgengine/editor 0.10.0 → 0.12.0

package/dist/networkSnapshot.d.ts

@@ -0,0 +1,82 @@
+import { type MultiplayerAdapterConfig, type MultiplayerAuthority } from "@jgengine/core/runtime/adapter";
+import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
+/** Transport kind declared by the game, or `"unknown"` when the config is unreadable. */
+export type EditorNetworkAdapterKind = MultiplayerAdapterConfig["kind"] | "unknown";
+/**
+ * One online actor from a host-supplied presence feed. Fields mirror
+ * {@link PresencePoseRow} so hosts can forward backend rows without inventing shape.
+ */
+export interface EditorNetworkPresenceActor {
+    userId: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    rotationPitch?: number;
+    lastSeenAt?: number;
+}
+/**
+ * Optional live session identity when a multiplayer backend is attached.
+ * Omit entirely when the host has no session — the panel reports offline honestly.
+ */
+export interface EditorNetworkSession {
+    userId: string;
+    /** Joined room/server id when known; `null` means joined but id not reported. */
+    serverId?: string | null;
+    feedActions?: readonly string[];
+}
+/**
+ * Host-facing network inspection payload for the editor Network workspace.
+ *
+ * - Adapter fields come from the game definition (always real config).
+ * - `session` is present only when the host attached a live multiplayer backend.
+ * - `online` is `undefined` when the host has not supplied a presence feed; `[]` when
+ *   the feed is connected but empty. Never fabricate actors.
+ */
+export interface EditorNetworkSnapshot {
+    gameId: string;
+    adapterKind: EditorNetworkAdapterKind;
+    /** `null` for offline / single-player games. */
+    authority: MultiplayerAuthority | null;
+    /** Optional topology string from the adapter when declared. */
+    topology?: string;
+    /** Optional endpoint hint from the adapter (ws/socketio url, lan port, p2p room). */
+    endpoint?: string;
+    session?: EditorNetworkSession;
+    /**
+     * Online presence roster from the host.
+     * - `undefined` — no feed supplied (honest empty / waiting).
+     * - array — real rows only (may be empty).
+     */
+    online?: readonly EditorNetworkPresenceActor[];
+    /** Wall-clock ms of the last presence update when the host tracks it. */
+    updatedAt?: number;
+}
+/** Optional live presence/session injection from the editor host. */
+export interface EditorNetworkPresenceInput {
+    userId?: string;
+    serverId?: string | null;
+    feedActions?: readonly string[];
+    online?: readonly PresencePoseRow[] | readonly EditorNetworkPresenceActor[];
+    updatedAt?: number;
+}
+/**
+ * Builds a Network workspace snapshot from the game's multiplayer config plus optional live
+ * presence rows. Adapter fields always reflect declared config; presence is only included when
+ * the host passes it.
+ *
+ * @internal
+ */
+export declare function buildEditorNetworkSnapshot(args: {
+    gameId: string;
+    multiplayer: unknown;
+    presence?: EditorNetworkPresenceInput;
+}): EditorNetworkSnapshot;
+/**
+ * True when the snapshot represents a multiplayer-capable game (not offline/unknown-null).
+ *
+ * @internal
+ */
+export declare function isNetworkMultiplayerConfigured(snapshot: EditorNetworkSnapshot): boolean;

package/dist/networkSnapshot.js

@@ -0,0 +1,73 @@
+import { adapterOf, resolveAuthority, } from "@jgengine/core/runtime/adapter";
+function endpointOf(adapter) {
+    if (adapter === null)
+        return undefined;
+    if (adapter.kind === "ws" || adapter.kind === "socketio")
+        return adapter.url;
+    if (adapter.kind === "lan") {
+        const port = adapter.port ?? 8080;
+        const path = adapter.path ?? "/ws";
+        return `port ${port}${path}`;
+    }
+    if (adapter.kind === "p2p")
+        return adapter.room;
+    return undefined;
+}
+function topologyOf(adapter) {
+    if (adapter === null || adapter.kind === "offline")
+        return undefined;
+    return "topology" in adapter ? adapter.topology : undefined;
+}
+/**
+ * Builds a Network workspace snapshot from the game's multiplayer config plus optional live
+ * presence rows. Adapter fields always reflect declared config; presence is only included when
+ * the host passes it.
+ *
+ * @internal
+ */
+export function buildEditorNetworkSnapshot(args) {
+    const adapter = adapterOf(args.multiplayer);
+    const adapterKind = adapter?.kind ?? "unknown";
+    const authority = resolveAuthority(args.multiplayer);
+    const snapshot = {
+        gameId: args.gameId,
+        adapterKind,
+        authority,
+    };
+    const topology = topologyOf(adapter);
+    if (topology !== undefined)
+        snapshot.topology = topology;
+    const endpoint = endpointOf(adapter);
+    if (endpoint !== undefined)
+        snapshot.endpoint = endpoint;
+    const presence = args.presence;
+    if (presence !== undefined) {
+        if (typeof presence.userId === "string" && presence.userId.length > 0) {
+            snapshot.session = {
+                userId: presence.userId,
+                ...(presence.serverId !== undefined ? { serverId: presence.serverId } : {}),
+                ...(presence.feedActions !== undefined ? { feedActions: presence.feedActions } : {}),
+            };
+        }
+        if (presence.online !== undefined) {
+            snapshot.online = presence.online.map((row) => ({
+                userId: row.userId,
+                position: { x: row.position.x, y: row.position.y, z: row.position.z },
+                rotationY: row.rotationY,
+                ...(row.rotationPitch !== undefined ? { rotationPitch: row.rotationPitch } : {}),
+                ...("lastSeenAt" in row && row.lastSeenAt !== undefined ? { lastSeenAt: row.lastSeenAt } : {}),
+            }));
+        }
+        if (presence.updatedAt !== undefined)
+            snapshot.updatedAt = presence.updatedAt;
+    }
+    return snapshot;
+}
+/**
+ * True when the snapshot represents a multiplayer-capable game (not offline/unknown-null).
+ *
+ * @internal
+ */
+export function isNetworkMultiplayerConfigured(snapshot) {
+    return snapshot.adapterKind !== "offline" && snapshot.adapterKind !== "unknown" && snapshot.authority !== null;
+}

package/dist/parentCandidates.d.ts

@@ -0,0 +1,12 @@
+import { type EditorDocument } from "@jgengine/core/editor/index";
+/** One option in the Parent-to… picker / inspector parent field. @internal */
+export interface ParentCandidate {
+    id: string;
+    label: string;
+}
+/**
+ * Placeable objects that may become parents of every id in `childIds` without creating a cycle:
+ * excludes the children themselves and all of their descendants.
+ * @internal
+ */
+export declare function listParentCandidates(document: EditorDocument, childIds: readonly string[]): ParentCandidate[];

package/dist/parentCandidates.js

@@ -0,0 +1,25 @@
+import { collectDescendants, } from "@jgengine/core/editor/index";
+/**
+ * Placeable objects that may become parents of every id in `childIds` without creating a cycle:
+ * excludes the children themselves and all of their descendants.
+ * @internal
+ */
+export function listParentCandidates(document, childIds) {
+    if (childIds.length === 0)
+        return [];
+    const banned = collectDescendants(document, childIds);
+    for (const id of childIds)
+        banned.add(id);
+    const labelOf = (node) => node.label ?? node.id;
+    const candidates = [
+        ...document.markers.map((m) => ({ id: m.id, label: labelOf(m) })),
+        ...document.volumes.map((v) => ({ id: v.id, label: labelOf(v) })),
+        ...document.paths.map((p) => ({ id: p.id, label: labelOf(p) })),
+        ...document.annotations.map((n) => ({
+            id: n.id,
+            label: n.text.slice(0, 30) || n.id,
+        })),
+    ].filter((entry) => !banned.has(entry.id));
+    candidates.sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
+    return candidates;
+}

package/dist/perfPill.d.ts

@@ -0,0 +1,21 @@
+/** Toolbar perf-pill health, separating an idle render-on-demand loop from a genuinely slow frame. */
+export type EditorPerfTone = "idle" | "healthy" | "busy";
+/**
+ * FPS at or below which an *actively rendering* editor frame is treated as struggling.
+ * Only applied when the loop is active — an idle / browser-throttled loop never trips it.
+ */
+export declare const EDITOR_PERF_LOW_FPS = 30;
+/**
+ * Classify a perf sample for the toolbar pill. The editor renders `frameloop="always"`, so a
+ * healthy visible loop sits at ~60fps; a low wall-clock fps only appears when the browser throttles
+ * rAF (backgrounded tab / headless screenshot) while nothing is happening. `PerfProbe` measures
+ * that idleness (no camera move, no raycast/rebuild, no scene change) and reports it as `active:false`,
+ * which classifies here as `"idle"` instead of the red danger cue. The danger cue (`"busy"`) is
+ * reserved for sustained low fps while the loop is genuinely active (orbit / drag / sculpt) — the
+ * regression actually worth surfacing.
+ * @internal — drives the editor toolbar perf pill; not game-facing.
+ */
+export declare function classifyEditorPerf(sample: {
+    fps: number;
+    active: boolean;
+}): EditorPerfTone;

package/dist/perfPill.js

@@ -0,0 +1,20 @@
+/**
+ * FPS at or below which an *actively rendering* editor frame is treated as struggling.
+ * Only applied when the loop is active — an idle / browser-throttled loop never trips it.
+ */
+export const EDITOR_PERF_LOW_FPS = 30;
+/**
+ * Classify a perf sample for the toolbar pill. The editor renders `frameloop="always"`, so a
+ * healthy visible loop sits at ~60fps; a low wall-clock fps only appears when the browser throttles
+ * rAF (backgrounded tab / headless screenshot) while nothing is happening. `PerfProbe` measures
+ * that idleness (no camera move, no raycast/rebuild, no scene change) and reports it as `active:false`,
+ * which classifies here as `"idle"` instead of the red danger cue. The danger cue (`"busy"`) is
+ * reserved for sustained low fps while the loop is genuinely active (orbit / drag / sculpt) — the
+ * regression actually worth surfacing.
+ * @internal — drives the editor toolbar perf pill; not game-facing.
+ */
+export function classifyEditorPerf(sample) {
+    if (!sample.active)
+        return "idle";
+    return sample.fps < EDITOR_PERF_LOW_FPS ? "busy" : "healthy";
+}

package/dist/session.d.ts

@@ -1,7 +1,11 @@
-import { type DocumentLiveSync, type DocumentPatch, type EditorCatalogDefinition, type EditorCommand, type EditorDocument, type EditorKindVisibility, type EditorLayersInput, type EditorSession, type EditorSessionState, type RuntimeEntityState, type RuntimePlayControl } from "@jgengine/core/editor/index";
-import { type TerraformMode, type TerrainMaterialLayer } from "@jgengine/core/world/terraform";
-/** How the editor hosts the game: frozen placement view, roamable world, or the real game. */
-export type EditorRunMode = "edit" | "walk" | "play";
+import { type DocumentLiveSync, type DocumentPatch, type EditorCatalogDefinition, type EditorCommand, type EditorDocument, type EditorGridPaletteEntry, type EditorKindVisibility, type EditorLayersInput, type EditorSession, type EditorSessionState, type RuntimeEntityState, type RuntimePlayControl } from "@jgengine/core/editor/index";
+import type { TerraformMode, TerrainMaterialLayer } from "@jgengine/core/world/terraform";
+import type { ParamSchema } from "@jgengine/core/scene/sceneKinds";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/** How the editor hosts the game: frozen placement view, roamable world, the real game, or HUD-layout authoring. */
+export type EditorRunMode = "edit" | "walk" | "play" | "hud";
+/** The accepted run modes, in canonical order — the runtime guard behind {@link EditorRunMode}. @internal */
+export declare const EDITOR_RUN_MODES: readonly EditorRunMode[];
 /** RPC request shapes the editor host understands, used by the MCP bridge and UI. */
 export type EditorBridgeRequest = {
     method: "editor_status";
@@ -24,6 +28,29 @@ export type EditorBridgeRequest = {
     entryId: string;
     patch: Record<string, unknown>;
     label?: string;
+} | {
+    method: "add_catalog_entry";
+    catalogId: string;
+    entryId: string;
+    meta?: Record<string, unknown>;
+    label?: string;
+} | {
+    method: "remove_catalog_entry";
+    catalogId: string;
+    entryId: string;
+} | {
+    method: "add_catalog";
+    catalogId: string;
+    label?: string;
+    schema?: ParamSchema;
+} | {
+    method: "remove_catalog";
+    catalogId: string;
+} | {
+    method: "set_catalog_schema";
+    catalogId: string;
+    schema: ParamSchema;
+    label?: string;
 } | {
     method: "list_selection";
 } | {
@@ -72,6 +99,10 @@ export type EditorBridgeRequest = {
     method: "set_meta";
     id: string;
     patch: Record<string, unknown>;
+} | {
+    method: "apply_preset";
+    id: string;
+    preset: string;
 } | {
     method: "select";
     ids: string[];
@@ -164,6 +195,11 @@ export type EditorBridgeRequest = {
 } | {
     method: "convert_scatter";
     pathId: string;
+} | {
+    method: "bake_minimap";
+    padding?: number;
+    resolution?: number;
+    waterLevel?: number;
 } | {
     method: "add_foliage";
     points: {
@@ -236,6 +272,11 @@ export type EditorBridgeRequest = {
 } | {
     method: "select_collection";
     id: string;
+} | {
+    method: "set_object_flags";
+    ids: string[];
+    locked?: boolean;
+    hidden?: boolean;
 } | {
     method: "batch_set_properties";
     ids: string[];
@@ -246,6 +287,89 @@ export type EditorBridgeRequest = {
     method: "assign_material";
     ids: string[];
     materialId: string;
+} | {
+    method: "list_grids";
+} | {
+    method: "get_grid_cell";
+    id: string;
+    col: number;
+    row: number;
+} | {
+    method: "add_grid_layer";
+    id: string;
+    kind: string;
+    cols: number;
+    rows: number;
+    label?: string;
+    cellSize?: number;
+    origin?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    axes?: "xz" | "xy";
+    empty?: string;
+    palette?: EditorGridPaletteEntry[];
+} | {
+    method: "remove_grid_layer";
+    id: string;
+} | {
+    method: "set_grid_layer";
+    id: string;
+    label?: string;
+    kind?: string;
+    visible?: boolean;
+    empty?: string;
+    cellSize?: number;
+    origin?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    axes?: "xz" | "xy";
+    palette?: EditorGridPaletteEntry[];
+} | {
+    method: "paint_grid_cells";
+    id: string;
+    cells: {
+        col: number;
+        row: number;
+        value: string;
+    }[];
+} | {
+    method: "fill_grid_rect";
+    id: string;
+    col0: number;
+    row0: number;
+    col1: number;
+    row1: number;
+    value: string;
+} | {
+    method: "flood_fill_grid";
+    id: string;
+    col: number;
+    row: number;
+    value: string;
+} | {
+    method: "resize_grid_layer";
+    id: string;
+    cols: number;
+    rows: number;
+} | {
+    method: "import_grid";
+    id: string;
+    kind: string;
+    format: "ascii" | "csv";
+    text: string;
+    empty?: string;
+    cellSize?: number;
+    origin?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    glyphMap?: Record<string, string>;
+    palette?: EditorGridPaletteEntry[];
 } | {
     method: "push_document_patch";
     patch: DocumentPatch;
@@ -319,17 +443,47 @@ export interface EditorAssetInfo {
 }
 /** Rolling frame-rate sample published by the in-canvas PerfProbe. */
 export interface EditorPerfSample {
+    /**
+     * JS heap used in megabytes when the browser exposes `performance.memory` (Chromium).
+     * Omitted entirely when unavailable — never fabricated.
+     */
+    memoryMb?: number;
     fps: number;
     frameMs: number;
     drawCalls: number;
     triangles: number;
     sampledAt: number;
+    /**
+     * Whether the sampled window saw camera or edit activity. `false` means the render-on-demand /
+     * browser-throttled loop is idle, so a low `fps` is expected pacing rather than lag — the pill
+     * shows a neutral "idle" instead of the red danger cue.
+     */
+    active: boolean;
     /** Avg viewport raycast (pick) time this window — editor-authoring cost, not sim cost. */
     raycastMs?: number;
     /** Avg preview-mesh rebuild (displace) time this window — editor-authoring cost, not sim cost. */
     rebuildMs?: number;
     /** raycastMs + rebuildMs — total authoring overhead separated from the frame/sim budget. */
     authoringMs?: number;
+    /**
+     * Average sim-driver time (ms) from core `devtools.frame` when FrameDriver has recorded frames.
+     * Same source as `debug_snapshot` / F2+D Perf panel — omitted when no frame samples exist
+     * (e.g. pure edit mode with no runtime tick). Never fabricated.
+     */
+    simMs?: number;
+    /**
+     * Average outside-sim time (ms) = frame − sim (render / React / GPU / GC / vsync miss).
+     * Same availability rule as `simMs`. Matches `FrameStats.avgOutsideMs`.
+     */
+    outsideMs?: number;
+    /**
+     * Top named sim phases (avg ms) from the same frame window when `measure("name", …)` marks exist.
+     * Omitted when the frame tracker has no named phases.
+     */
+    phases?: readonly {
+        name: string;
+        avgMs: number;
+    }[];
 }
 /** The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC. */
 export interface EditorHostApi {
@@ -360,12 +514,20 @@ export interface EditorHostApi {
     getCatalogDefinitions(): readonly EditorCatalogDefinition[];
     getPerf(): EditorPerfSample | null;
     setPerf(sample: EditorPerfSample): void;
+    /**
+     * The live composed ground field (base procedural terrain + document sculpt) from the mounted
+     * viewport, or null when no viewport is mounted. `bake_minimap` reads it to rasterize authored
+     * terrain; it exists only while the editor world is mounted, so headless CLIs get a null here.
+     */
+    getTerrainSampler(): TerrainField | null;
+    setTerrainSampler(field: TerrainField | null): void;
     getMode(): EditorRunMode;
     setMode(mode: EditorRunMode): void;
     subscribeMode(listener: (mode: EditorRunMode) => void): () => void;
     /** Play-mode pause/step gate consumed by the runtime publisher. */
     getPlayControl(): RuntimePlayControl;
-    setPlayControl(next: RuntimePlayControl): void;
+    /** Normalizes and stores the play control, notifies listeners, and returns the applied value. */
+    setPlayControl(next: RuntimePlayControl): RuntimePlayControl;
     subscribePlayControl(listener: (play: RuntimePlayControl) => void): () => void;
     handle(request: EditorBridgeRequest): EditorBridgeResponse;
 }