phibelle-kit 1.0.22 → 1.0.24

package/dist/commands/clone-scene.d.ts

@@ -1,5 +1 @@
-/**
- * Clone: one-time fetch of scene data. Creates scene dir, writes scene.json,
- * sets up package.json/global.d.ts, unpacks scripts. No watcher, no opening folder.
- */
-export declare function cloneSceneCommand(sceneId: string): Promise<void>;
+export declare function cloneSceneCommand(): Promise<void>;

package/dist/commands/clone-scene.js

@@ -1,37 +1,130 @@
 import chalk from "chalk";
-import * as path from "path";
-import { queryOnce, BASE_URL } from "../lib/api/index.js";
-import { api } from "../convex/_generated/api.js";
-import { sceneNameToFolder, setupSceneFiles, unpackageWithLogging } from "../lib/scene/index.js";
-/**
- * Clone: one-time fetch of scene data. Creates scene dir, writes scene.json,
- * sets up package.json/global.d.ts, unpacks scripts. No watcher, no opening folder.
- */
-export async function cloneSceneCommand(sceneId) {
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { WebSocketServer } from "ws";
+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;
+export async function cloneSceneCommand() {
+    const parentDir = process.cwd();
     console.log();
-    console.log(chalk.bold.cyan("  📥 Cloning scene..."));
-    console.log(chalk.gray(`  Scene ID: ${sceneId}`));
+    console.log(chalk.bold.cyan("  Cloning scene from editor..."));
+    console.log(chalk.gray(`  Target parent dir: ${parentDir}`));
+    console.log(chalk.yellow("  Keep the editor open while cloning and make sure the WebSocket is enabled."));
     console.log();
-    const scene = await queryOnce(api.scenes.getById, {
-        id: sceneId,
+    const payload = await requestClonePayload();
+    validateClonePayload(payload);
+    const safeDirName = sanitizeDirectoryName(payload.sceneName);
+    const sceneDir = path.join(parentDir, safeDirName);
+    await ensureDirectoryDoesNotExist(sceneDir);
+    await fs.mkdir(sceneDir, { recursive: false });
+    setupSceneDirectory(sceneDir);
+    await fs.writeFile(path.join(sceneDir, "scene.phibelle"), payload.sceneData, "utf8");
+    await unpackageScene(payload.sceneData, sceneDir, payload.sceneId);
+    console.log(chalk.green("  ✓ Scene cloned successfully"));
+    console.log(chalk.gray(`  Directory: ${sceneDir}`));
+    console.log(chalk.yellow("  Next steps:"));
+    console.log(chalk.cyan(`    1. cd "${safeDirName}"`));
+    console.log(chalk.cyan(`    2. npm install`));
+    console.log(chalk.cyan(`    3. npm run watch`));
+    console.log();
+    process.exit(0);
+}
+function requestClonePayload() {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const wss = new WebSocketServer({ port: WS_PORT });
+        const closeServer = () => {
+            try {
+                wss.close();
+            }
+            catch {
+                // no-op
+            }
+        };
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            closeServer();
+            reject(new Error("Timed out waiting for scene payload from editor. Make sure the editor is open on the scene you want to clone."));
+        }, CLONE_TIMEOUT_MS);
+        wss.on("connection", (ws) => {
+            ws.send(JSON.stringify({ type: CLONE_REQUEST_TYPE }));
+            ws.on("message", (data) => {
+                if (settled)
+                    return;
+                const raw = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    return;
+                }
+                if (!isCloneResponse(parsed))
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                closeServer();
+                resolve(parsed);
+            });
+            ws.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                closeServer();
+                reject(err);
+            });
+        });
+        wss.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            closeServer();
+            reject(err);
+        });
     });
-    if (scene === null) {
-        console.log(chalk.red("  ✖ Scene not found"));
-        console.log();
-        process.exit(1);
+}
+function isCloneResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const obj = value;
+    return (obj.type === CLONE_RESPONSE_TYPE &&
+        typeof obj.sceneName === "string" &&
+        typeof obj.sceneId === "string" &&
+        typeof obj.sceneData === "string");
+}
+function validateClonePayload(payload) {
+    if (!payload.sceneName.trim()) {
+        throw new Error("Clone payload is missing a valid scene name.");
     }
-    const sceneFolderName = sceneNameToFolder(scene.name);
-    const sceneDir = path.join(process.cwd(), sceneFolderName);
-    setupSceneFiles(scene, sceneDir, true);
-    await unpackageWithLogging(scene._id, sceneDir, "Edit the scene in the app once to create a scene file, then run clone again.");
-    console.log(chalk.green("  ✓ Cloned scene"));
-    console.log(chalk.white(`    Name: ${scene.name}`));
-    console.log(chalk.white(`    Path: ${sceneDir}`));
-    console.log(chalk.white("    Scene link: ") + chalk.cyan(`${BASE_URL}/editor?sceneId=${scene._id}`));
-    console.log();
-    console.log(chalk.gray("  Next steps:"));
-    console.log(chalk.gray("    1. ") + chalk.blueBright("cd ") + chalk.cyan(sceneFolderName) + chalk.gray(" to open the scene directory."));
-    console.log(chalk.gray("    2. ") + chalk.blueBright("npm install") + chalk.gray(" to install the dependencies."));
-    console.log(chalk.gray("    3. ") + chalk.blueBright("npm run watch ") + chalk.gray(" to watch for changes and push edits."));
-    console.log();
+    if (!payload.sceneId.trim()) {
+        throw new Error("Clone payload is missing a valid scene id.");
+    }
+    parseSceneJson(payload.sceneData);
+}
+function sanitizeDirectoryName(sceneName) {
+    const sanitized = sceneName
+        .trim()
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, "-")
+        .replace(/\s+/g, " ")
+        .replace(/\.+$/g, "");
+    if (!sanitized)
+        return "scene-clone";
+    return sanitized;
+}
+async function ensureDirectoryDoesNotExist(sceneDir) {
+    try {
+        await fs.access(sceneDir);
+    }
+    catch {
+        return;
+    }
+    throw new Error(`Target folder already exists: ${sceneDir}. Rename the scene or clone into another directory.`);
 }

package/dist/commands/init-scene.d.ts

@@ -0,0 +1 @@
+export declare function initSceneCommand(): void;

package/dist/commands/init-scene.js

@@ -0,0 +1,16 @@
+import chalk from "chalk";
+import { setupSceneDirectory, getInstallHint } from "../scene-setup/setup.js";
+export function initSceneCommand() {
+    const sceneDir = process.cwd();
+    console.log();
+    console.log(chalk.bold.cyan("  Initializing scene..."));
+    console.log(chalk.gray(`  Dir: ${sceneDir}`));
+    console.log();
+    const { shouldPromptInstall } = setupSceneDirectory(sceneDir);
+    console.log(chalk.green("  ✓ Created package.json, tsconfig.json, global.d.ts, AGENTS.md"));
+    if (shouldPromptInstall) {
+        console.log(chalk.yellow("  Install dependencies: ") + chalk.cyan(getInstallHint(sceneDir)));
+    }
+    console.log(chalk.gray("  Next: open a scene in the app, then run ") + chalk.cyan("pnpm run watch") + chalk.gray(" to sync."));
+    console.log();
+}

package/dist/commands/watch-scene.d.ts

@@ -1 +1,2 @@
-export declare function watchSceneCommand(sceneId: string): Promise<void>;
+export declare const BASE_URL: string;
+export declare function watchSceneCommand(): Promise<void>;

package/dist/commands/watch-scene.js

@@ -1,99 +1,132 @@
 import chalk from "chalk";
 import * as path from "path";
 import * as fs from "fs";
-import { subscribeToQuery, BASE_URL } from "../lib/api/index.js";
-import { api } from "../convex/_generated/api.js";
-import { getSessionId } from "../lib/auth/index.js";
-import { findSceneDirBySceneId, sceneNameToFolder, unpackageScene, createScriptWatcher, runFirstUpdateSetup, } from "../lib/scene/index.js";
+import { WebSocketServer } from "ws";
+import { unpackageScene, parseSceneJson } from "../lib/scene/scene-packaging.js";
+import { createScriptWatcher } from "../lib/scene/script-watcher.js";
 import { toErrorMessage } from "../lib/utils.js";
-function createWatchCallbacks() {
-    return {
-        onPushed: (file) => console.log(chalk.green("  ✓ Pushed " + file + " to Convex")),
-        onNewEntity: (engineId, fileName) => console.log(chalk.green("  ✓ Created new entity " + engineId + (fileName ? " (" + fileName + ")" : ""))),
-        onError: (file, err) => console.log(chalk.red("  ✖ Failed to push " + file + ": " + err.message)),
-    };
-}
-function startScriptWatcher(scene, sceneDir) {
-    const c = createWatchCallbacks();
-    return createScriptWatcher(scene._id, sceneDir, c.onPushed, c.onNewEntity, c.onError);
-}
-export async function watchSceneCommand(sceneId) {
+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();
+    const manifestSceneId = getRequiredManifestSceneId(sceneDir);
+    let lastPrintedEditorLink = null;
+    console.log();
+    console.log(chalk.bold.cyan("  Watching for scene sync (WebSocket)"));
+    console.log(chalk.gray(`  Dir: ${sceneDir}`));
+    lastPrintedEditorLink = printEditorLink(manifestSceneId, lastPrintedEditorLink);
+    console.log(chalk.yellow("  Waiting for connection from local development server..."));
     console.log();
-    console.log(chalk.bold.cyan("  👀 Watching scene updates..."));
-    console.log(chalk.gray(`  Scene ID: ${sceneId}`));
-    console.log(chalk.white("  Scene link: ") + chalk.cyan(`${BASE_URL}/editor?sceneId=${sceneId}`));
-    let previousUpdatedAt = null;
-    let isFirstUpdate = true;
+    console.log(chalk.gray("  Press Ctrl+C to stop"));
+    console.log();
+    let latestSceneJson = "";
     let scriptWatcher = null;
-    try {
-        const unsubscribe = subscribeToQuery(api.scenes.getById, { id: sceneId }, async (scene) => {
-            if (scene === null) {
-                if (isFirstUpdate) {
-                    console.log(chalk.red("  ✖ Scene not found"));
-                    console.log();
-                    process.exit(1);
-                }
+    let currentClient = null;
+    function startWatcher() {
+        scriptWatcher?.close();
+        scriptWatcher = createScriptWatcher(sceneDir, () => latestSceneJson, (json) => {
+            latestSceneJson = json;
+            if (currentClient && currentClient.readyState === 1)
+                currentClient.send(json);
+        }, (file, err) => console.log(chalk.red("  ✖ " + file + ": " + err.message)));
+    }
+    const wss = new WebSocketServer({ port: WS_PORT });
+    wss.on("connection", (ws) => {
+        currentClient = ws;
+        ws.on("message", async (data) => {
+            const raw = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+            if (!raw || raw.length === 0)
+                return;
+            const incoming = parseIncomingSceneMessage(raw);
+            if (!incoming)
+                return;
+            try {
+                parseSceneJson(incoming.sceneData);
+            }
+            catch {
                 return;
             }
-            const currentUpdatedAt = scene.updatedAt;
-            const cwd = process.cwd();
-            const sceneDir = findSceneDirBySceneId(cwd, sceneId) ?? path.join(cwd, sceneNameToFolder(scene.name));
-            const manifestPath = path.join(sceneDir, "manifest.json");
-            const alreadyCloned = fs.existsSync(manifestPath);
-            if (isFirstUpdate) {
-                if (alreadyCloned) {
-                    fs.writeFileSync(path.join(sceneDir, "scene.json"), JSON.stringify(scene));
-                    scriptWatcher = startScriptWatcher(scene, sceneDir);
-                    console.log(chalk.green("  ✓ Watching scene (previously cloned)"));
-                    console.log(chalk.white(`    Name: ${scene.name}`));
-                    console.log(chalk.white(`    Dir: ${sceneDir}`));
-                    console.log(chalk.gray("  Press Ctrl+C to stop"));
-                    console.log();
-                }
-                else {
-                    scriptWatcher = await runFirstUpdateSetup(scene, sceneDir, createWatchCallbacks());
-                }
-                previousUpdatedAt = currentUpdatedAt;
-                isFirstUpdate = false;
+            latestSceneJson = incoming.sceneData;
+            const scenePath = path.join(sceneDir, SCENE_FILE_NAME);
+            fs.writeFileSync(scenePath, incoming.sceneData, "utf8");
+            try {
+                await unpackageScene(incoming.sceneData, sceneDir, incoming.sceneId);
+                console.log(chalk.green("  ✓ Synced scene from app"));
+                const updatedManifestSceneId = getRequiredManifestSceneId(sceneDir);
+                lastPrintedEditorLink = printEditorLink(updatedManifestSceneId, lastPrintedEditorLink);
             }
-            else if (previousUpdatedAt !== null && currentUpdatedAt !== previousUpdatedAt) {
-                fs.writeFileSync(path.join(sceneDir, "scene.json"), JSON.stringify(scene));
-                console.log(chalk.green("  ✓ Scene updated"));
-                console.log(chalk.white(`    Timestamp: ${new Date(currentUpdatedAt).toLocaleString()}`));
-                const ourSessionId = getSessionId();
-                const weSaved = scene.lastModifiedSessionId != null && scene.lastModifiedSessionId === ourSessionId;
-                if (!weSaved) {
-                    scriptWatcher?.close();
-                    scriptWatcher = null;
-                    try {
-                        await unpackageScene(scene._id, sceneDir);
-                        console.log(chalk.green("  ✓ Re-unpackaged scene (scene-script.tsx, scene-properties.json, entity folders with script.tsx, properties.json, transforms.json, manifest.json)"));
-                        scriptWatcher = startScriptWatcher(scene, sceneDir);
-                    }
-                    catch (e) {
-                        console.log(chalk.yellow("  ⚠ Could not re-unpackage scene scripts: " + toErrorMessage(e)));
-                    }
-                }
-                console.log();
-                previousUpdatedAt = currentUpdatedAt;
+            catch (e) {
+                console.log(chalk.yellow("  ⚠ Unpackage: " + toErrorMessage(e)));
             }
+            startWatcher();
         });
-        process.on("SIGINT", () => {
-            console.log();
-            console.log(chalk.gray("  Unsubscribing..."));
-            scriptWatcher?.close();
-            scriptWatcher = null;
-            unsubscribe();
-            console.log(chalk.gray("  Goodbye! 👋"));
-            console.log();
-            process.exit(0);
+        ws.on("close", () => {
+            if (currentClient === ws)
+                currentClient = null;
         });
-        await new Promise(() => { });
-    }
-    catch (error) {
+    });
+    process.on("SIGINT", () => {
         console.log();
-        console.log(chalk.red(`  ✖ Error: ${toErrorMessage(error)}`));
+        scriptWatcher?.close();
+        scriptWatcher = null;
+        wss.close();
+        console.log(chalk.gray("  Goodbye"));
         console.log();
-        throw error;
+        process.exit(0);
+    });
+    await new Promise(() => { });
+}
+function parseIncomingSceneMessage(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (isSceneSyncMessage(parsed)) {
+            return { sceneData: parsed.sceneData, sceneId: parsed.sceneId?.trim() || undefined };
+        }
+    }
+    catch {
+        // Treat as raw scene payload for backwards compatibility.
+    }
+    return { sceneData: raw };
+}
+function isSceneSyncMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const obj = value;
+    return (obj.type === SCENE_SYNC_TYPE &&
+        typeof obj.sceneData === "string" &&
+        (obj.sceneId === undefined || typeof obj.sceneId === "string"));
+}
+function printEditorLink(sceneId, lastPrintedLink) {
+    const editorUrl = `${BASE_URL}/editor?sceneId=${encodeURIComponent(sceneId)}&wsEnabled=true`;
+    if (editorUrl === lastPrintedLink)
+        return lastPrintedLink;
+    console.log(chalk.cyan(`  Editor: ${editorUrl}`));
+    return editorUrl;
+}
+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/constants.d.ts

@@ -0,0 +1,2 @@
+/** WebSocket port for CLI ↔ app scene sync. Shared so the app and kit stay in sync. */
+export declare const CLI_WS_PORT = 31113;

package/dist/constants.js

@@ -0,0 +1,2 @@
+/** WebSocket port for CLI ↔ app scene sync. Shared so the app and kit stay in sync. */
+export const CLI_WS_PORT = 31113;

package/dist/index.js

@@ -1,30 +1,26 @@
 #!/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";
-import { waitForToken } from "./lib/auth/wait-for-token.js";
-const USAGE = "  Usage: phibelle-kit clone <sceneId> | phibelle-kit watch <sceneId>";
+const USAGE = "  Usage: phibelle-kit init | phibelle-kit watch | phibelle-kit clone";
 async function main() {
     const command = process.argv[2];
-    const sceneId = process.argv[3];
-    if (!command || !sceneId) {
-        console.log(chalk.red("  Command and scene ID are required"));
-        console.log(chalk.gray(USAGE));
-        process.exit(1);
+    if (command === "init") {
+        initSceneCommand();
+        return;
     }
-    await waitForToken();
-    if (command === "clone") {
-        await cloneSceneCommand(sceneId);
-        process.exit(0);
-    }
-    else if (command === "watch") {
-        await watchSceneCommand(sceneId);
+    if (command === "watch") {
+        await watchSceneCommand();
+        return;
     }
-    else {
-        console.log(chalk.red(`  Unknown command: ${command}`));
-        console.log(chalk.gray(USAGE));
-        process.exit(1);
+    if (command === "clone") {
+        await cloneSceneCommand();
+        return;
     }
+    console.log(chalk.red("  Unknown or missing command"));
+    console.log(chalk.gray(USAGE));
+    process.exit(1);
 }
 main().catch((error) => {
     console.error(chalk.red("Error:"), error.message);

package/dist/lib/api/index.d.ts

@@ -1,2 +1 @@
-export { createConvexClient, subscribeToQuery, queryOnce, mutateOnce } from "./convex-client.js";
-export { CONVEX_URL, BASE_URL } from "./public-env.js";
+export { BASE_URL } from "./public-env.js";

package/dist/lib/api/index.js

@@ -1,2 +1 @@
-export { createConvexClient, subscribeToQuery, queryOnce, mutateOnce } from "./convex-client.js";
-export { CONVEX_URL, BASE_URL } from "./public-env.js";
+export { BASE_URL } from "./public-env.js";

package/dist/lib/api/public-env.d.ts

@@ -1,3 +1,2 @@
 export declare const isDev: boolean;
 export declare const BASE_URL: string;
-export declare const CONVEX_URL: string;

package/dist/lib/api/public-env.js

@@ -1,3 +1,2 @@
 export const isDev = process.env.NODE_ENV === "development";
 export const BASE_URL = isDev ? "http://localhost:3131" : "https://phibelle.studio";
-export const CONVEX_URL = isDev ? "https://mellow-toad-676.convex.cloud" : "https://keen-dove-500.convex.cloud";

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

@@ -1,8 +1,9 @@
 export declare const SCENE_APP_DIR = "app";
+export declare const SCENE_FILE_NAME = "scene.phibelle";
 export declare function getSceneAppDir(sceneDir: string): string;
 export declare function folderExists(folderPath: string): boolean;
 export declare function createFolder(folderPath: string): void;
 /** Scene name to folder name: lowercased, spaces to hyphens, safe for filesystem. */
 export declare function sceneNameToFolder(name: string): string;
-/** Find directory containing scene.json with _id === sceneId: check cwd first, then subdirs. */
+/** Find directory containing scene.phibelle with _id === sceneId: check cwd first, then subdirs. */
 export declare function findSceneDirBySceneId(cwd: string, sceneId: string): string | null;

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

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import * as fs from "fs";
 export const SCENE_APP_DIR = "app";
+export const SCENE_FILE_NAME = "scene.phibelle";
 export function getSceneAppDir(sceneDir) {
     return path.join(sceneDir, SCENE_APP_DIR);
 }
@@ -21,9 +22,9 @@ export function sceneNameToFolder(name) {
         .replace(/-+/g, "-")
         .replace(/^-|-$/g, "") || "scene";
 }
-/** Find directory containing scene.json with _id === sceneId: check cwd first, then subdirs. */
+/** Find directory containing scene.phibelle with _id === sceneId: check cwd first, then subdirs. */
 export function findSceneDirBySceneId(cwd, sceneId) {
-    const scenePathInCwd = path.join(cwd, "scene.json");
+    const scenePathInCwd = path.join(cwd, SCENE_FILE_NAME);
     try {
         const raw = fs.readFileSync(scenePathInCwd, "utf8");
         const data = JSON.parse(raw);
@@ -43,7 +44,7 @@ export function findSceneDirBySceneId(cwd, sceneId) {
     for (const ent of entries) {
         if (!ent.isDirectory())
             continue;
-        const scenePath = path.join(cwd, ent.name, "scene.json");
+        const scenePath = path.join(cwd, ent.name, SCENE_FILE_NAME);
         try {
             const raw = fs.readFileSync(scenePath, "utf8");
             const data = JSON.parse(raw);
@@ -51,7 +52,7 @@ export function findSceneDirBySceneId(cwd, sceneId) {
                 return path.join(cwd, ent.name);
         }
         catch {
-            // no scene.json or invalid
+            // no scene.phibelle or invalid
         }
     }
     return null;

package/dist/lib/scene/first-run-setup.d.ts

@@ -1,7 +1,11 @@
 import { type ScriptWatcher } from "./script-watcher.js";
+import { type WsServer } from "../ws/index.js";
 import type { Scene, WatchCallbacks } from "../types.js";
 /** Create scene dir, write scene.json, setup package.json/global.d.ts; log install hint if needed. */
 export declare function setupSceneFiles(scene: Scene, sceneDir: string, ignoreHint?: boolean): void;
 /** Unpackage scene scripts; log success or hint on failure. */
 export declare function unpackageWithLogging(sceneId: string, sceneDir: string, failHint: string): Promise<void>;
-export declare function runFirstUpdateSetup(scene: Scene, sceneDir: string, callbacks: WatchCallbacks): Promise<ScriptWatcher>;
+export declare function runFirstUpdateSetup(scene: Scene, sceneDir: string, callbacks: WatchCallbacks, wsPort: number): Promise<{
+    scriptWatcher: ScriptWatcher;
+    wsServer: WsServer;
+}>;

package/dist/lib/scene/first-run-setup.js

@@ -3,8 +3,10 @@ import * as path from "path";
 import * as fs from "fs";
 import { BASE_URL } from "../api/public-env.js";
 import { createFolder } from "./file-system.js";
-import { unpackageScene } from "./scene-packaging.js";
-import { createScriptWatcher } from "./script-watcher.js";
+import { unpackageScene, getSceneFileContent } from "./scene-packaging.js";
+import { createWsScriptWatcher } from "./script-watcher.js";
+import { SceneState } from "./scene-state.js";
+import { createWsServer } from "../ws/index.js";
 import { setupSceneDirectory, getInstallHint } from "../../scene-setup/setup.js";
 import { toErrorMessage } from "../utils.js";
 const INSTALL_HINT_LABEL = "  ⚠ Install dependencies for types and intellisense:";
@@ -30,7 +32,7 @@ export async function unpackageWithLogging(sceneId, sceneDir, failHint) {
         console.log(chalk.gray("    " + failHint));
     }
 }
-export async function runFirstUpdateSetup(scene, sceneDir, callbacks) {
+export async function runFirstUpdateSetup(scene, sceneDir, callbacks, wsPort) {
     setupSceneFiles(scene, sceneDir);
     console.log(chalk.yellow("  Opening folder: " + sceneDir));
     console.log();
@@ -41,5 +43,9 @@ export async function runFirstUpdateSetup(scene, sceneDir, callbacks) {
     console.log(chalk.white(`    Last updated: ${new Date(scene.updatedAt).toLocaleString()}`));
     console.log(chalk.white("    Scene Link: ") + chalk.cyan(`${BASE_URL}/editor?sceneId=${scene._id}`));
     console.log();
-    return createScriptWatcher(scene._id, sceneDir, callbacks.onPushed, callbacks.onNewEntity, callbacks.onError);
+    const initialJson = await getSceneFileContent(scene._id);
+    const sceneState = new SceneState(initialJson);
+    const wsServer = createWsServer(wsPort, { getSceneJson: () => sceneState.getJson() });
+    const scriptWatcher = createWsScriptWatcher(sceneState, sceneDir, wsServer, callbacks.onPushed, callbacks.onNewEntity, callbacks.onError);
+    return { scriptWatcher, wsServer };
 }

package/dist/lib/scene/index.d.ts

@@ -1,4 +1,3 @@
-export { setupSceneFiles, unpackageWithLogging, runFirstUpdateSetup } from "./first-run-setup.js";
 export { createScriptWatcher, type ScriptWatcher } from "./script-watcher.js";
 export { findSceneDirBySceneId, sceneNameToFolder, getSceneAppDir, createFolder, folderExists, SCENE_APP_DIR, } from "./file-system.js";
-export { unpackageScene, entityNameToSlug, slugToEntityName, ENTITY_FOLDER_RE, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE, } from "./scene-packaging.js";
+export { unpackageScene, entityNameToSlug, slugToEntityName, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE, } from "./scene-packaging.js";

package/dist/lib/scene/index.js

@@ -1,4 +1,3 @@
-export { setupSceneFiles, unpackageWithLogging, runFirstUpdateSetup } from "./first-run-setup.js";
 export { createScriptWatcher } from "./script-watcher.js";
 export { findSceneDirBySceneId, sceneNameToFolder, getSceneAppDir, createFolder, folderExists, SCENE_APP_DIR, } from "./file-system.js";
-export { unpackageScene, entityNameToSlug, slugToEntityName, ENTITY_FOLDER_RE, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE, } from "./scene-packaging.js";
+export { unpackageScene, entityNameToSlug, slugToEntityName, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE, } from "./scene-packaging.js";

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

@@ -1,26 +1,20 @@
+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;
-/**
- * Matches entity folder names: <entity-name>-<engineId> (e.g. main-enemy-1).
- * Group 1 = slug, group 2 = engine id.
- */
-export declare const ENTITY_FOLDER_RE: RegExp;
 /** 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 unpackageScene(sceneId: string, sceneDir: string): Promise<void>;
-export declare function pushScriptChange(sceneId: string, sceneDir: string, changedFile: string): Promise<void>;
-/** Push entity properties from app/<folder>/properties.json to the scene. */
-export declare function pushPropertiesChange(sceneId: string, sceneDir: string, relativePath: string): Promise<void>;
-/** Push scene properties from app/scene-properties.json to the scene. */
-export declare function pushScenePropertiesChange(sceneId: string, sceneDir: string): Promise<void>;
-/** Push entity transform from app/<folder>/transforms.json to the scene. */
-export declare function pushTransformsChange(sceneId: string, sceneDir: string, relativePath: string): Promise<void>;
-/** Add a new entity to the scene when user creates <entity-name>-<engineId>/ with script.tsx (and optional properties.json, transforms.json). */
-export declare function pushNewEntity(sceneId: string, sceneDir: string, engineId: number, folderName: string): Promise<void>;
+/** 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>;