@jgengine/editor 0.11.0 → 0.12.0

package/dist/handlers/catalogs.js

@@ -0,0 +1,137 @@
+import { findEditorCatalog, findEditorCatalogEntry } from "@jgengine/core/editor/index";
+import { parseParams, validateParams } from "@jgengine/core/scene/sceneKinds";
+/** Gameplay data catalog verbs (list / get / merge-patch / add / remove rows). */
+export const catalogHandlers = {
+    list_catalogs: (ctx) => {
+        const state = ctx.session.getState();
+        const catalogs = ctx.catalogDefinitions.map((definition) => {
+            const data = findEditorCatalog(state.document, definition.id);
+            return {
+                id: definition.id,
+                label: definition.label,
+                schema: definition.schema,
+                entryCount: data?.entries.length ?? definition.entries.length,
+                entries: (data?.entries ?? definition.entries).map((entry) => ({ id: entry.id, label: entry.label })),
+            };
+        });
+        return { ok: true, result: { catalogs } };
+    },
+    get_catalog_entry: (ctx, request) => {
+        const definition = ctx.catalogById.get(request.catalogId);
+        if (definition === undefined)
+            return { ok: false, error: `catalog not found: ${request.catalogId}` };
+        const entry = findEditorCatalogEntry(ctx.session.getState().document, request.catalogId, request.entryId);
+        if (entry === undefined)
+            return { ok: false, error: `catalog entry not found: ${request.catalogId}/${request.entryId}` };
+        return { ok: true, result: { catalogId: request.catalogId, label: definition.label, schema: definition.schema, entry } };
+    },
+    set_catalog_entry: (ctx, request) => {
+        const definition = ctx.catalogById.get(request.catalogId);
+        if (definition === undefined)
+            return { ok: false, error: `catalog not found: ${request.catalogId}` };
+        const current = findEditorCatalogEntry(ctx.session.getState().document, request.catalogId, request.entryId);
+        if (current === undefined)
+            return { ok: false, error: `catalog entry not found: ${request.catalogId}/${request.entryId}` };
+        const merged = { ...current.meta, ...request.patch };
+        const invalid = validateParams(definition.schema, merged);
+        if (invalid.length > 0) {
+            return { ok: false, error: `invalid ${request.catalogId} params: ${invalid.map((issue) => `${issue.key} (${issue.message})`).join(", ")}` };
+        }
+        const coalesceKey = Object.keys(request.patch).length === 1
+            ? `catalog:${request.catalogId}:${request.entryId}:${Object.keys(request.patch)[0]}`
+            : `catalog:${request.catalogId}:${request.entryId}`;
+        const before = ctx.session.getState();
+        const state = ctx.session.dispatch({
+            type: "setCatalogEntry",
+            catalogId: request.catalogId,
+            entryId: request.entryId,
+            patch: { meta: merged, ...(request.label === undefined ? {} : { label: request.label }) },
+        }, { coalesce: coalesceKey });
+        if (state === before) {
+            return { ok: false, error: `set_catalog_entry rejected: ${request.catalogId}/${request.entryId}` };
+        }
+        const entry = findEditorCatalogEntry(state.document, request.catalogId, request.entryId);
+        return { ok: true, result: { catalogId: request.catalogId, entry } };
+    },
+    add_catalog_entry: (ctx, request) => {
+        const definition = ctx.catalogById.get(request.catalogId);
+        if (definition === undefined)
+            return { ok: false, error: `catalog not found: ${request.catalogId}` };
+        const entryId = request.entryId.trim();
+        if (entryId.length === 0)
+            return { ok: false, error: "add_catalog_entry: entryId is required" };
+        if (findEditorCatalogEntry(ctx.session.getState().document, request.catalogId, entryId) !== undefined) {
+            return { ok: false, error: `catalog entry already exists: ${request.catalogId}/${entryId}` };
+        }
+        // Seed a new row's meta from the schema defaults, then overlay any provided values, so the
+        // row is schema-valid the moment it lands — the same contract set_catalog_entry enforces.
+        const seeded = parseParams(definition.schema, request.meta);
+        const meta = { ...seeded, ...request.meta };
+        const invalid = validateParams(definition.schema, meta);
+        if (invalid.length > 0) {
+            return { ok: false, error: `invalid ${request.catalogId} params: ${invalid.map((issue) => `${issue.key} (${issue.message})`).join(", ")}` };
+        }
+        ctx.session.dispatch({
+            type: "addCatalogEntry",
+            catalogId: request.catalogId,
+            entry: { id: entryId, ...(request.label === undefined ? {} : { label: request.label }), meta },
+        });
+        const entry = findEditorCatalogEntry(ctx.session.getState().document, request.catalogId, entryId);
+        return { ok: true, result: { catalogId: request.catalogId, entry } };
+    },
+    remove_catalog_entry: (ctx, request) => {
+        const definition = ctx.catalogById.get(request.catalogId);
+        if (definition === undefined)
+            return { ok: false, error: `catalog not found: ${request.catalogId}` };
+        const before = ctx.session.getState();
+        const state = ctx.session.dispatch({ type: "removeCatalogEntry", catalogId: request.catalogId, entryId: request.entryId });
+        if (state === before) {
+            return { ok: false, error: `catalog entry not found: ${request.catalogId}/${request.entryId}` };
+        }
+        return { ok: true, result: { catalogId: request.catalogId, entryId: request.entryId } };
+    },
+    add_catalog: (ctx, request) => {
+        const catalogId = request.catalogId.trim();
+        if (catalogId.length === 0)
+            return { ok: false, error: "add_catalog: catalogId is required" };
+        if (ctx.catalogById.has(catalogId) || findEditorCatalog(ctx.session.getState().document, catalogId) !== undefined) {
+            return { ok: false, error: `catalog already exists: ${catalogId}` };
+        }
+        // Default to an empty schema so the catalog is a document-authored one — carried on the document,
+        // addressable via list_catalogs, and ready for set_catalog_schema to add fields.
+        const before = ctx.session.getState();
+        const state = ctx.session.dispatch({
+            type: "addCatalog",
+            id: catalogId,
+            ...(request.label === undefined ? {} : { label: request.label }),
+            schema: request.schema ?? { fields: [] },
+        });
+        if (state === before)
+            return { ok: false, error: `add_catalog rejected: ${catalogId}` };
+        const catalog = findEditorCatalog(state.document, catalogId);
+        return { ok: true, result: { catalogId, catalog } };
+    },
+    remove_catalog: (ctx, request) => {
+        const before = ctx.session.getState();
+        const state = ctx.session.dispatch({ type: "removeCatalog", id: request.catalogId });
+        if (state === before)
+            return { ok: false, error: `catalog not found: ${request.catalogId}` };
+        return { ok: true, result: { catalogId: request.catalogId } };
+    },
+    set_catalog_schema: (ctx, request) => {
+        if (findEditorCatalog(ctx.session.getState().document, request.catalogId) === undefined) {
+            return { ok: false, error: `catalog not found: ${request.catalogId}` };
+        }
+        const before = ctx.session.getState();
+        const state = ctx.session.dispatch({
+            type: "setCatalogSchema",
+            id: request.catalogId,
+            schema: request.schema,
+            ...(request.label === undefined ? {} : { label: request.label }),
+        });
+        if (state === before)
+            return { ok: false, error: `set_catalog_schema rejected: ${request.catalogId}` };
+        const catalog = findEditorCatalog(state.document, request.catalogId);
+        return { ok: true, result: { catalogId: request.catalogId, entries: catalog?.entries ?? [] } };
+    },
+};

package/dist/handlers/collections.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Named collection / selection-set verbs. */
+export declare const collectionHandlers: Pick<HandlerTable, "list_collections" | "create_collection" | "rename_collection" | "delete_collection" | "set_collection_members" | "add_to_collection" | "remove_from_collection" | "set_collection_flags" | "select_collection">;

package/dist/handlers/collections.js

@@ -0,0 +1,57 @@
+import { findEditorCollection } from "@jgengine/core/editor/index";
+/** Runs `fn` with the named collection, or short-circuits with an honest not-found response. */
+function withCollection(ctx, id, fn) {
+    const collection = findEditorCollection(ctx.session.getState().document, id);
+    if (collection === undefined)
+        return { ok: false, error: `collection not found: ${id}` };
+    return fn(collection);
+}
+/** Named collection / selection-set verbs. */
+export const collectionHandlers = {
+    list_collections: (ctx) => ({ ok: true, result: { collections: ctx.session.getState().document.collections } }),
+    create_collection: (ctx, request) => {
+        ctx.session.dispatch({
+            type: "createCollection",
+            id: request.id,
+            name: request.name,
+            ...(request.memberIds === undefined ? {} : { memberIds: request.memberIds }),
+        });
+        return { ok: true, result: findEditorCollection(ctx.session.getState().document, request.id) };
+    },
+    rename_collection: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({ type: "renameCollection", id: request.id, name: request.name });
+        return { ok: true, result: findEditorCollection(ctx.session.getState().document, request.id) };
+    }),
+    delete_collection: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({ type: "deleteCollection", id: request.id });
+        return { ok: true, result: { collections: ctx.session.getState().document.collections } };
+    }),
+    set_collection_members: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({ type: "setCollectionMembers", id: request.id, memberIds: request.memberIds });
+        return { ok: true, result: findEditorCollection(ctx.session.getState().document, request.id) };
+    }),
+    add_to_collection: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({ type: "addToCollection", id: request.id, ids: request.ids });
+        return { ok: true, result: findEditorCollection(ctx.session.getState().document, request.id) };
+    }),
+    remove_from_collection: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({ type: "removeFromCollection", id: request.id, ids: request.ids });
+        return { ok: true, result: findEditorCollection(ctx.session.getState().document, request.id) };
+    }),
+    set_collection_flags: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({
+            type: "setCollectionFlags",
+            id: request.id,
+            patch: {
+                ...(request.color === undefined ? {} : { color: request.color }),
+                ...(request.locked === undefined ? {} : { locked: request.locked }),
+                ...(request.visible === undefined ? {} : { visible: request.visible }),
+            },
+        });
+        return { ok: true, result: findEditorCollection(ctx.session.getState().document, request.id) };
+    }),
+    select_collection: (ctx, request) => withCollection(ctx, request.id, () => {
+        ctx.session.dispatch({ type: "selectCollection", id: request.id });
+        return { ok: true, result: { selection: ctx.session.getState().selection } };
+    }),
+};

package/dist/handlers/context.d.ts

@@ -0,0 +1,36 @@
+import type { DocumentLiveSync, EditorCatalogDefinition, EditorCommand, EditorSession, EditorSessionState } from "@jgengine/core/editor/index";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+import type { EditorBridgeRequest, EditorBridgeResponse, EditorHostApi } from "../session.js";
+/** Outcome of a guarded dispatch: whether it mutated the session, plus the resulting state. */
+export interface DispatchOutcome {
+    applied: boolean;
+    state: EditorSessionState;
+}
+/**
+ * Everything a per-domain RPC handler needs from the host. Mutable host state (focus, mode, play
+ * control, assets, visibility, perf) is reached through `api`'s getters/setters so handlers stay
+ * closure-free and independently testable; `dispatchGuarded` and the catalog lookups are threaded in
+ * because they are built once when the host is constructed.
+ */
+export interface HandlerContext {
+    api: EditorHostApi;
+    session: EditorSession;
+    liveSync: DocumentLiveSync;
+    gameId: string;
+    catalogDefinitions: readonly EditorCatalogDefinition[];
+    catalogById: ReadonlyMap<string, EditorCatalogDefinition>;
+    dispatchGuarded: (command: EditorCommand) => DispatchOutcome;
+    /** The live composed ground field from the mounted viewport (null when headless). Used by `bake_minimap`. */
+    getTerrainSampler: () => TerrainField | null;
+}
+/** One method's handler, with `request` narrowed to that method's union member. */
+export type HandlerFor<M extends EditorBridgeRequest["method"]> = (ctx: HandlerContext, request: Extract<EditorBridgeRequest, {
+    method: M;
+}>) => EditorBridgeResponse;
+/**
+ * The full method → handler map. Spreading the per-domain tables into a value of this type is the
+ * lockstep guarantee that every union method has exactly one handler: a missing verb fails to compile.
+ */
+export type HandlerTable = {
+    [M in EditorBridgeRequest["method"]]: HandlerFor<M>;
+};

package/dist/handlers/context.js

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

package/dist/handlers/document.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export declare const documentHandlers: Pick<HandlerTable, "editor_status" | "set_mode" | "perf_report" | "list_layers" | "list_selection" | "get_marker" | "get_volume" | "set_transform" | "set_volume" | "set_path" | "set_marker" | "set_note" | "set_meta" | "apply_preset" | "select" | "clear_selection" | "camera_goto" | "camera_frame" | "scene_summary" | "export_document" | "import_document" | "dispatch" | "undo" | "redo" | "list_assets" | "place_asset" | "batch_set_properties" | "assign_material" | "set_object_flags">;

package/dist/handlers/document.js

@@ -0,0 +1,350 @@
+import { editorDocumentBounds, listEditorKinds, summarizeEditorSession, } from "@jgengine/core/editor/index";
+import { resolvePlaceAsset, toEditorMarker } from "@jgengine/core/world/placeAsset";
+import { findSchemaPreset, getSceneKind, validateParams } from "@jgengine/core/scene/sceneKinds";
+import { EDITOR_RUN_MODES } from "../session.js";
+/** True when any of `ids` names a placeable object (marker/volume/path/note) in the document — used
+ * to reject batch mutations that would match nothing, so the caller hears an honest `ok:false`. */
+function documentHasAnyId(doc, ids) {
+    if (ids.length === 0)
+        return false;
+    const wanted = new Set(ids);
+    return (doc.markers.some((m) => wanted.has(m.id)) ||
+        doc.volumes.some((v) => wanted.has(v.id)) ||
+        doc.paths.some((p) => wanted.has(p.id)) ||
+        doc.annotations.some((n) => wanted.has(n.id)));
+}
+/** Which document collection an object lives in, plus its current kind + meta — for generic `set_meta`. */
+function findMetaTarget(doc, id) {
+    const marker = doc.markers.find((m) => m.id === id);
+    if (marker !== undefined)
+        return { target: "marker", kind: marker.kind, meta: marker.meta };
+    const volume = doc.volumes.find((v) => v.id === id);
+    if (volume !== undefined)
+        return { target: "volume", kind: volume.kind, meta: volume.meta };
+    const path = doc.paths.find((p) => p.id === id);
+    if (path !== undefined)
+        return { target: "path", kind: path.kind, meta: path.meta };
+    const note = doc.annotations.find((n) => n.id === id);
+    if (note !== undefined)
+        return { target: "note", kind: "note", meta: note.meta };
+    return null;
+}
+/** Validates a merged meta bag against a registered kind's schema; returns an error string or null. */
+function validateMetaForKind(kind, meta) {
+    const definition = getSceneKind(kind);
+    if (definition === undefined || meta === undefined)
+        return null;
+    const issues = validateParams(definition.schema, meta);
+    if (issues.length === 0)
+        return null;
+    return `invalid ${kind} params: ${issues.map((issue) => `${issue.key} (${issue.message})`).join(", ")}`;
+}
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export const documentHandlers = {
+    editor_status: (ctx) => ({
+        ok: true,
+        result: {
+            gameId: ctx.gameId,
+            connected: true,
+            ...summarizeEditorSession(ctx.session.getState()),
+            canUndo: ctx.session.canUndo(),
+            canRedo: ctx.session.canRedo(),
+            perf: ctx.api.getPerf(),
+            mode: ctx.api.getMode(),
+        },
+    }),
+    set_mode: (ctx, request) => {
+        if (!EDITOR_RUN_MODES.includes(request.mode)) {
+            return { ok: false, error: `unknown mode: ${String(request.mode)} (edit | walk | play | hud)` };
+        }
+        ctx.api.setMode(request.mode);
+        return { ok: true, result: { mode: request.mode } };
+    },
+    perf_report: (ctx) => {
+        const devtoolsGlobal = globalThis.__JG_DEVTOOLS;
+        if (devtoolsGlobal?.snapshot === undefined) {
+            return { ok: false, error: "engine devtools not mounted — open the browser editor (F2+D panel) first" };
+        }
+        return { ok: true, result: { perf: ctx.api.getPerf(), report: devtoolsGlobal.snapshot() } };
+    },
+    list_layers: (ctx) => {
+        const state = ctx.session.getState();
+        return { ok: true, result: { kinds: listEditorKinds(state.document), visibility: ctx.api.getVisibility(), document: state.document } };
+    },
+    list_selection: (ctx) => ({ ok: true, result: { selection: ctx.session.getState().selection } }),
+    get_marker: (ctx, request) => {
+        const marker = ctx.session.getState().document.markers.find((m) => m.id === request.id);
+        return marker === undefined ? { ok: false, error: `marker not found: ${request.id}` } : { ok: true, result: marker };
+    },
+    get_volume: (ctx, request) => {
+        const volume = ctx.session.getState().document.volumes.find((v) => v.id === request.id);
+        return volume === undefined ? { ok: false, error: `volume not found: ${request.id}` } : { ok: true, result: volume };
+    },
+    set_transform: (ctx, request) => {
+        const marker = ctx.session.getState().document.markers.find((m) => m.id === request.id);
+        const volume = ctx.session.getState().document.volumes.find((v) => v.id === request.id);
+        const base = marker?.position ?? volume?.center;
+        if (base === undefined)
+            return { ok: false, error: `id not found: ${request.id}` };
+        const { applied, state } = ctx.dispatchGuarded({
+            type: "setTransform",
+            id: request.id,
+            position: { x: request.x ?? base.x, y: request.y ?? base.y, z: request.z ?? base.z },
+            ...(request.rotationY === undefined ? {} : { rotationY: request.rotationY }),
+        });
+        if (!applied)
+            return { ok: false, error: `set_transform rejected: ${request.id} is locked` };
+        return { ok: true, result: summarizeEditorSession(state) };
+    },
+    set_volume: (ctx, request) => {
+        const volume = ctx.session.getState().document.volumes.find((v) => v.id === request.id);
+        if (volume === undefined)
+            return { ok: false, error: `volume not found: ${request.id}` };
+        ctx.session.dispatch({
+            type: "setVolume",
+            id: request.id,
+            patch: {
+                ...(request.radius === undefined ? {} : { radius: request.radius }),
+                ...(request.height === undefined ? {} : { height: request.height }),
+                ...(request.x === undefined && request.y === undefined && request.z === undefined
+                    ? {}
+                    : { center: { x: request.x ?? volume.center.x, y: request.y ?? volume.center.y, z: request.z ?? volume.center.z } }),
+            },
+        });
+        return { ok: true, result: ctx.session.getState().document.volumes.find((v) => v.id === request.id) };
+    },
+    set_path: (ctx, request) => {
+        const path = ctx.session.getState().document.paths.find((p) => p.id === request.id);
+        if (path === undefined)
+            return { ok: false, error: `path not found: ${request.id}` };
+        const merged = request.meta === undefined ? undefined : { ...path.meta, ...request.meta };
+        const invalid = validateMetaForKind(request.kind ?? path.kind, merged);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
+        ctx.session.dispatch({
+            type: "setPath",
+            id: request.id,
+            patch: {
+                ...(request.kind === undefined ? {} : { kind: request.kind }),
+                ...(request.width === undefined ? {} : { width: request.width }),
+                ...(request.color === undefined ? {} : { color: request.color }),
+                ...(request.label === undefined ? {} : { label: request.label }),
+                ...(merged === undefined ? {} : { meta: merged }),
+            },
+        });
+        return { ok: true, result: ctx.session.getState().document.paths.find((p) => p.id === request.id) };
+    },
+    set_marker: (ctx, request) => {
+        const marker = ctx.session.getState().document.markers.find((m) => m.id === request.id);
+        if (marker === undefined)
+            return { ok: false, error: `marker not found: ${request.id}` };
+        const merged = request.meta === undefined ? undefined : { ...marker.meta, ...request.meta };
+        const invalid = validateMetaForKind(request.kind ?? marker.kind, merged);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
+        ctx.session.dispatch({
+            type: "setMarker",
+            id: request.id,
+            patch: {
+                ...(request.kind === undefined ? {} : { kind: request.kind }),
+                ...(request.color === undefined ? {} : { color: request.color }),
+                ...(request.label === undefined ? {} : { label: request.label }),
+                ...(request.rotationY === undefined ? {} : { rotationY: request.rotationY }),
+                ...(merged === undefined ? {} : { meta: merged }),
+            },
+        });
+        return { ok: true, result: ctx.session.getState().document.markers.find((m) => m.id === request.id) };
+    },
+    set_note: (ctx, request) => {
+        const note = ctx.session.getState().document.annotations.find((n) => n.id === request.id);
+        if (note === undefined)
+            return { ok: false, error: `note not found: ${request.id}` };
+        const merged = request.meta === undefined ? undefined : { ...note.meta, ...request.meta };
+        ctx.session.dispatch({
+            type: "setNote",
+            id: request.id,
+            patch: { ...(request.text === undefined ? {} : { text: request.text }), ...(merged === undefined ? {} : { meta: merged }) },
+        });
+        return { ok: true, result: ctx.session.getState().document.annotations.find((n) => n.id === request.id) };
+    },
+    set_meta: (ctx, request) => {
+        const target = findMetaTarget(ctx.session.getState().document, request.id);
+        if (target === null)
+            return { ok: false, error: `object not found: ${request.id}` };
+        const merged = { ...target.meta, ...request.patch };
+        const invalid = validateMetaForKind(target.kind, merged);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
+        ctx.session.dispatch(target.target === "marker"
+            ? { type: "setMarker", id: request.id, patch: { meta: merged } }
+            : target.target === "volume"
+                ? { type: "setVolume", id: request.id, patch: { meta: merged } }
+                : target.target === "path"
+                    ? { type: "setPath", id: request.id, patch: { meta: merged } }
+                    : { type: "setNote", id: request.id, patch: { meta: merged } });
+        return { ok: true, result: { id: request.id, kind: target.kind, meta: merged } };
+    },
+    apply_preset: (ctx, request) => {
+        const target = findMetaTarget(ctx.session.getState().document, request.id);
+        if (target === null)
+            return { ok: false, error: `object not found: ${request.id}` };
+        const definition = getSceneKind(target.kind);
+        if (definition === undefined)
+            return { ok: false, error: `kind "${target.kind}" has no registered schema` };
+        const preset = findSchemaPreset(definition.schema, request.preset);
+        if (preset === undefined) {
+            const available = (definition.schema.presets ?? []).map((entry) => entry.id).join(", ") || "none";
+            return { ok: false, error: `unknown preset "${request.preset}" for kind "${target.kind}" (available: ${available})` };
+        }
+        const merged = { ...target.meta, ...preset.values };
+        const invalid = validateMetaForKind(target.kind, merged);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
+        ctx.session.dispatch(target.target === "marker"
+            ? { type: "setMarker", id: request.id, patch: { meta: merged } }
+            : target.target === "volume"
+                ? { type: "setVolume", id: request.id, patch: { meta: merged } }
+                : target.target === "path"
+                    ? { type: "setPath", id: request.id, patch: { meta: merged } }
+                    : { type: "setNote", id: request.id, patch: { meta: merged } });
+        return { ok: true, result: { id: request.id, kind: target.kind, preset: preset.id, meta: merged } };
+    },
+    select: (ctx, request) => {
+        ctx.session.dispatch({ type: "select", ids: request.ids });
+        return { ok: true, result: { selection: ctx.session.getState().selection } };
+    },
+    clear_selection: (ctx) => {
+        ctx.session.dispatch({ type: "clearSelection" });
+        return { ok: true, result: { selection: [] } };
+    },
+    camera_goto: (ctx, request) => {
+        if (request.id !== undefined) {
+            const state = ctx.session.getState();
+            const marker = state.document.markers.find((m) => m.id === request.id);
+            const volume = state.document.volumes.find((v) => v.id === request.id);
+            const point = marker?.position ?? volume?.center;
+            if (point === undefined)
+                return { ok: false, error: `id not found: ${request.id}` };
+            ctx.api.setFocusTarget({ ...point });
+            ctx.session.dispatch({ type: "select", ids: [request.id] });
+            return { ok: true, result: { target: point } };
+        }
+        if (request.x === undefined || request.z === undefined) {
+            return { ok: false, error: "camera_goto requires id or x/z" };
+        }
+        const target = { x: request.x, y: request.y ?? 0, z: request.z };
+        ctx.api.setFocusTarget(target);
+        return { ok: true, result: { target } };
+    },
+    camera_frame: (ctx) => {
+        const bounds = editorDocumentBounds(ctx.session.getState().document);
+        if (bounds === null)
+            return { ok: false, error: "document is empty" };
+        const target = {
+            x: (bounds.min.x + bounds.max.x) / 2,
+            y: (bounds.min.y + bounds.max.y) / 2,
+            z: (bounds.min.z + bounds.max.z) / 2,
+        };
+        ctx.api.setFocusTarget(target);
+        return { ok: true, result: { target, bounds } };
+    },
+    scene_summary: (ctx) => ({
+        ok: true,
+        result: {
+            gameId: ctx.gameId,
+            kinds: listEditorKinds(ctx.session.getState().document),
+            ...summarizeEditorSession(ctx.session.getState()),
+            bounds: editorDocumentBounds(ctx.session.getState().document),
+        },
+    }),
+    export_document: (ctx) => ({ ok: true, result: { json: ctx.session.exportJson(true) } }),
+    import_document: (ctx, request) => {
+        ctx.session.dispatch({ type: "importJson", json: request.json });
+        return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
+    },
+    dispatch: (ctx, request) => {
+        const { applied, state } = ctx.dispatchGuarded(request.command);
+        if (!applied)
+            return { ok: false, error: `${request.command.type} rejected: no effect` };
+        return { ok: true, result: summarizeEditorSession(state) };
+    },
+    undo: (ctx) => {
+        const { applied, state } = ctx.dispatchGuarded({ type: "undo" });
+        if (!applied)
+            return { ok: false, error: "nothing to undo" };
+        return { ok: true, result: summarizeEditorSession(state) };
+    },
+    redo: (ctx) => {
+        const { applied, state } = ctx.dispatchGuarded({ type: "redo" });
+        if (!applied)
+            return { ok: false, error: "nothing to redo" };
+        return { ok: true, result: summarizeEditorSession(state) };
+    },
+    list_assets: (ctx) => ({ ok: true, result: { assets: ctx.api.getAssets() } }),
+    place_asset: (ctx, request) => {
+        const focus = ctx.api.getFocusTarget() ?? { x: 0, y: 0, z: 0 };
+        const asset = ctx.api.getAssets().find((entry) => entry.id === request.id);
+        const placed = resolvePlaceAsset({
+            assetId: request.id,
+            position: { x: request.x ?? focus.x, y: request.y ?? focus.y, z: request.z ?? focus.z },
+            kind: request.kind,
+            knownKind: asset?.kind,
+            knownLabel: asset?.label,
+            knownUrl: asset?.url,
+        });
+        const placedMarker = toEditorMarker(placed);
+        // URL-backed catalog models need a first-class catalogId so AuthoredObjects places the mesh;
+        // generator assets keep meta.assetId only (no url) and render through AuthoredGenerators.
+        const marker = typeof asset?.url === "string" && asset.url.length > 0
+            ? { ...placedMarker, catalogId: request.id }
+            : placedMarker;
+        ctx.session.dispatch({ type: "addMarker", marker });
+        return {
+            ok: true,
+            result: {
+                id: marker.id,
+                position: marker.position,
+                marker: ctx.session.getState().document.markers.find((entry) => entry.id === marker.id),
+            },
+        };
+    },
+    batch_set_properties: (ctx, request) => {
+        if (!documentHasAnyId(ctx.session.getState().document, request.ids)) {
+            return { ok: false, error: "batch_set_properties matched no objects" };
+        }
+        ctx.session.dispatch({
+            type: "batchSetProperties",
+            ids: request.ids,
+            patch: {
+                ...(request.color === undefined ? {} : { color: request.color }),
+                ...(request.label === undefined ? {} : { label: request.label }),
+                ...(request.meta === undefined ? {} : { meta: request.meta }),
+            },
+        });
+        return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
+    },
+    set_object_flags: (ctx, request) => {
+        if (!documentHasAnyId(ctx.session.getState().document, request.ids)) {
+            return { ok: false, error: "set_object_flags matched no objects" };
+        }
+        if (request.locked === undefined && request.hidden === undefined) {
+            return { ok: false, error: "set_object_flags requires locked and/or hidden" };
+        }
+        ctx.session.dispatch({
+            type: "setObjectFlags",
+            ids: request.ids,
+            patch: {
+                ...(request.locked === undefined ? {} : { locked: request.locked }),
+                ...(request.hidden === undefined ? {} : { hidden: request.hidden }),
+            },
+        });
+        return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
+    },
+    assign_material: (ctx, request) => {
+        if (!documentHasAnyId(ctx.session.getState().document, request.ids)) {
+            return { ok: false, error: "assign_material matched no objects" };
+        }
+        ctx.session.dispatch({ type: "assignMaterial", ids: request.ids, materialId: request.materialId });
+        return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
+    },
+};

package/dist/handlers/grids.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Grid/tile layer verbs — create, edit, paint, fill, and import. */
+export declare const gridHandlers: Pick<HandlerTable, "list_grids" | "get_grid_cell" | "add_grid_layer" | "remove_grid_layer" | "set_grid_layer" | "paint_grid_cells" | "fill_grid_rect" | "flood_fill_grid" | "resize_grid_layer" | "import_grid">;