@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/modules/devtools/src/worker-expose.js

@@ -0,0 +1,59 @@
+// ============================================================================
+// Worker-side DevTools expose helper — adds the standard __devtools* RPC
+// methods to a worker's expose() API so the renderer can fetch the manifest
+// and forward commands.
+//
+// Data feeds are NOT served via RPC — they're written to the devtools SAB
+// by flushDataFeeds() (called from the sim loop). The renderer reads them
+// synchronously from the SAB. Only the manifest and commands use worker RPC.
+// ============================================================================
+import { exposeProfilingApi } from "@downdraft/engine/worker/instrumented-worker-host";
+import { _devtoolsImpl, devtools } from "./api.js";
+/**
+ * Wrap a worker API object with the standard devtools RPC methods.
+ * Call this inside the worker's expose() setup:
+ *
+ *   expose(exposeDevToolsApi({ init, pause, ... }));
+ */
+export function exposeDevToolsApi(api) {
+    // Merge profiling RPC methods (attachProfilingSAB, addWarningRule, onWarning)
+    // with the devtools RPC methods.
+    return exposeProfilingApi({
+        ...api,
+        __devtoolsGetManifest: () => {
+            return devtools.getManifest();
+        },
+        __devtoolsCallCommand: (name, args) => {
+            return _devtoolsImpl.callCommand(name, args);
+        },
+        __devtoolsGetSAB: () => {
+            return devtools.getSAB();
+        },
+        __devtoolsEval: async (expr) => {
+            try {
+                // Evaluate the expression in the worker's global scope.
+                // Use indirect eval so it runs in the global scope (not closure).
+                // eslint-disable-next-line no-new-func
+                const fn = new Function("return (" + expr + ")");
+                const result = fn();
+                return { result };
+            }
+            catch (err) {
+                return { error: String(err) };
+            }
+        },
+    });
+}
+/**
+ * Convenience: attach the devtools SAB to the worker-side registry and
+ * register it so the renderer can discover it via __devtoolsGetSAB().
+ *
+ * Games call this in their worker entry after allocating the devtools SAB:
+ *
+ *   const dtSAB = allocateDevToolsSAB();
+ *   attachDevToolsSAB(dtSAB);
+ *   // Pass dtSAB to the renderer via the init() RPC or a separate message.
+ */
+export function attachDevToolsSAB(sab) {
+    devtools.attachSAB(sab);
+}

package/dist/modules/devtools/src/worker-sync.js

@@ -0,0 +1,115 @@
+// ============================================================================
+// Renderer-side worker manifest sync — fetches the devtools manifest from
+// one or more sim workers via worker RPC, then wires the worker-registered panels,
+// data feeds, and commands into the renderer-side __sceneInspector API.
+//
+// Data feeds from workers are read from the devtools SAB (zero-copy).
+// Commands are forwarded via worker RPC.
+// Panel declarations are merged into the global registry.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+import { _devtoolsImpl, devtools } from "./api.js";
+const log = createLogger("info");
+/**
+ * Sync manifests from one or more workers into the renderer-side devtools
+ * registry. Called once during initDevTools(). Returns a function to
+ * re-sync on hot-reload.
+ */
+export async function syncWorkerManifests(entries) {
+    for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) {
+        const entry = _it[_i];
+        await syncOneWorker(entry);
+    }
+    // Return a re-sync function for hot-reload
+    return async () => {
+        for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) {
+            const entry = _it[_i];
+            await syncOneWorker(entry);
+        }
+    };
+}
+/** A crashed or still-initializing worker may never answer the manifest RPC —
+ *  bound the wait so devtools wiring can't wedge the whole game bootstrap. */
+const MANIFEST_TIMEOUT_MS = 5000;
+async function syncOneWorker(entry) {
+    const { prefix, proxy } = entry;
+    let manifest;
+    try {
+        manifest = await Promise.race([
+            proxy.__devtoolsGetManifest(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`timeout after ${MANIFEST_TIMEOUT_MS}ms`)), MANIFEST_TIMEOUT_MS)),
+        ]);
+    }
+    catch (e) {
+        log.warn("devtools", `Failed to fetch manifest from worker "${prefix}": ${e}`);
+        return;
+    }
+    // Fetch the devtools SAB from the worker (allocated and attached there)
+    let sab = entry.sab ?? null;
+    if (!sab) {
+        try {
+            sab = await proxy.__devtoolsGetSAB();
+        }
+        catch {
+            // Worker may not have a devtools SAB (older workers)
+        }
+    }
+    // Register panels (namespaced by prefix to avoid collisions)
+    manifest.panels.forEach((panel) => {
+        const namespaced = prefix
+            ? { ...panel, id: `${prefix}:${panel.id}` }
+            : panel;
+        devtools.registerPanel(namespaced);
+    });
+    // Register data feed readers — these read from the SAB synchronously
+    // We register them as main-realm data feeds that read from the worker SAB
+    if (sab) {
+        manifest.dataFeeds.forEach((feed) => {
+            const feedIndex = feed.feedIndex;
+            const readName = prefix ? `${prefix}:${feed.name}` : feed.name;
+            // Register a main-realm data feed that reads from the worker's SAB
+            _devtoolsImpl.registerDataFeed(readName, () => {
+                return readDataFeedFromSAB(sab, feedIndex);
+            }, 0); // writeRateHz=0 means "read on demand" (no polling needed)
+        });
+        // Register SAB stat readers
+        manifest.sabStats.forEach((stat) => {
+            const statName = prefix ? `${prefix}:${stat.name}` : stat.name;
+            _devtoolsImpl.registerSABStat(statName, stat.offset, stat.type);
+        });
+    }
+    // Register command forwarders — these call the worker via RPC
+    manifest.commands.forEach((cmdName) => {
+        const namespacedCmd = prefix ? `${prefix}:${cmdName}` : cmdName;
+        _devtoolsImpl.registerCommand(namespacedCmd, (...args) => {
+            // Fire-and-forget (commands return void in the panel context)
+            proxy.__devtoolsCallCommand(cmdName, args).catch((e) => {
+                log.warn("devtools", `Worker command "${cmdName}" failed: ${e}`);
+            });
+        });
+    });
+}
+/**
+ * Read a data feed value from a devtools SAB.
+ * The SAB layout is the standard one from computeDevToolsSABLayout().
+ */
+function readDataFeedFromSAB(sab, feedIndex) {
+    const u32 = new Uint32Array(sab);
+    const u8 = new Uint8Array(sab);
+    // Layout: header (8 bytes) + feed entries
+    // Each feed entry: [lengthBytes: u32][JSON blob...]
+    const feedEntryBytes = 4 + 4096; // DEVTOOLS_SAB_FEED_HEADER_BYTES + DEVTOOLS_SAB_DEFAULT_FEED_BLOB_BYTES
+    const entryByteOffset = 8 + feedIndex * feedEntryBytes;
+    const lengthBytes = u32[entryByteOffset / 4];
+    if (lengthBytes === 0 || lengthBytes === 0xFFFFFFFF)
+        return null;
+    const blobOffset = entryByteOffset + 4;
+    const jsonBytes = u8.subarray(blobOffset, blobOffset + lengthBytes);
+    try {
+        const json = new TextDecoder().decode(jsonBytes);
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/modules/editor/src/commands/component.js

@@ -0,0 +1,151 @@
+// ============================================================================
+// Component commands — add / set (merge-patch) / remove / inspect.
+//
+// `component.set` merges `changes` into existing data and inverses with the
+// captured old data — the workhorse behind inspector edits and gizmo drags.
+// ============================================================================
+import { sanitizeObject } from "@downdraft/engine";
+function readComponent(ctx, entityKey, componentName) {
+    const entity = ctx.parseEntity(entityKey);
+    if (!entity)
+        return null;
+    const cid = ctx.engine.getComponentIdByName(componentName);
+    const data = ctx.engine.ecsWorld.getComponent(entity, cid);
+    return data ? sanitizeObject({ ...data }) : null;
+}
+export function createComponentCommands() {
+    return [
+        {
+            id: "component.add",
+            title: "Add Component",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string" },
+                    component: { type: "string" },
+                    data: { type: "object", description: "Initial component data" },
+                },
+                required: ["entity", "component"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                const name = params.component;
+                const cid = ctx.engine.getComponentIdByName(name);
+                if (ctx.engine.ecsWorld.hasComponent(entity, cid)) {
+                    throw new Error(`Entity ${key} already has component "${name}"`);
+                }
+                const data = sanitizeObject({ ...params.data });
+                ctx.engine.ecsWorld.addComponent(entity, cid, data);
+                ctx.engine.ecsWorld.flushCommands();
+                ctx.document.markDirty({ kind: "data", entity: key });
+                ctx.adapter?.syncEntity?.(key);
+                return {
+                    value: { entity: key, component: name },
+                    inverse: [{ command: "component.remove", params: { entity: key, component: name } }],
+                    description: `Add ${name} to ${key}`,
+                };
+            },
+        },
+        {
+            id: "component.set",
+            title: "Set Component Data",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string" },
+                    component: { type: "string" },
+                    changes: { type: "object", description: "Partial data merged into the component" },
+                },
+                required: ["entity", "component", "changes"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const name = params.component;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                const oldData = readComponent(ctx, key, name);
+                if (oldData === null)
+                    throw new Error(`Entity ${key} has no component "${name}"`);
+                const changes = sanitizeObject({ ...params.changes });
+                const newData = sanitizeObject({ ...oldData, ...changes });
+                const cid = ctx.engine.getComponentIdByName(name);
+                ctx.engine.ecsWorld.setComponent(entity, cid, newData);
+                ctx.engine.ecsWorld.flushCommands();
+                ctx.document.markDirty({ kind: "data", entity: key });
+                ctx.adapter?.syncEntity?.(key);
+                return {
+                    value: { entity: key, component: name, updated: Object.keys(changes) },
+                    inverse: [{ command: "component.set", params: { entity: key, component: name, changes: oldData } }],
+                    description: `Set ${name} on ${key}`,
+                };
+            },
+        },
+        {
+            id: "component.remove",
+            title: "Remove Component",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string" },
+                    component: { type: "string" },
+                },
+                required: ["entity", "component"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const name = params.component;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                const oldData = readComponent(ctx, key, name);
+                if (oldData === null)
+                    throw new Error(`Entity ${key} has no component "${name}"`);
+                const cid = ctx.engine.getComponentIdByName(name);
+                ctx.engine.ecsWorld.removeComponent(entity, cid);
+                ctx.engine.ecsWorld.flushCommands();
+                ctx.document.markDirty({ kind: "data", entity: key });
+                ctx.adapter?.syncEntity?.(key);
+                return {
+                    value: { entity: key, component: name, removed: true },
+                    inverse: [{ command: "component.add", params: { entity: key, component: name, data: oldData } }],
+                    description: `Remove ${name} from ${key}`,
+                };
+            },
+        },
+        {
+            id: "component.list",
+            title: "List Components on Entity",
+            mutating: false,
+            params: {
+                type: "object",
+                properties: { entity: { type: "string" } },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                const arch = ctx.engine.ecsWorld.getArchetypeForEntity(entity);
+                const components = {};
+                if (arch) {
+                    const row = arch.entities.findIndex((e) => e.index === entity.index && e.generation === entity.generation);
+                    if (row >= 0) {
+                        for (const [cid] of arch.columns.entries()) {
+                            components[ctx.engine.getComponentNameById(cid)] =
+                                sanitizeObject(ctx.engine.ecsWorld.getComponent(entity, cid) ?? {});
+                        }
+                    }
+                }
+                return { value: { entity: key, components } };
+            },
+        },
+    ];
+}

package/dist/modules/editor/src/commands/entity.js

@@ -0,0 +1,253 @@
+// ============================================================================
+// Entity commands — spawn / remove / restore / duplicate / rename.
+//
+// Inverses are plain invocations: `entity.remove` captures a full snapshot
+// (components, name, parent, children) and its inverse is `entity.restore`.
+// Restored entities get NEW entity keys — `restore` reports the new key in
+// its result so the journal stays truthful, and `hierarchy.setParent`
+// inverses re-parent surviving children onto the restored entity.
+// ============================================================================
+import { getColumnValue, sanitizeObject } from "@downdraft/engine";
+function snapshotEntity(ctx, entity) {
+    const { world } = ctx.document;
+    const components = {};
+    const arch = world.getArchetypeForEntity(entity);
+    if (arch) {
+        const row = arch.entities.findIndex((e) => e.index === entity.index && e.generation === entity.generation);
+        if (row >= 0) {
+            for (const [cid, col] of arch.columns.entries()) {
+                const data = getColumnValue(col, row);
+                if (data !== undefined && data !== null) {
+                    components[ctx.engine.getComponentNameById(cid)] = sanitizeObject({ ...data });
+                }
+            }
+        }
+    }
+    const parent = ctx.engine.hierarchy.getParent(entity);
+    const key = ctx.key(entity);
+    return {
+        key,
+        name: ctx.document.entityName(key),
+        parent: parent ? ctx.key(parent) : null,
+        components,
+        children: ctx.engine.hierarchy.getChildren(entity).map((c) => ctx.key(c)),
+    };
+}
+/** Spawn from a component-name map. Shared by spawn/restore. */
+function spawnWithComponents(ctx, components) {
+    const map = new Map();
+    for (const [name, data] of Object.entries(components)) {
+        map.set(ctx.engine.getComponentIdByName(name), sanitizeObject({ ...data }));
+    }
+    const entity = ctx.engine.ecsWorld.spawn(map);
+    ctx.engine.scene.trackEntity(entity);
+    ctx.engine.ecsWorld.flushCommands();
+    return entity;
+}
+export function createEntityCommands() {
+    return [
+        {
+            id: "entity.spawn",
+            title: "Spawn Entity",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Display name" },
+                    components: { type: "object", description: "Component name → data" },
+                    parent: { type: "string", description: "Parent entity key" },
+                    position: { type: "array", items: { type: "number" }, description: "Shorthand for transform.position" },
+                },
+            },
+            apply(ctx, params) {
+                const components = (params.components ?? {});
+                // `position` shorthand merges into the transform component.
+                const position = params.position;
+                if (position) {
+                    components["transform"] = { ...components["transform"], position: [...position] };
+                }
+                const entity = spawnWithComponents(ctx, components);
+                const key = ctx.key(entity);
+                const name = params.name;
+                if (name)
+                    ctx.document.setEntityName(key, name);
+                const parentKey = params.parent;
+                const parent = parentKey ? ctx.parseEntity(parentKey) : null;
+                if (parent)
+                    ctx.engine.hierarchy.setParent(entity, parent);
+                ctx.document.markDirty({ kind: "structure", entity: key });
+                ctx.adapter?.syncEntity?.(key);
+                return {
+                    value: { entity: key, components: Object.keys(components) },
+                    inverse: [{ command: "entity.remove", params: { entity: key } }],
+                    description: `Spawn entity${name ? ` "${name}"` : ""} (${key})`,
+                };
+            },
+        },
+        {
+            id: "entity.remove",
+            title: "Remove Entity",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string", description: "Entity key" },
+                },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key)) {
+                    throw new Error(`Entity ${key} not found or already dead`);
+                }
+                const snap = snapshotEntity(ctx, entity);
+                ctx.engine.ecsWorld.despawn(entity);
+                ctx.engine.ecsWorld.flushCommands();
+                ctx.engine.scene.removeEntity(entity);
+                ctx.document.setEntityName(key, undefined);
+                ctx.selection.remove(key);
+                ctx.document.markDirty({ kind: "structure", entity: key });
+                ctx.adapter?.removeEntity?.(key);
+                // Restore puts the entity back; surviving children re-parent to the
+                // restored key (entity.restore returns it — the child's setParent
+                // inverse is resolved at undo time against the restore result).
+                const inverse = [
+                    { command: "entity.restore", params: { snapshot: snap, parent: snap.parent } },
+                ];
+                snap.children.forEach((childKey) => {
+                    if (ctx.isAliveKey(childKey)) {
+                        inverse.push({ command: "hierarchy.setParentToRestore", params: { child: childKey } });
+                    }
+                });
+                return {
+                    value: { removed: true, entity: key },
+                    inverse,
+                    description: `Remove entity ${snap.name ?? key}`,
+                };
+            },
+        },
+        {
+            id: "entity.restore",
+            title: "Restore Entity",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    snapshot: { type: "object", description: "Captured entity snapshot" },
+                    parent: { type: "string", description: "Parent entity key (resolves to latest restore)" },
+                },
+                required: ["snapshot"],
+            },
+            apply(ctx, params) {
+                const snap = params.snapshot;
+                const entity = spawnWithComponents(ctx, snap.components);
+                const key = ctx.key(entity);
+                if (snap.name)
+                    ctx.document.setEntityName(key, snap.name);
+                // `parent` may be a stale key (if the parent was itself restored in
+                // the same undo batch, the caller passes the restored key instead).
+                const parentKey = params.parent ?? snap.parent;
+                const parent = parentKey ? ctx.parseEntity(parentKey) : null;
+                if (parent && ctx.isAliveKey(ctx.key(parent))) {
+                    ctx.engine.hierarchy.setParent(entity, parent);
+                }
+                ctx.document.markDirty({ kind: "structure", entity: key });
+                ctx.adapter?.syncEntity?.(key);
+                // Alias the snapshotted (stale) key to the new one — redo of the
+                // original remove, and any journaled params carrying the old key,
+                // resolve through it. Also stash for `hierarchy.setParentToRestore`.
+                if (snap.key)
+                    ctx.registerKeyAlias(snap.key, key);
+                ctx.lastRestoredKey = key;
+                return {
+                    value: { entity: key },
+                    inverse: [{ command: "entity.remove", params: { entity: key } }],
+                    description: `Restore entity${snap.name ? ` "${snap.name}"` : ""}`,
+                };
+            },
+        },
+        {
+            id: "entity.duplicate",
+            title: "Duplicate Entity",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: { entity: { type: "string" } },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key)) {
+                    throw new Error(`Entity ${key} not found or dead`);
+                }
+                const snap = snapshotEntity(ctx, entity);
+                const clone = spawnWithComponents(ctx, snap.components);
+                const cloneKey = ctx.key(clone);
+                const origName = ctx.document.entityName(key);
+                if (origName)
+                    ctx.document.setEntityName(cloneKey, `${origName} (copy)`);
+                const parent = snap.parent ? ctx.parseEntity(snap.parent) : null;
+                if (parent)
+                    ctx.engine.hierarchy.setParent(clone, parent);
+                ctx.document.markDirty({ kind: "structure", entity: cloneKey });
+                ctx.adapter?.syncEntity?.(cloneKey);
+                return {
+                    value: { entity: cloneKey },
+                    inverse: [{ command: "entity.remove", params: { entity: cloneKey } }],
+                    description: `Duplicate entity ${origName ?? key}`,
+                };
+            },
+        },
+        {
+            id: "entity.rename",
+            title: "Rename Entity",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string" },
+                    name: { type: "string" },
+                },
+                required: ["entity", "name"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                if (!ctx.isAliveKey(key))
+                    throw new Error(`Entity ${key} not found or dead`);
+                const name = params.name;
+                const oldName = ctx.document.entityName(key);
+                ctx.document.setEntityName(key, name);
+                ctx.document.markDirty({ kind: "meta", entity: key });
+                return {
+                    value: { entity: key, name },
+                    inverse: oldName !== undefined
+                        ? [{ command: "entity.rename", params: { entity: key, name: oldName } }]
+                        : [{ command: "entity.rename", params: { entity: key, name: `Entity ${key}` } }],
+                    description: `Rename ${oldName ?? key} → "${name}"`,
+                };
+            },
+        },
+        {
+            id: "entity.list",
+            title: "List Entities",
+            mutating: false,
+            apply(ctx) {
+                const out = ctx.document.entities().map((e) => {
+                    const key = ctx.key(e);
+                    const parent = ctx.engine.hierarchy.getParent(e);
+                    const arch = ctx.engine.ecsWorld.getArchetypeForEntity(e);
+                    const comps = arch ? [...arch.columns.keys()].map((id) => ctx.engine.getComponentNameById(id)) : [];
+                    return {
+                        key,
+                        name: ctx.document.entityName(key) ?? null,
+                        parent: parent ? ctx.key(parent) : null,
+                        components: comps,
+                    };
+                });
+                return { value: { count: out.length, entities: out } };
+            },
+        },
+    ];
+}

package/dist/modules/editor/src/commands/hierarchy.js

@@ -0,0 +1,79 @@
+// ============================================================================
+// Hierarchy commands — setParent (+ setParentToRestore used inside undo
+// batches to re-parent children onto a restored entity's NEW key).
+// ============================================================================
+export function createHierarchyCommands() {
+    return [
+        {
+            id: "hierarchy.setParent",
+            title: "Set Parent",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: {
+                    entity: { type: "string" },
+                    parent: { type: "string", description: "New parent key, or omit/empty for root" },
+                },
+                required: ["entity"],
+            },
+            apply(ctx, params) {
+                const key = params.entity;
+                const entity = ctx.parseEntity(key);
+                if (!entity || !ctx.isAliveKey(key)) {
+                    throw new Error(`Entity ${key} not found or dead`);
+                }
+                const parentKey = params.parent || undefined;
+                const parent = parentKey ? ctx.parseEntity(parentKey) : null;
+                if (parentKey && (!parent || !ctx.isAliveKey(parentKey))) {
+                    throw new Error(`Parent ${parentKey} not found or dead`);
+                }
+                if (parent && parent.index === entity.index && parent.generation === entity.generation) {
+                    throw new Error("Cannot parent an entity to itself");
+                }
+                const oldParent = ctx.engine.hierarchy.getParent(entity);
+                ctx.engine.hierarchy.setParent(entity, parent);
+                ctx.document.markDirty({ kind: "structure", entity: key });
+                return {
+                    value: { entity: key, parent: parent ? ctx.key(parent) : null },
+                    inverse: [{
+                            command: "hierarchy.setParent",
+                            params: oldParent ? { entity: key, parent: ctx.key(oldParent) } : { entity: key },
+                        }],
+                    description: `Set parent of ${key} → ${parent ? ctx.key(parent) : "root"}`,
+                };
+            },
+        },
+        {
+            id: "hierarchy.setParentToRestore",
+            title: "Reparent to Restored Entity",
+            mutating: true,
+            params: {
+                type: "object",
+                properties: { child: { type: "string" } },
+                required: ["child"],
+            },
+            apply(ctx, params) {
+                const childKey = params.child;
+                const child = ctx.parseEntity(childKey);
+                if (!child || !ctx.isAliveKey(childKey)) {
+                    return { value: { skipped: true, child: childKey } };
+                }
+                const newParentKey = ctx.lastRestoredKey;
+                const parent = newParentKey ? ctx.parseEntity(newParentKey) : null;
+                if (!parent || !ctx.isAliveKey(newParentKey)) {
+                    return { value: { skipped: true, child: childKey } };
+                }
+                const oldParent = ctx.engine.hierarchy.getParent(child);
+                ctx.engine.hierarchy.setParent(child, parent);
+                return {
+                    value: { child: childKey, parent: newParentKey },
+                    inverse: [{
+                            command: "hierarchy.setParent",
+                            params: oldParent ? { entity: childKey, parent: ctx.key(oldParent) } : { entity: childKey },
+                        }],
+                    description: `Reparent ${childKey} → restored ${newParentKey}`,
+                };
+            },
+        },
+    ];
+}