phibelle-kit 1.0.30 → 1.0.32

package/dist/commands/clone-scene.js

@@ -4,11 +4,10 @@ import * as fs from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { WebSocketServer } from "ws";
+import { WS_PORT, CLONE_REQUEST_TYPE, CLONE_RESPONSE_TYPE, SCENE_FILE_NAME, } from "../lib/constants.js";
+import { getExecErrorText } from "../lib/utils.js";
 import { parseSceneJson, unpackageScene } from "../lib/scene/scene-packaging.js";
 import { setupSceneDirectory } from "../scene-setup/setup.js";
-const WS_PORT = 31113;
-const CLONE_REQUEST_TYPE = "phibelle-kit-clone-request";
-const CLONE_RESPONSE_TYPE = "phibelle-kit-clone-response";
 const CLONE_TIMEOUT_MS = 30_000;
 const INITIAL_COMMIT_MESSAGE = "Initial scene clone from Phibelle";
 const execFileAsync = promisify(execFile);
@@ -26,7 +25,7 @@ export async function cloneSceneCommand() {
     await ensureDirectoryDoesNotExist(sceneDir);
     await fs.mkdir(sceneDir, { recursive: false });
     setupSceneDirectory(sceneDir);
-    await fs.writeFile(path.join(sceneDir, "scene.phibelle"), payload.sceneData, "utf8");
+    await fs.writeFile(path.join(sceneDir, SCENE_FILE_NAME), payload.sceneData, "utf8");
     await unpackageScene(payload.sceneData, sceneDir, payload.sceneId);
     await initializeGitRepository(sceneDir);
     console.log(chalk.green("  ✓ Scene cloned successfully"));
@@ -148,7 +147,7 @@ async function initializeGitRepository(sceneDir) {
     }
     catch (error) {
         console.log(chalk.yellow("  ! Git initialization or first commit was skipped"));
-        const details = getErrorText(error);
+        const details = getExecErrorText(error);
         if (details) {
             console.log(chalk.gray(`    ${details}`));
         }
@@ -158,12 +157,3 @@ async function initializeGitRepository(sceneDir) {
 async function runGit(args, cwd) {
     await execFileAsync("git", args, { cwd });
 }
-function getErrorText(error) {
-    if (!error || typeof error !== "object")
-        return "";
-    const err = error;
-    const stderr = err.stderr?.trim();
-    if (stderr)
-        return stderr.split("\n").pop() ?? stderr;
-    return err.message?.trim() ?? "";
-}

package/dist/commands/watch-scene.js

@@ -1,16 +1,14 @@
 import chalk from "chalk";
-import * as path from "path";
-import * as fs from "fs";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import readline from "node:readline";
 import { WebSocketServer } from "ws";
+import { WS_PORT, SCENE_SYNC_TYPE, SCENE_FILE_NAME } from "../lib/constants.js";
+import { getRequiredManifestSceneId } from "../lib/manifest.js";
 import { unpackageScene, parseSceneJson, packageSceneFromFilesystem } from "../lib/scene/scene-packaging.js";
 import { createScriptWatcher } from "../lib/scene/script-watcher.js";
 import { toErrorMessage } from "../lib/utils.js";
-import readline from "readline";
 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-const WS_PORT = 31113;
-const SCENE_SYNC_TYPE = "phibelle-kit-scene-sync";
-const SCENE_FILE_NAME = "scene.phibelle";
-const MANIFEST_FILE_NAME = "manifest.json";
 export const BASE_URL = process.env.NODE_ENV === "development" ? "http://localhost:3131" : "https://phibelle.studio";
 export async function watchSceneCommand() {
     const sceneDir = process.cwd();
@@ -186,27 +184,3 @@ function askQuestion(prompt) {
         rl.question(prompt, resolve);
     });
 }
-function getRequiredManifestSceneId(sceneDir) {
-    const manifestPath = path.join(sceneDir, MANIFEST_FILE_NAME);
-    if (!fs.existsSync(manifestPath)) {
-        throw new Error(`Missing ${MANIFEST_FILE_NAME} in ${sceneDir}. Run "phibelle-kit clone" first or watch from a cloned scene folder.`);
-    }
-    let manifestRaw;
-    try {
-        manifestRaw = fs.readFileSync(manifestPath, "utf8");
-    }
-    catch {
-        throw new Error(`Failed to read ${MANIFEST_FILE_NAME} in ${sceneDir}.`);
-    }
-    let manifest;
-    try {
-        manifest = JSON.parse(manifestRaw);
-    }
-    catch {
-        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: expected valid JSON.`);
-    }
-    if (typeof manifest.sceneId !== "string" || !manifest.sceneId.trim()) {
-        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: missing required "sceneId".`);
-    }
-    return manifest.sceneId.trim();
-}

package/dist/index.js

@@ -1,15 +1,10 @@
 #!/usr/bin/env node
 import chalk from "chalk";
 import { watchSceneCommand } from "./commands/watch-scene.js";
-import { initSceneCommand } from "./commands/init-scene.js";
 import { cloneSceneCommand } from "./commands/clone-scene.js";
-const USAGE = "  Usage: phibelle-kit init | phibelle-kit watch | phibelle-kit clone";
+const USAGE = "  Usage: phibelle-kit watch | phibelle-kit clone";
 async function main() {
     const command = process.argv[2];
-    if (command === "init") {
-        initSceneCommand();
-        return;
-    }
     if (command === "watch") {
         await watchSceneCommand();
         return;

package/dist/lib/constants.d.ts

@@ -0,0 +1,12 @@
+/** WebSocket port for phibelle-kit CLI ↔ web app communication. Must match app's use-cli-websocket.ts */
+export declare const WS_PORT = 31113;
+/** Scene JSON file in cloned scene directory */
+export declare const SCENE_FILE_NAME = "scene.phibelle";
+/** Manifest file mapping entity IDs to filesystem paths */
+export declare const MANIFEST_FILE_NAME = "manifest.json";
+/** Message type for scene sync over WebSocket */
+export declare const SCENE_SYNC_TYPE = "phibelle-kit-scene-sync";
+/** Message type for clone request from kit to app */
+export declare const CLONE_REQUEST_TYPE = "phibelle-kit-clone-request";
+/** Message type for clone response from app to kit */
+export declare const CLONE_RESPONSE_TYPE = "phibelle-kit-clone-response";

package/dist/lib/constants.js

@@ -0,0 +1,12 @@
+/** WebSocket port for phibelle-kit CLI ↔ web app communication. Must match app's use-cli-websocket.ts */
+export const WS_PORT = 31113;
+/** Scene JSON file in cloned scene directory */
+export const SCENE_FILE_NAME = "scene.phibelle";
+/** Manifest file mapping entity IDs to filesystem paths */
+export const MANIFEST_FILE_NAME = "manifest.json";
+/** Message type for scene sync over WebSocket */
+export const SCENE_SYNC_TYPE = "phibelle-kit-scene-sync";
+/** Message type for clone request from kit to app */
+export const CLONE_REQUEST_TYPE = "phibelle-kit-clone-request";
+/** Message type for clone response from app to kit */
+export const CLONE_RESPONSE_TYPE = "phibelle-kit-clone-response";

package/dist/lib/manifest.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Read manifest.json from sceneDir and return the required sceneId.
+ * Throws with user-facing errors if manifest is missing, unreadable, invalid JSON, or missing sceneId.
+ */
+export declare function getRequiredManifestSceneId(sceneDir: string): string;

package/dist/lib/manifest.js

@@ -0,0 +1,31 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MANIFEST_FILE_NAME } from "./constants.js";
+/**
+ * Read manifest.json from sceneDir and return the required sceneId.
+ * Throws with user-facing errors if manifest is missing, unreadable, invalid JSON, or missing sceneId.
+ */
+export function getRequiredManifestSceneId(sceneDir) {
+    const manifestPath = path.join(sceneDir, MANIFEST_FILE_NAME);
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`Missing ${MANIFEST_FILE_NAME} in ${sceneDir}. Run "phibelle-kit clone" first or watch from a cloned scene folder.`);
+    }
+    let manifestRaw;
+    try {
+        manifestRaw = fs.readFileSync(manifestPath, "utf8");
+    }
+    catch {
+        throw new Error(`Failed to read ${MANIFEST_FILE_NAME} in ${sceneDir}.`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch {
+        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: expected valid JSON.`);
+    }
+    if (typeof manifest.sceneId !== "string" || !manifest.sceneId.trim()) {
+        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: missing required "sceneId".`);
+    }
+    return manifest.sceneId.trim();
+}

package/dist/lib/scene/file-system.d.ts

@@ -1,5 +1,6 @@
+import { SCENE_FILE_NAME } from "../constants.js";
 export declare const SCENE_APP_DIR = "app";
-export declare const SCENE_FILE_NAME = "scene.phibelle";
+export { SCENE_FILE_NAME };
 export declare function getSceneAppDir(sceneDir: string): string;
 export declare function folderExists(folderPath: string): boolean;
 export declare function createFolder(folderPath: string): void;

package/dist/lib/scene/file-system.js

@@ -1,7 +1,8 @@
 import * as path from "node:path";
-import * as fs from "fs";
+import * as fs from "node:fs";
+import { SCENE_FILE_NAME } from "../constants.js";
 export const SCENE_APP_DIR = "app";
-export const SCENE_FILE_NAME = "scene.phibelle";
+export { SCENE_FILE_NAME };
 export function getSceneAppDir(sceneDir) {
     return path.join(sceneDir, SCENE_APP_DIR);
 }

package/dist/lib/scene/scene-packaging.d.ts

@@ -2,20 +2,16 @@ import type { PhibelleScene } from "../types.js";
 /** Scene-level file names in app/. */
 export declare const SCENE_SCRIPT_FILE = "scene-script.tsx";
 export declare const SCENE_PROPERTIES_FILE = "scene-properties.json";
-export declare function parseSceneJson(content: string): PhibelleScene;
-/** Convert entity display name to slug: "Main Enemy" → "main-enemy". */
-export declare function entityNameToSlug(name: string): string;
-/** Convert slug to display name: "main-enemy" → "Main Enemy". */
-export declare function slugToEntityName(slug: string): string;
 /** Entity filenames inside an entity folder. */
 export declare const ENTITY_SCRIPT_FILE = "script.tsx";
 export declare const ENTITY_PROPERTIES_FILE = "properties.json";
 export declare const ENTITY_TRANSFORMS_FILE = "transforms.json";
+export declare function parseSceneJson(content: string): PhibelleScene;
+/** Convert entity display name to slug: "Main Enemy" -> "main-enemy". */
+export declare function entityNameToSlug(name: string): string;
+/** Convert slug to display name: "main-enemy" -> "Main Enemy". */
+export declare function slugToEntityName(slug: string): string;
 /** Unpackage scene JSON to filesystem. No DB; accepts full scene JSON string. */
 export declare function unpackageScene(sceneJson: string, sceneDir: string, sceneId?: string): Promise<void>;
-/**
- * Apply a single file change to the in-memory scene and return updated JSON.
- * Used by script watcher to produce scene snapshot to send to FE.
- */
-export declare function patchSceneFromFile(sceneJson: string, sceneDir: string, relativePath: string, eventType: "change" | "add"): Promise<string>;
+export declare function patchSceneFromFile(sceneJson: string, sceneDir: string, _relativePath: string, _eventType: "change" | "add" | "unlink" | "addDir" | "unlinkDir"): Promise<string>;
 export declare function packageSceneFromFilesystem(sceneJson: string, sceneDir: string): Promise<string>;

package/dist/lib/scene/scene-packaging.js

@@ -1,9 +1,19 @@
-import * as fs from "fs/promises";
-import * as path from "path";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { getSceneAppDir } from "./file-system.js";
+import { MANIFEST_FILE_NAME } from "../constants.js";
+const LEGACY_SCENE_FILE = "scene.tsx";
+const CHILDREN_DIR_NAME = "children";
 /** Scene-level file names in app/. */
 export const SCENE_SCRIPT_FILE = "scene-script.tsx";
 export const SCENE_PROPERTIES_FILE = "scene-properties.json";
+/** Entity filenames inside an entity folder. */
+export const ENTITY_SCRIPT_FILE = "script.tsx";
+export const ENTITY_PROPERTIES_FILE = "properties.json";
+export const ENTITY_TRANSFORMS_FILE = "transforms.json";
+const DEFAULT_POSITION = '{"x":0,"y":0,"z":0}';
+const DEFAULT_ROTATION = '{"isEuler":true,"_x":0,"_y":0,"_z":0,"_order":"XYZ"}';
+const DEFAULT_SCALE = '{"x":1,"y":1,"z":1}';
 export function parseSceneJson(content) {
     try {
         return JSON.parse(content);
@@ -12,7 +22,7 @@ export function parseSceneJson(content) {
         throw new Error("Invalid scene file: not valid JSON");
     }
 }
-/** Convert entity display name to slug: "Main Enemy" → "main-enemy". */
+/** Convert entity display name to slug: "Main Enemy" -> "main-enemy". */
 export function entityNameToSlug(name) {
     const slug = name
         .toLowerCase()
@@ -20,7 +30,7 @@ export function entityNameToSlug(name) {
         .replace(/^-|-$/g, "");
     return slug || "entity";
 }
-/** Convert slug to display name: "main-enemy" → "Main Enemy". */
+/** Convert slug to display name: "main-enemy" -> "Main Enemy". */
 export function slugToEntityName(slug) {
     if (!slug || slug === "entity")
         return "Entity";
@@ -29,13 +39,6 @@ export function slugToEntityName(slug) {
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join(" ");
 }
-/** Entity filenames inside an entity folder. */
-export const ENTITY_SCRIPT_FILE = "script.tsx";
-export const ENTITY_PROPERTIES_FILE = "properties.json";
-export const ENTITY_TRANSFORMS_FILE = "transforms.json";
-const DEFAULT_POSITION = '{"x":0,"y":0,"z":0}';
-const DEFAULT_ROTATION = '{"isEuler":true,"_x":0,"_y":0,"_z":0,"_order":"XYZ"}';
-const DEFAULT_SCALE = '{"x":1,"y":1,"z":1}';
 /** Unpackage scene JSON to filesystem. No DB; accepts full scene JSON string. */
 export async function unpackageScene(sceneJson, sceneDir, sceneId) {
     const parsed = parseSceneJson(sceneJson);
@@ -43,288 +46,508 @@ export async function unpackageScene(sceneJson, sceneDir, sceneId) {
         ? parsed._id
         : "";
     const appDir = getSceneAppDir(sceneDir);
+    const previousManifest = await readManifest(sceneDir);
     await fs.mkdir(appDir, { recursive: true });
+    await cleanupKnownEntityDirectories(appDir, previousManifest);
+    await cleanupLegacySceneFiles(appDir);
+    const manifest = {
+        sceneId: sceneId?.trim() || parsedSceneId,
+        sceneScript: SCENE_SCRIPT_FILE,
+        sceneProperties: SCENE_PROPERTIES_FILE,
+        entities: {},
+    };
+    await writeSceneFiles(parsed, appDir);
+    const store = ensureEntityStore(parsed);
+    const entities = store.entities ?? {};
+    const usedFolderNamesByParent = new Map();
+    const rootIds = getRootEntityIds(store);
+    for (const rootId of rootIds) {
+        await writeEntityTree({
+            appDir,
+            entities,
+            entityId: rootId,
+            manifest,
+            usedFolderNamesByParent,
+        });
+    }
+    await fs.mkdir(sceneDir, { recursive: true });
+    await writeManifest(sceneDir, manifest);
+}
+export async function patchSceneFromFile(sceneJson, sceneDir, _relativePath, _eventType) {
+    return packageSceneFromFilesystem(sceneJson, sceneDir);
+}
+export async function packageSceneFromFilesystem(sceneJson, sceneDir) {
+    const manifest = await readManifest(sceneDir);
+    const parsed = parseSceneJson(sceneJson);
+    const appDir = getSceneAppDir(sceneDir);
+    await applySceneFileChanges(parsed, appDir, manifest);
+    await reconcileEntitiesFromFilesystem(parsed, manifest, appDir);
+    await writeManifest(sceneDir, manifest);
+    return JSON.stringify(parsed);
+}
+function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/^\/+/, "");
+}
+function getEntityFolderFromRelativePath(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    const fileName = path.posix.basename(normalized);
+    if (fileName === ENTITY_SCRIPT_FILE ||
+        fileName === ENTITY_PROPERTIES_FILE ||
+        fileName === ENTITY_TRANSFORMS_FILE) {
+        const entityDir = path.posix.dirname(normalized);
+        return entityDir === "." ? null : entityDir;
+    }
+    return null;
+}
+function getEntityIdFromRelativePath(manifest, relativePath) {
+    const entityDir = getEntityFolderFromRelativePath(relativePath);
+    if (!entityDir)
+        return null;
+    return Object.entries(manifest.entities).find(([, folderPath]) => folderPath === entityDir)?.[0] ?? null;
+}
+function ensureEntityStore(parsed) {
+    if (!parsed.entityStore) {
+        parsed.entityStore = {
+            _currId: 0,
+            rootEntities: [],
+            entities: {},
+            rootRenderVersion: 0,
+            lastRenderedVersion: 0,
+            selectedEntityIds: [],
+        };
+    }
+    if (!parsed.entityStore.entities) {
+        parsed.entityStore.entities = {};
+    }
+    if (!Array.isArray(parsed.entityStore.rootEntities)) {
+        parsed.entityStore.rootEntities = [];
+    }
+    return parsed.entityStore;
+}
+function getRootEntityIds(store) {
+    if (Array.isArray(store.rootEntities) && store.rootEntities.length > 0) {
+        return store.rootEntities;
+    }
+    return Object.values(store.entities ?? {})
+        .filter((entity) => entity.parentId === undefined)
+        .map((entity) => entity.engineId);
+}
+async function readManifest(sceneDir) {
+    try {
+        const manifestRaw = await fs.readFile(path.join(sceneDir, MANIFEST_FILE_NAME), "utf8");
+        const parsed = JSON.parse(manifestRaw);
+        return {
+            sceneId: typeof parsed.sceneId === "string" ? parsed.sceneId : "",
+            sceneScript: typeof parsed.sceneScript === "string" ? parsed.sceneScript : SCENE_SCRIPT_FILE,
+            sceneProperties: typeof parsed.sceneProperties === "string" ? parsed.sceneProperties : SCENE_PROPERTIES_FILE,
+            entities: parsed.entities ?? {},
+        };
+    }
+    catch {
+        return {
+            sceneId: "",
+            sceneScript: SCENE_SCRIPT_FILE,
+            sceneProperties: SCENE_PROPERTIES_FILE,
+            entities: {},
+        };
+    }
+}
+async function writeManifest(sceneDir, manifest) {
+    await fs.writeFile(path.join(sceneDir, MANIFEST_FILE_NAME), JSON.stringify(manifest, null, 2), "utf8");
+}
+async function cleanupLegacySceneFiles(appDir) {
     try {
         const entries = await fs.readdir(appDir, { withFileTypes: true });
-        for (const ent of entries) {
-            if (ent.isFile()) {
-                if (ent.name === "scene.tsx")
-                    await fs.unlink(path.join(appDir, ent.name));
-                else if (ent.name.endsWith(".tsx") && ent.name !== SCENE_SCRIPT_FILE)
-                    await fs.unlink(path.join(appDir, ent.name));
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (entry.name === LEGACY_SCENE_FILE) {
+                await fs.rm(path.join(appDir, entry.name), { force: true });
             }
-            if (ent.isDirectory()) {
-                const scriptPath = path.join(appDir, ent.name, ENTITY_SCRIPT_FILE);
-                try {
-                    await fs.access(scriptPath);
-                    await fs.rm(path.join(appDir, ent.name), { recursive: true });
-                }
-                catch {
-                    /* no script.tsx, leave dir alone */
-                }
+            else if (entry.name.endsWith(".tsx") && entry.name !== SCENE_SCRIPT_FILE) {
+                await fs.rm(path.join(appDir, entry.name), { force: true });
             }
         }
     }
     catch {
-        /* directory might not exist or be empty */
+        // app directory may not exist yet
     }
-    const entities = parsed.entityStore?.entities ?? {};
-    const manifest = {
-        sceneId: sceneId?.trim() || parsedSceneId,
-        sceneScript: SCENE_SCRIPT_FILE,
-        sceneProperties: SCENE_PROPERTIES_FILE,
-        entities: {},
-    };
+}
+async function cleanupKnownEntityDirectories(appDir, manifest) {
+    const knownPaths = Array.from(new Set(Object.values(manifest.entities)
+        .map((relativePath) => normalizeRelativePath(relativePath))
+        .filter(Boolean)
+        .sort((a, b) => b.split("/").length - a.split("/").length)));
+    for (const relativePath of knownPaths) {
+        await fs.rm(path.join(appDir, relativePath), { recursive: true, force: true });
+        await removeEmptyAncestorChildrenDirs(appDir, path.posix.dirname(relativePath));
+    }
+}
+async function removeEmptyAncestorChildrenDirs(appDir, relativeDir) {
+    let current = relativeDir;
+    while (current && current !== ".") {
+        const basename = path.posix.basename(current);
+        if (basename !== CHILDREN_DIR_NAME) {
+            current = path.posix.dirname(current);
+            continue;
+        }
+        const absoluteDir = path.join(appDir, current);
+        try {
+            const entries = await fs.readdir(absoluteDir);
+            if (entries.length > 0)
+                break;
+            await fs.rmdir(absoluteDir);
+        }
+        catch {
+            break;
+        }
+        current = path.posix.dirname(current);
+    }
+}
+async function writeSceneFiles(parsed, appDir) {
     await fs.writeFile(path.join(appDir, SCENE_SCRIPT_FILE), parsed.sceneScriptStore?.sceneScript ?? "", "utf8");
     const scenePropertiesJson = JSON.stringify(parsed.sceneScriptStore?.sceneProperties ?? [], null, 2);
     await fs.writeFile(path.join(appDir, SCENE_PROPERTIES_FILE), scenePropertiesJson, "utf8");
-    const usedFolderNames = new Set();
-    for (const idStr of Object.keys(entities)) {
-        const entity = entities[idStr];
-        if (!entity || typeof entity.script !== "string")
-            continue;
-        const engineId = String(entity.engineId ?? idStr);
-        const baseName = entity.name ?? "Entity";
-        let folderName = baseName;
-        if (usedFolderNames.has(folderName))
-            folderName = `${baseName}-${engineId}`;
-        usedFolderNames.add(folderName);
-        const entityDir = path.join(appDir, folderName);
-        await fs.mkdir(entityDir, { recursive: true });
-        manifest.entities[engineId] = folderName;
-        await fs.writeFile(path.join(entityDir, ENTITY_SCRIPT_FILE), entity.script, "utf8");
-        const propertiesJson = JSON.stringify(entity.properties ?? [], null, 2);
-        await fs.writeFile(path.join(entityDir, ENTITY_PROPERTIES_FILE), propertiesJson, "utf8");
-        const transform = entity.transform ?? {
-            position: DEFAULT_POSITION,
-            rotation: DEFAULT_ROTATION,
-            scale: DEFAULT_SCALE,
-        };
-        const transformsData = {
-            position: JSON.parse(transform.position),
-            rotation: JSON.parse(transform.rotation),
-            scale: JSON.parse(transform.scale),
-        };
-        await fs.writeFile(path.join(entityDir, ENTITY_TRANSFORMS_FILE), JSON.stringify(transformsData, null, 2), "utf8");
+}
+async function writeEntityTree(args) {
+    const { appDir, entities, entityId, manifest, parentRelativePath, usedFolderNamesByParent } = args;
+    const entity = entities[String(entityId)];
+    if (!entity || typeof entity.script !== "string")
+        return;
+    const parentKey = parentRelativePath ?? "__root__";
+    const siblingNames = usedFolderNamesByParent.get(parentKey) ?? new Set();
+    usedFolderNamesByParent.set(parentKey, siblingNames);
+    const engineId = String(entity.engineId ?? entityId);
+    const baseName = (entity.name ?? "Entity").trim() || "Entity";
+    let folderName = baseName;
+    if (siblingNames.has(folderName))
+        folderName = `${baseName}-${engineId}`;
+    siblingNames.add(folderName);
+    const relativePath = parentRelativePath
+        ? path.posix.join(parentRelativePath, CHILDREN_DIR_NAME, folderName)
+        : folderName;
+    const entityDir = path.join(appDir, relativePath);
+    await fs.mkdir(entityDir, { recursive: true });
+    manifest.entities[engineId] = relativePath;
+    await writeEntityFiles(entityDir, entity);
+    for (const childId of entity.childrenIds ?? []) {
+        await writeEntityTree({
+            appDir,
+            entities,
+            entityId: childId,
+            manifest,
+            parentRelativePath: relativePath,
+            usedFolderNamesByParent,
+        });
     }
-    await fs.mkdir(sceneDir, { recursive: true });
-    await fs.writeFile(path.join(sceneDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
 }
-function getEntityIdFromRelativePath(manifest, relativePath) {
-    const normalized = relativePath.replace(/\\/g, "/");
-    const match = normalized.match(/^([^/]+)\/(.+)$/);
-    if (!match)
-        return null;
-    const [, folderName] = match;
-    const entityId = Object.entries(manifest.entities).find(([, folder]) => folder === folderName)?.[0];
-    return entityId ?? null;
-}
-/**
- * Apply a single file change to the in-memory scene and return updated JSON.
- * Used by script watcher to produce scene snapshot to send to FE.
- */
-export async function patchSceneFromFile(sceneJson, sceneDir, relativePath, eventType) {
-    const manifestRaw = await fs.readFile(path.join(sceneDir, "manifest.json"), "utf8");
-    const manifest = JSON.parse(manifestRaw);
-    const parsed = parseSceneJson(sceneJson);
-    const appDir = getSceneAppDir(sceneDir);
-    const filePath = path.join(appDir, relativePath);
-    if (relativePath === manifest.sceneScript || relativePath === SCENE_SCRIPT_FILE) {
-        const fileContent = await fs.readFile(filePath, "utf8");
-        if (!parsed.sceneScriptStore)
-            parsed.sceneScriptStore = { sceneScript: "", sceneProperties: [], lastModifiedSceneScript: 0 };
-        if (parsed.sceneScriptStore.sceneScript === fileContent)
-            return sceneJson;
-        parsed.sceneScriptStore.sceneScript = fileContent;
-        parsed.sceneScriptStore.lastModifiedSceneScript = Date.now();
-        return JSON.stringify(parsed);
-    }
-    if (relativePath === (manifest.sceneProperties ?? SCENE_PROPERTIES_FILE)) {
-        const fileContent = await fs.readFile(filePath, "utf8");
-        const sceneProperties = JSON.parse(fileContent);
-        if (!parsed.sceneScriptStore)
-            parsed.sceneScriptStore = { sceneScript: "", sceneProperties: [], lastModifiedSceneScript: 0 };
-        const nextSceneProperties = Array.isArray(sceneProperties) ? sceneProperties : [];
-        if (JSON.stringify(parsed.sceneScriptStore.sceneProperties ?? []) === JSON.stringify(nextSceneProperties)) {
-            return sceneJson;
+async function writeEntityFiles(entityDir, entity) {
+    await fs.writeFile(path.join(entityDir, ENTITY_SCRIPT_FILE), entity.script, "utf8");
+    await fs.writeFile(path.join(entityDir, ENTITY_PROPERTIES_FILE), JSON.stringify(entity.properties ?? [], null, 2), "utf8");
+    const transform = entity.transform ?? {
+        position: DEFAULT_POSITION,
+        rotation: DEFAULT_ROTATION,
+        scale: DEFAULT_SCALE,
+    };
+    const transformsData = {
+        position: safeJsonParse(transform.position, JSON.parse(DEFAULT_POSITION)),
+        rotation: safeJsonParse(transform.rotation, JSON.parse(DEFAULT_ROTATION)),
+        scale: safeJsonParse(transform.scale, JSON.parse(DEFAULT_SCALE)),
+    };
+    await fs.writeFile(path.join(entityDir, ENTITY_TRANSFORMS_FILE), JSON.stringify(transformsData, null, 2), "utf8");
+}
+function safeJsonParse(value, fallback) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+async function applySceneFileChanges(parsed, appDir, manifest) {
+    if (!parsed.sceneScriptStore) {
+        parsed.sceneScriptStore = { sceneScript: "", sceneProperties: [], lastModifiedSceneScript: 0 };
+    }
+    const sceneScriptPath = path.join(appDir, manifest.sceneScript ?? SCENE_SCRIPT_FILE);
+    try {
+        const sceneScript = await fs.readFile(sceneScriptPath, "utf8");
+        if (parsed.sceneScriptStore.sceneScript !== sceneScript) {
+            parsed.sceneScriptStore.sceneScript = sceneScript;
+            parsed.sceneScriptStore.lastModifiedSceneScript = Date.now();
         }
-        parsed.sceneScriptStore.sceneProperties = nextSceneProperties;
-        return JSON.stringify(parsed);
-    }
-    const scriptMatch = relativePath.match(new RegExp(`^([^/]+)\\/${ENTITY_SCRIPT_FILE.replace(".", "\\.")}$`));
-    if (scriptMatch) {
-        const folderName = scriptMatch[1];
-        const fileContent = await fs.readFile(filePath, "utf8");
-        const existingId = Object.entries(manifest.entities).find(([, f]) => f === folderName)?.[0];
-        if (existingId != null) {
-            const entities = parsed.entityStore?.entities ?? {};
-            const entity = entities[existingId];
-            if (!entity)
-                return sceneJson;
-            if (entity.script === fileContent)
-                return sceneJson;
-            entity.script = fileContent;
+    }
+    catch {
+        // keep existing script if file is missing
+    }
+    const scenePropertiesPath = path.join(appDir, manifest.sceneProperties ?? SCENE_PROPERTIES_FILE);
+    try {
+        const rawSceneProperties = await fs.readFile(scenePropertiesPath, "utf8");
+        const sceneProperties = JSON.parse(rawSceneProperties);
+        parsed.sceneScriptStore.sceneProperties = Array.isArray(sceneProperties) ? sceneProperties : [];
+    }
+    catch {
+        // keep existing properties if file is missing or invalid
+    }
+}
+async function reconcileEntitiesFromFilesystem(parsed, manifest, appDir) {
+    const store = ensureEntityStore(parsed);
+    const entities = store.entities;
+    const previousRootEntities = [...store.rootEntities];
+    const previousChildrenById = new Map();
+    for (const [entityId, entity] of Object.entries(entities)) {
+        previousChildrenById.set(entityId, [...(entity.childrenIds ?? [])]);
+    }
+    const discoveredEntities = await scanFilesystemEntities(appDir);
+    const discoveredByPath = new Map(discoveredEntities.map((entity) => [entity.relativePath, entity]));
+    const currentIds = Object.keys(entities);
+    const assignedEntityIds = new Set();
+    const discoveryIdByPath = new Map();
+    for (const [entityId, entityPath] of Object.entries(manifest.entities)) {
+        if (!entities[entityId])
+            continue;
+        const normalizedPath = normalizeRelativePath(entityPath);
+        if (!discoveredByPath.has(normalizedPath))
+            continue;
+        assignedEntityIds.add(entityId);
+        discoveryIdByPath.set(normalizedPath, entityId);
+    }
+    const unmatchedEntityIds = currentIds.filter((entityId) => !assignedEntityIds.has(entityId));
+    const unmatchedDiscoveries = discoveredEntities.filter((entity) => !discoveryIdByPath.has(entity.relativePath));
+    matchDiscoveriesByFolderName(unmatchedDiscoveries, unmatchedEntityIds, entities, manifest, assignedEntityIds, discoveryIdByPath);
+    matchDiscoveriesByContent(unmatchedDiscoveries, unmatchedEntityIds, entities, assignedEntityIds, discoveryIdByPath);
+    let nextEntityId = Math.max(store._currId, ...currentIds.map(Number).filter(Number.isFinite), 0);
+    for (const discovery of unmatchedDiscoveries) {
+        if (discoveryIdByPath.has(discovery.relativePath))
+            continue;
+        nextEntityId += 1;
+        const entityId = String(nextEntityId);
+        assignedEntityIds.add(entityId);
+        discoveryIdByPath.set(discovery.relativePath, entityId);
+        entities[entityId] = createEntityFromDiscovery(Number(entityId), discovery);
+    }
+    store._currId = nextEntityId;
+    for (const discovery of discoveredEntities) {
+        const entityId = discoveryIdByPath.get(discovery.relativePath);
+        if (!entityId)
+            continue;
+        const entity = entities[entityId] ?? createEntityFromDiscovery(Number(entityId), discovery);
+        entity.engineId = Number(entityId);
+        entity.name = discovery.folderName;
+        if (entity.script !== discovery.script) {
             entity.scriptVersion = (entity.scriptVersion ?? 0) + 1;
-            return JSON.stringify(parsed);
+            entity.script = discovery.script;
         }
-        if (eventType === "add") {
-            return addNewEntityFromFolder(parsed, manifest, sceneDir, folderName, appDir);
+        entity.properties = discovery.properties;
+        entity.transform = discovery.transform;
+        entity.childrenIds = [];
+        entity.childrenIdsSet = [];
+        entities[entityId] = entity;
+    }
+    const desiredParentById = new Map();
+    const desiredChildrenByParent = new Map();
+    for (const discovery of discoveredEntities) {
+        const entityId = discoveryIdByPath.get(discovery.relativePath);
+        if (!entityId)
+            continue;
+        const parentId = discovery.parentRelativePath != null
+            ? discoveryIdByPath.get(discovery.parentRelativePath)
+            : undefined;
+        desiredParentById.set(entityId, parentId);
+        const siblings = desiredChildrenByParent.get(parentId) ?? [];
+        siblings.push(entityId);
+        desiredChildrenByParent.set(parentId, siblings);
+    }
+    const finalEntityIds = new Set(discoveryIdByPath.values());
+    for (const entityId of Object.keys(entities)) {
+        if (!finalEntityIds.has(entityId)) {
+            delete entities[entityId];
         }
-        return sceneJson;
-    }
-    const propsMatch = relativePath.match(new RegExp(`^([^/]+)\\/${ENTITY_PROPERTIES_FILE.replace(".", "\\.")}$`));
-    if (propsMatch) {
-        const entityId = getEntityIdFromRelativePath(manifest, relativePath);
-        if (entityId == null)
-            return sceneJson;
-        const fileContent = await fs.readFile(filePath, "utf8");
-        const properties = JSON.parse(fileContent);
-        const entities = parsed.entityStore?.entities ?? {};
+    }
+    for (const entityId of finalEntityIds) {
         const entity = entities[entityId];
         if (!entity)
-            return sceneJson;
-        const nextProperties = Array.isArray(properties) ? properties : [];
-        if (JSON.stringify(entity.properties ?? []) === JSON.stringify(nextProperties))
-            return sceneJson;
-        entity.properties = nextProperties;
-        return JSON.stringify(parsed);
-    }
-    const transformsMatch = relativePath.match(new RegExp(`^([^/]+)\\/${ENTITY_TRANSFORMS_FILE.replace(".", "\\.")}$`));
-    if (transformsMatch) {
-        const entityId = getEntityIdFromRelativePath(manifest, relativePath);
-        if (entityId == null)
-            return sceneJson;
-        const fileContent = await fs.readFile(filePath, "utf8");
-        const data = JSON.parse(fileContent);
-        const entities = parsed.entityStore?.entities ?? {};
+            continue;
+        const desiredParentId = desiredParentById.get(entityId);
+        entity.parentId = desiredParentId != null ? Number(desiredParentId) : undefined;
+    }
+    store.rootEntities = mergeSiblingOrder(previousRootEntities.map(String), desiredChildrenByParent.get(undefined) ?? [], desiredParentById, undefined).map(Number);
+    for (const entityId of finalEntityIds) {
         const entity = entities[entityId];
         if (!entity)
-            return sceneJson;
-        if (!entity.transform)
-            entity.transform = { position: DEFAULT_POSITION, rotation: DEFAULT_ROTATION, scale: DEFAULT_SCALE };
-        const nextPosition = data.position !== undefined ? JSON.stringify(data.position) : entity.transform.position;
-        const nextRotation = data.rotation !== undefined ? JSON.stringify(data.rotation) : entity.transform.rotation;
-        const nextScale = data.scale !== undefined ? JSON.stringify(data.scale) : entity.transform.scale;
-        if (entity.transform.position === nextPosition &&
-            entity.transform.rotation === nextRotation &&
-            entity.transform.scale === nextScale) {
-            return sceneJson;
-        }
-        entity.transform.position = nextPosition;
-        entity.transform.rotation = nextRotation;
-        entity.transform.scale = nextScale;
-        return JSON.stringify(parsed);
+            continue;
+        const currentChildren = (previousChildrenById.get(entityId) ?? []).map(String);
+        const desiredChildren = desiredChildrenByParent.get(entityId) ?? [];
+        const mergedChildren = mergeSiblingOrder(currentChildren, desiredChildren, desiredParentById, entityId);
+        entity.childrenIds = mergedChildren.map(Number);
+        entity.childrenIdsSet = [...entity.childrenIds];
     }
-    return sceneJson;
+    manifest.entities = buildManifestEntityMap(store, entities, discoveryIdByPath);
 }
-export async function packageSceneFromFilesystem(sceneJson, sceneDir) {
-    const manifestRaw = await fs.readFile(path.join(sceneDir, "manifest.json"), "utf8");
-    const manifest = JSON.parse(manifestRaw);
-    const appDir = getSceneAppDir(sceneDir);
-    let packagedSceneJson = sceneJson;
-    packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, manifest.sceneScript ?? SCENE_SCRIPT_FILE);
-    packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, manifest.sceneProperties ?? SCENE_PROPERTIES_FILE);
-    for (const folderName of Object.values(manifest.entities)) {
-        packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, path.join(folderName, ENTITY_SCRIPT_FILE).replace(/\\/g, "/"));
-        packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, path.join(folderName, ENTITY_PROPERTIES_FILE).replace(/\\/g, "/"));
-        packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, path.join(folderName, ENTITY_TRANSFORMS_FILE).replace(/\\/g, "/"));
-    }
-    let appEntries = [];
-    try {
-        appEntries = await fs.readdir(appDir, { withFileTypes: true });
+function matchDiscoveriesByFolderName(discoveries, unmatchedEntityIds, entities, manifest, assignedEntityIds, discoveryIdByPath) {
+    for (const discovery of discoveries) {
+        if (discoveryIdByPath.has(discovery.relativePath))
+            continue;
+        const candidates = unmatchedEntityIds.filter((entityId) => {
+            if (assignedEntityIds.has(entityId))
+                return false;
+            const manifestPath = manifest.entities[entityId];
+            return manifestPath != null && path.posix.basename(normalizeRelativePath(manifestPath)) === discovery.folderName;
+        });
+        if (candidates.length !== 1)
+            continue;
+        const entityId = candidates[0];
+        if (!entities[entityId])
+            continue;
+        assignedEntityIds.add(entityId);
+        discoveryIdByPath.set(discovery.relativePath, entityId);
     }
-    catch {
-        return packagedSceneJson;
+}
+function matchDiscoveriesByContent(discoveries, unmatchedEntityIds, entities, assignedEntityIds, discoveryIdByPath) {
+    const signatureToEntityIds = new Map();
+    for (const entityId of unmatchedEntityIds) {
+        if (assignedEntityIds.has(entityId) || !entities[entityId])
+            continue;
+        const signature = getEntityContentSignature(entities[entityId]);
+        const entityIds = signatureToEntityIds.get(signature) ?? [];
+        entityIds.push(entityId);
+        signatureToEntityIds.set(signature, entityIds);
     }
-    for (const entry of appEntries) {
-        if (!entry.isDirectory())
+    for (const discovery of discoveries) {
+        if (discoveryIdByPath.has(discovery.relativePath))
             continue;
-        if (Object.values(manifest.entities).includes(entry.name))
+        const candidateIds = (signatureToEntityIds.get(getDiscoveryContentSignature(discovery)) ?? []).filter((entityId) => !assignedEntityIds.has(entityId));
+        if (candidateIds.length !== 1)
             continue;
-        const relativeScriptPath = path.join(entry.name, ENTITY_SCRIPT_FILE).replace(/\\/g, "/");
-        packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, relativeScriptPath, "add");
-        packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, path.join(entry.name, ENTITY_PROPERTIES_FILE).replace(/\\/g, "/"));
-        packagedSceneJson = await applyIfExists(packagedSceneJson, sceneDir, path.join(entry.name, ENTITY_TRANSFORMS_FILE).replace(/\\/g, "/"));
+        const entityId = candidateIds[0];
+        assignedEntityIds.add(entityId);
+        discoveryIdByPath.set(discovery.relativePath, entityId);
     }
-    return packagedSceneJson;
 }
-async function applyIfExists(sceneJson, sceneDir, relativePath, eventType = "change") {
-    const appDir = getSceneAppDir(sceneDir);
-    const filePath = path.join(appDir, relativePath);
-    try {
-        await fs.access(filePath);
+function getEntityContentSignature(entity) {
+    return JSON.stringify({
+        script: entity.script,
+        properties: entity.properties ?? [],
+        transform: entity.transform ?? {
+            position: DEFAULT_POSITION,
+            rotation: DEFAULT_ROTATION,
+            scale: DEFAULT_SCALE,
+        },
+    });
+}
+function getDiscoveryContentSignature(discovery) {
+    return JSON.stringify({
+        script: discovery.script,
+        properties: discovery.properties,
+        transform: discovery.transform,
+    });
+}
+function createEntityFromDiscovery(engineId, discovery) {
+    return {
+        name: discovery.folderName,
+        engineId,
+        parentId: undefined,
+        childrenIdsSet: [],
+        childrenIds: [],
+        isNodeOpen: false,
+        script: discovery.script,
+        scriptVersion: 0,
+        transform: discovery.transform,
+        renderVersion: 0,
+        properties: discovery.properties,
+        threeId: 0,
+    };
+}
+function mergeSiblingOrder(previousOrder, desiredOrder, desiredParentById, parentId) {
+    const desiredSet = new Set(desiredOrder);
+    const preserved = previousOrder.filter((entityId) => desiredSet.has(entityId) && desiredParentById.get(entityId) === parentId);
+    const appended = desiredOrder.filter((entityId) => !preserved.includes(entityId));
+    return [...preserved, ...appended];
+}
+function buildManifestEntityMap(store, entities, discoveryIdByPath) {
+    const manifestEntities = {};
+    const pathByEntityId = new Map();
+    for (const [relativePath, entityId] of discoveryIdByPath.entries()) {
+        pathByEntityId.set(entityId, relativePath);
     }
-    catch {
-        return sceneJson;
+    function visit(entityId) {
+        const entity = entities[String(entityId)];
+        if (!entity)
+            return;
+        const relativePath = pathByEntityId.get(String(entityId));
+        if (!relativePath)
+            return;
+        manifestEntities[String(entityId)] = relativePath;
+        for (const childId of entity.childrenIds ?? []) {
+            visit(childId);
+        }
+    }
+    for (const rootId of store.rootEntities ?? []) {
+        visit(rootId);
     }
-    return patchSceneFromFile(sceneJson, sceneDir, relativePath, eventType);
+    return manifestEntities;
 }
-async function addNewEntityFromFolder(parsed, manifest, sceneDir, folderName, appDir) {
-    if (Object.values(manifest.entities).includes(folderName))
-        return JSON.stringify(parsed);
-    const scriptPath = path.join(appDir, folderName, ENTITY_SCRIPT_FILE);
-    let script;
+async function scanFilesystemEntities(appDir) {
+    const discovered = [];
+    await scanEntityCollection(appDir, appDir, discovered);
+    return discovered;
+}
+async function scanEntityCollection(collectionDir, appDir, discovered, parentRelativePath) {
+    let entries = [];
     try {
-        script = await fs.readFile(scriptPath, "utf8");
+        entries = await fs.readdir(collectionDir, { withFileTypes: true });
     }
     catch {
-        return JSON.stringify(parsed);
+        return;
     }
-    let properties = [];
+    entries = entries.filter((entry) => entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const entityDir = path.join(collectionDir, entry.name);
+        const relativePath = normalizeRelativePath(path.relative(appDir, entityDir));
+        const scriptPath = path.join(entityDir, ENTITY_SCRIPT_FILE);
+        let script;
+        try {
+            script = await fs.readFile(scriptPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const discovery = {
+            relativePath,
+            folderName: entry.name,
+            parentRelativePath,
+            script,
+            properties: await readPropertiesFile(entityDir),
+            transform: await readTransformFile(entityDir),
+        };
+        discovered.push(discovery);
+        await scanEntityCollection(path.join(entityDir, CHILDREN_DIR_NAME), appDir, discovered, relativePath);
+    }
+}
+async function readPropertiesFile(entityDir) {
     try {
-        const raw = await fs.readFile(path.join(appDir, folderName, ENTITY_PROPERTIES_FILE), "utf8");
-        const parsedProps = JSON.parse(raw);
-        if (Array.isArray(parsedProps))
-            properties = parsedProps;
+        const raw = await fs.readFile(path.join(entityDir, ENTITY_PROPERTIES_FILE), "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
     }
     catch {
-        /* optional */
+        return [];
     }
-    let transform = { position: DEFAULT_POSITION, rotation: DEFAULT_ROTATION, scale: DEFAULT_SCALE };
+}
+async function readTransformFile(entityDir) {
     try {
-        const raw = await fs.readFile(path.join(appDir, folderName, ENTITY_TRANSFORMS_FILE), "utf8");
-        const t = JSON.parse(raw);
-        if (t.position !== undefined)
-            transform.position = JSON.stringify(t.position);
-        if (t.rotation !== undefined)
-            transform.rotation = JSON.stringify(t.rotation);
-        if (t.scale !== undefined)
-            transform.scale = JSON.stringify(t.scale);
+        const raw = await fs.readFile(path.join(entityDir, ENTITY_TRANSFORMS_FILE), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            position: parsed.position !== undefined ? JSON.stringify(parsed.position) : DEFAULT_POSITION,
+            rotation: parsed.rotation !== undefined ? JSON.stringify(parsed.rotation) : DEFAULT_ROTATION,
+            scale: parsed.scale !== undefined ? JSON.stringify(parsed.scale) : DEFAULT_SCALE,
+        };
     }
     catch {
-        /* optional */
-    }
-    if (!parsed.entityStore) {
-        parsed.entityStore = {
-            _currId: 0,
-            rootEntities: [],
-            entities: {},
-            rootRenderVersion: 0,
-            lastRenderedVersion: 0,
-            selectedEntityIds: [],
+        return {
+            position: DEFAULT_POSITION,
+            rotation: DEFAULT_ROTATION,
+            scale: DEFAULT_SCALE,
         };
     }
-    const store = parsed.entityStore;
-    const existingIds = [...Object.keys(manifest.entities).map(Number), store._currId];
-    const engineId = existingIds.length ? Math.max(...existingIds) + 1 : 1;
-    const idStr = String(engineId);
-    store._currId = Math.max(store._currId, engineId);
-    if (!store.rootEntities.includes(engineId))
-        store.rootEntities.push(engineId);
-    store.entities[idStr] = {
-        name: folderName,
-        engineId,
-        childrenIdsSet: [],
-        childrenIds: [],
-        isNodeOpen: false,
-        script,
-        scriptVersion: 0,
-        transform,
-        renderVersion: 0,
-        properties,
-        threeId: 0,
-    };
-    manifest.entities[idStr] = folderName;
-    await fs.writeFile(path.join(sceneDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
-    return JSON.stringify(parsed);
 }

package/dist/lib/scene/script-watcher.js

@@ -1,39 +1,43 @@
-import * as path from "path";
+import * as path from "node:path";
 import chokidar from "chokidar";
+import { MANIFEST_FILE_NAME } from "../constants.js";
 import { getSceneAppDir } from "./file-system.js";
-import { patchSceneFromFile, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE } from "./scene-packaging.js";
+import { packageSceneFromFilesystem, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE, } from "./scene-packaging.js";
 const DEBOUNCE_MS = 100;
 export function createScriptWatcher(sceneDir, getLatestSceneJson, onSceneUpdated, onError) {
     const appDir = getSceneAppDir(sceneDir);
     function toRelativePath(filePath) {
         return path.relative(appDir, filePath).replace(/\\/g, "/");
     }
-    function isRelevantFile(relativePath) {
+    function isRelevantPath(relativePath) {
         if (relativePath === SCENE_SCRIPT_FILE || relativePath === SCENE_PROPERTIES_FILE)
             return true;
-        const match = relativePath.match(/^([^/]+)\/(.+)$/);
-        if (!match)
+        if (!relativePath || relativePath === ".")
             return false;
-        const [, , fileName] = match;
-        return (fileName === ENTITY_SCRIPT_FILE ||
-            fileName === ENTITY_PROPERTIES_FILE ||
-            fileName === ENTITY_TRANSFORMS_FILE);
+        const fileName = path.posix.basename(relativePath);
+        if (fileName === ENTITY_SCRIPT_FILE || fileName === ENTITY_PROPERTIES_FILE || fileName === ENTITY_TRANSFORMS_FILE) {
+            return true;
+        }
+        // Directory adds/removals can represent entity creates, deletes, or moves.
+        if (!path.posix.extname(fileName)) {
+            return true;
+        }
+        return false;
     }
     let debounceTimer = null;
-    let lastEvent = null;
-    function schedule(type, relativePath) {
-        lastEvent = { type, relativePath };
+    let lastRelativePath = null;
+    function schedule(relativePath) {
+        lastRelativePath = relativePath;
         if (debounceTimer)
             clearTimeout(debounceTimer);
         debounceTimer = setTimeout(async () => {
             debounceTimer = null;
-            const ev = lastEvent;
-            lastEvent = null;
-            if (!ev)
+            const rp = lastRelativePath;
+            lastRelativePath = null;
+            if (!rp)
                 return;
-            const rp = ev.relativePath;
             try {
-                const updated = await patchSceneFromFile(getLatestSceneJson(), sceneDir, rp, ev.type);
+                const updated = await packageSceneFromFilesystem(getLatestSceneJson(), sceneDir);
                 onSceneUpdated(updated);
             }
             catch (err) {
@@ -43,20 +47,18 @@ export function createScriptWatcher(sceneDir, getLatestSceneJson, onSceneUpdated
         }, DEBOUNCE_MS);
     }
     const watcher = chokidar.watch(appDir, { ignoreInitial: true });
-    watcher.on("change", (filePath) => {
+    function handlePathEvent(filePath) {
         const relativePath = toRelativePath(filePath);
-        if (relativePath === "manifest.json")
+        if (relativePath === MANIFEST_FILE_NAME)
             return;
-        if (isRelevantFile(relativePath))
-            schedule("change", relativePath);
-    });
-    watcher.on("add", (filePath) => {
-        const relativePath = toRelativePath(filePath);
-        if (relativePath === "manifest.json")
-            return;
-        if (isRelevantFile(relativePath))
-            schedule("add", relativePath);
-    });
+        if (isRelevantPath(relativePath))
+            schedule(relativePath);
+    }
+    watcher.on("change", handlePathEvent);
+    watcher.on("add", handlePathEvent);
+    watcher.on("unlink", handlePathEvent);
+    watcher.on("addDir", handlePathEvent);
+    watcher.on("unlinkDir", handlePathEvent);
     return {
         close: () => {
             if (debounceTimer)

package/dist/lib/types.d.ts

@@ -19,6 +19,7 @@ export type PhibelleScene = {
             [id: string]: {
                 name: string;
                 engineId: number;
+                parentId?: number;
                 childrenIdsSet: number[];
                 childrenIds: number[];
                 isNodeOpen: boolean;

package/dist/lib/utils.d.ts

@@ -1 +1,3 @@
 export declare function toErrorMessage(err: unknown): string;
+/** For exec/child_process errors: prefer stderr (last line), otherwise message. */
+export declare function getExecErrorText(error: unknown): string;

package/dist/lib/utils.js

@@ -1,3 +1,13 @@
 export function toErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** For exec/child_process errors: prefer stderr (last line), otherwise message. */
+export function getExecErrorText(error) {
+    if (!error || typeof error !== "object")
+        return "";
+    const err = error;
+    const stderr = err.stderr?.trim();
+    if (stderr)
+        return stderr.split("\n").pop() ?? stderr;
+    return err.message?.trim() ?? "";
+}

package/dist/scene-setup/setup.d.ts

@@ -1,4 +1,3 @@
 export declare function setupSceneDirectory(sceneDir: string): {
     shouldPromptInstall: boolean;
 };
-export declare function getInstallHint(sceneDir: string): string;

package/dist/scene-setup/setup.js

@@ -39,18 +39,3 @@ export function setupSceneDirectory(sceneDir) {
     }
     return { shouldPromptInstall };
 }
-export function getInstallHint(sceneDir) {
-    const hasPnpm = fs.existsSync(path.join(sceneDir, "pnpm-lock.yaml"));
-    const hasYarn = fs.existsSync(path.join(sceneDir, "yarn.lock"));
-    const hasBun = fs.existsSync(path.join(sceneDir, "bun.lockb"));
-    const hasNpm = fs.existsSync(path.join(sceneDir, "package-lock.json"));
-    if (hasPnpm)
-        return "pnpm install";
-    if (hasBun)
-        return "bun install";
-    if (hasYarn)
-        return "yarn install";
-    if (hasNpm)
-        return "npm install";
-    return "npm install (or pnpm / bun / yarn install)";
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phibelle-kit",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "CLI tool for interacting with the Phibelle engine",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test tests/*.test.mjs"
   },
   "engines": {
     "node": ">=20"