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

package/dist/file-sync-vite-plugin.js

@@ -1,30 +1,258 @@
+import { readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import path from "node:path";
-import { ApiTriggerType } from "@superblocksteam/shared";
+import { pipeline } from "node:stream/promises";
+import archiver from "archiver";
 import bodyParser from "body-parser";
-import { stripIndent } from "common-tags";
+import { debounce } from "lodash-es";
 import { normalizePath } from "vite";
-import { extractApiDependencies, extractIdentifierPathsFromApi, } from "./binding-extraction/extract-identifiers.js";
+import { getAppScopeDefaultStructure } from "@superblocksteam/library-shared";
+import { buildRouterParseErrorPrompt, } from "@superblocksteam/library-shared/types";
+import { ApiTriggerType, SUPERBLOCKS_LIVE_GIT_BRANCH, } from "@superblocksteam/shared";
+import { wireContextFlush } from "./ai-service/context-flush.js";
+import { extractInputsFromApi } from "./binding-extraction/extract-identifiers.js";
+import { ImportError } from "./build-errors.js";
+import { createClarkLogForwarder } from "./clark-log-forwarder.js";
 import { ComponentsManager } from "./components-manager.js";
+import { getDownloadArchiveFilename } from "./download-filename.js";
 import { makeServerError } from "./errors/make-server-error.js";
-import { getPageFilePath, SCOPE_FILE } from "./file-system-helpers.js";
-import { FileSyncManager } from "./file-system-manager.js";
+import { isApiFilePath, isPageFilePath, getCodeModeDownloadArchiveGlobPatterns, isSkillFilePath, listCodeViewerFiles, } from "./file-system-helpers.js";
+import { FileSystemManager } from "./file-system-manager.js";
+import { createGitOperationLock } from "./git-operation-lock.js";
+import { createCheckpointGitCommitter } from "./git-service/checkpoint-committer.js";
+import { ensureLiveBranchCheckedOut } from "./git-service/live-branch.js";
 import { indexHtmlMiddleware } from "./injected-index.js";
 import { LockServiceStatus } from "./lock-service/index.js";
+import { registerMigrationRoutes } from "./migration/migration-routes.js";
+import { getImports } from "./parsing/imports.js";
 import { getLegacyComponentsFolder, isCustomBuildEnabled, setOptions, } from "./plugin-options.js";
-import { generateRootSource } from "./routing.js";
-import { SocketManager } from "./socket-manager.js";
+import { registerPolicyGateRoutes } from "./policy-gate-runner.js";
+import { createIdResolver, getFullImportPath } from "./resolver.js";
+import { recordRouterParseFailure } from "./router-parser-metrics.js";
+import { parseRouterFile } from "./router-parser.js";
+import { registerSnapshotRoutes } from "./snapshot-routes.js";
+import { createSocketManager, disposeSocketManager } from "./socket-manager.js";
+import { shouldReportDraftStateOnConnect } from "./sync-service/draft-reconcile.js";
+import { getAllPages } from "./util.js";
 import { GenerationNumberSequence } from "./util/generation-number-sequence.js";
-import { getErrorMeta, setLogger } from "./util/logger.js";
-import { getAllApiDefinitions, getAllPages } from "./util.js";
+import { getErrorMeta, getLogger, setDefaultLogger } from "./util/logger.js";
+import { resolvedVirtualRegisteredComponentsId, virtualLegacyId, resolvedVirtualLegacyId, virtualRegisteredComponentsId, } from "./virtual-modules.js";
+import { YAML_TYPES_PLUGIN_NAME, yamlApiTypesPlugin, } from "./vite-plugin-yaml-types.js";
 let hasStarted = false;
 let isInitialized = false;
 let config;
-const virtualLegacyId = "virtual:legacy-wrapper";
-const resolvedVirtualLegacyId = `\0${virtualLegacyId}`;
-const virtualRegisteredComponentsId = "virtual:registered-components";
-const resolvedVirtualRegisteredComponentsId = `\0${virtualRegisteredComponentsId}`;
-export const fileSyncVitePlugin = (pluginParams, options) => {
-    const logger = setLogger(pluginParams.logger);
+// Store file transform errors to send when editor clients connect
+let pendingFileTransformError = null;
+const loggedViteErrors = [];
+// Cadence for flushing conversation context to Bucketeer during a generation.
+// A single agent turn persists many times before it completes; debounce those
+// into one upload, but force one at the hard max so a long turn still flushes.
+// Overridable so the cadence can be tuned without a code change.
+// A mistyped override (e.g. "abc") would parse to NaN and collapse the debounce
+// to zero, turning every persist into an upload; fall back to the default
+// instead of silently changing the cadence.
+const readPositiveMs = (raw, fallback) => {
+    const parsed = Number(raw ?? fallback);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+const CONTEXT_FLUSH_DEBOUNCE_MS = readPositiveMs(process.env.SUPERBLOCKS_CONTEXT_FLUSH_DEBOUNCE_MS, 2000);
+const CONTEXT_FLUSH_MAX_WAIT_MS = readPositiveMs(process.env.SUPERBLOCKS_CONTEXT_FLUSH_MAX_WAIT_MS, 20000);
+const PLUGIN_NAME = "sb-file-sync";
+export function createGenerationFreshnessTracker() {
+    let latestGenerationId;
+    return {
+        markStarted: (generationId) => {
+            latestGenerationId = generationId;
+        },
+        isLatest: (generationId) => generationId === latestGenerationId,
+    };
+}
+export function createLatestAppScopePublisher({ publishAppScope, readAppScope, }) {
+    let latestRevision = 0;
+    return async () => {
+        const revision = ++latestRevision;
+        const appScope = await readAppScope();
+        if (revision !== latestRevision) {
+            return undefined;
+        }
+        publishAppScope(appScope);
+        return appScope;
+    };
+}
+export function shouldForwardServerError({ errorType, isAiBusy, }) {
+    return errorType === "dev-server/sync" || !isAiBusy;
+}
+export async function handleTokenUpdateRequest({ authorization, checkAuthorization, logger, tokenManager, }) {
+    if (!authorization?.startsWith("Bearer ")) {
+        return {
+            statusCode: 401,
+            body: JSON.stringify({ error: "Invalid authorization header" }),
+        };
+    }
+    const result = await checkAuthorization(authorization);
+    if (!result.success) {
+        return {
+            statusCode: result.status,
+            body: JSON.stringify({ error: result.error }),
+        };
+    }
+    if (!tokenManager) {
+        logger.warn("[auth] token refresh received without a tokenManager");
+        return { statusCode: 204 };
+    }
+    tokenManager.updateToken(authorization.substring("Bearer ".length));
+    logger.info("[auth] updated tokenManager from editor token refresh");
+    return { statusCode: 204 };
+}
+export async function handleGenerationCompletedFileSync({ aiService, contextFlushScheduler, hasHadAnyDrafts, isFirstContentfulGeneration, isLatestGeneration = () => true, logger, producedDraft, server, syncService, }) {
+    logger.info("[file-sync] generationCompleted event received", {
+        applicationId: syncService.applicationId,
+        branchName: syncService.branchName,
+        hasHadAnyDrafts,
+        isFirstContentfulGeneration,
+        producedDraft,
+    });
+    aiService.handleClearBuildSystemErrors();
+    if (!producedDraft) {
+        logger.info("[file-sync] Skipping post-generation upload because producedDraft=false", {
+            applicationId: syncService.applicationId,
+            branchName: syncService.branchName,
+            hasHadAnyDrafts,
+            isFirstContentfulGeneration,
+        });
+        // Chat-only turns can still persist context; flush so the completed turn is durable.
+        contextFlushScheduler?.flushNow();
+        return { isFirstContentfulGeneration };
+    }
+    let nextIsFirstContentfulGeneration = isFirstContentfulGeneration;
+    const shouldFireFirstGenerationReload = isFirstContentfulGeneration && hasHadAnyDrafts;
+    if (!aiService.hasConnectedPeer()) {
+        logger.warn("[file-sync] Contentful generation but no peer is connected");
+    }
+    logger.info("[file-sync] Triggering post-generation upload");
+    await syncService.uploadDirectory("ai:generate:post");
+    const result = await syncService.uploadDirectoryNowIfNeeded("ai:generate:post");
+    logger.info("[file-sync] Post-generation upload completed", {
+        applicationId: syncService.applicationId,
+        branchName: syncService.branchName,
+        commitId: result.commitId,
+        directoryHashPrefix: result.directoryHash.slice(0, 12),
+    });
+    // Defer full-reload until after the post-generation upload so the socket
+    // teardown does not race with the upload drain. If another generation started
+    // while this upload was in flight, leave the one-time reload eligible for the
+    // newer generation instead of tearing down its editor socket.
+    if (shouldFireFirstGenerationReload) {
+        if (isLatestGeneration()) {
+            logger.debug("Sending full-reload after first generation (deferred)");
+            server.ws.send({
+                type: "full-reload",
+            });
+            nextIsFirstContentfulGeneration = false;
+        }
+        else {
+            logger.debug("[file-sync] Skipping deferred first-generation full-reload because a newer generation started");
+        }
+    }
+    // Flush context to Bucketeer now (bypassing the debounce) so the freshest
+    // complete turn is durable as soon as the generation ends.
+    contextFlushScheduler?.flushNow();
+    return {
+        isFirstContentfulGeneration: nextIsFirstContentfulGeneration,
+    };
+}
+const ROUTER_PARSE_ERROR_MESSAGE = "The editor could not discover any pages because the router uses an unsupported route element shape.";
+export function createRouterParseReporter({ aiService, devServerStatus, logger, now = () => new Date(), rootDir, socketManager, }) {
+    let currentDiagnosticKey;
+    // Kept so a newly connected editor can be handed the active error. The
+    // broadcast at parse time only reaches sockets that were already registered.
+    let currentError = null;
+    return {
+        getCurrentError: () => currentError,
+        report: async (diagnostic) => {
+            if (diagnostic?.kind === "parse_exception") {
+                // Reading or parsing the router failed, so we know nothing about the
+                // routes. Keep the last known state rather than reporting recovery:
+                // clearing here would drop the overlay mid-edit and let the false 404
+                // back in. Vite reports the syntax error itself.
+                return;
+            }
+            const diagnosticKey = diagnostic
+                ? `${diagnostic.kind}:${diagnostic.routeObjectCount}:${diagnostic.routerFilePath}`
+                : undefined;
+            if (diagnosticKey === currentDiagnosticKey) {
+                return;
+            }
+            const replacesDiagnostic = currentDiagnosticKey !== undefined;
+            currentDiagnosticKey = diagnosticKey;
+            if (!diagnostic) {
+                currentError = null;
+                if (devServerStatus) {
+                    devServerStatus.serverErrors = devServerStatus.serverErrors.filter((error) => error.type !== "dev-server/router-parse");
+                }
+                aiService?.handleClearBuildSystemErrors("router-parser");
+                try {
+                    await socketManager.callEditorClients((socket) => socket.call.routerParseError(null));
+                }
+                catch (error) {
+                    logger.error("Failed to notify editor clients about router parsing", getErrorMeta(error));
+                }
+                return;
+            }
+            const routerFilePath = normalizePath(path.relative(rootDir, diagnostic.routerFilePath));
+            const error = {
+                type: "dev-server/router-parse",
+                category: diagnostic.kind,
+                critical: false,
+                message: ROUTER_PARSE_ERROR_MESSAGE,
+                routeObjectCount: diagnostic.routeObjectCount,
+                routerFilePath,
+                timestamp: now().toISOString(),
+            };
+            currentError = error;
+            if (devServerStatus) {
+                devServerStatus.serverErrors = [
+                    ...devServerStatus.serverErrors.filter((entry) => entry.type !== "dev-server/router-parse"),
+                    error,
+                ];
+            }
+            recordRouterParseFailure(error.category);
+            logger.warnStructured?.("Router parsing failed", {
+                "router.parse.category": error.category,
+                "router.parse.route_object_count": error.routeObjectCount,
+                "router.parse.file_path": routerFilePath,
+            });
+            try {
+                await socketManager.callEditorClients((socket) => socket.call.routerParseError(error));
+            }
+            catch (notificationError) {
+                logger.error("Failed to notify editor clients about router parsing", getErrorMeta(notificationError));
+            }
+            if (replacesDiagnostic) {
+                aiService?.handleClearBuildSystemErrors("router-parser");
+            }
+            const buildSystemError = new Error(buildRouterParseErrorPrompt(routerFilePath));
+            buildSystemError.source = "router-parser";
+            aiService?.handleBuildSystemError(buildSystemError, "transform");
+        },
+    };
+}
+export function fileSyncVitePlugin(pluginParams, options) {
+    if (!pluginParams) {
+        // Noop stubs for the warm-standby pre-warm pass. Must mirror `enforce`
+        // and `apply` on the real plugins below — Vite sorts plugins by those
+        // fields before hashing the plugin list into the dep cache key, so a
+        // mismatch would make activation discard the pre-warmed cache.
+        return {
+            plugin: [
+                { name: PLUGIN_NAME, apply: "serve", enforce: "pre" },
+                { name: YAML_TYPES_PLUGIN_NAME, enforce: "pre" },
+            ],
+            dispose: () => { },
+        };
+    }
+    const logger = pluginParams.logger;
+    // Set the default logger for all files that still use getLogger()
+    setDefaultLogger(logger);
     setOptions(options ?? {
         legacyComponentsFolder: "legacy",
     });
@@ -32,28 +260,147 @@ export const fileSyncVitePlugin = (pluginParams, options) => {
     const syncService = pluginParams.syncService;
     const lockService = pluginParams.lockService;
     const aiService = pluginParams.aiService;
+    const gitService = pluginParams.gitService;
+    const activateGitService = pluginParams.activateGitService;
+    const refreshGitCredentials = pluginParams.refreshGitCredentials;
+    const gitOperationLock = createGitOperationLock();
     const fsOperationQueue = pluginParams.fsOperationQueue;
     const httpServer = pluginParams.httpServer;
-    const fileSyncManager = new FileSyncManager(fsOperationQueue, generationNumberSequence);
+    let socketManager;
+    let unregisterLogForwarder;
+    let contextFlushScheduler;
+    const fileSyncManager = new FileSystemManager(fsOperationQueue, generationNumberSequence, pluginParams.tracer);
     if (syncService) {
         syncService.generationNumberSequence = generationNumberSequence;
     }
-    // Set up sync callback in lock service
     if (lockService && syncService) {
         lockService.setSyncCallback(async () => {
-            await syncService.uploadDirectory();
-            await syncService.uploadDirectoryNowIfNeeded();
+            await syncService.uploadDirectory("initialSync");
+            await syncService.uploadDirectoryNowIfNeeded("initialSync");
         });
     }
-    return {
-        name: "sb-file-sync",
+    if (aiService && lockService) {
+        lockService.setWaitForGenerationCompleteCallback(async () => {
+            await aiService.waitUntilGenerationComplete();
+        });
+    }
+    // Wire up commit ID updates for recording sessions
+    if (aiService && syncService) {
+        syncService.on("commitIdChanged", (commitId) => {
+            void aiService.getRecordingManager().setCurrentCommitId(commitId);
+        });
+    }
+    if (syncService && pluginParams.features?.autoCommitCheckpointsToGitEnabled) {
+        const commitCheckpointToGit = createCheckpointGitCommitter({
+            getGitService: async () => {
+                // Only a git-connected app runs on the live branch, and activation
+                // costs an API round trip, so this keeps every other app out of it.
+                if (syncService.branchName !== SUPERBLOCKS_LIVE_GIT_BRANCH) {
+                    return undefined;
+                }
+                const service = gitService ?? (await activateGitService?.());
+                if (service) {
+                    await ensureLiveBranchCheckedOut(service);
+                }
+                return service;
+            },
+            onGitStateChanged: () => {
+                socketManager?.callEditorClients((socket) => socket.call.requestGitRefresh());
+            },
+            superblocksBaseUrl: pluginParams.superblocksBaseUrl,
+            tryAcquireRepo: () => {
+                const lock = gitOperationLock.tryAcquire();
+                return lock.acquired ? lock.release : undefined;
+            },
+        });
+        syncService.on("checkpointCreated", (checkpoint) => {
+            void commitCheckpointToGit(checkpoint);
+        });
+    }
+    const componentsManager = ComponentsManager.setInstance(pluginParams.tracer);
+    const lastImportErrorFiles = new Set();
+    let isFirstContentfulGeneration = true;
+    const generationFreshnessTracker = createGenerationFreshnessTracker();
+    let hasHadAnyDrafts = false;
+    const debouncedFileUpdateHandlers = new Map();
+    const addFileTransformError = (filePath, error) => {
+        const fileTransformError = makeServerError(error, {
+            critical: false,
+        });
+        if (error.stack) {
+            const stackLines = error.stack.split("\n");
+            const clampedStack = stackLines.length > 20
+                ? stackLines.slice(0, 20).join("\n") + "\n... (stack truncated)"
+                : error.stack;
+            fileTransformError.stackTrace = clampedStack;
+        }
+        // Add specific advice for common Babel traversal errors
+        if (error.message.includes("pass a scope and parentPath unless traversing a Program/File")) {
+            fileTransformError.message = `File transformation error in ${filePath}: ${error.message}. This error commonly occurs when there are duplicate identifiers in scope destructuring. Check for repeated variable names in destructuring assignments.`;
+        }
+        pendingFileTransformError = { filePath, error };
+    };
+    const plugin = {
+        name: PLUGIN_NAME,
         apply: "serve",
         enforce: "pre",
+        config() {
+            return {
+                server: {
+                    watch: {
+                        ignored: ["**/.superblocks/**"],
+                    },
+                },
+            };
+        },
         async configureServer(server) {
+            const tracer = pluginParams.tracer;
             config = server.config;
-            const componentsManager = ComponentsManager.getInstance();
+            // SDK/fullstack apps override `root` to "./client" in their
+            // vite.config.ts, so config.root points to the client/ subdir.
+            // Operations that need the full app tree use this instead.
+            const appRootDir = pluginParams.appRootDir ?? config.root;
+            // Normalized prefix for detecting server/* file changes.
+            // Used to eagerly sync server files to DBFS on write so
+            // ensureFilesSynced() is a no-op on the SDK API execution path.
+            const serverPrefix = normalizePath(appRootDir) + "/server/";
+            // Debounce timer for eager server sync — coalesces Clark's burst writes
+            // (e.g. API file + index.ts barrel, 1-4s apart) into a single upload.
+            let eagerServerSyncTimer;
+            // Set up Vite module invalidation callback for SyncService
+            // This ensures that when Clark writes files, Vite's module cache is invalidated
+            if (syncService) {
+                syncService.setModuleInvalidationCallback((filePath) => {
+                    const fullPath = normalizePath(path.join(config.root, filePath));
+                    const module = server.moduleGraph.getModuleById(fullPath);
+                    if (module) {
+                        server.moduleGraph.invalidateModule(module);
+                        logger.info(`[vite-plugin] Invalidated module graph for: ${filePath}`);
+                    }
+                });
+            }
+            // Wrap logger.error to forward errors to AI and track them,
+            // while downgrading Vite errors to info level for our own logger.
+            // User notification is unaffected — Vite still sends vite:error via HMR.
+            config.logger.error = (message, options) => {
+                if (aiService?.isBusy()) {
+                    void aiService.handleBuildSystemError(new Error(message));
+                }
+                if (options?.error) {
+                    loggedViteErrors.push(options.error);
+                }
+                logger.info("[vite-plugin] Build system error", { message });
+            };
+            createIdResolver(server.config, server.environments.client);
             await Promise.all([
-                componentsManager.initialize(process.cwd(), server.watcher),
+                tracer.startActiveSpan("componentsManagerInitialize", async (compSpan) => {
+                    try {
+                        await componentsManager.initialize(process.cwd(), server.watcher);
+                    }
+                    finally {
+                        compSpan.end();
+                    }
+                }),
                 server.waitForRequestsIdle("sb-file-sync").then(async () => {
                     if (hasStarted) {
                         // We only want to initialize the file sync once, but vite seems to fire this multiple times
@@ -62,8 +409,15 @@ export const fileSyncVitePlugin = (pluginParams, options) => {
                     hasStarted = true;
                     const root = server.config.root;
                     try {
-                        await fileSyncManager.watch(server.watcher, root).then(() => {
-                            isInitialized = true;
+                        await tracer.startActiveSpan("fileSyncManagerWatch", async (watchSpan) => {
+                            try {
+                                await fileSyncManager.watch(server.watcher, root).then(() => {
+                                    isInitialized = true;
+                                });
+                            }
+                            finally {
+                                watchSpan.end();
+                            }
                         });
                     }
                     catch (e) {
@@ -71,501 +425,929 @@ export const fileSyncVitePlugin = (pluginParams, options) => {
                     }
                 }),
             ]);
-            server.middlewares.use(indexHtmlMiddleware(server, fileSyncManager));
-            server.middlewares.use("/sb-init", bodyParser.json({ strict: true }));
-            server.middlewares.use("/sb-init", async (req, res, next) => {
-                if (!isInitialized) {
-                    return next();
-                }
-                if (req.method !== "GET" && req.method !== "OPTIONS") {
-                    res.statusCode = 405;
-                    res.end("Method not allowed");
-                    return res.end();
-                }
-                res.setHeader("Access-Control-Allow-Origin", "*");
-                res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
-                res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-                if (req.method === "OPTIONS") {
-                    res.statusCode = 204;
-                    res.end();
-                    return;
-                }
-                const fullUrl = new URL(req.url ?? "/", "http://localhost:5173");
-                if (!fullUrl.searchParams.get("route")) {
-                    res.statusCode = 400;
-                    res.end("Missing route, use ?route=/route");
-                    return res.end();
-                }
-                const actualUrl = new URL(fullUrl.searchParams.get("route") ?? "/", fullUrl);
-                const files = await getAllApiDefinitions({
-                    rootDir: config.root,
-                    currentUrl: actualUrl.toString(),
+            if (aiService) {
+                aiService.setSourceTracker(fileSyncManager.getSourceTracker());
+                aiService.setFileSystemManager(fileSyncManager);
+                aiService.setViteServer(server);
+                aiService.setRuntimeGitServices(gitService, syncService, gitOperationLock);
+            }
+            server.middlewares.use("/_sb_update_token", (req, res) => {
+                void (async () => {
+                    if (req.method !== "POST" && req.method !== "OPTIONS") {
+                        res.statusCode = 405;
+                        res.end("Method not allowed");
+                        return;
+                    }
+                    if (req.method === "OPTIONS") {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    const result = await handleTokenUpdateRequest({
+                        authorization: req.headers.authorization,
+                        checkAuthorization: pluginParams.checkAuthorization,
+                        logger,
+                        tokenManager: pluginParams.tokenManager,
+                    });
+                    res.statusCode = result.statusCode;
+                    if (result.body) {
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(result.body);
+                    }
+                    else {
+                        res.end();
+                    }
+                })().catch((error) => {
+                    logger.error("Error updating auth token", getErrorMeta(error));
+                    if (!res.headersSent) {
+                        res.statusCode = 500;
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(JSON.stringify({ error: "Failed to update auth token" }));
+                    }
                 });
-                res.setHeader("Content-Type", "application/json");
-                return res.end(JSON.stringify(files));
             });
-            server.middlewares.use("/sb-scopes", bodyParser.json({ strict: true }));
-            server.middlewares.use("/sb-scopes", async (req, res, next) => {
-                if (!isInitialized) {
+            server.middlewares.use((req, res, next) => {
+                void indexHtmlMiddleware(server, pluginParams?.features)(req, res, next);
+            });
+            // Serve raw API source files without Vite transforms (for editor display)
+            server.middlewares.use("/sb-raw-source/", (req, res, next) => {
+                const relativePath = req.url?.replace(/^\//, "");
+                if (!relativePath) {
                     return next();
                 }
-                if (req.method !== "GET" && req.method !== "OPTIONS") {
-                    res.statusCode = 405;
-                    res.end("Method not allowed");
-                    return res.end();
+                try {
+                    const absolutePath = path.join(config.root, relativePath);
+                    // Prevent path traversal
+                    if (!absolutePath.startsWith(config.root)) {
+                        res.statusCode = 403;
+                        res.end("Forbidden");
+                        return;
+                    }
+                    const content = readFileSync(absolutePath, "utf-8");
+                    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                    res.end(content);
                 }
-                res.setHeader("Access-Control-Allow-Origin", "*");
-                res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
-                res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-                if (req.method === "OPTIONS") {
-                    res.statusCode = 204;
-                    res.end();
-                    return;
+                catch {
+                    res.statusCode = 404;
+                    res.end("Not found");
                 }
-                const appScope = await getAppScope(fileSyncManager);
-                res.setHeader("Content-Type", "application/json");
-                return res.end(JSON.stringify(appScope));
             });
-            // AI ping endpoint to keep connection alive during generation
-            server.middlewares.use("/sb-ping", async (req, res, _next) => {
-                if (req.method !== "GET" && req.method !== "OPTIONS") {
-                    res.statusCode = 405;
-                    res.end("Method not allowed");
-                    return res.end();
-                }
-                res.setHeader("Access-Control-Allow-Origin", "*");
-                res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
-                res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-                if (req.method === "OPTIONS") {
-                    res.statusCode = 204;
-                    res.end();
-                    return;
-                }
-                res.setHeader("Content-Type", "application/json");
-                return res.end(JSON.stringify({ status: "ok", timestamp: Date.now() }));
+            server.middlewares.use("/sb-scopes", bodyParser.json({ strict: true }));
+            server.middlewares.use("/sb-scopes", (req, res, next) => {
+                void (async () => {
+                    if (!isInitialized) {
+                        return next();
+                    }
+                    if (req.method !== "GET" && req.method !== "OPTIONS") {
+                        res.statusCode = 405;
+                        res.end("Method not allowed");
+                        return res.end();
+                    }
+                    res.setHeader("Access-Control-Allow-Origin", "*");
+                    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+                    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+                    if (req.method === "OPTIONS") {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    const appScope = await getAppScope(fileSyncManager, routerParseReporter.report);
+                    res.setHeader("Content-Type", "application/json");
+                    return res.end(JSON.stringify(appScope));
+                })();
+            });
+            server.middlewares.use("/sb-list-files", (req, res, next) => {
+                void (async () => {
+                    if (!isInitialized) {
+                        return next();
+                    }
+                    if (req.method !== "GET" && req.method !== "OPTIONS") {
+                        res.statusCode = 405;
+                        res.end("Method not allowed");
+                        return;
+                    }
+                    res.setHeader("Access-Control-Allow-Origin", "*");
+                    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+                    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+                    if (req.method === "OPTIONS") {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    try {
+                        const files = await listCodeViewerFiles(config.root);
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(JSON.stringify(files));
+                    }
+                    catch {
+                        res.statusCode = 500;
+                        res.end(JSON.stringify({ error: "Failed to list files" }));
+                    }
+                })();
             });
-            const socketManager = new SocketManager();
-            socketManager.startSocketServer({
-                server: httpServer,
-                fileSyncManager,
-                lockService,
+            server.middlewares.use("/sb-download", bodyParser.urlencoded({ extended: false }));
+            server.middlewares.use("/sb-download", (req, res, next) => {
+                void (async () => {
+                    if (!isInitialized) {
+                        return next();
+                    }
+                    if (req.method !== "POST" && req.method !== "OPTIONS") {
+                        res.statusCode = 405;
+                        res.end("Method not allowed");
+                        return;
+                    }
+                    res.setHeader("Access-Control-Allow-Origin", "*");
+                    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+                    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+                    if (req.method === "OPTIONS") {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    try {
+                        const rootDir = appRootDir;
+                        let metadataFilePath = null;
+                        const metadata = JSON.parse(req.body.metadata);
+                        const metadataDir = path.join(rootDir, ".superblocks");
+                        metadataFilePath = path.join(metadataDir, "download-metadata.json");
+                        writeFileSync(metadataFilePath, JSON.stringify(metadata, null, 2));
+                        const filename = getDownloadArchiveFilename({
+                            rootDir,
+                            metadata,
+                        });
+                        res.setHeader("Content-Type", "application/zip");
+                        res.setHeader("Content-Disposition", `attachment; filename="${filename}"`);
+                        res.setHeader("Transfer-Encoding", "chunked");
+                        const archive = archiver("zip", {
+                            zlib: { level: 9 },
+                        });
+                        archive.on("error", (err) => {
+                            logger.error("Archive error", getErrorMeta(err));
+                        });
+                        const { skip: archiveSkipPatterns, ignore: archiveIgnorePatterns } = getCodeModeDownloadArchiveGlobPatterns();
+                        archive.glob("**/*", {
+                            cwd: rootDir,
+                            dot: true,
+                            skip: archiveSkipPatterns,
+                            ignore: archiveIgnorePatterns,
+                        }, {});
+                        void archive.finalize();
+                        await pipeline(archive, res);
+                        if (metadataFilePath) {
+                            try {
+                                unlinkSync(metadataFilePath);
+                            }
+                            catch (cleanupError) {
+                                logger.error("Failed to cleanup metadata file", getErrorMeta(cleanupError));
+                            }
+                        }
+                    }
+                    catch (error) {
+                        logger.error("Error creating zip download", getErrorMeta(error));
+                        if (!res.headersSent) {
+                            res.statusCode = 500;
+                            res.setHeader("Content-Type", "application/json");
+                            res.end(JSON.stringify({ error: "Failed to create download" }));
+                        }
+                    }
+                })();
+            });
+            server.middlewares.use("/sb-set-file-contents", bodyParser.json({ strict: true }));
+            server.middlewares.use("/sb-set-file-contents", (req, res, next) => {
+                void (async () => {
+                    if (!isInitialized) {
+                        return next();
+                    }
+                    if (req.method !== "POST" && req.method !== "OPTIONS") {
+                        res.statusCode = 405;
+                        res.end("Method not allowed");
+                        return;
+                    }
+                    const requestOrigin = typeof req.headers.origin === "string"
+                        ? req.headers.origin
+                        : undefined;
+                    const isSameOrigin = !requestOrigin ||
+                        (() => {
+                            try {
+                                return new URL(requestOrigin).host === req.headers.host;
+                            }
+                            catch {
+                                return false;
+                            }
+                        })();
+                    if (!isSameOrigin) {
+                        logger.warn(`[sb-set-file-contents] rejected cross-origin request origin=${requestOrigin ?? ""} host=${req.headers.host ?? ""}`);
+                        res.statusCode = 403;
+                        res.end("Forbidden");
+                        return;
+                    }
+                    if (requestOrigin) {
+                        res.setHeader("Access-Control-Allow-Origin", requestOrigin);
+                        res.setHeader("Vary", "Origin");
+                    }
+                    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+                    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+                    if (req.method === "OPTIONS") {
+                        res.statusCode = 204;
+                        res.end();
+                        return;
+                    }
+                    try {
+                        const body = req.body;
+                        const files = body && Array.isArray(body.files) && body.files.length > 0
+                            ? body.files
+                            : body &&
+                                (body.path !== undefined || body.contents !== undefined)
+                                ? [{ path: body.path, contents: body.contents }]
+                                : [];
+                        if (!body ||
+                            files.length === 0 ||
+                            files.some((file) => typeof file.path !== "string" ||
+                                typeof file.contents !== "string")) {
+                            res.statusCode = 400;
+                            res.setHeader("Content-Type", "application/json");
+                            res.end(JSON.stringify({
+                                error: "Invalid request body. Expected { path: string, contents: string } or { files: Array<{ path: string, contents: string }> }",
+                            }));
+                            return;
+                        }
+                        for (const file of files) {
+                            await fileSyncManager.setFileContents(file.path, file.contents);
+                        }
+                        const syncResult = body.waitForSync && syncService
+                            ? await (async () => {
+                                // Fixture writes need the live-edit hash updated before the
+                                // test continues, but they should not create a user-visible
+                                // savepoint or invoke AI commit-message generation.
+                                // `asUserEdit` opts out: a test building version history
+                                // needs the write to land on a version. Writing the file
+                                // also emits `fileChanged`, whose own upload may open the
+                                // coalesced burst and name its source, so both paths must
+                                // name the same source to be deterministic.
+                                const source = body.asUserEdit
+                                    ? "fileChanged"
+                                    : "initialSync";
+                                await syncService.uploadDirectory(source);
+                                return syncService.uploadDirectoryNowIfNeeded(source);
+                            })()
+                            : undefined;
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(JSON.stringify({
+                            directoryHash: syncResult?.directoryHash,
+                            success: true,
+                        }));
+                    }
+                    catch (error) {
+                        logger.error("Error setting file contents", getErrorMeta(error));
+                        if (!res.headersSent) {
+                            res.statusCode = 500;
+                            res.setHeader("Content-Type", "application/json");
+                            res.end(JSON.stringify({
+                                error: error instanceof Error
+                                    ? error.message
+                                    : "Failed to set file contents",
+                            }));
+                        }
+                    }
+                })();
+            });
+            socketManager = createSocketManager(pluginParams.tracer);
+            const routerParseReporter = createRouterParseReporter({
+                aiService,
+                devServerStatus: pluginParams.devServerStatus,
+                logger,
+                rootDir: config.root,
+                socketManager,
+            });
+            registerSnapshotRoutes(server, {
+                getIsInitialized: () => isInitialized,
+                appRootDir,
+                snapshotManager: pluginParams.snapshotManager,
+                socketManager,
+                logger,
+                getAvailableIntegrationIds: aiService
+                    ? () => aiService.getAvailableIntegrationIds()
+                    : undefined,
+                isSessionManagementEnabled: aiService?.isSessionManagementEnabled ?? false,
+            });
+            registerMigrationRoutes(server, {
+                appRootDir,
+                checkAuthorization: pluginParams.checkAuthorization,
+                getIsInitialized: () => isInitialized,
                 syncService,
+                logger,
+                viteRoot: config.root,
+                inPlaceTemplateRestartEnabled: pluginParams.features?.inPlaceTemplateRestartEnabled ?? false,
+                getAiService: () => aiService,
+                prepareInPlaceRestart: pluginParams.prepareInPlaceRestart,
+            });
+            registerPolicyGateRoutes(server, {
                 aiService,
-                tracer: pluginParams.tracer,
-                path: "/sb-updates",
+                superblocksBaseUrl: pluginParams.superblocksBaseUrl,
+            });
+            await tracer.startActiveSpan("socketServerStart", async (socketSpan) => {
+                try {
+                    socketManager.startSocketServer({
+                        server: httpServer,
+                        fileSyncManager,
+                        lockService,
+                        syncService,
+                        aiService,
+                        gitService,
+                        gitBootstrapAuthFailed: pluginParams.gitBootstrapAuthFailed,
+                        gitBootstrapFailed: pluginParams.gitBootstrapFailed,
+                        activateGitService,
+                        refreshGitCredentials,
+                        checkAuthorization: pluginParams.checkAuthorization,
+                        tracer: pluginParams.tracer,
+                        path: "/sb-updates",
+                        gitOperationLock,
+                        superblocksBaseUrl: pluginParams.superblocksBaseUrl,
+                    });
+                }
+                finally {
+                    socketSpan.end();
+                }
             });
             socketManager.removeAllListeners();
             const sendError = (errorEvent) => {
-                socketManager.callEditorClients((socket) => socket.call.error(errorEvent));
+                logger.error("Unhandled server error", getErrorMeta(errorEvent));
+                if (!shouldForwardServerError({
+                    errorType: errorEvent.type,
+                    isAiBusy: aiService?.isBusy() ?? false,
+                })) {
+                    return;
+                }
+                void socketManager.callEditorClients((socket) => socket.call.error(errorEvent));
+            };
+            const isExpectedRejection = (reason) => {
+                const code = reason instanceof Error
+                    ? reason.code
+                    : typeof reason === "object" && reason !== null
+                        ? reason.code
+                        : undefined;
+                // code 8 = connection closed, code 10 = post-close request
+                // These are expected when users close browser tabs or navigate away
+                return code === 8 || code === 10;
             };
             // Add some process error handling to ensure to notify the user of
             // any uncaught exceptions or rejections
             process.on("uncaughtException", (error) => {
                 sendError(makeServerError(error));
-                process.exit(1);
             });
             process.on("unhandledRejection", (reason) => {
-                logger.error("Unhandled rejection", reason);
+                if (isExpectedRejection(reason)) {
+                    logger.warn(`Expected unhandled rejection: ${JSON.stringify(reason)}`);
+                    return;
+                }
+                const reasonStr = JSON.stringify(reason);
+                logger.error(`Unhandled rejection: ${reasonStr}`);
                 const error = reason instanceof Error
                     ? reason
                     : typeof reason === "object"
                         ? new Error(JSON.stringify(reason))
                         : new Error(String(reason));
                 sendError(makeServerError(error));
-                process.exit(1);
             });
             syncService?.removeListener?.("error", sendError);
             syncService?.on?.("error", sendError);
             lockService?.removeListener?.("error", sendError);
             lockService?.on?.("error", sendError);
-            const extractApiParamsAndDependencies = (socket) => {
-                const allApis = fileSyncManager.getApiFiles();
-                const allApiNames = Object.values(allApis).map(({ api }) => api.apiPb.metadata.name);
-                const apiDependencyMap = {};
-                Promise.all([
-                    ...Object.values(allApis).map(async ({ api }) => {
-                        const bindings = await extractIdentifierPathsFromApi(api);
-                        const allIdentifiers = bindings.flatMap((binding) => binding.bindings);
-                        const apiDependencies = extractApiDependencies(allApiNames, bindings);
-                        apiDependencyMap[api.apiPb.metadata.name] = apiDependencies;
-                        return socket.call.updateApiParams({
-                            apiName: api.apiPb.metadata.name,
-                            params: allIdentifiers,
-                            apiDependencies,
-                        });
-                    }),
-                ]).then(() => {
-                    socketManager.callEditorClients((editorClientSocket) => {
-                        return editorClientSocket.call.setApiDependencies({
-                            apiDependencies: apiDependencyMap,
-                        });
+            syncService?.on?.("degradedModeChange", (degradedMode) => {
+                void (async () => {
+                    void socketManager.callEditorClients((socket) => {
+                        return socket.call.setDegradedMode({ degradedMode });
                     });
-                });
-            };
-            socketManager.on("connect:library", async (socket) => {
-                const allApis = fileSyncManager.getApiFiles();
-                socket.call
-                    .setApiDefinitions(allApis)
-                    .then(() => extractApiParamsAndDependencies(socket));
-                const tsFilePaths = fileSyncManager.getTsFilePaths();
-                return socket.call.updateLocalBindingEntities({
-                    entities: Array.from(new Set(tsFilePaths.flatMap((file) => fileSyncManager.getLocalBindingEntities(file)))),
-                });
+                })();
             });
-            const sendRootUpdate = async (path, sync = false) => {
-                const roots = fileSyncManager.getPageRoots(path);
-                const scope = fileSyncManager.getScope(path);
-                if (!roots || !scope) {
-                    logger?.error(`sendRootUpdate: no roots or scope ${path}`);
-                    return;
-                }
-                const { scopeId } = scope;
-                socketManager.callEditorClients((socket) => {
-                    return socket.call.updateScope({
-                        scopeId,
-                        updates: { roots },
-                    });
+            // Forward Clark logs to browser DevTools
+            if (aiService) {
+                unregisterLogForwarder = createClarkLogForwarder({
+                    getEditorClients: () => socketManager.getEditorClients(),
+                    getClarkState: () => aiService.clarkState,
                 });
-                if (sync && syncService) {
-                    await syncService.uploadDirectory();
-                }
+            }
+            const sendFileUpdate = createLatestAppScopePublisher({
+                publishAppScope: (appScope) => {
+                    socketManager.reportEditorHasDefaultStructure(getAppScopeDefaultStructure(appScope));
+                    void socketManager.callEditorClients((socket) => socket.call.resetScope({ appScope }));
+                },
+                readAppScope: () => getAppScope(fileSyncManager, routerParseReporter.report),
+            });
+            const toApiV3Dto = (api) => {
+                const { apiPb } = api;
+                return {
+                    id: apiPb.metadata.id,
+                    name: apiPb.metadata.name,
+                    scopeId: apiPb.trigger?.application?.id,
+                    applicationId: apiPb.trigger?.application?.id,
+                    pageId: apiPb.trigger?.application?.pageId,
+                    organizationId: apiPb.metadata?.organization,
+                    updated: apiPb.metadata?.timestamps?.updated
+                        ? new Date(apiPb.metadata?.timestamps?.updated)
+                        : undefined,
+                    triggerType: ApiTriggerType.UI,
+                    apiPb: apiPb,
+                };
             };
-            const sendMultiRootUpdate = async (paths, sync = false) => {
-                paths.forEach((path) => {
-                    sendRootUpdate(path);
+            // configured twice otherwise, always remove all listeners
+            fileSyncManager.removeAllListeners();
+            fileSyncManager.on("error", sendError);
+            const parseAndPublishRouter = async (routerFilePath) => {
+                let routerParseDiagnostic;
+                const routes = await parseRouterFile(routerFilePath, config.root, (diagnostic) => {
+                    routerParseDiagnostic = diagnostic;
                 });
-                if (sync && syncService) {
-                    await syncService.uploadDirectory();
-                }
+                logger.info(`Routes updated: ${routes.length} routes found`);
+                await routerParseReporter.report(routerParseDiagnostic);
+                return routes;
             };
-            const sendRootReset = async (sync = false) => {
-                const appScope = await getAppScope(fileSyncManager);
-                socketManager.callEditorClients((socket) => {
-                    return socket.call.resetScope({
-                        appScope,
-                    });
+            fileSyncManager.on("routerChange", (routerFilePath) => {
+                void (async () => {
+                    try {
+                        logger.info("Router file changed, re-parsing routes");
+                        await parseAndPublishRouter(routerFilePath);
+                        void sendFileUpdate();
+                        await syncService?.uploadDirectory(aiService?.isBusy() ? "ai:generate:interim" : "fileChanged");
+                    }
+                    catch (e) {
+                        logger.error("Error parsing router file", getErrorMeta(e));
+                    }
+                })();
+            });
+            if (fileSyncManager.routerFilePath) {
+                void parseAndPublishRouter(fileSyncManager.routerFilePath).catch((e) => {
+                    logger.error("Error parsing router file on startup", getErrorMeta(e));
                 });
-                if (sync && syncService) {
-                    await syncService.uploadDirectory();
-                }
-            };
-            // TODO: @damian - Check if we need both sendFileUpdate and sendEntityUpdate
-            const sendFileUpdate = (path) => {
-                const scope = fileSyncManager.getScope(path);
-                const entities = scope?.entities ?? {};
-                const scopeId = scope?.scopeId ?? "";
-                const roots = fileSyncManager.getPageRoots(path);
-                socketManager.callEditorClients((socket) => socket.call.updateScope({
-                    scopeId,
-                    updates: { entities, roots: roots ?? undefined },
-                }));
-            };
-            const sendDeleteComponentsUpdate = async (path, sourceIds) => {
-                const scope = fileSyncManager.getScope(path);
-                if (!scope) {
-                    console.error("No scope found for", path);
-                    return;
-                }
-                await sendRootUpdate(path);
-                socketManager.callLibraryClients((socket) => {
-                    return socket.call.deleteEntities(sourceIds.map((sourceId) => ({
-                        scopeId: scope.scopeId,
-                        sourceId,
-                    })));
+            }
+            if (aiService) {
+                fileSyncManager.on("fileChanged", debounce((filePath) => {
+                    void (async () => {
+                        const appScope = await getAppScope(fileSyncManager, routerParseReporter.report);
+                        void aiService.appContext.handleAppScopeReset(appScope);
+                        if (!aiService.isBusy()) {
+                            void aiService.handleUserChange({
+                                type: "fileChanged",
+                                filePath,
+                            });
+                        }
+                    })();
+                }, 1000));
+                fileSyncManager.on("addPage", (path) => {
+                    void (async () => {
+                        const appScope = await getAppScope(fileSyncManager, routerParseReporter.report);
+                        void aiService.appContext.handleAppScopeReset(appScope);
+                        if (!aiService.isBusy()) {
+                            void aiService.handleUserChange({ type: "addPage", path });
+                        }
+                    })();
                 });
-            };
-            const sendDeleteEntityUpdate = async (path, entityName) => {
-                const scope = fileSyncManager.getScope(path);
-                if (!scope) {
-                    console.error("No scope found for", path);
-                    return;
-                }
-                const { scopeId } = scope;
-                await sendEntityUpdate(path);
-                socketManager.callLibraryClients((socket) => {
-                    return socket.call.deleteEntities([
-                        {
-                            scopeId,
-                            entityName,
-                        },
-                    ]);
+                fileSyncManager.on("deletePage", (path) => {
+                    void (async () => {
+                        const appScope = await getAppScope(fileSyncManager, routerParseReporter.report);
+                        void aiService.appContext.handleAppScopeReset(appScope);
+                        if (!aiService.isBusy()) {
+                            void aiService.handleUserChange({ type: "deletePage", path });
+                        }
+                    })();
                 });
-            };
-            const sendEntityUpdate = (path) => {
-                const scope = fileSyncManager.getScope(path);
-                if (!scope) {
-                    console.error("No scope found for", path);
-                    return;
+            }
+            const debouncedFileUpdate = (filePath) => {
+                let fn = debouncedFileUpdateHandlers.get(filePath);
+                if (!fn) {
+                    fn = debounce(() => {
+                        void sendFileUpdate();
+                    }, 100, { leading: true, trailing: true, maxWait: 500 });
                 }
-                const { entities, scopeId } = scope;
-                socketManager.callEditorClients((socket) => socket.call.updateScope({
-                    scopeId,
-                    updates: {
-                        entities,
-                    },
-                }));
+                debouncedFileUpdateHandlers.set(filePath, fn);
+                fn();
             };
-            // configured twice otherwise, always remove all listeners
-            fileSyncManager.removeAllListeners();
-            fileSyncManager.on("error", sendError);
-            fileSyncManager.on("reparent", sendRootUpdate);
-            fileSyncManager.on("batchUpdate", sendMultiRootUpdate);
-            fileSyncManager.on("createComponent", sendRootUpdate);
-            fileSyncManager.on("deleteComponents", sendDeleteComponentsUpdate);
-            fileSyncManager.on("addEntity", sendEntityUpdate);
-            fileSyncManager.on("updateEntity", sendEntityUpdate);
-            fileSyncManager.on("deleteEntity", sendDeleteEntityUpdate);
-            fileSyncManager.on("renameComponent", sendFileUpdate);
-            fileSyncManager.on("renameEntity", sendFileUpdate);
-            fileSyncManager.on("addPage", sendRootUpdate);
-            fileSyncManager.on("renamePage", () => sendRootReset(true));
-            fileSyncManager.on("fileChanged", async (path, _content, isNonVisualEdit) => {
-                socketManager.callLibraryClients((socket) => {
-                    return socket.call.updateLocalBindingEntities({
-                        entities: fileSyncManager.getLocalBindingEntities(path),
-                    });
-                });
-                if (isNonVisualEdit) {
-                    sendFileUpdate(path);
-                    socketManager.callLibraryClients((socket) => {
-                        return socket.call.nonVisualEdit();
-                    });
-                }
-                if (syncService) {
-                    await syncService.uploadDirectory();
-                }
+            fileSyncManager.on("fileChanged", (path, _content) => {
+                void (async () => {
+                    void debouncedFileUpdate(path);
+                    if (syncService) {
+                        // Use different source during AI generation to prevent individual draft commits
+                        const source = aiService && aiService.isBusy()
+                            ? "ai:generate:interim"
+                            : "fileChanged";
+                        // Eagerly sync server file changes so ensureFilesSynced() is a
+                        // no-op on the SDK API execution path (avoids 10s debounce wait).
+                        // Uses `source` so AI-generation edits sync without creating commits.
+                        // Debounced at 750ms to coalesce Clark's burst writes (e.g. API
+                        // file + index.ts barrel, typically 1-4s apart) into one upload.
+                        // Scheduled before the `uploadDirectory` await so the most-recent
+                        // event's `source` wins even if prior IIFEs complete out of order.
+                        if (normalizePath(path).startsWith(serverPrefix)) {
+                            clearTimeout(eagerServerSyncTimer);
+                            eagerServerSyncTimer = setTimeout(() => {
+                                syncService.uploadDirectoryNowIfNeeded(source).catch((err) => {
+                                    logger.error("Eager server file sync failed", getErrorMeta(err));
+                                });
+                            }, 750);
+                        }
+                        await syncService.uploadDirectory(source);
+                    }
+                })();
             });
-            fileSyncManager.on("apiUpdate", async (payload) => {
-                socketManager.callLibraryClients(async (socket) => {
-                    Promise.all([
-                        socket.call.updateApi(payload),
-                        extractApiParamsAndDependencies(socket),
-                    ]);
-                });
-                if (payload.api.pageName) {
-                    const pagePath = getPageFilePath(config.root, payload.api.pageName);
-                    sendEntityUpdate(pagePath);
-                }
-                if (syncService) {
-                    await syncService.uploadDirectory();
-                }
+            fileSyncManager.on("apiUpdate", (payload) => {
+                void (async () => {
+                    void socketManager.callEditorClients(async (socket) => {
+                        if (payload.api.apiPb?.metadata?.id) {
+                            const inputs = await extractInputsFromApi(payload.api);
+                            void socket.call
+                                .updateApiInputs({
+                                apiId: payload.api.apiPb.metadata.id,
+                                inputs,
+                            })
+                                .catch(() => {
+                                logger.warn(`Failed to update API inputs on apiUpdate event for ${payload.api.apiPb.metadata.id} (connection closed)`);
+                            });
+                        }
+                        return socket.call.manualUpdateApi({
+                            api: {
+                                ...payload.api,
+                                scopeId: payload.scopeId ?? "",
+                            },
+                        });
+                    });
+                    if (syncService) {
+                        await syncService.uploadDirectory("apiUpdate");
+                    }
+                    if (aiService) {
+                        void aiService.handleApiUpdate({
+                            author: "clark",
+                            payload: toApiV3Dto(payload.api),
+                        });
+                    }
+                })();
             });
-            fileSyncManager.on("apiManualUpdate", async (payload, sendScopeUpdates = false) => {
-                socketManager.callLibraryClients(async (socket) => {
-                    Promise.all([
-                        socket.call.updateApi(payload),
-                        extractApiParamsAndDependencies(socket),
-                    ]);
-                });
-                if (sendScopeUpdates) {
-                    sendFileUpdate(getPageFilePath(config.root, payload.api.pageName));
-                }
-                if (syncService) {
-                    await syncService.uploadDirectory();
-                }
-                socketManager.callEditorClients((socket) => {
-                    return socket.call.manualUpdateApi({
-                        api: payload.api,
+            fileSyncManager.on("apiManualUpdate", (payload, sendScopeUpdates = false) => {
+                void (async () => {
+                    if (sendScopeUpdates) {
+                        void sendFileUpdate();
+                    }
+                    if (syncService) {
+                        // Use different source during AI generation to prevent individual draft commits
+                        const source = aiService && aiService.isBusy()
+                            ? "ai:generate:interim"
+                            : "apiManualUpdate";
+                        void syncService.uploadDirectory(source);
+                    }
+                    void socketManager.callEditorClients(async (socket) => {
+                        const inputs = await extractInputsFromApi(payload.api);
+                        void socket.call
+                            .updateApiInputs({
+                            apiId: payload.api.apiPb.metadata.id,
+                            inputs,
+                        })
+                            .catch(() => {
+                            logger.warn(`Failed to update API inputs on file change for ${payload.api.apiPb.metadata.id} (connection closed)`);
+                        });
+                        return socket.call.manualUpdateApi({
+                            api: {
+                                ...payload.api,
+                                scopeId: payload.scopeId ?? "",
+                            },
+                        });
                     });
-                });
+                    if (aiService) {
+                        void aiService.handleApiUpdate({
+                            author: "user",
+                            payload: toApiV3Dto(payload.api),
+                        });
+                    }
+                })();
             });
             if (syncService) {
-                syncService.on("synchronizationStatusChange", async (status, generationNumber) => {
-                    socketManager.callEditorClients(async (socket) => {
-                        try {
-                            await socket.call.syncStatus({ status, generationNumber });
-                        }
-                        catch (err) {
-                            logger.error("Failed to send syncStatus", getErrorMeta(err));
-                        }
-                    });
+                syncService.on("synchronizationStatusChange", (status, generationNumber, source) => {
+                    void (async () => {
+                        // Gateway peers too: a headless turn checkpoints its own work and
+                        // has to wait for a pending sync the same way the UI does.
+                        void socketManager.callEditorAndGatewayClients(async (socket) => {
+                            try {
+                                await socket.call.syncStatus({
+                                    generationNumber,
+                                    source,
+                                    status,
+                                });
+                            }
+                            catch (err) {
+                                // Failed to send is expected when clients disconnect - log as WARNING
+                                logger.warn("Failed to send syncStatus", getErrorMeta(err));
+                            }
+                        });
+                    })();
                 });
             }
             if (lockService) {
                 lockService.on("statusChange", (status) => {
-                    if (status === LockServiceStatus.FAILED_TO_ACQUIRE_LOCK ||
-                        status === LockServiceStatus.RELEASING) {
-                        socketManager.callEditorClients(async (socket) => {
+                    if (status === LockServiceStatus.RELEASING ||
+                        status === LockServiceStatus.LOCK_INVALID) {
+                        void socketManager.callEditorClients(async (socket) => {
                             try {
                                 await socket.call.releasingLock();
                             }
                             catch (err) {
-                                logger.error("Failed to send releasingLock", getErrorMeta(err));
+                                // Failed to send is expected when clients disconnect - log as WARNING
+                                logger.warn("Failed to send releasingLock", getErrorMeta(err));
                             }
                         });
                     }
-                    else if (status === LockServiceStatus.LOCK_INVALID) {
-                        sendError(makeServerError(new Error("Error renewing connection to editing session. Please refresh the page.")));
-                    }
-                    else if (status === LockServiceStatus.LOCK_RELEASED) {
-                        sendError(makeServerError(new Error("Editing session is no longer active. Please refresh the page or move to local mode.")));
-                    }
+                });
+                lockService.on("closedByServer", (data) => {
+                    void socketManager.callEditorClients(async (socket) => {
+                        try {
+                            await socket.call.closedByServer(data);
+                        }
+                        catch (err) {
+                            // Failed to send is expected when clients disconnect - log as WARNING
+                            logger.warn("Failed to send closedByServer", getErrorMeta(err));
+                        }
+                    });
                 });
             }
-            fileSyncManager.on("routesChanged", () => {
-                const rootId = normalizePath(path.join(config.root, "root.tsx"));
-                const module = server.moduleGraph.getModuleById(rootId);
-                if (module) {
-                    server.reloadModule(module);
-                }
+            fileSyncManager.on("apiDelete", (payload) => {
+                void (async () => {
+                    if (syncService) {
+                        await syncService.uploadDirectory("apiDelete");
+                    }
+                    if (aiService) {
+                        for (const api of payload.apis) {
+                            void aiService.appContext.handleApiDelete(api.apiName);
+                            if (!aiService.isBusy()) {
+                                void aiService.handleUserChange({
+                                    type: "apiDelete",
+                                    apiName: api.apiName,
+                                });
+                            }
+                        }
+                    }
+                })();
             });
-            fileSyncManager.on("apiDelete", async (payload) => {
-                socketManager.callLibraryClients(async (socket) => {
-                    Promise.all([
-                        socket.call.deleteApis(payload.apis.map((api) => ({
-                            apiName: api.apiName,
-                            scopeId: api.scopeId,
-                        }))),
-                        extractApiParamsAndDependencies(socket),
-                    ]);
-                    // All APIs should belong to the same page but to be consistant we iterate over all APIs
-                    const pageNames = new Set(payload.apis.map((api) => api.pageName));
-                    if (pageNames.size > 0) {
-                        pageNames.forEach((pageName) => {
-                            const pagePath = getPageFilePath(config.root, pageName);
-                            sendEntityUpdate(pagePath);
+            fileSyncManager.on("apiManualDelete", (payload) => {
+                void (async () => {
+                    void socketManager.callEditorClients((socket) => {
+                        return socket.call.manualDeleteApi({
+                            id: payload.api.id,
                         });
-                    }
+                    });
                     if (syncService) {
-                        await syncService.uploadDirectory();
+                        // Use different source during AI generation to prevent individual draft commits
+                        const source = aiService && aiService.isBusy()
+                            ? "ai:generate:interim"
+                            : "apiManualDelete";
+                        await syncService.uploadDirectory(source);
                     }
-                });
-            });
-            fileSyncManager.on("apiManualDelete", async (payload) => {
-                socketManager.callLibraryClients(async (socket) => {
-                    Promise.all([
-                        socket.call.deleteApis([
-                            {
+                    if (aiService) {
+                        void aiService.appContext.handleApiDelete(payload.api.apiName);
+                        if (!aiService.isBusy()) {
+                            void aiService.handleUserChange({
+                                type: "apiDelete",
                                 apiName: payload.api.apiName,
-                                scopeId: payload.api.scopeId,
-                            },
-                        ]),
-                        extractApiParamsAndDependencies(socket),
-                    ]);
-                    const pagePath = getPageFilePath(config.root, payload.api.pageName);
-                    sendEntityUpdate(pagePath);
-                });
-                socketManager.callEditorClients((socket) => {
-                    return socket.call.manualDeleteApi({
-                        id: payload.api.id,
-                    });
+                            });
+                        }
+                    }
+                })();
+            });
+            fileSyncManager.on("appFactsChanged", () => {
+                void socketManager.callEditorClients((socket) => {
+                    return socket.call.appFactsChanged();
                 });
-                if (syncService) {
-                    await syncService.uploadDirectory();
-                }
             });
             if (syncService && aiService) {
-                socketManager.on("connect:editor", async (socket) => {
-                    const hasDraft = await syncService.hasLocalDraftChanges();
-                    return socket.call.aiSetDraftState({ hasDraft });
+                socketManager.on("connect:editor", (socket, peerId, liveness) => {
+                    void (async () => {
+                        // Rebind StablePeer's inner on every connect so queued calls flush.
+                        aiService.handleUserConnected(socket, peerId, liveness);
+                        const allApis = fileSyncManager.getApiFiles();
+                        for (const api of Object.values(allApis)) {
+                            if (api.api.apiPb?.metadata?.id) {
+                                const inputs = await extractInputsFromApi(api.api);
+                                void socket.call
+                                    .updateApiInputs({
+                                    apiId: api.api.apiPb.metadata.id,
+                                    inputs,
+                                })
+                                    .catch(() => {
+                                    logger.warn(`Failed to update API inputs on client connection for ${api.api.apiPb.metadata.id} (connection closed)`);
+                                });
+                            }
+                        }
+                        // Send any pending file transform error
+                        if (pendingFileTransformError) {
+                            const { filePath, error } = pendingFileTransformError;
+                            const fileTransformError = makeServerError(error, {
+                                critical: false,
+                            });
+                            fileTransformError.message = `File transformation error in ${filePath.replace(/^.*\/pages\//, "pages/")}: ${error.message}`;
+                            await socket.call.error(fileTransformError);
+                            pendingFileTransformError = null;
+                        }
+                        const hasDraft = await syncService.hasLocalDraftChanges();
+                        // Reconcile the server's draft flag with the marker state on the
+                        // PVC, which is the source of truth. A session that ended uncleanly
+                        // (pod death, OOM, crash) never sent draftState.set(false), so
+                        // ApplicationLiveEdit.isDraft can be stuck true while no draft
+                        // actually exists; that blocks every git-sync commit with "Cannot
+                        // commit in draft mode" indefinitely (APPS-4670). Reporting the
+                        // freshly-derived state on reconnect self-heals the stuck flag the
+                        // moment the user reopens the editor: markers gone -> report false
+                        // -> commits unblock; markers present -> report true -> the genuine
+                        // draft still blocks until the user accepts/rejects it.
+                        //
+                        // Skip a false report while a generation is in flight: a reconnect
+                        // can briefly observe no markers just before generation writes them,
+                        // and reporting false over a real in-progress draft would be wrong.
+                        // Reporting true is always safe. We await so reopen-recovery
+                        // completes deterministically before the editor proceeds.
+                        if (shouldReportDraftStateOnConnect(hasDraft, aiService.isBusy())) {
+                            await syncService.reportDraftStateToServer(hasDraft);
+                        }
+                        else {
+                            logger.info("[file-sync] Skipping connect-time draft=false reconciliation while AI generation is busy", {
+                                applicationId: syncService.applicationId,
+                                branchName: syncService.branchName,
+                            });
+                        }
+                        const appScope = await getAppScope(fileSyncManager, routerParseReporter.report);
+                        await socket.call.resetScope({ appScope });
+                        // Hand this editor the active router parse error. The parse that
+                        // found it may have finished before this socket registered, and
+                        // the readiness response may have been sent before the parse, so
+                        // neither of those paths reaches an editor that connects in
+                        // between. The reporter deduplicates repeat parses of the same
+                        // failure, so replaying here is the only thing that closes that
+                        // window. Nothing is sent when the router parses cleanly.
+                        const activeRouterParseError = routerParseReporter.getCurrentError();
+                        if (activeRouterParseError) {
+                            await socket.call.routerParseError(activeRouterParseError);
+                        }
+                        return socket.call.aiSetDraftState({ hasDraft });
+                    })();
+                });
+                socketManager.on("disconnect:editor", (peerId, socket, liveness) => {
+                    aiService.handleUserDisconnected(peerId, socketManager.getSurvivingEditorClient(socket), liveness);
+                });
+                aiService.setOnGitOperationComplete(() => {
+                    void socketManager.callEditorClients((socket) => socket.call.requestGitRefresh());
                 });
                 syncService.on("draftStateChanged", (hasDraft) => {
-                    socketManager.callEditorClients((socket) => {
+                    logger.info("[file-sync] draftStateChanged event", { hasDraft });
+                    if (hasDraft) {
+                        hasHadAnyDrafts = true;
+                        logger.debug("hasHadAnyDrafts set to true");
+                    }
+                    void socketManager.callEditorClients((socket) => {
                         return socket.call.aiSetDraftState({ hasDraft });
                     });
                 });
-                aiService.on("generationCompleted", (hasDraft) => {
-                    if (hasDraft) {
-                        // we have been deferring hot updates; trigger a reload to render the ai draft
-                        logger.info("Requesting full reload to render AI draft");
-                        server.ws.send({
-                            type: "full-reload",
-                        });
-                    }
+                // Keep the Bucketeer copy of the conversation fresh during a long
+                // generation; see wireContextFlush for the flush rules.
+                contextFlushScheduler = wireContextFlush({
+                    aiService,
+                    syncService,
+                    logger,
+                    debounceMs: CONTEXT_FLUSH_DEBOUNCE_MS,
+                    maxWaitMs: CONTEXT_FLUSH_MAX_WAIT_MS,
                 });
-                // capture vite error logging
-                const originalErrorLogger = config.logger.error;
-                config.logger.error = (...args) => {
-                    if (aiService.isBusy()) {
-                        const [message, options] = args;
-                        let error;
-                        if (options?.error instanceof Error) {
-                            error = options.error;
-                        }
-                        else if (typeof options?.error?.stack === "string") {
-                            // it's a RollupError
-                            error = new Error(options.error.stack);
-                        }
-                        else {
-                            error = new Error(message);
+                aiService.on("generationStarted", (generationId) => {
+                    generationFreshnessTracker.markStarted(generationId);
+                    void (async () => {
+                        await syncService.uploadDirectory("ai:generate:pre");
+                        await syncService.uploadDirectoryNowIfNeeded("ai:generate:pre");
+                    })();
+                });
+                aiService.on("generationCompleted", (producedDraft, generationId) => {
+                    void (async () => {
+                        const isLatestCompletedGeneration = () => generationFreshnessTracker.isLatest(generationId);
+                        const result = await handleGenerationCompletedFileSync({
+                            aiService,
+                            contextFlushScheduler,
+                            producedDraft,
+                            hasHadAnyDrafts,
+                            isFirstContentfulGeneration,
+                            isLatestGeneration: isLatestCompletedGeneration,
+                            logger,
+                            server,
+                            syncService,
+                        });
+                        if (isLatestCompletedGeneration()) {
+                            isFirstContentfulGeneration = result.isFirstContentfulGeneration;
                         }
-                        aiService.handleBuildSystemError(error);
-                    }
-                    return originalErrorLogger.apply(config.logger, args);
-                };
+                    })();
+                });
+                aiService.on("generationFailed", () => {
+                    logger.error("Generation failed");
+                });
+                const appScope = await sendFileUpdate();
+                if (appScope) {
+                    void aiService.appContext.handleAppScopeReset(appScope);
+                }
             }
             const triggerRegisteredComponentUpdate = () => {
                 const module = server.moduleGraph.getModuleById(resolvedVirtualRegisteredComponentsId);
                 if (module) {
-                    server.reloadModule(module);
+                    server.moduleGraph.invalidateModule(module, new Set(), Date.now(), true);
+                    void server.reloadModule(module);
                 }
             };
             componentsManager.on("error", sendError);
             componentsManager.on("registeredComponentAdded", triggerRegisteredComponentUpdate);
             componentsManager.on("registeredComponentRemoved", (name) => {
                 triggerRegisteredComponentUpdate();
-                socketManager.callLibraryClients((socket) => {
+                void socketManager.callLibraryClients((socket) => {
                     return socket.call.removeRegisteredComponent({
                         name,
                     });
                 });
             });
             componentsManager.on("registeredComponentChanged", (name, oldName) => {
-                triggerRegisteredComponentUpdate();
-                if (oldName) {
-                    socketManager.callLibraryClients(async (socket) => {
-                        await socket.call.renameRegisteredComponent({
-                            name,
-                            oldName,
+                void (async () => {
+                    triggerRegisteredComponentUpdate();
+                    if (oldName) {
+                        void socketManager.callLibraryClients(async (socket) => {
+                            await socket.call.renameRegisteredComponent({
+                                name,
+                                oldName,
+                            });
                         });
-                    });
-                }
+                    }
+                })();
             });
         },
         async transform(code, id) {
+            if (id.includes("/node_modules/") || id.endsWith(".d.ts")) {
+                return;
+            }
             const relativePath = path.relative(config.root, id);
             if (!this.meta.watchMode)
                 return;
-            if (relativePath === "root.tsx") {
-                const source = generateRootSource(code, fileSyncManager);
-                return {
-                    code: /*js*/ stripIndent `
-            import "${virtualRegisteredComponentsId}";
-
-            ${source}
-          `,
-                    map: null,
-                };
-            }
-            else if (id.endsWith(".tsx") &&
-                !id.includes(`${getLegacyComponentsFolder()}/`)) {
+            // Source-id rewrite is .tsx only. Leftover Superblocks scope.ts and
+            // user *-scope.ts must not hit getFileWithIds: the tracker is seeded
+            // from .tsx at init, so a miss throws and hangs the iframe.
+            if (id.endsWith(".tsx")) {
                 try {
-                    if (!fileSyncManager.readFile(id)) {
+                    const normalizedId = normalizePath(id);
+                    if (!fileSyncManager.readFile(normalizedId)) {
                         return { code, map: null };
                     }
-                    const fileContents = await fileSyncManager.getFileWithIds(id);
+                    const fileContents = await fileSyncManager.getFileWithIds(normalizedId);
                     if (!fileContents) {
                         throw new Error("File not found in file sync manager " + id);
                     }
+                    if (id === fileSyncManager.routerFilePath) {
+                        return;
+                    }
+                    if (componentsManager.isCustomComponentFile(normalizedId)) {
+                        return {
+                            code: fileContents,
+                            map: null,
+                        };
+                    }
+                    const isComponentFile = id.endsWith(".tsx") ||
+                        id.endsWith(".jsx") ||
+                        id.endsWith(".ts") ||
+                        id.endsWith(".js");
+                    if (isComponentFile && componentsManager.isInComponentDirectory(id)) {
+                        return {
+                            code: fileContents,
+                            map: null,
+                        };
+                    }
+                    if (isPageFilePath(id)) {
+                        // Clear pending transform error for this file since transform succeeded
+                        if (pendingFileTransformError?.filePath === relativePath &&
+                            aiService) {
+                            pendingFileTransformError = null;
+                            aiService.handleClearBuildSystemErrors();
+                        }
+                        return {
+                            code: `import "${virtualRegisteredComponentsId}";\n\n${fileContents}`,
+                            map: null,
+                        };
+                    }
+                    // Clear pending transform error for this file since transform succeeded
+                    if (pendingFileTransformError?.filePath === relativePath &&
+                        aiService) {
+                        pendingFileTransformError = null;
+                        aiService.handleClearBuildSystemErrors();
+                    }
                     return {
                         code: fileContents,
                         map: null,
                     };
                 }
                 catch (e) {
+                    if (aiService) {
+                        const error = e instanceof Error ? e : new Error(String(e));
+                        getLogger().info("Sending transform error to UI for file: " + relativePath);
+                        addFileTransformError(relativePath, error);
+                        // Add transform error as build system error
+                        aiService.handleBuildSystemError(error, "transform");
+                    }
                     logger.error("Error transforming file", getErrorMeta(e));
                 }
             }
-            else if (id.endsWith(SCOPE_FILE)) {
-                const fileContents = await fileSyncManager.getFileWithIds(id);
-                if (!fileContents) {
-                    throw new Error("File not found in file sync manager " + id);
-                }
-                return {
-                    code: fileContents,
-                    map: null,
-                };
-            }
             return {
                 code,
                 map: null,
@@ -575,7 +1357,8 @@ export const fileSyncVitePlugin = (pluginParams, options) => {
             if (id === virtualLegacyId && isCustomBuildEnabled()) {
                 return resolvedVirtualLegacyId;
             }
-            if (id === virtualRegisteredComponentsId) {
+            if (id === virtualRegisteredComponentsId ||
+                id === `/${virtualRegisteredComponentsId}`) {
                 return resolvedVirtualRegisteredComponentsId;
             }
         },
@@ -586,103 +1369,249 @@ export const fileSyncVitePlugin = (pluginParams, options) => {
             if (id === resolvedVirtualLegacyId) {
                 const customFolder = getLegacyComponentsFolder();
                 return /*js*/ `
-        import React from "react";
-        import ReactDOMLegacy from "/${customFolder}/dist/react-dom";
-        import ReactLegacy from "/${customFolder}/dist/react";
+          import React from "react";
+          import ReactDOMLegacy from "/${customFolder}/dist/react-dom";
+          import ReactLegacy from "/${customFolder}/dist/react";
 
-        export function wrapCustomComponent(CustomComponent) {
-          return React.forwardRef((props, ref) => {
-            const containerRef = React.useRef(null);
+          export function wrapCustomComponent(CustomComponent) {
+            return React.forwardRef((props, ref) => {
+              const containerRef = React.useRef(null);
 
-            React.useEffect(() => {
-              if (!containerRef.current) return;
+              React.useEffect(() => {
+                if (!containerRef.current) return;
 
-              const container = containerRef.current;
+                const container = containerRef.current;
 
-              ReactDOMLegacy.render(
-                ReactLegacy.createElement(CustomComponent, props),
-                container,
-              );
+                ReactDOMLegacy.render(
+                  ReactLegacy.createElement(CustomComponent, props),
+                  container,
+                );
 
-              return () => {
-                if (container) {
-                  ReactDOMLegacy.unmountComponentAtNode(container);
-                }
-              };
-            }, [props]);
-
-            return React.createElement("div", { ref: mergeRefs(containerRef, ref) });
-          });
-        }
+                return () => {
+                  if (container) {
+                    ReactDOMLegacy.unmountComponentAtNode(container);
+                  }
+                };
+              }, [props]);
 
-        function mergeRefs(...refs) {
-          return (value) => {
-            refs.forEach((ref) => {
-              if (typeof ref === "function") {
-                ref(value);
-              } else if (ref != null) {
-                ref.current = value;
-              }
+              return React.createElement("div", { ref: mergeRefs(containerRef, ref) });
             });
-          };
-        }
-      `;
+          }
+
+          function mergeRefs(...refs) {
+            return (value) => {
+              refs.forEach((ref) => {
+                if (typeof ref === "function") {
+                  ref(value);
+                } else if (ref != null) {
+                  ref.current = value;
+                }
+              });
+            };
+          }
+        `;
             }
             if (id === resolvedVirtualRegisteredComponentsId) {
-                const componentsManager = ComponentsManager.getInstance();
                 const paths = componentsManager.componentFilePaths;
                 return /*js*/ `
-        ${Array.from(paths)
-                    .map((filePath) => `
-              import "/${path.relative(config.root, filePath)}";
-            `)
+          ${Array.from(paths)
+                    .map((filePath) => {
+                    // Normalize to forward slashes for import paths (cross-platform compatibility)
+                    const relativePath = normalizePath(path.relative(config.root, filePath));
+                    return `
+                import "/${relativePath}";
+              `;
+                })
                     .join("\n")}
-        `;
+          `;
             }
         },
-        handleHotUpdate() {
-            // prevent hot updates if the AI service is busy generating a draft
-            if (aiService?.isBusy()) {
+        async handleHotUpdate(ctx) {
+            // Prevent full page reloads for API files - they're handled by the file system watcher
+            if (isApiFilePath(ctx.file)) {
+                return [];
+            }
+            // Prevent full page reloads for skill files (app facts) - they're internal metadata
+            if (isSkillFilePath(ctx.file)) {
                 return [];
             }
+            // if this HMR call reloads a file that an error was thrown about before,
+            // perform a full-reload and clear the error.
+            if (loggedViteErrors.length > 0) {
+                // Normalize paths for comparison only (Windows compatibility)
+                const normalizedCtxFile = normalizePath(ctx.file);
+                const errorIndex = loggedViteErrors.findIndex((error) => {
+                    return ("id" in error &&
+                        error.id &&
+                        normalizePath(error.id) === normalizedCtxFile);
+                });
+                if (errorIndex !== -1) {
+                    loggedViteErrors.splice(errorIndex, 1);
+                    logger.debug("Sending full-reload after error");
+                    void ctx.server.ws.send({ type: "full-reload" });
+                    return [];
+                }
+            }
+            if (ctx.file.startsWith(config.root)) {
+                if (aiService?.isBusy()) {
+                    // let's check to make sure the file being written has the correct imports
+                    // there is no real nice way to accomplish this server side, because we need the browser to resolve all of a
+                    // file's exports, which we cannot do in any sane way via vite. when an export cannot be resolved, the browser
+                    // will throw an SyntaxError, and we can catch that and send it back here to the server.
+                    // it's janky, but it works. this does mean we incur a slight performance hit, because in the happy path we are
+                    // going to do two import calls (this one, and the one normal vite HMR does), but it's a small price to pay for a
+                    // better gen experience.
+                    try {
+                        const libraryClient = socketManager.getAnyLibraryClient();
+                        if (!libraryClient) {
+                            return;
+                        }
+                        const module = ctx.server.moduleGraph.getModuleById(ctx.file);
+                        if (module) {
+                            const error = await libraryClient.call.clientImport({
+                                importPath: module.url,
+                            });
+                            if (error) {
+                                const err = new Error(error.message);
+                                err.stack = error.stack;
+                                err.name = error.name;
+                                void aiService.handleBuildSystemError(err, "import");
+                                logger.error(`Error loading import ${module.url}: ${error.message}`, getErrorMeta(err));
+                                return [];
+                            }
+                        }
+                    }
+                    catch {
+                        // we ignore these and just fall through to the normal import checking
+                    }
+                }
+                const source = await ctx.read();
+                const importsToCheck = getImports(source);
+                for (const importPath of importsToCheck) {
+                    try {
+                        let finalPath = await getFullImportPath(importPath);
+                        // super simple check to see if we are trying a relative import
+                        // we don't want to catch absolute imports (node modules, root imports)
+                        // because the client environment is resolving from the root of the app
+                        if (!finalPath &&
+                            (importPath.startsWith("./") || importPath.startsWith("../"))) {
+                            finalPath = path.join(path.dirname(ctx.file), importPath);
+                        }
+                        // important! we do this here intentionally instead of a ?? chain above because the resolver above,
+                        // should have already resolved the import path, but if it didn't we want to first check if we can do the relative path check
+                        // then do a final fallback to the original import path
+                        else if (!finalPath) {
+                            finalPath = importPath;
+                        }
+                        await ctx.server.environments?.client?.fetchModule(finalPath, ctx.file);
+                    }
+                    catch (error) {
+                        if (error instanceof Error &&
+                            "code" in error &&
+                            (error.code === "ERR_LOAD_URL" ||
+                                error.code === "ERR_MODULE_NOT_FOUND")) {
+                            // we don't need to send the same error multiple times
+                            if (lastImportErrorFiles.has(ctx.file)) {
+                                return [];
+                            }
+                            lastImportErrorFiles.add(ctx.file);
+                            if (aiService?.isBusy()) {
+                                // A path that does not resolve is our own bad import, not a
+                                // downstream symptom, so it is not tagged `import`.
+                                void aiService.handleBuildSystemError(error, "resolve");
+                                return [];
+                            }
+                            else {
+                                // Rethrow as ImportError so Vite's error overlay can handle it
+                                // This will trigger vite:error events that the vanilla overlay listens to
+                                throw new ImportError(error.message, importPath);
+                            }
+                        }
+                    }
+                }
+            }
+            // Clear import errors when file is successfully transformed
+            if (lastImportErrorFiles.has(ctx.file)) {
+                lastImportErrorFiles.delete(ctx.file);
+                // Clear build system errors when import errors are resolved
+                if (aiService?.isBusy()) {
+                    aiService.handleClearBuildSystemErrors();
+                }
+            }
+            // this is a bandaid fix for a full-reload problem to ensure that we do not trigger full page reloads
+            // for components that are not imported anywhere. please leave it alone for now, or talk to omar if
+            // this is causing problems and you need to fix it.
+            return ctx.modules.filter((module) => {
+                if (module.id?.startsWith(ctx.file)) {
+                    return module.importers.size > 0;
+                }
+                return true;
+            });
         },
     };
-};
-async function getAppScope(fileSyncManager) {
+    return {
+        plugin: [plugin, yamlApiTypesPlugin(syncService, aiService)],
+        dispose: () => {
+            // Cancel all pending debounced root updates
+            debouncedFileUpdateHandlers.forEach((fn) => fn.cancel());
+            debouncedFileUpdateHandlers.clear();
+            unregisterLogForwarder?.();
+            // Cancel any pending debounced context flush timer so a torn-down plugin
+            // does not fire an upload over stale aiService/syncService state.
+            contextFlushScheduler?.dispose();
+            disposeSocketManager();
+        },
+    };
+}
+async function getAppScope(fileSyncManager, reportRouterParseDiagnostic) {
+    let routerParseDiagnostic;
     const pageContents = await getAllPages({
         rootDir: config.root,
+        onRouterParseDiagnostic: (diagnostic) => {
+            routerParseDiagnostic = diagnostic;
+        },
     });
-    const pages = pageContents.reduce((acc, { name, route, fileName }) => {
-        const roots = fileSyncManager.getPageRoots(fileName);
+    await reportRouterParseDiagnostic(routerParseDiagnostic);
+    const pages = {};
+    for (const { name, route, fileName } of pageContents) {
+        const roots = await fileSyncManager.getPageRootNodes(fileName);
         const pageScopeDef = fileSyncManager.getScope(fileName);
-        if (roots && pageScopeDef) {
-            acc[name] = {
-                name,
-                ...pageScopeDef,
-                route,
-                roots,
-            };
+        if (!roots || !pageScopeDef)
+            continue;
+        if (pages[name]) {
+            // Page already exists, add this route to its routes array
+            pages[name].routes.push(route);
+            continue;
         }
-        return acc;
-    }, {});
-    const appScopeDef = fileSyncManager.getScope(fileSyncManager.appFilePath);
+        // New page, initialize with routes array
+        pages[name] = {
+            name,
+            ...pageScopeDef,
+            routes: [route],
+            roots,
+        };
+    }
+    const appScopeDef = fileSyncManager.getScope(fileSyncManager.appFilePath, true);
+    const appRoots = await fileSyncManager.getAppRootNodes();
     const apiFiles = fileSyncManager.getApiFiles();
     const apis = Object.values(apiFiles)
-        .filter(({ api: { apiPb } }) => !!apiPb.metadata && !!apiPb.trigger?.application)
-        .map(({ api: { apiPb } }) => ({
+        .filter(({ api: { apiPb } }) => !!apiPb.metadata)
+        .map(({ api: { apiPb }, scopeId }) => ({
         id: apiPb.metadata.id,
         name: apiPb.metadata.name,
-        applicationId: apiPb.trigger.application?.id,
-        pageId: apiPb.trigger.application?.pageId,
+        applicationId: apiPb.trigger?.application?.id,
+        pageId: apiPb.trigger?.application?.pageId,
         organizationId: apiPb.metadata.organization,
         updated: apiPb.metadata?.timestamps?.updated
             ? new Date(apiPb.metadata?.timestamps?.updated)
             : undefined,
         triggerType: ApiTriggerType.UI,
         apiPb: apiPb,
+        scopeId,
     }));
     const appScope = {
         ...appScopeDef,
+        roots: appRoots ?? [],
         pages,
         apis,
     };