@jgengine/editor 0.10.0

package/dist/outlinerModel.d.ts

@@ -0,0 +1,76 @@
+import { type EditorDocument } from "@jgengine/core/editor/index";
+/** A distinct label under a kind, backing one or more object ids (×N dedup rows). */
+export interface OutlinerRow {
+    label: string;
+    ids: string[];
+}
+/** A kind group in the "By kind" outliner view. */
+export interface OutlinerGroup {
+    kind: string;
+    rows: OutlinerRow[];
+    total: number;
+}
+interface OutlinerDocument {
+    markers: readonly {
+        id: string;
+        kind: string;
+        label?: string;
+    }[];
+    volumes: readonly {
+        id: string;
+        kind: string;
+        label?: string;
+    }[];
+    paths: readonly {
+        id: string;
+        kind: string;
+        label?: string;
+    }[];
+    annotations: readonly {
+        id: string;
+        text: string;
+    }[];
+}
+/** Groups every object by kind, deduping identical labels into ×N rows.
+ * @internal — outliner rendering helper. */
+export declare function buildOutlinerGroups(document: OutlinerDocument): OutlinerGroup[];
+/** Filters groups by a case-insensitive query against kind and row labels.
+ * @internal — outliner rendering helper. */
+export declare function filterOutlinerGroups(groups: readonly OutlinerGroup[], query: string): OutlinerGroup[];
+/** One rendered outliner line — a kind header, a deduped kind row, or a hierarchy tree node. */
+export type OutlinerFlatRow = {
+    type: "group";
+    key: string;
+    kind: string;
+    total: number;
+    collapsed: boolean;
+} | {
+    type: "kindItem";
+    key: string;
+    kind: string;
+    label: string;
+    ids: string[];
+} | {
+    type: "treeItem";
+    key: string;
+    id: string;
+    label: string;
+    kind: string;
+    depth: number;
+    hasChildren: boolean;
+};
+/** How the outliner is displayed and folded — the state a flat row list is built from. */
+export interface OutlinerViewState {
+    view: "kind" | "tree";
+    query: string;
+    collapsedKinds: Record<string, boolean>;
+    collapsedNodes: Record<string, boolean>;
+}
+/**
+ * Flattens either outliner view into a single uniform row list (headers + rows / nested tree nodes),
+ * honoring the query and collapse state — the input a fixed-height virtual list windows over, so the
+ * DOM never holds more than the visible slice regardless of scene size.
+ * @internal — outliner rendering helper.
+ */
+export declare function flattenOutliner(document: EditorDocument, state: OutlinerViewState): OutlinerFlatRow[];
+export {};

package/dist/outlinerModel.js

@@ -0,0 +1,95 @@
+import { editorChildren, editorRoots } from "@jgengine/core/editor/index";
+/** Groups every object by kind, deduping identical labels into ×N rows.
+ * @internal — outliner rendering helper. */
+export function buildOutlinerGroups(document) {
+    const byKind = new Map();
+    const push = (kind, label, id) => {
+        let labels = byKind.get(kind);
+        if (labels === undefined) {
+            labels = new Map();
+            byKind.set(kind, labels);
+        }
+        const row = labels.get(label);
+        if (row === undefined)
+            labels.set(label, { label, ids: [id] });
+        else
+            row.ids.push(id);
+    };
+    for (const marker of document.markers)
+        push(marker.kind, marker.label ?? marker.id, marker.id);
+    for (const volume of document.volumes)
+        push(volume.kind, volume.label ?? volume.id, volume.id);
+    for (const path of document.paths)
+        push(path.kind, path.label ?? path.id, path.id);
+    for (const note of document.annotations)
+        push("note", note.text.slice(0, 40) || note.id, note.id);
+    return [...byKind.entries()]
+        .map(([kind, labels]) => {
+        const rows = [...labels.values()];
+        return { kind, rows, total: rows.reduce((sum, row) => sum + row.ids.length, 0) };
+    })
+        .sort((a, b) => a.kind.localeCompare(b.kind));
+}
+/** Filters groups by a case-insensitive query against kind and row labels.
+ * @internal — outliner rendering helper. */
+export function filterOutlinerGroups(groups, query) {
+    const normalized = query.trim().toLowerCase();
+    if (normalized.length === 0)
+        return [...groups];
+    return groups
+        .map((group) => {
+        const kindMatches = group.kind.toLowerCase().includes(normalized);
+        const rows = kindMatches
+            ? group.rows
+            : group.rows.filter((row) => row.label.toLowerCase().includes(normalized));
+        return { ...group, rows, total: rows.reduce((sum, row) => sum + row.ids.length, 0) };
+    })
+        .filter((group) => group.rows.length > 0);
+}
+function objectLabels(document) {
+    const label = new Map();
+    for (const marker of document.markers)
+        label.set(marker.id, { label: marker.label ?? marker.id, kind: marker.kind });
+    for (const volume of document.volumes)
+        label.set(volume.id, { label: volume.label ?? volume.id, kind: volume.kind });
+    for (const path of document.paths)
+        label.set(path.id, { label: path.label ?? path.id, kind: path.kind });
+    for (const note of document.annotations)
+        label.set(note.id, { label: note.text.slice(0, 40) || note.id, kind: "note" });
+    return label;
+}
+/**
+ * Flattens either outliner view into a single uniform row list (headers + rows / nested tree nodes),
+ * honoring the query and collapse state — the input a fixed-height virtual list windows over, so the
+ * DOM never holds more than the visible slice regardless of scene size.
+ * @internal — outliner rendering helper.
+ */
+export function flattenOutliner(document, state) {
+    if (state.view === "tree") {
+        const labels = objectLabels(document);
+        const rows = [];
+        const visit = (id, depth) => {
+            const info = labels.get(id) ?? { label: id, kind: "?" };
+            const children = editorChildren(document, id).sort((a, b) => (labels.get(a)?.label ?? a).localeCompare(labels.get(b)?.label ?? b));
+            rows.push({ type: "treeItem", key: id, id, label: info.label, kind: info.kind, depth, hasChildren: children.length > 0 });
+            if (state.collapsedNodes[id] === true)
+                return;
+            for (const child of children)
+                visit(child, depth + 1);
+        };
+        for (const root of editorRoots(document))
+            visit(root, 0);
+        return rows;
+    }
+    const groups = filterOutlinerGroups(buildOutlinerGroups(document), state.query);
+    const rows = [];
+    for (const group of groups) {
+        const collapsed = state.collapsedKinds[group.kind] === true;
+        rows.push({ type: "group", key: `g:${group.kind}`, kind: group.kind, total: group.total, collapsed });
+        if (collapsed)
+            continue;
+        for (const row of group.rows)
+            rows.push({ type: "kindItem", key: `${group.kind}:${row.label}`, kind: group.kind, label: row.label, ids: row.ids });
+    }
+    return rows;
+}

package/dist/perfMarks.d.ts

@@ -0,0 +1,25 @@
+/** Editor-authoring cost the {@link PerfProbe} folds into its sample, separate from frame/sim cost. */
+export type PerfMarkKind = "raycast" | "rebuild";
+/** Rolling averages (ms) of the authoring marks recorded since the last flush. */
+export interface PerfMarkSummary {
+    raycastMs: number;
+    rebuildMs: number;
+    authoringMs: number;
+}
+/**
+ * Accumulates editor-authoring timings (viewport raycasts, preview-mesh rebuilds) and flushes them
+ * as rolling averages — so the perf probe can report authoring cost apart from frame/sim cost, and
+ * "the editor feels laggy" resolves to a number instead of a guess.
+ */
+export interface PerfAccumulator {
+    record(kind: PerfMarkKind, ms: number): void;
+    /** Average ms per mark since the last flush, then reset the window. */
+    flush(): PerfMarkSummary;
+}
+/**
+ * Creates an isolated authoring-perf accumulator.
+ * @internal — the editor's `PerfProbe` folds `editorPerfMarks` into the perf sample; not game-facing.
+ */
+export declare function createPerfAccumulator(): PerfAccumulator;
+/** Shared accumulator the sculpt/paint layer records into and the perf probe flushes each window. */
+export declare const editorPerfMarks: PerfAccumulator;

package/dist/perfMarks.js

@@ -0,0 +1,36 @@
+/**
+ * Creates an isolated authoring-perf accumulator.
+ * @internal — the editor's `PerfProbe` folds `editorPerfMarks` into the perf sample; not game-facing.
+ */
+export function createPerfAccumulator() {
+    let raycastSum = 0;
+    let raycastCount = 0;
+    let rebuildSum = 0;
+    let rebuildCount = 0;
+    const round = (value) => Math.round(value * 1000) / 1000;
+    return {
+        record(kind, ms) {
+            if (!Number.isFinite(ms) || ms < 0)
+                return;
+            if (kind === "raycast") {
+                raycastSum += ms;
+                raycastCount += 1;
+            }
+            else {
+                rebuildSum += ms;
+                rebuildCount += 1;
+            }
+        },
+        flush() {
+            const raycastMs = raycastCount === 0 ? 0 : round(raycastSum / raycastCount);
+            const rebuildMs = rebuildCount === 0 ? 0 : round(rebuildSum / rebuildCount);
+            raycastSum = 0;
+            raycastCount = 0;
+            rebuildSum = 0;
+            rebuildCount = 0;
+            return { raycastMs, rebuildMs, authoringMs: round(raycastMs + rebuildMs) };
+        },
+    };
+}
+/** Shared accumulator the sculpt/paint layer records into and the perf probe flushes each window. */
+export const editorPerfMarks = createPerfAccumulator();

package/dist/session.d.ts

@@ -0,0 +1,400 @@
+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";
+/** RPC request shapes the editor host understands, used by the MCP bridge and UI. */
+export type EditorBridgeRequest = {
+    method: "editor_status";
+} | {
+    method: "set_mode";
+    mode: EditorRunMode;
+} | {
+    method: "perf_report";
+} | {
+    method: "list_layers";
+} | {
+    method: "list_catalogs";
+} | {
+    method: "get_catalog_entry";
+    catalogId: string;
+    entryId: string;
+} | {
+    method: "set_catalog_entry";
+    catalogId: string;
+    entryId: string;
+    patch: Record<string, unknown>;
+    label?: string;
+} | {
+    method: "list_selection";
+} | {
+    method: "get_marker";
+    id: string;
+} | {
+    method: "get_volume";
+    id: string;
+} | {
+    method: "set_transform";
+    id: string;
+    x?: number;
+    y?: number;
+    z?: number;
+    rotationY?: number;
+} | {
+    method: "set_volume";
+    id: string;
+    radius?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+    z?: number;
+} | {
+    method: "set_path";
+    id: string;
+    kind?: string;
+    width?: number;
+    color?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+} | {
+    method: "set_marker";
+    id: string;
+    kind?: string;
+    color?: string;
+    label?: string;
+    rotationY?: number;
+    meta?: Record<string, unknown>;
+} | {
+    method: "set_note";
+    id: string;
+    text?: string;
+    meta?: Record<string, unknown>;
+} | {
+    method: "set_meta";
+    id: string;
+    patch: Record<string, unknown>;
+} | {
+    method: "select";
+    ids: string[];
+} | {
+    method: "clear_selection";
+} | {
+    method: "camera_goto";
+    id?: string;
+    x?: number;
+    y?: number;
+    z?: number;
+} | {
+    method: "camera_frame";
+} | {
+    method: "scene_summary";
+} | {
+    method: "export_document";
+} | {
+    method: "import_document";
+    json: string;
+} | {
+    method: "dispatch";
+    command: EditorCommand;
+} | {
+    method: "undo";
+} | {
+    method: "redo";
+} | {
+    method: "list_assets";
+} | {
+    method: "place_asset";
+    id: string;
+    kind?: string;
+    x?: number;
+    y?: number;
+    z?: number;
+} | {
+    method: "create_terrain";
+    width?: number;
+    depth?: number;
+    cellSize?: number;
+    centerX?: number;
+    centerZ?: number;
+} | {
+    method: "sculpt_terrain";
+    mode: TerraformMode;
+    x: number;
+    z: number;
+    radius?: number;
+    strength?: number;
+    target?: number;
+    toX?: number;
+    toZ?: number;
+    seed?: number;
+    shape?: "circle" | "square";
+} | {
+    method: "terrain_summary";
+} | {
+    method: "paint_terrain";
+    surface: string;
+    x: number;
+    z: number;
+    radius?: number;
+    shape?: "circle" | "square";
+} | {
+    method: "fill_terrain";
+    surface: string | null;
+} | {
+    method: "auto_paint";
+    surface: string;
+    minSlope?: number;
+    maxSlope?: number;
+    minHeight?: number;
+    maxHeight?: number;
+} | {
+    method: "terrain_materials";
+} | {
+    method: "terrain_layers";
+} | {
+    method: "set_terrain_layers";
+    layers: TerrainMaterialLayer[];
+} | {
+    method: "blend_terrain";
+    surface: string;
+    x: number;
+    z: number;
+    radius?: number;
+    strength?: number;
+    shape?: "circle" | "square";
+} | {
+    method: "convert_scatter";
+    pathId: string;
+} | {
+    method: "add_foliage";
+    points: {
+        x: number;
+        z: number;
+    }[];
+    density?: number;
+    item?: string;
+    seed?: string;
+    minSpacing?: number;
+} | {
+    method: "scatter_summary";
+} | {
+    method: "set_parent";
+    ids: string[];
+    parentId: string | null;
+} | {
+    method: "hierarchy";
+} | {
+    method: "list_prefabs";
+} | {
+    method: "create_prefab";
+    id: string;
+    name: string;
+    ids: string[];
+} | {
+    method: "insert_prefab";
+    prefabId: string;
+    x?: number;
+    y?: number;
+    z?: number;
+} | {
+    method: "detach_prefab_instance";
+    instanceId: string;
+} | {
+    method: "delete_prefab";
+    prefabId: string;
+} | {
+    method: "list_collections";
+} | {
+    method: "create_collection";
+    id: string;
+    name: string;
+    memberIds?: string[];
+} | {
+    method: "rename_collection";
+    id: string;
+    name: string;
+} | {
+    method: "delete_collection";
+    id: string;
+} | {
+    method: "set_collection_members";
+    id: string;
+    memberIds: string[];
+} | {
+    method: "add_to_collection";
+    id: string;
+    ids: string[];
+} | {
+    method: "remove_from_collection";
+    id: string;
+    ids: string[];
+} | {
+    method: "set_collection_flags";
+    id: string;
+    color?: string;
+    locked?: boolean;
+    visible?: boolean;
+} | {
+    method: "select_collection";
+    id: string;
+} | {
+    method: "batch_set_properties";
+    ids: string[];
+    color?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+} | {
+    method: "assign_material";
+    ids: string[];
+    materialId: string;
+} | {
+    method: "push_document_patch";
+    patch: DocumentPatch;
+    force?: boolean;
+} | {
+    method: "pull_document_patches";
+    sinceRevision?: number;
+} | {
+    method: "document_revision";
+    includeDocument?: boolean;
+} | {
+    method: "push_runtime_delta";
+    at?: number;
+    entities?: RuntimeEntityState[];
+    removeIds?: string[];
+    tunables?: Record<string, unknown>;
+} | {
+    method: "pull_runtime_deltas";
+    sinceSeq?: number;
+    includeSnapshot?: boolean;
+} | {
+    method: "runtime_snapshot";
+} | {
+    method: "runtime_summary";
+} | {
+    method: "runtime_get";
+    id: string;
+    path?: string;
+} | {
+    method: "runtime_set";
+    id: string;
+    path?: string;
+    value?: unknown;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY?: number;
+    values?: Record<string, unknown>;
+    writeBack?: boolean;
+} | {
+    method: "runtime_pause";
+} | {
+    method: "runtime_resume";
+} | {
+    method: "runtime_step";
+    frames?: number;
+} | {
+    method: "set_runtime_override";
+    entity: RuntimeEntityState;
+} | {
+    method: "clear_runtime_override";
+    id: string;
+} | {
+    method: "write_back_override";
+    id: string;
+};
+/** Result envelope returned by every editor host RPC call. */
+export type EditorBridgeResponse = {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+};
+/** A placeable asset entry offered in the editor's asset browser. */
+export interface EditorAssetInfo {
+    id: string;
+    label: string;
+    kind: string;
+    url?: string;
+}
+/** Rolling frame-rate sample published by the in-canvas PerfProbe. */
+export interface EditorPerfSample {
+    fps: number;
+    frameMs: number;
+    drawCalls: number;
+    triangles: number;
+    sampledAt: number;
+    /** 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;
+}
+/** The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC. */
+export interface EditorHostApi {
+    gameId: string;
+    getSession(): EditorSession;
+    /** Two-way document/runtime live-sync bus shared with AuthoredScene and the bridge. */
+    getLiveSync(): DocumentLiveSync;
+    getVisibility(): EditorKindVisibility;
+    setVisibility(next: EditorKindVisibility): void;
+    subscribeVisibility(listener: () => void): () => void;
+    getFocusTarget(): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    setFocusTarget(target: {
+        x: number;
+        y: number;
+        z: number;
+    } | null): void;
+    subscribeFocus(listener: (target: {
+        x: number;
+        y: number;
+        z: number;
+    } | null) => void): () => void;
+    getAssets(): readonly EditorAssetInfo[];
+    setAssets(assets: readonly EditorAssetInfo[]): void;
+    getCatalogDefinitions(): readonly EditorCatalogDefinition[];
+    getPerf(): EditorPerfSample | null;
+    setPerf(sample: EditorPerfSample): 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;
+    subscribePlayControl(listener: (play: RuntimePlayControl) => void): () => void;
+    handle(request: EditorBridgeRequest): EditorBridgeResponse;
+}
+/** Publishes an editor host globally so devtools and MCP agents can reach it; returns a cleanup fn. */
+export declare function installEditorHost(api: EditorHostApi): () => void;
+/** Retrieves the globally installed editor host, or null if none is mounted. @internal */
+export declare function getEditorHost(): EditorHostApi | null;
+/** Builds and installs an editor host for a game: session, visibility, assets, and RPC handling. @internal */
+export declare function createEditorHost(options: {
+    gameId: string;
+    layers: EditorLayersInput | undefined;
+    /** Game-exported gameplay catalog definitions (schemas + defaults); seeds document.catalogs. */
+    catalogs?: readonly EditorCatalogDefinition[];
+    assets?: readonly EditorAssetInfo[];
+    onFocus?: (target: {
+        x: number;
+        y: number;
+        z: number;
+    } | null) => void;
+}): {
+    session: EditorSession;
+    api: EditorHostApi;
+    dispose: () => void;
+};
+/** The full authored scene: every marker, volume, path, and note for a game. */
+export type { EditorDocument };
+/** Per-kind show/hide flags for the editor's layer panel. */
+export type { EditorKindVisibility };
+/** Stateful, undoable handle for driving scene edits from UI or an MCP agent. */
+export type { EditorSession };
+/** The document plus current selection at a point in editor history. */
+export type { EditorSessionState };