@jgengine/editor 0.10.0

package/dist/agent/turn.d.ts

@@ -0,0 +1,71 @@
+import type { EditorHostApi } from "../session.js";
+import { type AgentEditorContext } from "./context.js";
+import type { AgentChatMessage, AgentEndpoint } from "./endpoint.js";
+import { type AgentToolResult } from "./toolBridge.js";
+/** One agent edit shown in the panel transcript — human can undo when it is the top of the stack. */
+export interface AgentPatchEntry {
+    id: string;
+    toolCallId: string;
+    method: string;
+    summary: string;
+    at: number;
+    undone: boolean;
+}
+/** One rendered line in the agent panel transcript (user, assistant, tool, error, or patch). */
+export type AgentTranscriptEntry = {
+    kind: "user";
+    id: string;
+    content: string;
+    at: number;
+} | {
+    kind: "assistant";
+    id: string;
+    content: string;
+    at: number;
+} | {
+    kind: "tool";
+    id: string;
+    result: AgentToolResult;
+    at: number;
+} | {
+    kind: "error";
+    id: string;
+    content: string;
+    at: number;
+} | {
+    kind: "patch";
+    id: string;
+    patch: AgentPatchEntry;
+    at: number;
+};
+/** Result of {@link runAgentTurn}: chat history, UI transcript, undoable patches, and packed context. */
+export interface AgentTurnResult {
+    messages: AgentChatMessage[];
+    transcript: AgentTranscriptEntry[];
+    patches: AgentPatchEntry[];
+    context: AgentEditorContext;
+}
+/**
+ * Runs one user message against an agent endpoint: injects live editor context via
+ * `packAgentContext`, executes tool calls through `routeToolCall` (shared undo), and returns
+ * transcript + patch entries the human can reverse with `undoAgentPatch`.
+ */
+export declare function runAgentTurn(options: {
+    api: EditorHostApi;
+    endpoint: AgentEndpoint;
+    history: readonly AgentChatMessage[];
+    userMessage: string;
+    maxRounds?: number;
+    now?: () => number;
+}): Promise<AgentTurnResult>;
+/**
+ * Undoes one agent patch when it is still the top of the session undo stack.
+ * Newer live agent patches must be undone first; returns the updated list immutably.
+ */
+export declare function undoAgentPatch(api: EditorHostApi, patches: readonly AgentPatchEntry[], patchId: string): {
+    ok: true;
+    patches: AgentPatchEntry[];
+} | {
+    ok: false;
+    error: string;
+};

package/dist/agent/turn.js

@@ -0,0 +1,113 @@
+import { EDITOR_MCP_TOOLS } from "../mcp/tools.js";
+import { formatAgentContext, packAgentContext } from "./context.js";
+import { routeToolCall } from "./toolBridge.js";
+function nextId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.floor(Math.random() * 1296).toString(36)}`;
+}
+const DEFAULT_MAX_ROUNDS = 6;
+/**
+ * Runs one user message against an agent endpoint: injects live editor context via
+ * `packAgentContext`, executes tool calls through `routeToolCall` (shared undo), and returns
+ * transcript + patch entries the human can reverse with `undoAgentPatch`.
+ */
+export async function runAgentTurn(options) {
+    const now = options.now ?? Date.now;
+    const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+    const context = packAgentContext(options.api);
+    const system = {
+        role: "system",
+        content: [
+            "You are the in-editor scene agent. Edit the live scene only via the provided tools.",
+            "Each tool name is an editor RPC verb — the same surface as the GUI and MCP bridge.",
+            "Current editor context:",
+            formatAgentContext(context),
+        ].join("\n"),
+    };
+    const messages = [
+        system,
+        ...options.history.filter((m) => m.role !== "system"),
+        { role: "user", content: options.userMessage },
+    ];
+    const transcript = [
+        { kind: "user", id: nextId("user"), content: options.userMessage, at: now() },
+    ];
+    const patches = [];
+    for (let round = 0; round < maxRounds; round += 1) {
+        const liveContext = packAgentContext(options.api);
+        let response;
+        try {
+            response = await options.endpoint.chat({
+                messages,
+                context: liveContext,
+                tools: EDITOR_MCP_TOOLS,
+            });
+        }
+        catch (error) {
+            const content = error instanceof Error ? error.message : String(error);
+            transcript.push({ kind: "error", id: nextId("err"), content, at: now() });
+            break;
+        }
+        if (typeof response.message === "string" && response.message.length > 0) {
+            messages.push({ role: "assistant", content: response.message });
+            transcript.push({ kind: "assistant", id: nextId("asst"), content: response.message, at: now() });
+        }
+        const toolCalls = response.toolCalls ?? [];
+        if (toolCalls.length === 0)
+            break;
+        for (const call of toolCalls) {
+            const result = routeToolCall(options.api, call);
+            messages.push({
+                role: "tool",
+                toolCallId: result.id,
+                name: result.name,
+                content: JSON.stringify(result.ok
+                    ? { ok: true, result: result.result, mutated: result.mutated }
+                    : { ok: false, error: result.error }),
+            });
+            transcript.push({ kind: "tool", id: nextId("tool"), result, at: now() });
+            if (result.mutated) {
+                const patch = {
+                    id: nextId("patch"),
+                    toolCallId: result.id,
+                    method: result.name,
+                    summary: result.patchSummary,
+                    at: now(),
+                    undone: false,
+                };
+                patches.push(patch);
+                transcript.push({ kind: "patch", id: patch.id, patch, at: patch.at });
+            }
+        }
+    }
+    return {
+        messages: messages.filter((m) => m.role !== "system"),
+        transcript,
+        patches,
+        context,
+    };
+}
+/**
+ * Undoes one agent patch when it is still the top of the session undo stack.
+ * Newer live agent patches must be undone first; returns the updated list immutably.
+ */
+export function undoAgentPatch(api, patches, patchId) {
+    const index = patches.findIndex((p) => p.id === patchId);
+    if (index < 0)
+        return { ok: false, error: "patch not found" };
+    const patch = patches[index];
+    if (patch.undone)
+        return { ok: false, error: "already undone" };
+    const laterLive = patches.slice(index + 1).some((p) => !p.undone);
+    if (laterLive) {
+        return { ok: false, error: "undo newer agent edits first" };
+    }
+    if (!api.getSession().canUndo()) {
+        return { ok: false, error: "nothing to undo (human may have undone already)" };
+    }
+    const response = api.handle({ method: "undo" });
+    if (!response.ok) {
+        return { ok: false, error: response.error ?? "undo failed" };
+    }
+    const next = patches.map((p, i) => (i === index ? { ...p, undone: true } : p));
+    return { ok: true, patches: next };
+}

package/dist/chromeFields.d.ts

@@ -0,0 +1,15 @@
+export declare function NumberField({ label, value, onCommit, step, }: {
+    label: string;
+    value: number;
+    onCommit: (value: number) => void;
+    step?: number;
+}): import("react").JSX.Element;
+export declare function SliderRow({ label, value, min, max, step, onChange, format, }: {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    onChange: (value: number) => void;
+    format?: (value: number) => string;
+}): import("react").JSX.Element;

package/dist/chromeFields.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { INPUT } from "./chromeStyles.js";
+export function NumberField({ label, value, onCommit, step = 1, }) {
+    return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: label }), _jsx("input", { type: "number", step: step, className: `w-32 ${INPUT}`, value: value, onChange: (event) => {
+                    const next = Number(event.target.value);
+                    if (!Number.isFinite(next))
+                        return;
+                    onCommit(next);
+                } })] }));
+}
+export function SliderRow({ label, value, min, max, step, onChange, format, }) {
+    return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: label }), _jsx("span", { className: "text-cyan-200", children: format ? format(value) : value.toFixed(2) })] }), _jsx("input", { type: "range", min: min, max: max, step: step, value: value, onChange: (event) => onChange(Number(event.target.value)), className: "w-full accent-amber-400" })] }));
+}

package/dist/chromeStyles.d.ts

@@ -0,0 +1,3 @@
+export declare const BTN = "rounded-md bg-white/[0.04] px-2 py-1 text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10 hover:text-neutral-100";
+export declare const INPUT = "rounded-md border border-white/10 bg-black/40 px-2 py-1 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/60 focus:bg-black/60";
+export declare const MICRO = "text-[9px] font-semibold uppercase tracking-[0.14em] text-neutral-500";

package/dist/chromeStyles.js

@@ -0,0 +1,3 @@
+export const BTN = "rounded-md bg-white/[0.04] px-2 py-1 text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10 hover:text-neutral-100";
+export const INPUT = "rounded-md border border-white/10 bg-black/40 px-2 py-1 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/60 focus:bg-black/60";
+export const MICRO = "text-[9px] font-semibold uppercase tracking-[0.14em] text-neutral-500";

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { EditorApp, type EditorAppProps, type EditorSaveFn } from "./EditorApp.js";
+export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, type StandaloneEditorProps, type StandaloneAsset, type BlankPlayableOptions, } from "./StandaloneEditor.js";
+export { EditorLayerOverlays, PathDraftPreview } from "./DebugDraw.js";
+export { EditorChrome } from "./EditorChrome.js";
+export { SelectionGizmo, ViewportSelect } from "./SelectionGizmo.js";
+export { createEditorUiStore, newPlacementId, DEFAULT_SCULPT_SETTINGS, DEFAULT_PAINT_SETTINGS, TERRAIN_MATERIALS, TERRAIN_MATERIAL_COLORS, type EditorTool, type EditorUiState, type EditorUiStore, type GizmoMode, type PaintSettings, type PlacementTool, type SculptSettings, type SnapMode, type TerrainBrushKind, type TerrainMaterial, type TerrainMode, } from "./uiStore.js";
+export { TerrainSculpt } from "./TerrainSculpt.js";
+export { ScatterPreview } from "./ScatterPreview.js";
+export { EditorCameraDriver } from "./EditorCameraDriver.js";
+export { AssetBrowser, assetsFromCatalog, type EditorAssetEntry } from "./AssetBrowser.js";
+export { createEditorHost, getEditorHost, installEditorHost, type EditorAssetInfo, type EditorBridgeRequest, type EditorBridgeResponse, type EditorHostApi, type EditorPerfSample, type EditorRunMode, } from "./session.js";
+export { PerfProbe } from "./PerfProbe.js";
+export { useStoreSelector, shallowArrayEqual, virtualWindow, type SubscribableStore, type VirtualWindow, } from "./useStoreSelector.js";
+export { useF2Chord } from "./useF2Chord.js";
+export type { EditorBridgeServerOptions, EditorBridgeServer } from "./mcp/bridgeServer.js";
+export { EDITOR_MCP_TOOLS, type EditorMcpTool } from "./mcp/tools.js";
+export { packAgentContext, type AgentEditorContext } from "./agent/context.js";
+export { routeToolCall, type AgentToolCall, type AgentToolResult } from "./agent/toolBridge.js";
+export { createDefaultAgentEndpoint, createHttpAgentEndpoint, resolveAgentEndpointConfig, EDITOR_AGENT_URL_ENV, EDITOR_AGENT_KEY_ENV, EDITOR_AGENT_KEY_FALLBACK_ENV, type AgentEndpoint, type AgentEndpointConfig, type AgentChatMessage, type AgentChatRequest, type AgentChatResponse, type AgentChatRole, } from "./agent/endpoint.js";
+export { runAgentTurn, undoAgentPatch, type AgentPatchEntry, type AgentTranscriptEntry, type AgentTurnResult, } from "./agent/turn.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+export { EditorApp } from "./EditorApp.js";
+export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, } from "./StandaloneEditor.js";
+export { EditorLayerOverlays, PathDraftPreview } from "./DebugDraw.js";
+export { EditorChrome } from "./EditorChrome.js";
+export { SelectionGizmo, ViewportSelect } from "./SelectionGizmo.js";
+export { createEditorUiStore, newPlacementId, DEFAULT_SCULPT_SETTINGS, DEFAULT_PAINT_SETTINGS, TERRAIN_MATERIALS, TERRAIN_MATERIAL_COLORS, } from "./uiStore.js";
+export { TerrainSculpt } from "./TerrainSculpt.js";
+export { ScatterPreview } from "./ScatterPreview.js";
+export { EditorCameraDriver } from "./EditorCameraDriver.js";
+export { AssetBrowser, assetsFromCatalog } from "./AssetBrowser.js";
+export { createEditorHost, getEditorHost, installEditorHost, } from "./session.js";
+export { PerfProbe } from "./PerfProbe.js";
+export { useStoreSelector, shallowArrayEqual, virtualWindow, } from "./useStoreSelector.js";
+export { useF2Chord } from "./useF2Chord.js";
+export { EDITOR_MCP_TOOLS } from "./mcp/tools.js";
+export { packAgentContext } from "./agent/context.js";
+export { routeToolCall } from "./agent/toolBridge.js";
+export { createDefaultAgentEndpoint, createHttpAgentEndpoint, resolveAgentEndpointConfig, EDITOR_AGENT_URL_ENV, EDITOR_AGENT_KEY_ENV, EDITOR_AGENT_KEY_FALLBACK_ENV, } from "./agent/endpoint.js";
+export { runAgentTurn, undoAgentPatch, } from "./agent/turn.js";

package/dist/mcp/bridgeServer.d.ts

@@ -0,0 +1,13 @@
+import type { EditorHostApi } from "../session.js";
+/** Options for starting the editor's HTTP bridge server: host api, port, hostname. */
+export interface EditorBridgeServerOptions {
+    host: EditorHostApi;
+    port?: number;
+    hostname?: string;
+}
+/** A running editor bridge server: its bound port, URL, and a stop handle. */
+export interface EditorBridgeServer {
+    port: number;
+    url: string;
+    stop: () => void;
+}

package/dist/mcp/bridgeServer.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/loadGameCatalogs.d.ts

@@ -0,0 +1,24 @@
+import type { EditorCatalogDefinition } from "@jgengine/core/editor/index";
+/** Result of {@link loadGameCatalogs}: validated definitions, or diagnostics when the export is malformed. */
+export type LoadGameCatalogsResult = {
+    ok: true;
+    catalogs: readonly EditorCatalogDefinition[];
+} | {
+    ok: false;
+    errors: {
+        path: string;
+        message: string;
+    }[];
+};
+/**
+ * Validates an already-resolved `editorCatalogs` export (post module-load, post factory-call).
+ * Missing/undefined yields an empty list — games without catalogs are valid.
+ * @internal
+ */
+export declare function decodeGameCatalogs(resolved: unknown): LoadGameCatalogsResult;
+/**
+ * Node-only: resolves a game's `editorCatalogs` export from Games/<id>/src and validates its shape
+ * before it reaches a live editor session.
+ * @internal
+ */
+export declare function loadGameCatalogs(gameId: string): Promise<LoadGameCatalogsResult>;

package/dist/mcp/loadGameCatalogs.js

@@ -0,0 +1,87 @@
+async function importOptionalEditorCatalogsModule(gameId) {
+    try {
+        const path = new URL(`../../../../Games/${gameId}/src/editorCatalogs.ts`, import.meta.url);
+        return (await import(path.href));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeSchema(value, path, errors) {
+    if (!isPlainObject(value) || !Array.isArray(value.fields)) {
+        errors.push({ path, message: "expected { fields: ParamField[] }" });
+        return null;
+    }
+    return value;
+}
+/**
+ * Validates an already-resolved `editorCatalogs` export (post module-load, post factory-call).
+ * Missing/undefined yields an empty list — games without catalogs are valid.
+ * @internal
+ */
+export function decodeGameCatalogs(resolved) {
+    if (resolved === undefined || resolved === null)
+        return { ok: true, catalogs: [] };
+    if (!Array.isArray(resolved)) {
+        return { ok: false, errors: [{ path: "$", message: "editorCatalogs must be an array" }] };
+    }
+    const errors = [];
+    const catalogs = [];
+    resolved.forEach((item, index) => {
+        const path = `$[${index}]`;
+        if (!isPlainObject(item)) {
+            errors.push({ path, message: "expected an object" });
+            return;
+        }
+        if (typeof item.id !== "string")
+            errors.push({ path: `${path}.id`, message: "expected a string" });
+        if (typeof item.label !== "string")
+            errors.push({ path: `${path}.label`, message: "expected a string" });
+        const schema = decodeSchema(item.schema, `${path}.schema`, errors);
+        if (!Array.isArray(item.entries)) {
+            errors.push({ path: `${path}.entries`, message: "expected an array" });
+            return;
+        }
+        if (typeof item.id !== "string" || typeof item.label !== "string" || schema === null)
+            return;
+        const entries = [];
+        item.entries.forEach((entry, entryIndex) => {
+            const entryPath = `${path}.entries[${entryIndex}]`;
+            if (!isPlainObject(entry) || typeof entry.id !== "string") {
+                errors.push({ path: entryPath, message: "expected { id: string, label?, meta? }" });
+                return;
+            }
+            entries.push({
+                id: entry.id,
+                ...(typeof entry.label === "string" ? { label: entry.label } : {}),
+                ...(isPlainObject(entry.meta) ? { meta: entry.meta } : {}),
+            });
+        });
+        catalogs.push({ id: item.id, label: item.label, schema, entries });
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, catalogs };
+}
+/**
+ * Node-only: resolves a game's `editorCatalogs` export from Games/<id>/src and validates its shape
+ * before it reaches a live editor session.
+ * @internal
+ */
+export async function loadGameCatalogs(gameId) {
+    const mod = await importOptionalEditorCatalogsModule(gameId);
+    if (mod?.editorCatalogs === undefined)
+        return { ok: true, catalogs: [] };
+    let resolved;
+    try {
+        const value = mod.editorCatalogs;
+        resolved = typeof value === "function" ? value() : value;
+    }
+    catch (error) {
+        return { ok: false, errors: [{ path: "$", message: error instanceof Error ? error.message : String(error) }] };
+    }
+    return decodeGameCatalogs(resolved);
+}

package/dist/mcp/rpcRequest.d.ts

@@ -0,0 +1,22 @@
+import type { EditorBridgeRequest } from "../session.js";
+/** One field-level failure surfaced while decoding an untrusted RPC request. */
+export interface RpcRequestDiagnostic {
+    path: string;
+    message: string;
+}
+/** Result of {@link decodeEditorBridgeRequest}: a request whose `method` is a real one, or the diagnostic that rejected it. */
+export type DecodeRpcRequestResult = {
+    ok: true;
+    request: EditorBridgeRequest;
+} | {
+    ok: false;
+    errors: RpcRequestDiagnostic[];
+};
+/**
+ * Validates an untrusted JSON-decoded RPC payload (from `--rpc` or the HTTP bridge) before it
+ * reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method` name.
+ * Per-method field shape is still enforced by `handle`'s own dispatch, but a garbled or
+ * unknown-method payload is rejected here with a path-specific diagnostic instead of flowing
+ * through on a blind cast.
+ */
+export declare function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult;

package/dist/mcp/rpcRequest.js

@@ -0,0 +1,97 @@
+/** Every `method` an {@link EditorBridgeRequest} may carry — kept in lockstep with the union in `session.ts`. */
+const EDITOR_BRIDGE_METHODS = new Set([
+    "add_foliage",
+    "add_to_collection",
+    "assign_material",
+    "auto_paint",
+    "batch_set_properties",
+    "blend_terrain",
+    "camera_frame",
+    "camera_goto",
+    "clear_runtime_override",
+    "clear_selection",
+    "convert_scatter",
+    "create_collection",
+    "create_prefab",
+    "create_terrain",
+    "delete_collection",
+    "delete_prefab",
+    "detach_prefab_instance",
+    "dispatch",
+    "document_revision",
+    "editor_status",
+    "export_document",
+    "fill_terrain",
+    "get_marker",
+    "get_volume",
+    "hierarchy",
+    "import_document",
+    "insert_prefab",
+    "get_catalog_entry",
+    "list_assets",
+    "list_catalogs",
+    "list_collections",
+    "list_layers",
+    "list_prefabs",
+    "list_selection",
+    "paint_terrain",
+    "perf_report",
+    "place_asset",
+    "pull_document_patches",
+    "pull_runtime_deltas",
+    "push_document_patch",
+    "push_runtime_delta",
+    "redo",
+    "remove_from_collection",
+    "rename_collection",
+    "runtime_get",
+    "runtime_pause",
+    "runtime_resume",
+    "runtime_set",
+    "runtime_snapshot",
+    "runtime_step",
+    "runtime_summary",
+    "scatter_summary",
+    "scene_summary",
+    "sculpt_terrain",
+    "select",
+    "select_collection",
+    "set_catalog_entry",
+    "set_collection_flags",
+    "set_collection_members",
+    "set_marker",
+    "set_meta",
+    "set_mode",
+    "set_note",
+    "set_parent",
+    "set_path",
+    "set_runtime_override",
+    "set_terrain_layers",
+    "set_transform",
+    "set_volume",
+    "terrain_layers",
+    "terrain_materials",
+    "terrain_summary",
+    "undo",
+    "write_back_override",
+]);
+/**
+ * Validates an untrusted JSON-decoded RPC payload (from `--rpc` or the HTTP bridge) before it
+ * reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method` name.
+ * Per-method field shape is still enforced by `handle`'s own dispatch, but a garbled or
+ * unknown-method payload is rejected here with a path-specific diagnostic instead of flowing
+ * through on a blind cast.
+ */
+export function decodeEditorBridgeRequest(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { ok: false, errors: [{ path: "$", message: "expected an RPC request object" }] };
+    }
+    const method = raw.method;
+    if (typeof method !== "string") {
+        return { ok: false, errors: [{ path: "$.method", message: "expected a string" }] };
+    }
+    if (!EDITOR_BRIDGE_METHODS.has(method)) {
+        return { ok: false, errors: [{ path: "$.method", message: `unknown method "${method}"` }] };
+    }
+    return { ok: true, request: raw };
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,8 @@
+/** One MCP tool descriptor — same verbs as the in-browser host RPC. */
+export interface EditorMcpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/** Full set of MCP tools an agent can call to drive the live scene editor. */
+export declare const EDITOR_MCP_TOOLS: readonly EditorMcpTool[];