@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/file-system-manager.js

@@ -1,30 +1,36 @@
 import fs from "fs/promises";
-import EventEmitter from "node:events";
-import path from "node:path";
-import { transformFromAstAsync } from "@babel/core";
-import t from "@babel/types";
-import { getClientApiId, PROCESSED_TRANSACTIONS_ATTRIBUTE, ROOT_WIDGET_ATTRIBUTE, WIDGET_SOURCE_ID_ATTRIBUTE, } from "@superblocksteam/library-shared";
-import { readAppApiYamlFile, writeApiFiles, } from "@superblocksteam/util";
+import nodePath from "node:path";
+import * as t from "@babel/types";
 import { glob } from "glob";
-import { isEqual } from "lodash-es";
+import { isEqual, debounce } from "lodash-es";
+import { normalizePath } from "vite";
 import yaml from "yaml";
+import { PROCESSED_TRANSACTIONS_ATTRIBUTE, ROOT_WIDGET_ATTRIBUTE, SOURCE_ID_ATTRIBUTE, } from "@superblocksteam/library-shared";
+import { addTracingToMethods, TracedEventEmitter, } from "@superblocksteam/shared";
+import { readAppApiYamlFile, writeApiFiles, } from "@superblocksteam/util";
 import { generateJSXAttribute } from "./codegen.js";
+import { ComponentsManager } from "./components-manager.js";
 import { addLegacyCustomComponentVariables, modifyLegacyCustomComponentElements, modifyLegacyCustomComponentImports, } from "./custom-components.js";
 import { applyErrorHandling, } from "./errors/error-handler.js";
-import { getPageFolder, PAGES_DIRECTORY, ROUTES_FILE, SCOPE_FILE, } from "./file-system-helpers.js";
+import { getApiFilePath, isApiFilePath, isPageFilePath, PAGES_DIRECTORY, SCOPE_FILE, } from "./file-system-helpers.js";
 import { generate } from "./generate.js";
-import { doesElementHaveBinding } from "./parsing/bindings.js";
+import { doesNodePathHaveBinding } from "./parsing/bindings.js";
 import { getSbElementId } from "./parsing/ids.js";
 import { makeJSXAttribute } from "./parsing/jsx.js";
-import { getPageRoots } from "./parsing/page.js";
-import { getScope } from "./parsing/scope.js";
+import { getRootNodes } from "./parsing/page.js";
 import { getLegacyComponentsFolder, isCustomBuildEnabled, } from "./plugin-options.js";
 import { RenameManager } from "./rename-manager.js";
+import { getFullImportPath } from "./resolver.js";
+import { findRouterFile } from "./router-parser.js";
 import { SourceTracker } from "./source-tracker.js";
 import { traverse } from "./traverse.js";
+import { getScopeIdFromName, getScopeNameFromPath } from "./util.js";
 import { getErrorMeta, getLogger } from "./util/logger.js";
-import { isValidApi } from "./util.js";
 const SUPPORTED_FILETYPES = [
+    {
+        type: "ts",
+        extension: ".ts",
+    },
     {
         type: "tsx",
         extension: ".tsx",
@@ -45,87 +51,92 @@ const SUPPORTED_FILETYPES = [
         type: "js-api-step",
         extension: ".js",
     },
+    {
+        type: "json",
+        extension: ".json",
+    },
+    {
+        type: "md",
+        extension: ".md",
+    },
 ];
-const APP_THEME_FILE_NAME = "appTheme.ts";
-export class FileSyncManager extends EventEmitter {
+export class FileSystemManager extends TracedEventEmitter {
     rootDir;
     tsFiles = {};
     apiFiles = {};
     sourceTracker;
     fsOperationQueue;
     generationNumberSequence;
-    routes = {};
+    routeChangesQueue = [];
+    pageAdditionQueue = new Set();
+    routerFilePath = null;
     watcher;
     registeredComponentPaths = {};
     renameManager = new RenameManager();
-    constructor(fsOperationQueue, generationNumberSequence) {
-        super({ captureRejections: true });
+    _tracer;
+    transactionNonce = Date.now();
+    pendingTransactions = new Set();
+    processedTransactions = [];
+    debouncedFileUpdateHandlers = new Map();
+    debouncedAppFactsChanged = debounce(() => {
+        this.emit("appFactsChanged");
+    }, 100, { leading: true, trailing: true, maxWait: 500 });
+    templateRenderer;
+    constructor(fsOperationQueue, generationNumberSequence, tracer) {
+        super(tracer, { captureRejections: true });
         this.rootDir = "/";
         this.fsOperationQueue = fsOperationQueue;
         this.generationNumberSequence = generationNumberSequence;
+        this._tracer = tracer;
         applyErrorHandling(this, {
             watch: { operation: "editing from code" },
-            handleCreatePage: { operation: "creating a page" },
-            handleReparent: { operation: "moving a component" },
-            handleCreateComponent: { operation: "creating a component" },
-            handleDeleteComponents: { operation: "deleting components" },
-            handleSetProperty: { operation: "setting a property" },
-            handleSetProperties: { operation: "setting properties" },
-            handleDeleteProperties: { operation: "deleting properties" },
-            handleBatchUpdate: { operation: "updating multiple things" },
             handleUpdateApi: { operation: "updating an API" },
             handleDeleteApi: { operation: "deleting an API" },
             handleRenameApi: { operation: "renaming an API" },
-            handleAddEntity: { operation: "adding an entity" },
-            handleUpdateEntity: { operation: "updating an entity" },
-            handleDeleteEntity: { operation: "deleting an entity" },
-            handleUpdateTheme: { operation: "updating the theme" },
             handleRenameElement: { operation: "renaming an element" },
         });
+        const methods = [
+            "handleUpdateApi",
+            "handleDeleteApi",
+            "handleRenameApi",
+            "handleRenameElement",
+        ];
+        addTracingToMethods(this, methods, tracer);
     }
     get appFilePath() {
         if (!this.rootDir) {
             throw new Error("Root directory not set");
         }
-        return path.join(this.rootDir, "App.tsx");
+        const directPath = normalizePath(nodePath.join(this.rootDir, "App.tsx"));
+        if (this.tsFiles[directPath]) {
+            return directPath;
+        }
+        for (const subdir of ["client", "src"]) {
+            const subPath = normalizePath(nodePath.join(this.rootDir, subdir, "App.tsx"));
+            if (this.tsFiles[subPath]) {
+                return subPath;
+            }
+        }
+        return directPath;
     }
-    updateApi = (content, path) => {
+    get rootScopeFilePath() {
         if (!this.rootDir) {
             throw new Error("Root directory not set");
         }
-        const { api: apiContents, stepPathMap } = content;
-        const pageName = getPageName(path);
-        let scopeId = this.sourceTracker?.getScopeDefinitionForPage(pageName)?.id;
-        if (!scopeId) {
-            console.warn("Scope ID not found for API", apiContents.metadata.name);
-            scopeId = "";
-        }
-        const updatedApi = {
-            apiPb: yaml.parse(JSON.stringify(apiContents)),
-            pageName,
-            stepPathMap,
-            scopeId,
-        };
-        const isNewApi = !this.apiFiles[path];
-        this.apiFiles[path] = updatedApi;
-        return { updatedApi, pageName, isNewApi };
-    };
+        return nodePath.join(this.rootDir, SCOPE_FILE);
+    }
+    // MARK: core setup/init
     async watch(watcher, rootPath) {
         const logger = getLogger();
         this.rootDir = rootPath;
         this.watcher = watcher;
         // APIs and pages are in the pages subfolder
-        const fileNames = await readFiles(path.join(rootPath));
+        const fileNames = await readFiles(nodePath.join(rootPath));
         // this reads all files excluding ignore list in the root path. Should we read all files in pages and add root.tsx and App.tsx instead?
         const tsxFiles = fileNames.filter((f) => f.endsWith(".tsx") && !f.includes(`${getLegacyComponentsFolder()}/`));
-        const yamlFiles = fileNames.filter((f) => f.endsWith(".yaml"));
-        const scopeFiles = fileNames.filter((f) => f.endsWith(SCOPE_FILE));
-        // For the moment, the theme file is `appTheme.ts`. This may change in the future.
-        const appThemeFile = path.join(rootPath, APP_THEME_FILE_NAME);
-        logger.info(`files to be scanned ${JSON.stringify(tsxFiles)}`);
-        logger.info(`api files to be scanned ${JSON.stringify(yamlFiles)}`);
-        logger.info(`app theme file to be scanned ${JSON.stringify(appThemeFile)}`);
-        logger.info(`scope files to be scanned ${JSON.stringify(scopeFiles)}`);
+        const yamlFiles = fileNames.filter((f) => f.endsWith(".yaml") && f.includes("/apis/"));
+        logger.info(`scanning ${tsxFiles.length} code files`);
+        logger.info(`scanning ${yamlFiles.length} api files`);
         const allFiles = [
             ...tsxFiles.map((f) => {
                 return {
@@ -134,13 +145,6 @@ export class FileSyncManager extends EventEmitter {
                     content: readFile(f),
                 };
             }),
-            ...scopeFiles.map((f) => {
-                return {
-                    type: "ts",
-                    path: f,
-                    content: readFile(f),
-                };
-            }),
             ...yamlFiles.map((f) => {
                 return {
                     type: "api",
@@ -149,15 +153,13 @@ export class FileSyncManager extends EventEmitter {
                 };
             }),
         ].flat();
-        if (appThemeFile) {
-            allFiles.push({
-                type: "ts",
-                path: appThemeFile,
-                content: readFile(appThemeFile),
-            });
-        }
-        const contents = await Promise.all(allFiles.map((f) => f.content));
-        contents.forEach((content, i) => {
+        const contents = await Promise.allSettled(allFiles.map((f) => f.content));
+        contents.forEach((result, i) => {
+            if (result.status === "rejected") {
+                logger.error(`Error getting content for file: ${allFiles[i]?.path}`, getErrorMeta(result.reason));
+                return;
+            }
+            const content = result.value;
             if (!content)
                 return;
             const file = allFiles[i];
@@ -167,27 +169,21 @@ export class FileSyncManager extends EventEmitter {
             // We only want to load the typescript files here, before the source tracker is initialized
             // API setup needs to be deferred until we've parsed the scope files (which is done in the source tracker)
             if (type === "tsx" || type === "ts") {
-                this.tsFiles[path] = content;
+                this.tsFiles[normalizePath(path)] = content;
             }
         });
-        // And routes are in the root
-        const routePath = path.join(rootPath, ROUTES_FILE);
-        const routeFile = await readFile(routePath);
-        if (routeFile) {
-            try {
-                this.routes = JSON.parse(routeFile);
-            }
-            catch (e) {
-                logger.error("Error parsing routes file", getErrorMeta(e));
-            }
-        }
         try {
             this.initializeSourceTracker();
         }
         catch (e) {
             logger.error("Error initializing source tracker", getErrorMeta(e));
         }
-        contents.forEach((content, i) => {
+        contents.forEach((result, i) => {
+            if (result.status === "rejected") {
+                logger.error(`Error getting content for file: ${allFiles[i]?.path}`, getErrorMeta(result.reason));
+                return;
+            }
+            const content = result.value;
             if (!content)
                 return;
             const file = allFiles[i];
@@ -195,214 +191,103 @@ export class FileSyncManager extends EventEmitter {
                 return;
             const { type, path } = file;
             if (type === "api") {
-                this.updateApi(content, path);
-            }
-        });
-        watcher.on("all", async (event, filePath) => {
-            logger.info(`File changed: ${filePath}, event: ${event}`);
-            switch (event) {
-                case "add": {
-                    const fileType = SUPPORTED_FILETYPES.find((f) => filePath.endsWith(f.extension));
-                    if (!fileType || !filePath.startsWith(rootPath)) {
-                        return;
-                    }
-                    const data = await readFile(filePath);
-                    if (typeof data !== "string")
-                        return;
-                    // if we match pages/*/index.tsx, we want to emit an addPage event
-                    if (/pages\/.*\/index\.tsx/.test(filePath)) {
-                        const file = await readFile(filePath);
-                        if (!file) {
-                            logger.error(`Failed to read file: ${filePath}`);
-                            return;
-                        }
-                        if (!(filePath in this.tsFiles)) {
-                            this.tsFiles[filePath] = file;
-                            this.handleNonVisualChangeByDeletingIds(filePath, file);
-                            this.emit("addPage", filePath);
-                        }
-                    }
-                    switch (fileType.type) {
-                        case "api":
-                        case "python-api-step":
-                        case "js-api-step": {
-                            await this.processApiUpdates(filePath, fileType);
-                            break;
-                        }
-                    }
-                    break;
-                }
-                case "change": {
-                    // Special routes file handling
-                    if (filePath === routePath) {
-                        const data = await readFile(filePath);
-                        try {
-                            this.routes = JSON.parse(data);
-                            this.emit("routesChanged", this.routes);
-                        }
-                        catch (e) {
-                            logger.error("Error parsing routes file", getErrorMeta(e));
-                        }
-                        return;
-                    }
-                    const fileType = SUPPORTED_FILETYPES.find((f) => filePath.endsWith(f.extension));
-                    if (!fileType || !filePath.startsWith(rootPath)) {
-                        return;
-                    }
-                    const data = await readFile(filePath);
-                    if (typeof data !== "string")
-                        return;
-                    switch (fileType.type) {
-                        case "tsx":
-                        case "scope":
-                            {
-                                if (!(filePath in this.tsFiles && this.tsFiles[filePath] === data)) {
-                                    logger.info(`File changed: ${filePath} updating AST tracker`);
-                                    this.tsFiles[filePath] = data;
-                                    // only update the source tracker if the file is different
-                                    this.handleNonVisualChangeByDeletingIds(filePath, data);
-                                    this.emit("fileChanged", filePath, data, true);
-                                }
-                                else {
-                                    logger.info(`File unchanged from last tracked state: ${filePath}`);
-                                    this.emit("fileChanged", filePath, data, false);
-                                }
-                            }
-                            break;
-                        case "api":
-                        case "python-api-step":
-                        case "js-api-step":
-                            {
-                                await this.processApiUpdates(filePath, fileType);
-                            }
-                            break;
-                    }
-                    break;
-                }
-                case "unlink": {
-                    if (filePath in this.apiFiles) {
-                        const api = this.apiFiles[filePath];
-                        delete this.apiFiles[filePath];
-                        if (!api || !this.sourceTracker)
-                            break;
-                        const scopeId = await this.sourceTracker.deleteApi({
-                            pageName: api.pageName,
-                            apiName: api.apiPb.metadata.name,
-                        });
-                        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-                        await this.writeChanges(changes);
-                        this.emit("apiManualDelete", {
-                            api: {
-                                id: getClientApiId(api.apiPb.metadata.name, api.pageName),
-                                apiName: api.apiPb.metadata.name,
-                                // TODO(saksham): get pagename more defensively
-                                pageName: getPageName(filePath),
-                                scopeId,
-                            },
-                        });
-                    }
-                    if (filePath in this.tsFiles) {
-                        delete this.tsFiles[filePath];
-                        this.sourceTracker?.removeFile(filePath);
-                        this.emit("deletePage", filePath);
-                    }
-                    break;
-                }
+                this.updateInternalApiData(content, path);
             }
         });
-    }
-    getApiFiles() {
-        return this.formatApisToClientApis(this.apiFiles);
-    }
-    getTsFilePaths() {
-        return Object.keys(this.tsFiles);
-    }
-    async writeFile(path, content, kind) {
-        if (kind === "ts") {
-            // happens eagerly regardless of error - possible desync
-            this.tsFiles[path] = content;
-            // TODO(george): as an optimization, we could update the memory snapshot of the file that SyncService is holding
-            await this.fsOperationQueue.enqueue(async () => {
-                await fs.writeFile(path, content);
-            });
+        // Find and store the router file path for watching
+        try {
+            this.routerFilePath = await findRouterFile(rootPath);
+            logger.info(`Router file found at: ${this.routerFilePath}`);
         }
-        else if (kind === "api") {
-            const currentApiFile = this.apiFiles[path];
-            const apiPb = yaml.parse(content);
-            // Client APIs have id, but server APIs don't
-            if (apiPb.metadata.id) {
-                delete apiPb.metadata.id;
-            }
-            const stepPathMap = currentApiFile?.stepPathMap ?? {};
-            this.updateApi({ api: apiPb, stepPathMap }, path);
-            // TODO(george): as an optimization, we could update the memory snapshot of the file that SyncService is holding
-            await this.fsOperationQueue.enqueue(async () => {
-                await writeApiFiles({ apiPb }, "api", path.split("/").slice(0, -1).join("/"), false, [], [], { extractLargeSourceFiles: true, minLinesForExtraction: 1 }, new Set(Object.keys(this.apiFiles)), stepPathMap);
-                // stepPathMap will be generated after the write when the file doesn't exist
-                if (this.apiFiles[path]) {
-                    this.apiFiles[path].stepPathMap = stepPathMap;
-                }
-            });
+        catch (e) {
+            logger.error("No router file found", getErrorMeta(e));
+            this.routerFilePath = null;
         }
-    }
-    readFile(path) {
-        return this.tsFiles[path];
+        watcher.on("all", (event, filePath) => {
+            if (event == "add" || event == "unlink") {
+                void this.handleFileChange(event, filePath);
+                return;
+            }
+            let handler = this.debouncedFileUpdateHandlers.get(filePath);
+            if (!handler) {
+                handler = debounce(() => {
+                    void this.handleFileChange(event, filePath);
+                }, 100, { leading: true, trailing: true, maxWait: 500 });
+                this.debouncedFileUpdateHandlers.set(filePath, handler);
+            }
+            handler();
+        });
     }
     initializeSourceTracker() {
-        this.sourceTracker = new SourceTracker();
+        this.sourceTracker = new SourceTracker(this._tracer);
         this.sourceTracker.initializeSourceTracker({
             files: this.tsFiles,
         });
     }
-    handleNonVisualChangeByDeletingIds(path, content) {
-        if (!this.sourceTracker) {
-            throw new Error("Source tracker not initialized");
-        }
-        return this.sourceTracker.handleNonVisualChangeByDeletingIds(path, content);
-    }
-    async getFileWithIds(path) {
+    async getFileWithIds(filePath) {
         const logger = getLogger();
         if (!this.sourceTracker) {
             throw new Error("Source tracker not initialized");
         }
+        const normalizedPath = normalizePath(filePath);
         const files = this.sourceTracker.getCurrentFiles();
-        if (!files[path]) {
-            throw new Error("File not found in source tracker " + path);
+        if (!files[normalizedPath]) {
+            throw new Error("File not found in source tracker " + normalizedPath);
         }
-        const ast = files[path].ast;
+        let ast = files[normalizedPath].ast;
         if (!ast) {
-            throw new Error("No AST found for file in source tracker " + path);
+            throw new Error("No AST found for file in source tracker " + normalizedPath);
         }
-        const clonedAst = await transformFromAstAsync(ast, undefined, {
-            ast: true,
-        });
-        if (!clonedAst?.ast) {
-            throw new Error("Failed to clone AST for file " + path);
+        if (normalizedPath in this.tsFiles &&
+            this.tsFiles[normalizedPath] &&
+            files[normalizedPath].code !== this.tsFiles[normalizedPath]) {
+            getLogger().error("File code mismatch in source tracker, this should never happen: " +
+                filePath);
+            // Re-initialize source tracker to sync with current file state
+            this.sourceTracker.initializeSourceTracker({
+                files: this.tsFiles,
+            });
+            const newAst = this.sourceTracker.getCurrentFiles()[normalizedPath]?.ast;
+            if (!newAst) {
+                throw new Error("No AST found for file in source tracker after mismatch:" + filePath);
+            }
+            ast = newAst;
+        }
+        const clonedAst = t.cloneNode(ast, true, false);
+        if (!clonedAst) {
+            throw new Error("Failed to clone AST for file " + filePath);
         }
+        const componentsManager = ComponentsManager.getInstance();
         const processedTransactions = this.getProcessedTransactionsWithNonce();
         const customImports = new Set();
-        let customBuildTraversal = {};
-        if (isCustomBuildEnabled()) {
-            customBuildTraversal = {
-                ImportDeclaration(path) {
+        traverse(clonedAst, {
+            Program: {
+                exit(nodePath) {
+                    if (isCustomBuildEnabled()) {
+                        addLegacyCustomComponentVariables(nodePath, customImports);
+                    }
+                    // we want to inject the component name into the file so we can use it for hot reloading purposes
+                    const name = componentsManager.getComponentName(filePath);
+                    if (name) {
+                        nodePath.pushContainer("body", t.variableDeclaration("const", [
+                            t.variableDeclarator(t.identifier("componentName"), t.stringLiteral(name)),
+                        ]));
+                    }
+                },
+            },
+            ImportDeclaration(path) {
+                if (isCustomBuildEnabled()) {
                     // when we see a custom component, we want to track the import and modify it to point
                     // to the built source
                     modifyLegacyCustomComponentImports(path, customImports);
-                },
-                JSXElement(path) {
+                }
+            },
+            JSXElement(path) {
+                if (isCustomBuildEnabled()) {
                     // based on the imports we see, we want to modify the JSXElement that uses the custom component
                     modifyLegacyCustomComponentElements(path, customImports);
-                },
-                Program: {
-                    // we want to write the wrapped custom elements as local variables to the file
-                    exit(path) {
-                        addLegacyCustomComponentVariables(path, customImports);
-                    },
-                },
-            };
-        }
-        traverse(clonedAst.ast, {
-            ...customBuildTraversal,
+                }
+            },
             ReturnStatement(path) {
                 const argument = path.get("argument");
                 if (!argument.isJSXElement()) {
@@ -412,23 +297,27 @@ export class FileSyncManager extends EventEmitter {
                 if (!openingElement.isJSXOpeningElement()) {
                     return;
                 }
-                openingElement.pushContainer("attributes", makeJSXAttribute(ROOT_WIDGET_ATTRIBUTE, "true"));
-                openingElement.pushContainer("attributes", generateJSXAttribute(PROCESSED_TRANSACTIONS_ATTRIBUTE, {
-                    value: processedTransactions,
-                    type: "EXPRESSION",
-                    __info: true,
-                }));
+                // we are checking here if the return statement is either the top level return statement of a function or
+                // inside some inner function in the component (i.e. in a map)
+                const isProgramParentsScope = path.scope.parent === path.scope.getProgramParent();
+                if (isProgramParentsScope) {
+                    openingElement.pushContainer("attributes", makeJSXAttribute(ROOT_WIDGET_ATTRIBUTE, "true"));
+                    openingElement.pushContainer("attributes", generateJSXAttribute(PROCESSED_TRANSACTIONS_ATTRIBUTE, {
+                        value: processedTransactions,
+                        type: "EXPRESSION",
+                        __info: true,
+                    }));
+                }
             },
             JSXOpeningElement(path) {
                 const elementId = getSbElementId(path.node);
                 if (elementId) {
-                    path.pushContainer("attributes", makeJSXAttribute(WIDGET_SOURCE_ID_ATTRIBUTE, elementId));
+                    path.pushContainer("attributes", makeJSXAttribute(SOURCE_ID_ATTRIBUTE, elementId));
                 }
             },
             ObjectProperty(path) {
                 const elementId = getSbElementId(path.node);
                 if (!elementId) {
-                    path.skip();
                     return;
                 }
                 path.traverse({
@@ -440,7 +329,7 @@ export class FileSyncManager extends EventEmitter {
             },
         });
         try {
-            const result = generate(clonedAst.ast);
+            const result = generate(clonedAst);
             return result.code;
         }
         catch (e) {
@@ -448,16 +337,252 @@ export class FileSyncManager extends EventEmitter {
             return null;
         }
     }
+    // MARK: file change handling
+    handleFileChange = async (event, filePath) => {
+        const logger = getLogger();
+        logger.info(`File changed: ${filePath}, event: ${event}`);
+        const rootPath = this.rootDir;
+        if (!rootPath) {
+            throw new Error("Root directory not set");
+        }
+        // Skip directory events
+        if (event === "addDir" || event === "unlinkDir") {
+            return;
+        }
+        const fileType = SUPPORTED_FILETYPES.find((f) => filePath.endsWith(f.extension));
+        // Normalize both paths for comparison (Windows compatibility)
+        const normalizedFilePath = normalizePath(filePath);
+        const normalizedRootPath = normalizePath(rootPath);
+        // Only handle files we care about and that are in our root path
+        if (!fileType || !normalizedFilePath.startsWith(normalizedRootPath)) {
+            return;
+        }
+        // Queue the operation based on the event type
+        switch (event) {
+            case "add": {
+                const file = await readFile(normalizedFilePath);
+                if (typeof file !== "string")
+                    return;
+                switch (fileType.type) {
+                    case "api":
+                    case "python-api-step":
+                    case "js-api-step": {
+                        await this.processApiFileUpdates(normalizedFilePath, fileType);
+                        break;
+                    }
+                    case "ts":
+                    case "tsx":
+                        if (!(normalizedFilePath in this.tsFiles)) {
+                            this.tsFiles[normalizedFilePath] = file;
+                            this.sourceTracker?.initializeSourceTracker({
+                                files: this.tsFiles,
+                            });
+                            this.emit("fileChanged", normalizedFilePath, file);
+                            return;
+                        }
+                        break;
+                    case "md": {
+                        if (this.isSkillFile(normalizedFilePath)) {
+                            this.debouncedAppFactsChanged();
+                        }
+                        break;
+                    }
+                }
+                break;
+            }
+            case "change": {
+                const fileType = SUPPORTED_FILETYPES.find((f) => normalizedFilePath.endsWith(f.extension));
+                if (!fileType || !normalizedFilePath.startsWith(rootPath)) {
+                    return;
+                }
+                const data = await readFile(normalizedFilePath);
+                if (typeof data !== "string")
+                    return;
+                // Handle router file changes
+                if (this.routerFilePath && normalizedFilePath === this.routerFilePath) {
+                    logger.info("Router file changed, emitting routerChange event");
+                    this.emit("routerChange", normalizedFilePath);
+                    return;
+                }
+                switch (fileType.type) {
+                    case "ts":
+                    case "tsx":
+                    case "scope":
+                        {
+                            if (!(normalizedFilePath in this.tsFiles &&
+                                this.tsFiles[normalizedFilePath] === data)) {
+                                logger.info(`File changed: ${normalizedFilePath} updating AST tracker`);
+                                this.tsFiles[normalizedFilePath] = data;
+                                // Update the source tracker when the file changes
+                                this.sourceTracker?.initializeSourceTracker({
+                                    files: this.tsFiles,
+                                });
+                                this.emit("fileChanged", normalizedFilePath, data);
+                            }
+                            else {
+                                logger.info(`File unchanged from last tracked state: ${normalizedFilePath}`);
+                                this.sourceTracker?.updateFileContents(normalizedFilePath, data);
+                            }
+                        }
+                        break;
+                    case "api":
+                    case "python-api-step":
+                    case "js-api-step":
+                        {
+                            await this.processApiFileUpdates(normalizedFilePath, fileType);
+                        }
+                        break;
+                    case "md": {
+                        if (this.isSkillFile(normalizedFilePath)) {
+                            this.debouncedAppFactsChanged();
+                        }
+                        break;
+                    }
+                }
+                break;
+            }
+            case "unlink": {
+                if (normalizedFilePath in this.tsFiles) {
+                    await this.deleteTsFile(normalizedFilePath);
+                    if (this.routerFilePath &&
+                        normalizedFilePath === this.routerFilePath) {
+                        logger.warn("Router file was deleted, attempting to find new router file");
+                        try {
+                            this.routerFilePath = await findRouterFile(rootPath);
+                            logger.info(`New router file found at: ${this.routerFilePath}`);
+                            this.emit("routerChange", this.routerFilePath);
+                        }
+                        catch {
+                            this.routerFilePath = null;
+                            const error = new Error("Router file was deleted and no replacement could be found.");
+                            logger.error("Router file missing", getErrorMeta(error));
+                        }
+                    }
+                }
+                else if (normalizedFilePath in this.apiFiles) {
+                    await this.removeApiData(normalizedFilePath);
+                }
+                else if (this.isSkillFile(normalizedFilePath)) {
+                    this.debouncedAppFactsChanged();
+                }
+                break;
+            }
+        }
+    };
+    async deleteTsFile(filePath) {
+        const normalizedPath = normalizePath(filePath);
+        delete this.tsFiles[normalizedPath];
+        this.sourceTracker?.removeFile(normalizedPath);
+        if (isPageFilePath(normalizedPath)) {
+            this.emit("deletePage", normalizedPath);
+        }
+    }
+    getTsFilePaths() {
+        return Object.keys(this.tsFiles);
+    }
+    getSourceTracker() {
+        return this.sourceTracker;
+    }
+    /**
+     * Set the template renderer for YAML→TS transformations.
+     * Called by AiService after initialization.
+     */
+    setTemplateRenderer(templateRenderer) {
+        this.templateRenderer = templateRenderer;
+    }
+    // MARK: fs read/write
+    async writeFile(path, content, kind) {
+        getLogger().info(`Writing file: ${path}, kind: ${kind ?? "other"}`);
+        switch (kind) {
+            case "ts": {
+                // happens eagerly regardless of error - possible desync
+                const normalizedPath = normalizePath(path);
+                this.tsFiles[normalizedPath] = content;
+                // TODO(george): as an optimization, we could update the memory snapshot of the file that SyncService is holding
+                await this.fsOperationQueue.enqueue(async () => {
+                    const dir = path.substring(0, path.lastIndexOf("/"));
+                    if (dir) {
+                        await fs.mkdir(dir, { recursive: true });
+                    }
+                    await fs.writeFile(path, content);
+                });
+                break;
+            }
+            case "api": {
+                const normalizedPath = normalizePath(path);
+                const currentApiFile = this.apiFiles[normalizedPath];
+                const apiPb = yaml.parse(content);
+                // We don't need ID, organization, or trigger data in code-mode APIs
+                if (apiPb.metadata) {
+                    delete apiPb.metadata.id;
+                    delete apiPb.metadata.organization;
+                }
+                if (apiPb.trigger) {
+                    delete apiPb.trigger;
+                }
+                const stepPathMap = currentApiFile?.stepPathMap ?? {};
+                const scopeId = getScopeIdFromName("App");
+                // Update in-memory state before writing to disk (similar to TS files)
+                // This allows the file watcher to detect no change and skip duplicate events
+                this.apiFiles[normalizedPath] = {
+                    apiPb: yaml.parse(JSON.stringify(apiPb)),
+                    stepPathMap,
+                    scopeId,
+                };
+                // TODO(george): as an optimization, we could update the memory snapshot of the file that SyncService is holding
+                const apiDir = nodePath.dirname(path);
+                await this.fsOperationQueue.enqueue(async () => {
+                    await writeApiFiles({ apiPb }, "api", apiDir, false, [], [], { extractLargeSourceFiles: true, minLinesForExtraction: 1 }, new Set(Object.keys(this.apiFiles)), stepPathMap);
+                });
+                break;
+            }
+            default: {
+                // TODO(george): as an optimization, we could update the memory snapshot of the file that SyncService is holding
+                await this.fsOperationQueue.enqueue(async () => {
+                    const dir = path.substring(0, path.lastIndexOf("/"));
+                    if (dir) {
+                        await fs.mkdir(dir, { recursive: true });
+                    }
+                    await fs.writeFile(path, content);
+                });
+            }
+        }
+    }
+    readFile(path) {
+        return this.tsFiles[normalizePath(path)];
+    }
+    async setFileContents(path, contents) {
+        const logger = getLogger();
+        logger.info(`Setting file contents: ${path}`);
+        // Determine file kind
+        const kind = isApiFilePath(path)
+            ? "api"
+            : path.endsWith(".ts") || path.endsWith(".tsx")
+                ? "ts"
+                : undefined;
+        await this.writeFile(path, contents, kind);
+        // Emit fileChanged event for TypeScript files
+        if (kind === "ts") {
+            this.emit("fileChanged", path, contents);
+        }
+    }
+    async writeChanges(changes, callback) {
+        return Promise.all(changes.map(async ({ fileName, source, kind }) => {
+            await this.writeFile(fileName, source, kind);
+            return callback?.(fileName, source);
+        }));
+    }
     getLocalBindingEntities(path) {
         const logger = getLogger();
+        const normalizedPath = normalizePath(path);
         const files = this.sourceTracker?.getCurrentFiles();
-        if (!files || !files[path]) {
-            logger.warn(`File not found in source tracker for local binding entities: ${path}`);
+        if (!files || !files[normalizedPath]) {
+            logger.warn(`File not found in source tracker for local binding entities: ${normalizedPath}`);
             return [];
         }
-        const ast = files[path].ast;
+        const ast = files[normalizedPath].ast;
         if (!ast) {
-            logger.warn(`No AST found for file in source tracker for local binding entities: ${path}`);
+            logger.warn(`No AST found for file in source tracker for local binding entities: ${normalizedPath}`);
             return [];
         }
         const localBindingEntities = new Set();
@@ -467,7 +592,7 @@ export class FileSyncManager extends EventEmitter {
                 if (!elementId) {
                     return;
                 }
-                const hasLocalBinding = doesElementHaveBinding(path);
+                const hasLocalBinding = doesNodePathHaveBinding(path);
                 if (hasLocalBinding) {
                     localBindingEntities.add(elementId);
                 }
@@ -475,8 +600,93 @@ export class FileSyncManager extends EventEmitter {
         });
         return Array.from(localBindingEntities);
     }
-    pendingTransactions = new Set();
-    processedTransactions = [];
+    getPageRootNodes(filePath) {
+        const scopeFilePath = normalizePath(nodePath.join(nodePath.dirname(filePath), "index.tsx"));
+        return this.getRootNodesForFile(scopeFilePath);
+    }
+    getAppRootNodes() {
+        return this.getRootNodesForFile(this.appFilePath);
+    }
+    async collectAllImports(filePath, allFiles, visited = new Set()) {
+        const importedFiles = {};
+        if (visited.has(filePath)) {
+            return importedFiles; // Avoid circular dependencies
+        }
+        visited.add(filePath);
+        const currentFile = allFiles[filePath];
+        if (!currentFile) {
+            return importedFiles;
+        }
+        for (const [_name, localPath] of Object.entries(currentFile.imports)) {
+            let resolvedPath = await getFullImportPath(localPath);
+            // Fallback: manually resolve relative paths if Vite resolver fails
+            if (!resolvedPath && localPath.startsWith(".")) {
+                const currentDir = nodePath.dirname(filePath);
+                const potentialPath = nodePath.resolve(currentDir, localPath);
+                // Try with different extensions
+                const extensions = [
+                    "/index.tsx",
+                    "/index.ts",
+                    ".tsx",
+                    ".ts",
+                    ".jsx",
+                    ".js",
+                ];
+                for (const ext of extensions) {
+                    const testPath = potentialPath + ext;
+                    if (allFiles[testPath]) {
+                        resolvedPath = testPath;
+                        break;
+                    }
+                }
+            }
+            if (resolvedPath &&
+                allFiles[resolvedPath] &&
+                !importedFiles[resolvedPath]) {
+                importedFiles[resolvedPath] = allFiles[resolvedPath];
+                // Recursively collect imports from this file
+                const nestedImports = await this.collectAllImports(resolvedPath, allFiles, visited);
+                Object.assign(importedFiles, nestedImports);
+            }
+        }
+        return importedFiles;
+    }
+    async getRootNodesForFile(filePath) {
+        const normalizedPath = normalizePath(filePath);
+        const currentFile = this.sourceTracker?.getCurrentFiles()[normalizedPath];
+        if (!currentFile) {
+            return undefined;
+        }
+        const allFiles = this.sourceTracker?.getCurrentFiles() ?? {};
+        // Collect all imported files recursively (including transitive imports)
+        const importedNamesToFiles = await this.collectAllImports(normalizedPath, allFiles);
+        // Get roots from imported files (custom components)
+        const importedRoots = Object.entries(importedNamesToFiles).flatMap(([filePath, file]) => getRootNodes(filePath, file));
+        // Get roots from the current file
+        const roots = getRootNodes(normalizedPath, currentFile);
+        return [...roots, ...importedRoots];
+    }
+    getScope(filePath, fallback) {
+        // Since we no longer use scope.ts files, generate scope info from file path. Pages retain page scope, everything else is App.
+        const normalizedPath = normalizePath(filePath);
+        const scopeName = getScopeNameFromPath(normalizedPath);
+        if (!scopeName) {
+            if (fallback) {
+                return {
+                    entities: {},
+                    scopeName: "App",
+                    scopeId: getScopeIdFromName("App"),
+                };
+            }
+            return undefined;
+        }
+        return {
+            entities: {},
+            scopeName,
+            scopeId: getScopeIdFromName(scopeName),
+        };
+    }
+    // MARK: transaction handling
     flushTransactions = () => {
         // TODO do something more sophisticated than this.
         this.processedTransactions = this.processedTransactions.slice(-20);
@@ -489,158 +699,40 @@ export class FileSyncManager extends EventEmitter {
         }
         this.pendingTransactions.add(transactionId);
     };
-    transactionNonce = Date.now();
     // Until we have a sophisticated way to track ALL operations, including non-UI initiated ops, we will use a nonce
     // TODO https://github.com/superblocksteam/superblocks/pull/11788
     getProcessedTransactionsWithNonce() {
         const nonce = `t-${this.transactionNonce++}`;
         return this.processedTransactions.concat(nonce);
     }
-    handleCreatePage = async (payload) => {
-        const { name } = payload;
-        if (!this.rootDir) {
-            throw new Error("Root directory not set");
-        }
-        const pagePath = getPageFolder(this.rootDir, name);
-        const pageIndexPath = path.join(pagePath, "index.tsx");
-        const pageContent = /*js*/ `import { SbPage, SbContainer, registerPage } from "@superblocksteam/library";
-function Page() {
-  return <SbPage name="${name}">
-    <SbContainer width={Dim.fill()} />
-  </SbPage>;
-}
-
-export default registerPage(Page, { name: "${name}" });
-`;
-        await fs.mkdir(pagePath, { recursive: true });
-        await this.writeFile(pageIndexPath, pageContent, "ts");
-        await this.handleNonVisualChangeByDeletingIds(pageIndexPath, pageContent);
-        this.emit("addPage", pageIndexPath);
-    };
-    handleReparent = async (payload, writeFile = true) => {
-        const { from, to, changedProps, transaction } = payload;
-        this.trackTransaction(transaction?.id);
-        await this.sourceTracker?.setProperties({
-            source: from.source,
-            changes: changedProps ?? {},
-        });
-        await this.sourceTracker?.moveElement({
-            from,
-            to,
-        });
-        if (writeFile) {
-            const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-            await this.writeChanges(changes ?? [], (fileName) => {
-                this.emit("reparent", fileName);
-            });
-            this.flushTransactions();
-        }
-    };
-    handleCreateComponent = async (payload, writeFile = true) => {
-        this.trackTransaction(payload.transaction?.id);
-        const sourceId = await this.sourceTracker?.addElement(payload);
-        if (writeFile) {
-            const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-            await this.writeChanges(changes ?? [], (fileName) => {
-                this.emit("createComponent", fileName);
-            });
-            this.flushTransactions();
-        }
-        return sourceId;
-    };
-    handleDeleteComponents = async (payload, writeFile = true) => {
-        const { elements, transaction } = payload;
-        this.trackTransaction(transaction?.id);
-        for (const element of elements) {
-            await this.sourceTracker?.deleteElement({
-                source: element.source,
-                scopeName: element.scopeName,
-            });
-        }
-        if (writeFile) {
-            const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-            await this.writeChanges(changes ?? [], (fileName) => {
-                this.emit("deleteComponents", fileName, elements.map((el) => el.source.id));
-            });
-            this.flushTransactions();
-        }
-    };
-    handleSetProperty = async (payload, writeFile = true) => {
-        const { element: { source }, property, value: { value, type }, transaction, } = payload;
-        this.trackTransaction(transaction?.id);
-        await this.sourceTracker?.setProperty({
-            source,
-            property,
-            value: value,
-            type,
-        });
-        if (writeFile) {
-            const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-            await this.writeChanges(changes ?? []);
-            this.flushTransactions();
-        }
-        this.emit("setProperty", payload);
-    };
-    handleSetProperties = async (payload, writeFile = true) => {
-        const { element: { source }, properties, transaction, } = payload;
-        this.trackTransaction(transaction?.id);
-        await this.sourceTracker?.setProperties({
-            source,
-            changes: properties,
-        });
-        if (writeFile) {
-            const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-            await this.writeChanges(changes ?? []);
-            this.flushTransactions();
+    // MARK: editor operations
+    get routeChange() {
+        return this.routeChangesQueue.shift();
+    }
+    // MARK: rename operations
+    handleRenameElement = async (payload) => {
+        if (payload.kind === "component") {
+            return this.handleRenameComponent(payload);
         }
-        this.emit("setProperties", payload);
     };
-    handleDeleteProperties = async (payload, writeFile = true) => {
-        this.trackTransaction(payload.transaction?.id);
-        await this.sourceTracker?.deleteProperties({
-            source: payload.element.source,
-            properties: payload.properties,
-        });
-        if (writeFile) {
-            const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-            await this.writeChanges(changes ?? []);
-            this.flushTransactions();
-        }
-        this.emit("deleteProperties", payload);
+    handleRenameComponent = async (_payload) => {
+        // there are no component names anymore, so there is nothing to do here
+        // TODO: remove this method entirely
     };
-    handleBatchUpdate = async (payload) => {
-        const { updates, transaction } = payload;
-        this.trackTransaction(transaction?.id);
-        const returnValues = [];
-        for (const update of updates) {
-            switch (update.type) {
-                case "editor:setProperty":
-                    returnValues.push(await this.handleSetProperty(update.payload, false));
-                    break;
-                case "editor:setProperties":
-                    returnValues.push(await this.handleSetProperties(update.payload, false));
-                    break;
-                case "editor:moveComponent":
-                    returnValues.push(await this.handleReparent(update.payload, false));
-                    break;
-                case "editor:createComponent":
-                    returnValues.push(await this.handleCreateComponent(update.payload, false));
-                    break;
-                case "editor:deleteProperties":
-                    returnValues.push(await this.handleDeleteProperties(update.payload, false));
-                    break;
-                case "editor:deleteComponents":
-                    returnValues.push(await this.handleDeleteComponents(update.payload, false));
-                    break;
-            }
+    getRelativeRoutePath(filePath) {
+        if (!this.rootDir) {
+            throw new Error("Root directory not set");
         }
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes ?? []);
-        this.emit("batchUpdate", Array.from(new Set(changes.map((c) => c.fileName))));
-        this.flushTransactions();
-        return returnValues;
-    };
+        // no leading slash, normalize to forward slashes for routes (Windows compatibility)
+        return normalizePath(nodePath.relative(nodePath.join(this.rootDir, PAGES_DIRECTORY), filePath));
+    }
+    // MARK: API operations
     handleUpdateApi = async (payload) => {
+        const apiName = payload.api.apiPb.metadata.name;
+        if (!apiName) {
+            throw new Error("API name is not set");
+        }
+        getLogger().info("Handling API update for " + apiName);
         const { api } = payload;
         if (!this.sourceTracker) {
             throw new Error("Source tracker not initialized");
@@ -648,53 +740,25 @@ export default registerPage(Page, { name: "${name}" });
         if (!this.rootDir) {
             throw new Error("Root directory not set");
         }
-        if (!api.pageName) {
-            throw new Error("API page name is not set");
-        }
-        const apiName = api.apiPb.metadata.name;
-        if (!apiName) {
-            throw new Error("API name is not set");
-        }
-        const apiDir = path.join(this.rootDir, "pages", api.pageName, "apis", apiName);
-        const apiPath = path.join(apiDir, "api.yaml");
-        const isNewApi = !this.getApiFiles()[apiPath];
+        const apiFilePath = getApiFilePath(this.rootDir, apiName);
+        const normalizedApiFilePath = normalizePath(apiFilePath);
+        const apiDir = nodePath.dirname(normalizedApiFilePath);
         try {
             const stats = await fs.stat(apiDir);
             if (!stats.isDirectory()) {
-                await fs.mkdir(apiDir, { recursive: true });
+                await this.fsOperationQueue.enqueue(async () => await fs.mkdir(apiDir, { recursive: true }));
             }
         }
         catch {
-            await fs.mkdir(apiDir, { recursive: true });
+            await this.fsOperationQueue.enqueue(async () => await fs.mkdir(apiDir, { recursive: true }));
         }
-        await this.writeFile(apiPath, yaml.stringify(api.apiPb), "api");
+        await this.writeFile(apiFilePath, yaml.stringify(api.apiPb), "api");
         const generationNumber = this.generationNumberSequence.next();
+        const scopeId = getScopeIdFromName("App");
         const apiDef = this.createClientApi(api);
-        let scopeId = "";
-        if (isNewApi) {
-            scopeId = await this.createScopedApi(api);
-        }
-        else {
-            const scopeDef = this.sourceTracker.getScopeDefinitionForPage(api.pageName);
-            scopeId = scopeDef?.id ?? "";
-        }
         this.emit("apiUpdate", { api: apiDef, scopeId });
         return { api: apiDef, scopeId, generationNumber };
     };
-    createScopedApi = async (api) => {
-        if (!this.sourceTracker) {
-            throw new Error("Source tracker not initialized");
-        }
-        // We want to add the API entity to our scope, but we do not want to emit entity events, because
-        // the API update event handles this particular side effect.
-        const scopeId = await this.sourceTracker.addApi({
-            pageName: api.pageName,
-            apiName: api.apiPb.metadata.name,
-        });
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes);
-        return scopeId;
-    };
     handleDeleteApi = async (payload) => {
         const logger = getLogger();
         const { apis } = payload;
@@ -702,40 +766,35 @@ export default registerPage(Page, { name: "${name}" });
             throw new Error("Root directory not set");
         }
         const rootDir = this.rootDir;
-        const executeDeleteApis = Promise.all(apis.map(({ apiName, pageName }) => {
-            return new Promise(
-            // eslint-disable-next-line no-async-promise-executor
-            async (resolve) => {
-                const apiFilePath = path.join(rootDir, "pages", pageName, "apis", apiName, "api.yaml");
-                const api = this.apiFiles[apiFilePath];
-                if (!api || !this.sourceTracker) {
-                    return resolve(undefined);
-                }
-                const apiDir = path.join(rootDir, "pages", pageName, "apis", apiName);
-                try {
+        const deletedApis = [];
+        for (const { apiName } of apis) {
+            const apiFilePath = getApiFilePath(rootDir, apiName);
+            const normalizedApiFilePath = normalizePath(apiFilePath);
+            const api = this.apiFiles[normalizedApiFilePath];
+            if (!api || !this.sourceTracker) {
+                continue;
+            }
+            const apiDir = nodePath.dirname(apiFilePath);
+            try {
+                await this.fsOperationQueue.enqueue(async () => {
                     const stats = await fs.stat(apiDir);
                     if (stats.isDirectory()) {
                         await fs.rmdir(apiDir, { recursive: true });
                     }
-                    delete this.apiFiles[apiFilePath];
-                    const scopeId = await this.sourceTracker.deleteApi({
-                        pageName,
-                        apiName,
-                    });
-                    resolve({
-                        apiName,
-                        pageName,
-                        scopeId,
-                    });
-                }
-                catch (e) {
-                    logger.warn(`Could not delete api ${apiFilePath} ${JSON.stringify(e)}`);
-                    resolve(undefined);
-                }
-                resolve(undefined);
-            });
-        }));
-        const deletedApis = (await executeDeleteApis).filter((api) => api !== undefined);
+                });
+                delete this.apiFiles[normalizedApiFilePath];
+                const scopeId = this.sourceTracker.deleteApi({
+                    apiName,
+                });
+                deletedApis.push({
+                    apiName,
+                    scopeId,
+                });
+            }
+            catch (e) {
+                logger.warn(`Could not delete api ${apiFilePath}`, e);
+            }
+        }
         const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
         await this.writeChanges(changes);
         this.emit("apiDelete", {
@@ -744,25 +803,20 @@ export default registerPage(Page, { name: "${name}" });
         return { deletedApis };
     };
     handleRenameApi = async (payload) => {
-        const { oldName, newName, pageName } = payload;
+        const { oldName, newName } = payload;
         if (!this.rootDir) {
             throw new Error("Root directory not set");
         }
-        const pagePath = getPageFolder(this.rootDir, pageName);
-        const existingApiFolder = path.join(this.rootDir, "pages", pageName, "apis", oldName);
-        const newApiFolder = path.join(this.rootDir, "pages", pageName, "apis", newName);
-        const files = this.sourceTracker?.getCurrentFiles();
-        const file = files?.[path.join(pagePath, "index.tsx")];
-        if (!file || !file.ast) {
-            throw new Error(`Page ${pageName} not found`);
-        }
-        const apiFilePath = path.join(existingApiFolder, "api.yaml");
-        const apiDef = this.apiFiles[apiFilePath];
+        const existingApiFolder = nodePath.join(this.rootDir, "apis", oldName);
+        const newApiFolder = nodePath.join(this.rootDir, "apis", newName);
+        const apiFilePath = nodePath.join(existingApiFolder, "api.yaml");
+        const normalizedApiFilePath = normalizePath(apiFilePath);
+        const apiDef = this.apiFiles[normalizedApiFilePath];
         if (!apiDef) {
             throw new Error(`API ${oldName} not found`);
         }
-        const otherPageAPIs = structuredClone(Object.keys(this.apiFiles)
-            .filter((path) => path.startsWith(pagePath) && path !== apiFilePath)
+        const otherAPIs = structuredClone(Object.keys(this.apiFiles)
+            .filter((path) => path !== normalizedApiFilePath)
             .map((path) => ({
             api: { apiPb: this.apiFiles[path]?.apiPb },
             filePath: path,
@@ -776,17 +830,10 @@ export default registerPage(Page, { name: "${name}" });
         this.watcher?.unwatch(newApiFolder);
         apiDef.apiPb.metadata.name = newName;
         await fs.rename(existingApiFolder, newApiFolder);
-        const scopeDef = this.sourceTracker?.getScopeDefinitionForPage(pageName);
-        if (!scopeDef) {
-            throw new Error(`Scope definition not found for API`);
-        }
-        this.sourceTracker?.renameEntity({
-            oldName,
-            newName,
-            entityId: scopeDef.scopeNameToEntityId[oldName],
-        });
-        delete this.apiFiles[apiFilePath];
-        this.writeFile(path.join(newApiFolder, "api.yaml"), yaml.stringify(apiDef.apiPb), "api");
+        const scopeId = getScopeIdFromName("App");
+        delete this.apiFiles[normalizedApiFilePath];
+        // not waiting because we are queueing the write further down
+        void this.writeFile(nodePath.join(newApiFolder, "api.yaml"), yaml.stringify(apiDef.apiPb), "api");
         this.watcher?.add(existingApiFolder);
         this.watcher?.add(newApiFolder);
         const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
@@ -794,255 +841,61 @@ export default registerPage(Page, { name: "${name}" });
         this.emit("apiManualUpdate", {
             api: this.createClientApi(apiDef),
             oldName,
-            pageName,
-            scopeId: scopeDef?.id ?? "",
+            scopeId,
         }, true);
         await this.renameManager.renameEntityInApis({
             oldName,
             newName,
-            apis: otherPageAPIs,
+            apis: otherAPIs,
         });
         // only save the APIs that have changed
-        await Promise.all(otherPageAPIs.map(async ({ api, filePath }) => {
+        await Promise.all(otherAPIs.map(async ({ api, filePath }) => {
             if (isEqual(api?.apiPb, this.apiFiles[filePath]?.apiPb)) {
                 return Promise.resolve();
             }
             await this.writeFile(filePath, yaml.stringify(api?.apiPb), "api");
             this.emit("apiManualUpdate", {
                 api: this.createClientApi(api),
-                pageName,
-                scopeId: scopeDef?.id ?? "",
+                scopeId,
             }, true);
-            // TODO: Should I delete here?
         }));
     };
-    handleAddEntity = async (payload) => {
-        await this.sourceTracker?.addEntity({
-            scopeId: payload.scopeId,
-            entity: {
-                type: payload.type,
-                name: payload.name,
-                attributes: payload.attributes,
-            },
-        });
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes, (fileName) => {
-            this.emit("addEntity", fileName, payload);
-        });
-    };
-    handleUpdateEntity = async (payload) => {
-        await this.sourceTracker?.updateEntity({
-            entityId: payload.entityId,
-            updates: payload.updates,
-        });
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes, (fileName) => {
-            this.emit("updateEntity", fileName, payload);
-        });
-    };
-    handleDeleteEntity = async (payload) => {
-        const deletedEntityName = await this.sourceTracker?.deleteEntity({
-            entityId: payload.entityId,
-        });
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes, (fileName) => {
-            if (deletedEntityName) {
-                this.emit("deleteEntity", fileName, deletedEntityName);
-            }
-        });
-    };
-    handleUpdateTheme = async (payload) => {
-        const { theme } = payload;
-        if (!this.rootDir) {
-            throw new Error("Root directory not set");
+    async removeApiData(filePath) {
+        const normalizedPath = normalizePath(filePath);
+        const api = this.apiFiles[normalizedPath];
+        if (!api) {
+            return;
         }
-        const filePath = path.join(this.rootDir, APP_THEME_FILE_NAME);
-        await this.sourceTracker?.updateTheme({
-            themeFilePath: filePath,
-            theme,
+        delete this.apiFiles[normalizedPath];
+        this.sourceTracker?.deleteApi({
+            apiName: api.apiPb.metadata.name,
         });
         const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
         await this.writeChanges(changes);
-    };
-    handleRenameElement = async (payload) => {
-        if (payload.kind === "component") {
-            return this.handleRenameComponent(payload);
-        }
-        else if (payload.kind === "entity") {
-            return this.handleRenameEntity(payload);
-        }
-        else if (payload.kind === "page") {
-            return this.handleRenamePage(payload);
-        }
-    };
-    handleRenameComponent = async (payload) => {
-        const { elementId, newName, oldName, scopeName } = payload;
-        await this.sourceTracker?.renameComponent({
-            widgetSourceId: elementId,
-            oldName,
-            newName,
-            scopeName,
-        });
-        await this.renameIdentifierInApis({
-            elementId,
-            oldName,
-            newName,
-        });
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes, (fileName) => {
-            this.emit("renameComponent", fileName);
-        });
-    };
-    handleRenameEntity = async (payload) => {
-        const { elementId, newName, oldName, scopeName } = payload;
-        await this.sourceTracker?.renameEntity({
-            entityId: elementId,
-            oldName,
-            newName,
-            scopeName,
-        });
-        await this.renameIdentifierInApis(payload);
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes, (fileName) => {
-            this.emit("renameEntity", fileName);
-        });
-    };
-    handleRenamePage = async (payload) => {
-        const { newName, oldName } = payload;
-        if (!this.rootDir) {
-            throw new Error("Root directory not set");
-        }
-        const newPageFolder = getPageFolder(this.rootDir, newName);
-        const newIndexFilePath = path.join(newPageFolder, "index.tsx");
-        const oldIndexFilePath = path.join(this.rootDir, "pages", oldName, "index.tsx");
-        const oldPageFolder = getPageFolder(this.rootDir, oldName);
-        this.watcher?.unwatch(newPageFolder);
-        this.watcher?.unwatch(oldPageFolder);
-        const existingRoute = Object.keys(this.routes).find((route) => this.routes[route]?.file ===
-            this.getRelativeRoutePath(oldIndexFilePath));
-        if (!existingRoute) {
-            throw new Error(`Route for ${oldName} not found`);
-        }
-        // Write the name attribute to the page file
-        await this.sourceTracker?.renamePage({
-            newName,
-            filePath: oldIndexFilePath,
+        const scopeId = getScopeIdFromName("App");
+        this.emit("apiManualDelete", {
+            api: {
+                id: api.apiPb.metadata.name,
+                apiName: api.apiPb.metadata.name,
+                scopeId,
+            },
         });
-        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
-        await this.writeChanges(changes);
-        // A rename of a folder is an unlink followed by an add, so the file watcher will take over initializing this
-        // "new" page
-        await fs.rename(oldPageFolder, newPageFolder);
-        // Now we just clean up the routes
-        await this.removeRoute(oldIndexFilePath);
-        await this.addRoute(existingRoute, newIndexFilePath);
-        const newIndexFile = await readFile(newIndexFilePath);
-        if (!newIndexFile) {
-            throw new Error(`New index file ${newIndexFilePath} not found`);
-        }
-        this.tsFiles[newIndexFilePath] = newIndexFile;
-        await this.handleNonVisualChangeByDeletingIds(newIndexFilePath, newIndexFile);
-        this.emit("renamePage", newIndexFilePath);
-        // Re-add the watcher
-        this.watcher?.add(newPageFolder);
-        this.watcher?.add(oldPageFolder);
-    };
-    getPageRoots(filePath) {
-        const scopeFilePath = path.join(path.dirname(filePath), "index.tsx");
-        const currentFile = this.sourceTracker?.getCurrentFiles()[scopeFilePath];
-        if (!currentFile) {
-            return null;
-        }
-        return getPageRoots(filePath, currentFile);
-    }
-    getScope(filePath) {
-        // get the scope.ts file in the same directory as path
-        const scopeFilePath = path.join(path.dirname(filePath), SCOPE_FILE);
-        const currentFile = this.sourceTracker?.getCurrentFiles()[scopeFilePath];
-        if (!currentFile) {
-            console.log("File not found", scopeFilePath);
-            return null;
-        }
-        const scope = getScope(scopeFilePath, currentFile);
-        return scope;
     }
-    getRoutes() {
-        const routes = [];
-        for (const [path, { file }] of Object.entries(this.routes)) {
-            routes.push({
-                path,
-                component: file,
-            });
-        }
-        return routes;
-    }
-    async addRoute(route, filePath) {
-        if (!this.rootDir) {
-            throw new Error("Root directory not set");
-        }
-        this.routes[route] = { file: this.getRelativeRoutePath(filePath) };
-        await this.writeFile(path.join(this.rootDir, ROUTES_FILE), JSON.stringify(this.routes, null, 2));
-    }
-    async removeRoute(filePath) {
-        if (!this.rootDir) {
-            throw new Error("Root directory not set");
-        }
-        const relativeFilePath = this.getRelativeRoutePath(filePath);
-        this.routes = Object.fromEntries(Object.entries(this.routes).filter(([_, value]) => value.file !== relativeFilePath));
-        await this.writeFile(path.join(this.rootDir, ROUTES_FILE), JSON.stringify(this.routes, null, 2));
-    }
-    async writeChanges(changes, callback) {
-        return Promise.all(changes.map(async ({ fileName, source, kind }) => {
-            await this.writeFile(fileName, source, kind);
-            return callback?.(fileName, source);
-        }));
-    }
-    getNodeForWidgetSourceId(id) {
-        return this.sourceTracker?.getElementToLocation(id);
-    }
-    getAstForWidgetSourceId(id) {
-        const filePath = this.sourceTracker?.getElementToFilePath(id);
-        if (!filePath) {
-            return null;
-        }
-        return this.sourceTracker?.getCurrentFiles()[filePath]?.ast;
-    }
-    renameIdentifierInApis = async ({ elementId, oldName, newName, parentBinding, }) => {
-        const apisInScope = structuredClone(this.getApisInScope(elementId));
-        await this.renameManager.renameEntityInApis({
-            oldName,
-            newName,
-            parentBinding,
-            apis: apisInScope,
-        });
-        // only save the APIs that have changed
-        await Promise.all(apisInScope.map(({ api, filePath }) => {
-            if (isEqual(api?.apiPb, this.apiFiles[filePath]?.apiPb)) {
-                return Promise.resolve();
+    getApiFiles() {
+        return Object.keys(this.apiFiles).reduce((acc, key) => {
+            if (!this.apiFiles[key]) {
+                return acc;
             }
-            return this.writeFile(filePath, yaml.stringify(api?.apiPb), "api");
-        }));
-    };
-    getApisInScope = (elementId) => {
-        const filePath = this.sourceTracker?.getElementToFilePath(elementId);
-        if (!filePath) {
-            return [];
-        }
-        const pagePath = path.dirname(filePath);
-        return Object.entries(this.apiFiles)
-            .filter(([filePath]) => filePath.includes(pagePath))
-            .map(([filePath, api]) => ({ api, filePath }));
-    };
-    getRelativeRoutePath(filePath) {
-        if (!this.rootDir) {
-            throw new Error("Root directory not set");
-        }
-        // no leading slash
-        return path.relative(path.join(this.rootDir, PAGES_DIRECTORY), filePath);
+            acc[key] = {
+                api: this.createClientApi(this.apiFiles[key]),
+                scopeId: this.apiFiles[key].scopeId,
+            };
+            return acc;
+        }, {});
     }
     // Utilities for converting server API format to Client API format
     // We internally save the API as the server does, but we return should always return it
-    // to the client with an id generated as PageName_ApiName
+    // to the client with an id equal to the API name
     createClientApi(api) {
         return {
             pageName: api.pageName,
@@ -1050,72 +903,106 @@ export default registerPage(Page, { name: "${name}" });
                 ...api.apiPb,
                 metadata: {
                     ...api.apiPb.metadata,
-                    id: getClientApiId(api.apiPb.metadata.name, api.pageName),
+                    id: api.apiPb.metadata.name,
                 },
             },
         };
     }
-    formatApisToClientApis(serverApis) {
-        return Object.keys(serverApis).reduce((acc, key) => {
-            if (!serverApis[key]) {
-                return acc;
-            }
-            acc[key] = {
-                api: this.createClientApi(serverApis[key]),
-                scopeId: serverApis[key].scopeId,
-            };
-            return acc;
-        }, {});
-    }
-    async processApiUpdates(filePath, fileType) {
+    addApiToScope = async (api) => {
+        if (!this.sourceTracker) {
+            throw new Error("Source tracker not initialized");
+        }
+        // We want to add the API entity to our scope, but we do not want to emit entity events, because
+        // the API update event handles this particular side effect.
+        const scopeId = await this.sourceTracker.addApi({
+            apiName: api.apiPb.metadata.name,
+        });
+        const changes = (await this.sourceTracker?.getAndFlushChanges()) ?? [];
+        await this.writeChanges(changes);
+        return scopeId;
+    };
+    async processApiFileUpdates(filePath, fileType) {
         let yamlPath = filePath;
         if (fileType.type === "python-api-step" ||
             fileType.type === "js-api-step") {
-            const apiFolderPath = filePath.split("/").slice(0, -1).join("/");
-            yamlPath = path.join(apiFolderPath, "api.yaml");
+            const apiFolderPath = nodePath.dirname(filePath);
+            yamlPath = nodePath.join(apiFolderPath, "api.yaml");
         }
+        const normalizedYamlPath = normalizePath(yamlPath);
         const logger = getLogger();
+        logger.info(`Processing API file update: ${yamlPath}`);
         try {
             const apiContent = await getMergedApiContent(yamlPath);
-            if (!isValidApi(apiContent.api)) {
-                return;
-            }
+            logger.info(`API content read successfully: ${yamlPath}`);
             if (!apiContent) {
                 return;
             }
+            logger.info(`API structure is valid: ${yamlPath}`);
             const parsedData = { apiPb: apiContent?.api };
-            if (!(yamlPath in this.apiFiles &&
-                isEqual(this.apiFiles[yamlPath]?.apiPb, parsedData.apiPb))) {
-                const { updatedApi, pageName, isNewApi } = this.updateApi({
-                    api: parsedData.apiPb,
-                    stepPathMap: apiContent.stepPathMap,
-                }, yamlPath);
-                logger.info(`API changed: ${yamlPath}`);
-                const scopeDef = this.sourceTracker?.getScopeDefinitionForPage(pageName);
-                if (!scopeDef) {
-                    logger.error(`Scope definition not found for API`);
-                    return;
-                }
-                if (isNewApi) {
-                    await this.createScopedApi(updatedApi);
-                }
-                this.emit("apiManualUpdate", {
-                    api: this.createClientApi(updatedApi),
-                    pageName,
-                    scopeId: scopeDef.id,
-                }, isNewApi);
-            }
-            else {
-                logger.info(`File unchanged from last tracked state: ${filePath}`);
+            if (normalizedYamlPath in this.apiFiles &&
+                isEqual(this.apiFiles[normalizedYamlPath]?.apiPb, parsedData.apiPb)) {
+                logger.info(`No changes detected in API: ${normalizedYamlPath}`);
+                return;
             }
+            const { updatedApi, isNewApi } = this.updateInternalApiData({
+                api: parsedData.apiPb,
+                stepPathMap: apiContent.stepPathMap,
+            }, yamlPath);
+            logger.info(`API changed: ${yamlPath}`);
+            const scopeId = getScopeIdFromName("App");
+            this.emit("apiManualUpdate", {
+                api: this.createClientApi(updatedApi),
+                scopeId,
+            }, isNewApi);
         }
-        catch {
-            logger.info(`API file incomplete: ${yamlPath}`);
+        catch (error) {
+            logger.error(`Error updating API: ${yamlPath}, error: ${error}`);
         }
     }
+    updateInternalApiData = (content, path) => {
+        if (!this.rootDir) {
+            throw new Error("Root directory not set");
+        }
+        const { api: apiContents, stepPathMap } = content;
+        const scopeId = getScopeIdFromName("App");
+        const updatedApi = {
+            apiPb: yaml.parse(JSON.stringify(apiContents)),
+            stepPathMap,
+            scopeId,
+        };
+        const isNewApi = !this.apiFiles[path];
+        this.apiFiles[path] = updatedApi;
+        return { updatedApi, isNewApi };
+    };
+    renameIdentifierInApis = async ({ elementId, oldName, newName, parentBinding, }) => {
+        const apisInScope = structuredClone(this.getApisInScope(elementId));
+        await this.renameManager.renameEntityInApis({
+            oldName,
+            newName,
+            parentBinding,
+            apis: apisInScope,
+        });
+        // only save the APIs that have changed
+        await Promise.all(apisInScope.map(({ api, filePath }) => {
+            if (isEqual(api?.apiPb, this.apiFiles[filePath]?.apiPb)) {
+                return Promise.resolve();
+            }
+            return this.writeFile(filePath, yaml.stringify(api?.apiPb), "api");
+        }));
+    };
+    getApisInScope = (_elementId) => {
+        // All APIs are now at app-level scope
+        return Object.entries(this.apiFiles).map(([filePath, api]) => ({
+            api,
+            filePath,
+        }));
+    };
+    isSkillFile(filePath) {
+        return filePath.includes("/skills/app/") && filePath.endsWith(".md");
+    }
 }
 // Add new mock implementation
-export class MockFileSyncManager extends FileSyncManager {
+export class MockFileSyncManager extends FileSystemManager {
     tsFiles = {};
     apiFiles = {};
     async watch(_watcher, _path) {
@@ -1123,57 +1010,58 @@ export class MockFileSyncManager extends FileSyncManager {
     }
     async writeFile(path, content, kind) {
         await this.fsOperationQueue.enqueue(async () => {
+            const normalizedPath = normalizePath(path);
             if (kind === "ts") {
-                this.tsFiles[path] = content;
+                this.tsFiles[normalizedPath] = content;
             }
             else {
-                this.apiFiles[path] = {
+                this.apiFiles[normalizedPath] = {
                     apiPb: yaml.parse(content),
-                    pageName: getPageName(path),
                     stepPathMap: {},
-                    // TODO: generate a scope ID for tests
-                    scopeId: "",
+                    scopeId: getScopeIdFromName("App"),
                 };
             }
             // Notify subscribers
-            this.emit("fileChanged", path, content, true);
+            this.emit("fileChanged", normalizedPath, content);
         });
     }
     // Helper methods for testing
     mockFileChange(path, content) {
-        this.tsFiles[path] = content;
-        this.emit("fileChanged", path, content, true);
+        const normalizedPath = normalizePath(path);
+        this.tsFiles[normalizedPath] = content;
+        this.emit("fileChanged", normalizedPath, content);
     }
     handleUpdateApi = async (payload) => {
         const apiName = payload.api.apiPb.metadata.name;
-        this.apiFiles[apiName] = {
+        if (!this.rootDir) {
+            throw new Error("Root directory not set");
+        }
+        const apiFilePath = getApiFilePath(this.rootDir, apiName);
+        const normalizedApiFilePath = normalizePath(apiFilePath);
+        this.apiFiles[normalizedApiFilePath] = {
             ...payload.api,
             stepPathMap: {},
             scopeId: payload.scopeId,
         };
-        const scopeDef = this.sourceTracker?.getScopeDefinitionForPage(payload.api.pageName);
+        const scopeId = getScopeIdFromName("App");
         const generationNumber = this.generationNumberSequence.next();
         this.emit("apiUpdate", {
             api: payload.api,
-            scopeId: scopeDef?.id ?? "",
+            scopeId,
         });
         return {
             api: payload.api,
             generationNumber,
-            scopeId: scopeDef?.id ?? "",
+            scopeId,
         };
     };
-    getSourceTracker() {
-        return this.sourceTracker;
-    }
 }
 async function readFile(path) {
     try {
         // in order for try-catch to work, we need to intentionally await the readFile call,
         // otherwise the error won't be be caught
         // see: https://github.com/nodejs/node/issues/51894#issuecomment-1974017737
-        const content = await fs.readFile(path, "utf-8");
-        return content;
+        return await fs.readFile(path, "utf-8");
     }
     catch (e) {
         getLogger().error(`error reading file: ${path}`, getErrorMeta(e));
@@ -1181,7 +1069,9 @@ async function readFile(path) {
     }
 }
 async function readFiles(dir) {
-    return await glob(path.join(dir, "**/*.{tsx,yaml,ts}"), {
+    const files = await glob("**/*.{tsx,yaml,ts}", {
+        cwd: dir,
+        absolute: true,
         ignore: [
             "node_modules/**",
             "dist/**",
@@ -1190,16 +1080,10 @@ async function readFiles(dir) {
             `./${getLegacyComponentsFolder()}/**`,
         ],
     });
+    // Normalize paths to use forward slashes on all platforms (Windows returns backslashes)
+    return files.map((file) => normalizePath(file));
 }
-const getMergedApiContent = async (path) => {
-    return readAppApiYamlFile(path.split("/").slice(0, -1).join("/"));
-};
-const getPageName = (path) => {
-    const parts = path.split("/");
-    const pagesIndex = parts.findIndex((part) => part === "pages");
-    if (pagesIndex !== -1 && parts[pagesIndex + 1]) {
-        return parts[pagesIndex + 1] ?? "";
-    }
-    return "";
+const getMergedApiContent = async (filePath) => {
+    return readAppApiYamlFile(nodePath.dirname(filePath));
 };
 //# sourceMappingURL=file-system-manager.js.map