framer-code-link 0.17.0 → 0.17.1-alpha.0

package/dist/index.mjs

@@ -1,12 +1,20 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import fs from "fs/promises";
 import path from "path";
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import nodeFs from "node:fs";
+import fs$1 from "node:fs/promises";
+import os from "node:os";
+import path$1 from "node:path";
+import { promisify } from "node:util";
+import https from "node:https";
 import { WebSocketServer } from "ws";
-import { createHash } from "crypto";
+import { createHash as createHash$1 } from "crypto";
 import { execSync } from "child_process";
-import fs$1 from "fs";
+import fs$2 from "fs";
 import { setupTypeAcquisition } from "@typescript/ata";
 import ts from "typescript";
 import { fileURLToPath } from "node:url";
@@ -142,7 +150,7 @@ function pathJoin(...parts) {
 	});
 	return res;
 }
-function normalizePath$1(filePath) {
+function normalizePath(filePath) {
 	if (!filePath) return "";
 	const isAbsolute = filePath.startsWith("/");
 	const segments = filePath.replace(/\\/g, "/").split("/");
@@ -159,12 +167,24 @@ function normalizePath$1(filePath) {
 	if (isAbsolute) return `/${normalized}`;
 	return normalized;
 }
+/**
+* Use when you only want path normalization.
+* Preserves the caller-provided extension so `Foo.ts` and `Foo.tsx` stay distinct.
+*/
 function normalizeCodeFilePath(filePath) {
-	const normalized = normalizePath$1(filePath);
+	const normalized = normalizePath(filePath);
 	return normalized.startsWith("/") ? normalized.slice(1) : normalized;
 }
-function canonicalFileName(filePath) {
-	return normalizeCodeFilePath(filePath);
+function ensureExtension(filePath, extension = ".tsx") {
+	const normalized = normalizeCodeFilePath(filePath);
+	return /\.(tsx?|jsx?|json)$/i.test(normalized) ? normalized : `${normalized}${extension}`;
+}
+/**
+* Use when the path must match the code-file API contract.
+* Normalizes the path and ensures a default `.tsx` extension when one is missing.
+*/
+function normalizeCodeFilePathWithExtension(filePath) {
+	return ensureExtension(filePath);
 }
 function sanitizeFilePath(input, capitalizeReactComponent = true) {
 	const trimmed = input.trim();
@@ -188,7 +208,7 @@ function isSupportedExtension$1(filePath) {
 * Use this for Map keys on operating systems where "File.tsx" and "file.tsx" are the same file.
 */
 function fileKeyForLookup(filePath) {
-	return canonicalFileName(filePath).toLowerCase();
+	return normalizeCodeFilePath(filePath).toLowerCase();
 }
 /**
 * Pluralize a word based on count
@@ -220,6 +240,11 @@ function getPortFromHash(projectHash) {
 	return 3847 + Math.abs(hash) % 250;
 }
 
+//#endregion
+//#region ../code-link-shared/src/types.ts
+/** Custom close code sent when a new plugin tab replaces the active one. */
+const CLOSE_CODE_REPLACED = 4001;
+
 //#endregion
 //#region ../../node_modules/picocolors/picocolors.js
 var require_picocolors = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -292,14 +317,22 @@ var require_picocolors = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 //#endregion
 //#region src/utils/logging.ts
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
-let LogLevel = /* @__PURE__ */ function(LogLevel) {
-	LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
-	LogLevel[LogLevel["INFO"] = 1] = "INFO";
-	LogLevel[LogLevel["WARN"] = 2] = "WARN";
-	LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
-	return LogLevel;
-}({});
+const LogLevel = {
+	DEBUG: "debug",
+	INFO: "info",
+	WARN: "warn",
+	ERROR: "error"
+};
+const LOG_PRIORITY = {
+	[LogLevel.DEBUG]: 0,
+	[LogLevel.INFO]: 1,
+	[LogLevel.WARN]: 2,
+	[LogLevel.ERROR]: 3
+};
 let currentLevel = LogLevel.INFO;
+function allows(level) {
+	return LOG_PRIORITY[currentLevel] <= LOG_PRIORITY[level];
+}
 let lastMessage = "";
 let lastMessageCount = 0;
 const CLEAR_LINE = "\x1B[2K";
@@ -308,10 +341,6 @@ function rewriteLastLine(text) {
 	if (process.stdout.isTTY) process.stdout.write(`${MOVE_CURSOR_UP}\r${CLEAR_LINE}${text}\n`);
 	else process.stdout.write(`${text}\n`);
 }
-let disconnectTimer = null;
-let isShowingDisconnect = false;
-let hadRecentDisconnect = false;
-const DISCONNECT_DELAY_MS = 4e3;
 function setLogLevel(level) {
 	currentLevel = level;
 }
@@ -345,7 +374,7 @@ function logWithDedupe(message, writer) {
 function banner(version, port) {
 	console.log();
 	let message = `  ${import_picocolors.default.cyan(import_picocolors.default.bold("⚡ Code Link"))} ${import_picocolors.default.dim(`v${version}`)}`;
-	if (currentLevel <= LogLevel.DEBUG) message += `  ${import_picocolors.default.dim("Port")} ${import_picocolors.default.yellow(port)}`;
+	if (allows(LogLevel.DEBUG)) message += `  ${import_picocolors.default.dim("Port")} ${import_picocolors.default.yellow(port)}`;
 	console.log(message);
 	console.log();
 }
@@ -353,13 +382,13 @@ function banner(version, port) {
 * Debug-level logging - only shown with --verbose flag
 */
 function debug(message, ...args) {
-	if (currentLevel <= LogLevel.DEBUG) console.debug(import_picocolors.default.dim(`[DEBUG] ${message}`), ...args);
+	if (allows(LogLevel.DEBUG)) console.debug(import_picocolors.default.dim(`[DEBUG] ${message}`), ...args);
 }
 /**
 * Info-level logging - shown by default, no prefix
 */
 function info(message, ...args) {
-	if (currentLevel <= LogLevel.INFO) {
+	if (allows(LogLevel.INFO)) {
 		const formatted = args.length > 0 ? `${message} ${args.join(" ")}` : message;
 		logWithDedupe(formatted, () => {
 			console.log(formatted);
@@ -370,7 +399,7 @@ function info(message, ...args) {
 * Warning-level logging
 */
 function warn(message, ...args) {
-	if (currentLevel <= LogLevel.WARN) {
+	if (allows(LogLevel.WARN)) {
 		if (message === lastMessage) return;
 		flushDedupe();
 		lastMessage = message;
@@ -382,7 +411,7 @@ function warn(message, ...args) {
 * Error-level logging
 */
 function error(message, ...args) {
-	if (currentLevel <= LogLevel.ERROR) {
+	if (allows(LogLevel.ERROR)) {
 		flushDedupe();
 		console.error(import_picocolors.default.red(`✗ ${message}`), ...args);
 	}
@@ -391,7 +420,7 @@ function error(message, ...args) {
 * Success message with checkmark
 */
 function success(message, ...args) {
-	if (currentLevel <= LogLevel.INFO) {
+	if (allows(LogLevel.INFO)) {
 		flushDedupe();
 		console.log(import_picocolors.default.green(`✓ ${message}`), ...args);
 	}
@@ -400,7 +429,7 @@ function success(message, ...args) {
 * File sync indicators
 */
 function fileDown(fileName) {
-	if (currentLevel <= LogLevel.INFO) {
+	if (allows(LogLevel.INFO)) {
 		const msg = `  ${import_picocolors.default.blue("↓")} ${fileName}`;
 		logWithDedupe(msg, () => {
 			console.log(msg);
@@ -408,7 +437,7 @@ function fileDown(fileName) {
 	}
 }
 function fileUp(fileName) {
-	if (currentLevel <= LogLevel.INFO) {
+	if (allows(LogLevel.INFO)) {
 		const msg = `  ${import_picocolors.default.green("↑")} ${fileName}`;
 		logWithDedupe(msg, () => {
 			console.log(msg);
@@ -416,7 +445,7 @@ function fileUp(fileName) {
 	}
 }
 function fileDelete(fileName) {
-	if (currentLevel <= LogLevel.INFO) {
+	if (allows(LogLevel.INFO)) {
 		const msg = `  ${import_picocolors.default.red("×")} ${fileName}`;
 		logWithDedupe(msg, () => {
 			console.log(msg);
@@ -427,76 +456,256 @@ function fileDelete(fileName) {
 * Status message (dimmed, for "watching for changes..." etc)
 */
 function status(message) {
-	if (currentLevel <= LogLevel.INFO) {
+	if (allows(LogLevel.INFO)) {
 		flushDedupe();
 		console.log(import_picocolors.default.dim(`  ${message}`));
 	}
 }
+
+//#endregion
+//#region src/helpers/certs.ts
 /**
-* Schedule a delayed disconnect message.
-* If reconnection happens before the delay, the message is cancelled.
+* Certificate management for WSS support.
+*
+* Downloads FiloSottile's mkcert binary on first run, then shells out to it
+* to generate and trust a local CA + server certificate for wss://localhost.
+*
+* The mkcert binary is SHA-256 verified before execution (update
+* MKCERT_CHECKSUMS when bumping MKCERT_VERSION). The CA key is user-only;
+* never share or commit the cert directory.
+*
+* Certs and the mkcert binary are cached in ~/.framer/code-link/.
 */
-function scheduleDisconnectMessage(callback) {
-	if (disconnectTimer) clearTimeout(disconnectTimer);
-	hadRecentDisconnect = true;
-	isShowingDisconnect = false;
-	disconnectTimer = setTimeout(() => {
-		isShowingDisconnect = true;
-		callback();
-		disconnectTimer = null;
-	}, DISCONNECT_DELAY_MS);
-}
+const execFileAsync = promisify(execFile);
+/** Keep in sync with MKCERT_CHECKSUMS below. */
+const MKCERT_VERSION = "v1.4.4";
+const CERT_DIR = process.env.FRAMER_CODE_LINK_CERT_DIR ?? path$1.join(os.homedir(), ".framer", "code-link");
+const MKCERT_BIN_NAME = process.platform === "win32" ? "mkcert.exe" : "mkcert";
+const MKCERT_BIN_PATH = path$1.join(CERT_DIR, MKCERT_BIN_NAME);
+const ROOT_CA_CERT_PATH = path$1.join(CERT_DIR, "rootCA.pem");
+const ROOT_CA_KEY_PATH = path$1.join(CERT_DIR, "rootCA-key.pem");
+const SERVER_KEY_PATH = path$1.join(CERT_DIR, "localhost-key.pem");
+const SERVER_CERT_PATH = path$1.join(CERT_DIR, "localhost.pem");
 /**
-* Cancel pending disconnect message (called on reconnect)
+* SHA-256 checksums for mkcert v1.4.4 release binaries, keyed by "platform-arch".
+* These must be updated whenever MKCERT_VERSION changes.
+* Source: https://github.com/FiloSottile/mkcert/releases/tag/v1.4.4
 */
-function cancelDisconnectMessage() {
-	if (disconnectTimer) {
-		clearTimeout(disconnectTimer);
-		disconnectTimer = null;
-	}
-}
+const MKCERT_CHECKSUMS = {
+	"darwin-amd64": "a32dfab51f1845d51e810db8e47dcf0e6b51ae3422426514bf5a2b8302e97d4e",
+	"darwin-arm64": "c8af0df44bce04359794dad8ea28d750437411d632748049d08644ffb66a60c6",
+	"linux-amd64": "6d31c65b03972c6dc4a14ab429f2928300518b26503f58723e532d1b0a3bbb52",
+	"linux-arm64": "b98f2cc69fd9147fe4d405d859c57504571adec0d3611c3eefd04107c7ac00d0",
+	"windows-amd64": "d2660b50a9ed59eada480750561c96abc2ed4c9a38c6a24d93e30e0977631398",
+	"windows-arm64": "793747256c562622d40127c8080df26add2fb44c50906ce9db63b42a5280582e"
+};
+/** Env vars passed to every mkcert invocation. */
+const MKCERT_ENV = {
+	...process.env,
+	CAROOT: CERT_DIR,
+	JAVA_HOME: "",
+	...process.platform === "darwin" ? { TRUST_STORES: "system" } : {}
+};
 /**
-* Check if we showed a disconnect message (need to show reconnect)
+* Returns a TLS cert bundle for the WSS server, or null if generation fails.
+* On first run, downloads mkcert, installs a local CA into trust stores, and
+* generates a server cert for localhost.
 */
-function didShowDisconnect() {
-	return isShowingDisconnect;
+async function getOrCreateCerts() {
+	try {
+		await fs$1.mkdir(CERT_DIR, { recursive: true });
+		const mkcertPath = await ensureMkcertBinary();
+		const rootCAState = await syncRootCA(mkcertPath);
+		if (rootCAState !== "unchanged") await invalidateServerCerts(rootCAState);
+		const existingKey = await loadFile(SERVER_KEY_PATH);
+		const existingCert = await loadFile(SERVER_CERT_PATH);
+		if (existingKey && existingCert) {
+			debug("Loaded existing server certificates from disk");
+			return {
+				key: existingKey,
+				cert: existingCert
+			};
+		}
+		if (existingKey || existingCert) await invalidateIncompleteServerBundle();
+		status("Generating local certificates to connect securely. You may be asked for your password.");
+		await generateCerts(mkcertPath);
+		status("Successfully generated certificates.");
+		return {
+			key: await fs$1.readFile(SERVER_KEY_PATH, "utf-8"),
+			cert: await fs$1.readFile(SERVER_CERT_PATH, "utf-8")
+		};
+	} catch (err) {
+		error(`Failed to set up TLS certificates: ${err instanceof Error ? err.message : String(err)}`);
+		return null;
+	}
 }
-/**
-* Check if we recently saw a disconnect (even if the message was suppressed)
-*/
-function wasRecentlyDisconnected() {
-	return hadRecentDisconnect;
+function getDownloadInfo() {
+	const platformMap = {
+		darwin: "darwin",
+		linux: "linux",
+		win32: "windows"
+	};
+	const archMap = {
+		x64: "amd64",
+		arm64: "arm64"
+	};
+	const platform = platformMap[process.platform];
+	const arch = archMap[process.arch];
+	if (!platform || !arch) throw new Error(`Unsupported platform: ${process.platform}/${process.arch}. Install mkcert manually: https://github.com/FiloSottile/mkcert#installation`);
+	const key = `${platform}-${arch}`;
+	const expectedChecksum = MKCERT_CHECKSUMS[key];
+	if (!expectedChecksum) throw new Error(`No checksum available for mkcert ${key}. Install mkcert manually: https://github.com/FiloSottile/mkcert#installation`);
+	return {
+		url: `https://github.com/FiloSottile/mkcert/releases/download/${MKCERT_VERSION}/${`mkcert-${MKCERT_VERSION}-${platform}-${arch}${process.platform === "win32" ? ".exe" : ""}`}`,
+		expectedChecksum
+	};
 }
-/**
-* Reset disconnect state after successful reconnect
-*/
-function resetDisconnectState() {
-	isShowingDisconnect = false;
-	hadRecentDisconnect = false;
+async function ensureMkcertBinary() {
+	const { url, expectedChecksum } = getDownloadInfo();
+	try {
+		await fs$1.access(MKCERT_BIN_PATH, nodeFs.constants.X_OK);
+		if (await verifyFileChecksum(MKCERT_BIN_PATH, expectedChecksum)) {
+			debug("mkcert binary already available and verified");
+			return MKCERT_BIN_PATH;
+		}
+		warn("Cached mkcert binary failed checksum verification, re-downloading...");
+	} catch {}
+	debug(`Downloading mkcert from ${url}`);
+	status("Downloading mkcert for certificate generation...");
+	try {
+		const response = await fetch(url, { redirect: "follow" });
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		const buffer = Buffer.from(await response.arrayBuffer());
+		const actualChecksum = createHash("sha256").update(buffer).digest("hex");
+		if (actualChecksum !== expectedChecksum) throw new Error(`mkcert binary checksum mismatch — the download may have been tampered with.\n  Expected: ${expectedChecksum}\n  Actual:   ${actualChecksum}`);
+		await fs$1.writeFile(MKCERT_BIN_PATH, buffer, { mode: 493 });
+		debug(`mkcert binary saved to ${MKCERT_BIN_PATH}`);
+		return MKCERT_BIN_PATH;
+	} catch (err) {
+		await fs$1.rm(MKCERT_BIN_PATH, { force: true });
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to download mkcert: ${message}\nYou can install it manually: https://github.com/FiloSottile/mkcert#installation\nThen run: mkcert -install && mkcert -key-file "${SERVER_KEY_PATH}" -cert-file "${SERVER_CERT_PATH}" localhost 127.0.0.1`);
+	}
+}
+async function generateCerts(mkcertPath) {
+	debug("Running mkcert to install the local root CA...");
+	try {
+		await execFileAsync(mkcertPath, ["-install"], { env: MKCERT_ENV });
+	} catch (err) {
+		throw new Error(`Failed to install mkcert root CA into the system trust store. If you canceled the password prompt, rerun this command and allow the install.
+mkcert error: ${formatMkcertError(err)}`);
+	}
+	debug("Running mkcert to generate the localhost server certificate...");
+	try {
+		await execFileAsync(mkcertPath, [
+			"-key-file",
+			SERVER_KEY_PATH,
+			"-cert-file",
+			SERVER_CERT_PATH,
+			"localhost",
+			"127.0.0.1"
+		], { env: MKCERT_ENV });
+	} catch (err) {
+		if (await loadFile(SERVER_KEY_PATH) || await loadFile(SERVER_CERT_PATH)) await invalidateIncompleteServerBundle();
+		throw new Error(`Failed to generate localhost TLS certificate and key with mkcert.
+mkcert error: ${formatMkcertError(err)}\nPlease rerun:\n  mkcert -key-file "${SERVER_KEY_PATH}" -cert-file "${SERVER_CERT_PATH}" localhost 127.0.0.1`);
+	}
+	const [generatedKey, generatedCert] = await Promise.all([loadFile(SERVER_KEY_PATH), loadFile(SERVER_CERT_PATH)]);
+	if (generatedKey && generatedCert) {
+		debug("CA installed and server certificate generated successfully");
+		return;
+	}
+	if (generatedKey || generatedCert) await invalidateIncompleteServerBundle();
+	throw new Error(`Failed to generate localhost TLS certificate and key with mkcert. Please ensure mkcert is installed and rerun:
+  mkcert -install && mkcert -key-file "${SERVER_KEY_PATH}" -cert-file "${SERVER_CERT_PATH}" localhost 127.0.0.1`);
+}
+async function syncRootCA(mkcertPath) {
+	const existingRootCert = await loadFile(ROOT_CA_CERT_PATH);
+	const existingRootKey = await loadFile(ROOT_CA_KEY_PATH);
+	const { stdout } = await execFileAsync(mkcertPath, ["-CAROOT"], { env: {
+		...process.env,
+		JAVA_HOME: ""
+	} });
+	const defaultCAROOT = stdout.trim();
+	if (!defaultCAROOT || defaultCAROOT === CERT_DIR) return existingRootCert && existingRootKey ? "unchanged" : "missing";
+	const defaultRootCert = await loadFile(path$1.join(defaultCAROOT, "rootCA.pem"));
+	const defaultRootKey = await loadFile(path$1.join(defaultCAROOT, "rootCA-key.pem"));
+	if (!defaultRootCert || !defaultRootKey) return existingRootCert && existingRootKey ? "unchanged" : "missing";
+	if (existingRootCert === defaultRootCert && existingRootKey === defaultRootKey) return "unchanged";
+	await Promise.all([fs$1.rm(ROOT_CA_CERT_PATH, { force: true }), fs$1.rm(ROOT_CA_KEY_PATH, { force: true })]);
+	await fs$1.writeFile(ROOT_CA_CERT_PATH, defaultRootCert, { mode: 420 });
+	await fs$1.writeFile(ROOT_CA_KEY_PATH, defaultRootKey, { mode: 384 });
+	return existingRootCert && existingRootKey ? "updated" : "copied";
+}
+async function invalidateServerCerts(rootCAState) {
+	const reasons = {
+		copied: "Copied an existing mkcert root CA into the Code Link cache",
+		updated: "Detected a different mkcert root CA and refreshed the Code Link cache",
+		missing: "No cached mkcert root CA was available for the existing server certificate"
+	};
+	if (!(await loadFile(SERVER_KEY_PATH) !== null || await loadFile(SERVER_CERT_PATH) !== null)) return;
+	await fs$1.rm(SERVER_KEY_PATH, { force: true });
+	await fs$1.rm(SERVER_CERT_PATH, { force: true });
+	debug(`${reasons[rootCAState]}; removed stale localhost certificate`);
+}
+async function invalidateIncompleteServerBundle() {
+	await fs$1.rm(SERVER_KEY_PATH, { force: true });
+	await fs$1.rm(SERVER_CERT_PATH, { force: true });
+	warn("Found an incomplete localhost certificate bundle; regenerating it");
+}
+async function verifyFileChecksum(filePath, expectedHash) {
+	const data = await fs$1.readFile(filePath);
+	return createHash("sha256").update(data).digest("hex") === expectedHash;
+}
+async function loadFile(filePath) {
+	try {
+		return await fs$1.readFile(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+function formatMkcertError(err) {
+	if (err instanceof Error) {
+		const stdout = "stdout" in err && typeof err.stdout === "string" ? err.stdout.trim() : "";
+		const output = ["stderr" in err && typeof err.stderr === "string" ? err.stderr.trim() : "", stdout].filter(Boolean).join("\n");
+		return output ? `${err.message}\n${output}` : err.message;
+	}
+	return String(err);
 }
 
 //#endregion
 //#region src/helpers/connection.ts
 /**
-* Initializes a WebSocket server and returns a connection interface
-* Returns a Promise that resolves when the server is ready, or rejects on startup errors
+* WebSocket connection helper
+*
+* Wrapper around ws.Server that normalizes handshake and surfaces callbacks.
+*/
+/**
+* Initializes a WSS (TLS) WebSocket server and returns a connection interface.
+* Returns a Promise that resolves when the server is ready, or rejects on startup errors.
 */
-function initConnection(port) {
+function initConnection(port, certs) {
 	return new Promise((resolve, reject) => {
-		const wss = new WebSocketServer({ port });
 		const handlers = {};
 		let connectionId = 0;
 		let isReady = false;
+		const httpsServer = https.createServer({
+			key: certs.key,
+			cert: certs.cert
+		});
+		const wss = new WebSocketServer({ server: httpsServer });
 		wss.on("error", (err) => {
+			error(`WebSocket server error: ${err.message}`);
+			handlers.onError?.(err);
+		});
+		const handleError = (err) => {
 			if (!isReady) {
 				if (err.code === "EADDRINUSE") {
 					error(`Port ${port} is already in use.`);
-					error(`This usually means another instance of Code Link is already running.`);
-					error(``);
-					error(`To fix this:`);
-					error(`  1. Close any other terminal running Code Link for this project`);
-					error(`  2. Or run: lsof -i :${port} | grep LISTEN`);
-					error(`     Then kill the process: kill -9 <PID>`);
+					info(`This usually means another instance of Code Link is already running.`);
+					info(``);
+					info(`To fix this:`);
+					info(`  Close any other terminal running Code Link for this project`);
 					reject(/* @__PURE__ */ new Error(`Port ${port} is already in use`));
 				} else {
 					error(`Failed to start WebSocket server: ${err.message}`);
@@ -505,10 +714,11 @@ function initConnection(port) {
 				return;
 			}
 			error(`WebSocket server error: ${err.message}`);
-		});
-		wss.on("listening", () => {
+			handlers.onError?.(err);
+		};
+		const handleListening = () => {
 			isReady = true;
-			debug(`WebSocket server listening on port ${port}`);
+			debug(`WSS server listening on port ${port}`);
 			let activeClient = null;
 			wss.on("connection", (ws) => {
 				const connId = ++connectionId;
@@ -524,7 +734,7 @@ function initConnection(port) {
 							activeClient = ws;
 							if (previousActiveClient && previousActiveClient !== activeClient) {
 								debug(`Replacing active client with conn ${connId}`);
-								if (previousActiveClient.readyState === READY_STATE.OPEN || previousActiveClient.readyState === READY_STATE.CONNECTING) previousActiveClient.close();
+								if (previousActiveClient.readyState === READY_STATE.OPEN || previousActiveClient.readyState === READY_STATE.CONNECTING) previousActiveClient.close(CLOSE_CODE_REPLACED);
 							}
 							handlers.onHandshake?.(ws, message);
 						} else if (handshakeReceived && activeClient === ws) handlers.onMessage?.(message);
@@ -563,10 +773,15 @@ function initConnection(port) {
 					}
 				},
 				close() {
+					for (const client of wss.clients) client.close(1001);
 					wss.close();
+					httpsServer.close();
 				}
 			});
-		});
+		};
+		httpsServer.on("error", handleError);
+		httpsServer.on("listening", handleListening);
+		httpsServer.listen(port);
 	});
 }
 /**
@@ -608,41 +823,6 @@ function sendMessage(socket, message) {
 	});
 }
 
-//#endregion
-//#region src/utils/node-paths.ts
-/**
-* Path manipulation utilities
-*/
-/**
-* Gets a relative path from the project directory
-*/
-function getRelativePath(projectDir, absolutePath) {
-	return path.relative(projectDir, absolutePath);
-}
-/**
-* Normalizes a file path by:
-* - Converting backslashes to forward slashes
-* - Resolving . and .. segments
-* - Removing duplicate slashes
-*/
-function normalizePath(filePath) {
-	if (!filePath) return "";
-	const isAbsolute = filePath.startsWith("/");
-	const segments = filePath.replace(/\\/g, "/").split("/");
-	const stack = [];
-	for (const segment of segments) {
-		if (!segment || segment === ".") continue;
-		if (segment === "..") {
-			if (stack.length > 0) stack.pop();
-			continue;
-		}
-		stack.push(segment);
-	}
-	const normalized = stack.join("/");
-	if (isAbsolute) return `/${normalized}`;
-	return normalized;
-}
-
 //#endregion
 //#region src/utils/state-persistence.ts
 /**
@@ -654,24 +834,14 @@ function normalizePath(filePath) {
 */
 const STATE_FILE_NAME = ".framer-sync-state.json";
 const CURRENT_VERSION = 1;
-const SUPPORTED_EXTENSIONS$1 = [
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".json"
-];
-const DEFAULT_EXTENSION$1 = ".tsx";
-function normalizePersistedFileName(fileName) {
-	let normalized = normalizePath(fileName.trim());
-	if (!SUPPORTED_EXTENSIONS$1.some((ext) => normalized.toLowerCase().endsWith(ext))) normalized = `${normalized}${DEFAULT_EXTENSION$1}`;
-	return normalized;
+function persistedFileKey(fileName) {
+	return fileKeyForLookup(normalizeCodeFilePathWithExtension(fileName));
 }
 /**
 * Hash file content to detect changes
 */
 function hashFileContent(content) {
-	return createHash("sha256").update(content, "utf-8").digest("hex");
+	return createHash$1("sha256").update(content, "utf-8").digest("hex");
 }
 /**
 * Load persisted state from disk
@@ -687,7 +857,7 @@ async function loadPersistedState(projectDir) {
 			return result;
 		}
 		for (const [fileName, state] of Object.entries(parsed.files)) {
-			const normalizedName = normalizePersistedFileName(fileName);
+			const normalizedName = persistedFileKey(fileName);
 			if (normalizedName !== fileName) debug(`Normalized persisted key "${fileName}" -> "${normalizedName}" for compatibility`);
 			result.set(normalizedName, state);
 		}
@@ -755,7 +925,7 @@ async function listFiles(filesDir) {
 				continue;
 			}
 			if (!isSupportedExtension(entry.name)) continue;
-			const sanitizedPath = sanitizeFilePath(normalizePath$1(path.relative(filesDir, entryPath)), false).path;
+			const sanitizedPath = sanitizeFilePath(normalizePath(path.relative(filesDir, entryPath)), false).path;
 			try {
 				const [content, stats] = await Promise.all([fs.readFile(entryPath, "utf-8"), fs.stat(entryPath)]);
 				files.push({
@@ -933,42 +1103,67 @@ function autoResolveConflicts(conflicts, versions, options = {}) {
 		remainingConflicts
 	};
 }
-/**
-* Writes remote files to disk and updates hash tracker to prevent echoes
-* CRITICAL: Update hashTracker BEFORE writing to disk
-*/
-async function writeRemoteFiles(files, filesDir, hashTracker, installer) {
+async function writeRemoteFiles(files, filesDir, memory) {
 	debug(`Writing ${pluralize(files.length, "remote file")}`);
-	for (const file of files) try {
+	const results = [];
+	for (const file of files) {
 		const normalized = resolveRemoteReference(filesDir, file.name);
 		const fullPath = normalized.absolutePath;
-		await fs.mkdir(path.dirname(fullPath), { recursive: true });
-		hashTracker.remember(normalized.relativePath, file.content);
-		await fs.writeFile(fullPath, file.content, "utf-8");
-		debug(`Wrote file: ${normalized.relativePath}`);
-		installer?.process(normalized.relativePath, file.content);
-	} catch (err) {
-		warn(`Failed to write file ${file.name}:`, err);
+		const prepared = memory.armContentEcho(normalized.relativePath, file.content);
+		try {
+			await fs.mkdir(path.dirname(fullPath), { recursive: true });
+			await fs.writeFile(fullPath, file.content, "utf-8");
+			debug(`Wrote file: ${normalized.relativePath}`);
+			results.push({
+				file: {
+					...file,
+					name: normalized.relativePath
+				},
+				path: normalized.relativePath,
+				ok: true
+			});
+		} catch (err) {
+			memory.rollbackWriteFailure(prepared);
+			warn(`Failed to write file ${file.name}:`, err);
+			results.push({
+				file: {
+					...file,
+					name: normalized.relativePath
+				},
+				path: normalized.relativePath,
+				ok: false
+			});
+		}
 	}
+	return results;
 }
-/**
-* Deletes a local file from disk
-*/
-async function deleteLocalFile(fileName, filesDir, hashTracker) {
+async function deleteLocalFile(fileName, filesDir, memory) {
 	const normalized = resolveRemoteReference(filesDir, fileName);
+	const prepared = memory.armExpectedDeleteEcho(normalized.relativePath);
 	try {
-		hashTracker.markDelete(normalized.relativePath);
 		await fs.unlink(normalized.absolutePath);
-		hashTracker.forget(normalized.relativePath);
 		debug(`Deleted file: ${normalized.relativePath}`);
+		return {
+			fileName: normalized.relativePath,
+			ok: true,
+			alreadyMissing: false
+		};
 	} catch (err) {
 		if (err.code === "ENOENT") {
-			hashTracker.forget(normalized.relativePath);
 			debug(`File already deleted: ${normalized.relativePath}`);
-			return;
+			return {
+				fileName: normalized.relativePath,
+				ok: true,
+				alreadyMissing: true
+			};
 		}
-		hashTracker.clearDelete(normalized.relativePath);
+		memory.rollbackExpectedDeleteEcho(prepared);
 		warn(`Failed to delete file ${fileName}:`, err);
+		return {
+			fileName: normalized.relativePath,
+			ok: false,
+			alreadyMissing: false
+		};
 	}
 }
 /**
@@ -986,9 +1181,9 @@ async function readFileSafe(fileName, filesDir) {
 * Filter out files whose content matches the last remembered hash.
 * Used to skip inbound echoes of our own local sends.
 */
-function filterEchoedFiles(files, hashTracker) {
+function filterEchoedFiles(files, memory) {
 	return files.filter((file) => {
-		return !hashTracker.shouldSkip(file.name, file.content);
+		return !memory.matchesContentEcho(file.name, file.content);
 	});
 }
 function resolveRemoteReference(filesDir, rawName) {
@@ -1000,9 +1195,9 @@ function resolveRemoteReference(filesDir, rawName) {
 	};
 }
 function sanitizeRelativePath(relativePath) {
-	const trimmed = normalizePath$1(relativePath.trim());
+	const trimmed = normalizePath(relativePath.trim());
 	const sanitized = sanitizeFilePath(SUPPORTED_EXTENSIONS.some((ext) => trimmed.toLowerCase().endsWith(ext)) ? trimmed : `${trimmed}${DEFAULT_EXTENSION}`, false);
-	const normalized = normalizePath$1(sanitized.path);
+	const normalized = normalizePath(sanitized.path);
 	return {
 		relativePath: normalized,
 		extension: sanitized.extension || path.extname(normalized) || DEFAULT_EXTENSION
@@ -1061,6 +1256,7 @@ function tryGitInit(projectDir) {
 			debug("Already in a repository, skipping git init");
 			return false;
 		}
+		status("Initializing git repository...");
 		execSync("git init", {
 			stdio: "ignore",
 			cwd: projectDir
@@ -1082,7 +1278,7 @@ function tryGitInit(projectDir) {
 		return true;
 	} catch (e) {
 		if (didInit) try {
-			fs$1.rmSync(path.join(projectDir, ".git"), {
+			fs$2.rmSync(path.join(projectDir, ".git"), {
 				recursive: true,
 				force: true
 			});
@@ -1250,9 +1446,21 @@ async function findSkillsSourceDir() {
 const FETCH_TIMEOUT_MS = 6e4;
 const MAX_FETCH_RETRIES = 3;
 const MAX_CONSECUTIVE_FAILURES = 10;
-const REACT_TYPES_VERSION = "18.3.12";
-const REACT_DOM_TYPES_VERSION = "18.3.1";
-const CORE_LIBRARIES = ["framer-motion", "framer"];
+const FRAMER_PACKAGE_NAME = "framer";
+const CORE_LIBRARIES = [
+	"framer-motion",
+	"framer",
+	"react",
+	"react-dom"
+];
+/** Packages with pinned type versions — used by ATA's `// types:` comment syntax */
+const DEFAULT_PINNED_TYPE_VERSIONS = {
+	"framer-motion": "12.34.3",
+	react: "18.2.0",
+	"react-dom": "18.2.0",
+	"@types/react": "18.2.0",
+	"@types/react-dom": "18.2.0"
+};
 const JSON_EXTENSION_REGEX = /\.json$/i;
 /**
 * Packages that are officially supported for type acquisition.
@@ -1262,6 +1470,7 @@ const SUPPORTED_PACKAGES = new Set([
 	"framer",
 	"framer-motion",
 	"react",
+	"react-dom",
 	"@types/react",
 	"eventemitter3",
 	"csstype",
@@ -1273,13 +1482,19 @@ const SUPPORTED_PACKAGES = new Set([
 */
 var Installer = class {
 	projectDir;
-	allowUnsupportedNpm;
+	npmStrategy;
+	requestDependencyVersions;
 	ata;
 	processedImports = /* @__PURE__ */ new Set();
+	packageManagerPackages = /* @__PURE__ */ new Set();
+	packageJsonRefreshPromise = Promise.resolve();
 	initializationPromise = null;
+	pinnedTypeVersions = { ...DEFAULT_PINNED_TYPE_VERSIONS };
+	pinnedTypeVersionsPromise = null;
 	constructor(config) {
 		this.projectDir = config.projectDir;
-		this.allowUnsupportedNpm = config.allowUnsupportedNpm ?? false;
+		this.npmStrategy = config.npmStrategy ?? "none";
+		this.requestDependencyVersions = config.requestDependencyVersions ?? (async (packages) => Object.fromEntries(packages.map((packageName) => [packageName, null])));
 		const seenPackages = /* @__PURE__ */ new Set();
 		this.ata = setupTypeAcquisition({
 			projectName: "framer-code-link",
@@ -1357,10 +1572,16 @@ var Installer = class {
 			this.ensureSkills(),
 			this.ensureGitignore()
 		]);
+		if (this.npmStrategy === "package-manager") {
+			await this.enqueuePackageJsonRefresh(await this.collectPackageManagerPackageNames());
+			return;
+		}
+		this.pinnedTypeVersionsPromise = this.resolvePinnedTypeVersions();
 		Promise.resolve().then(async () => {
-			await this.ensureReact18Types();
-			const coreImports = CORE_LIBRARIES.map((lib) => `import "${lib}";`).join("\n");
-			await this.ata(coreImports);
+			const coreImports = await this.buildPinnedImports(CORE_LIBRARIES);
+			const packageJsonDeps = this.npmStrategy === "acquire-types" ? Object.keys(this.pinnedTypeVersions).filter((name) => !SUPPORTED_PACKAGES.has(name)) : [];
+			const imports = [...coreImports, ...await this.buildPinnedImports(packageJsonDeps)].join("\n");
+			await this.ata(imports);
 		}).catch((err) => {
 			debug("Type installation failed", err);
 		});
@@ -1368,19 +1589,84 @@ var Installer = class {
 	async processImports(fileName, content) {
 		const allImports = extractImports(content).filter((i) => i.type === "npm");
 		if (allImports.length === 0) return;
-		const imports = this.allowUnsupportedNpm ? allImports : allImports.filter((i) => this.isSupportedPackage(i.name));
-		if (allImports.length - imports.length > 0 && !this.allowUnsupportedNpm) debug(`Skipping unsupported packages: ${allImports.filter((i) => !this.isSupportedPackage(i.name)).map((i) => i.name).join(", ")} (use --unsupported-npm to enable)`);
+		if (this.npmStrategy === "package-manager") {
+			await this.enqueuePackageJsonRefresh(allImports.map((imp) => getBasePackageName(imp.name)));
+			return;
+		}
+		const imports = this.npmStrategy === "acquire-types" ? allImports : allImports.filter((i) => this.isSupportedPackage(i.name));
+		if (allImports.length - imports.length > 0 && this.npmStrategy !== "acquire-types") debug(`Skipping unsupported packages: ${allImports.filter((i) => !this.isSupportedPackage(i.name)).map((i) => i.name).join(", ")} (use --unsupported-npm to enable)`);
 		if (imports.length === 0) return;
-		const hash = imports.map((imp) => imp.name).sort().join(",");
+		await this.pinnedTypeVersionsPromise;
+		if (this.npmStrategy === "acquire-types") await this.resolvePackageJsonPins();
+		const hash = imports.map((imp) => this.pinImport(imp.name)).sort().join(",");
 		if (this.processedImports.has(hash)) return;
 		this.processedImports.add(hash);
 		debug(`Processing imports for ${fileName} (${imports.length} packages)`);
-		const filteredContent = this.allowUnsupportedNpm ? content : this.buildFilteredImports(imports);
+		const filteredContent = this.npmStrategy === "acquire-types" ? content : await this.buildFilteredImports(imports);
 		try {
 			await this.ata(filteredContent);
 		} catch (err) {
-			warn(`ATA failed for ${fileName}`, err);
+			warn(`Type fetching failed for ${fileName}`);
+			debug(`ATA error for ${fileName}:`, err);
+		}
+	}
+	async collectPackageManagerPackageNames() {
+		const packageNames = new Set(CORE_LIBRARIES);
+		await this.addPackageNamesFromDirectory(path.join(this.projectDir, "files"), packageNames);
+		return [...packageNames];
+	}
+	async addPackageNamesFromDirectory(directory, packageNames) {
+		let entries;
+		try {
+			entries = await fs.readdir(directory, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		await Promise.all(entries.map(async (entry) => {
+			const entryPath = path.join(directory, entry.name);
+			if (entry.isDirectory()) {
+				await this.addPackageNamesFromDirectory(entryPath, packageNames);
+				return;
+			}
+			if (!entry.isFile() || JSON_EXTENSION_REGEX.test(entry.name)) return;
+			try {
+				const content = await fs.readFile(entryPath, "utf-8");
+				for (const imported of extractImports(content).filter((i) => i.type === "npm")) packageNames.add(getBasePackageName(imported.name));
+			} catch {}
+		}));
+	}
+	async enqueuePackageJsonRefresh(packageNames) {
+		const missingPackageNames = packageNames.map((name) => getBasePackageName(name)).filter((name) => {
+			if (this.packageManagerPackages.has(name)) return false;
+			this.packageManagerPackages.add(name);
+			return true;
+		});
+		if (missingPackageNames.length === 0) return this.packageJsonRefreshPromise;
+		this.packageJsonRefreshPromise = this.packageJsonRefreshPromise.then(async () => {
+			await this.refreshPackageJsonFromPlugin(missingPackageNames);
+		}).catch((err) => {
+			warn("Could not refresh package.json dependency versions", err);
+		});
+		return this.packageJsonRefreshPromise;
+	}
+	async refreshPackageJsonFromPlugin(packageNames) {
+		const uniquePackageNames = [...new Set(packageNames)].sort();
+		const versions = await this.requestDependencyVersions(uniquePackageNames);
+		const packagePath = path.join(this.projectDir, "package.json");
+		const raw = await fs.readFile(packagePath, "utf-8");
+		const pkg = JSON.parse(raw);
+		const dependencies = typeof pkg.dependencies === "object" && pkg.dependencies !== null && !Array.isArray(pkg.dependencies) ? { ...pkg.dependencies } : {};
+		let changed = false;
+		for (const packageName of uniquePackageNames) {
+			const version = versions[packageName];
+			if (!version || dependencies[packageName] === version) continue;
+			dependencies[packageName] = version;
+			changed = true;
 		}
+		if (!changed) return;
+		pkg.dependencies = dependencies;
+		await fs.writeFile(packagePath, JSON.stringify(pkg, null, 4));
+		debug(`Updated package.json dependency versions for ${uniquePackageNames.join(", ")}`);
 	}
 	/**
 	* Check if a package is in the supported list.
@@ -1388,14 +1674,61 @@ var Installer = class {
 	*/
 	isSupportedPackage(pkgName) {
 		if (SUPPORTED_PACKAGES.has(pkgName)) return true;
-		const basePkg = pkgName.startsWith("@") ? pkgName.split("/").slice(0, 2).join("/") : pkgName.split("/")[0];
+		const basePkg = getBasePackageName(pkgName);
 		return SUPPORTED_PACKAGES.has(basePkg);
 	}
 	/**
 	* Build synthetic import statements for ATA from filtered imports
 	*/
-	buildFilteredImports(imports) {
-		return imports.map((imp) => `import "${imp.name}";`).join("\n");
+	async buildFilteredImports(imports) {
+		return (await this.buildPinnedImports(imports.map((imp) => imp.name))).join("\n");
+	}
+	async buildPinnedImports(imports) {
+		await this.pinnedTypeVersionsPromise;
+		return imports.map((name) => this.pinImport(name));
+	}
+	async resolvePinnedTypeVersions() {
+		try {
+			const framerManifest = await fetchNpmPackageManifest(FRAMER_PACKAGE_NAME);
+			const framerVersion = normalizePinnedVersion(framerManifest.version);
+			if (framerVersion) this.pinnedTypeVersions.framer = framerVersion;
+			for (const [pkg, defaultVersion] of Object.entries(DEFAULT_PINNED_TYPE_VERSIONS)) {
+				const manifestDep = pkg.replace(/^@types\//, "");
+				this.pinnedTypeVersions[pkg] = normalizePinnedVersion(getManifestDependencyVersion(framerManifest, manifestDep)) ?? defaultVersion;
+			}
+			debug(`Resolved ATA pins from ${FRAMER_PACKAGE_NAME}@${framerVersion ?? "latest"} (framer-motion ${this.pinnedTypeVersions["framer-motion"]}, react ${this.pinnedTypeVersions.react})`);
+		} catch (err) {
+			debug(`Falling back to default ATA pins for ${FRAMER_PACKAGE_NAME}`, err);
+		}
+		if (this.npmStrategy === "acquire-types") await this.resolvePackageJsonPins();
+	}
+	async resolvePackageJsonPins() {
+		try {
+			const pkgPath = path.join(this.projectDir, "package.json");
+			const raw = await fs.readFile(pkgPath, "utf-8");
+			const pkg = JSON.parse(raw);
+			const allDeps = {
+				...pkg.dependencies ?? {},
+				...pkg.devDependencies ?? {}
+			};
+			for (const [name, range] of Object.entries(allDeps)) {
+				const version = normalizePinnedVersion(range);
+				if (version) this.pinnedTypeVersions[name] = version;
+			}
+			debug(`Resolved ${Object.keys(allDeps).length} package.json version pins`);
+		} catch {
+			warn("Could not read package.json for version pinning");
+		}
+	}
+	/**
+	* Build an import statement with an optional `// types:` version pin for ATA.
+	* Resolves the base package name for subpath imports (e.g., "framer-motion/dist" -> "framer-motion").
+	*/
+	pinImport(name) {
+		const base = getBasePackageName(name);
+		const version = this.pinnedTypeVersions[base];
+		if (version) return `import "${name}"; // types: ${version}`;
+		return `import "${name}";`;
 	}
 	async writeTypeFile(receivedPath, code) {
 		const normalized = receivedPath.replace(/^\//, "");
@@ -1419,7 +1752,8 @@ var Installer = class {
 			const response = await fetch(`https://registry.npmjs.org/${pkgName}`);
 			if (!response.ok) return;
 			const npmData = await response.json();
-			const version = npmData["dist-tags"]?.latest;
+			const pinnedVersion = this.pinnedTypeVersions[pkgName];
+			const version = pinnedVersion ? this.findMatchingVersion(Object.keys(npmData.versions ?? {}), pinnedVersion) : npmData["dist-tags"]?.latest;
 			if (!version || !npmData.versions?.[version]) return;
 			const pkg = npmData.versions[version];
 			if (pkg.exports) for (const key of Object.keys(pkg.exports)) pkg.exports[key] = fixExportTypes(pkg.exports[key]);
@@ -1427,6 +1761,17 @@ var Installer = class {
 			await fs.writeFile(pkgJsonPath, JSON.stringify(pkg, null, 2));
 		} catch {}
 	}
+	/**
+	* Find the best matching version from a list of available versions.
+	* Supports exact versions ("18.2.0") — returns exact match if available.
+	*/
+	findMatchingVersion(versions, pinned) {
+		if (versions.includes(pinned)) return pinned;
+		const [major, minor] = pinned.split(".");
+		const prefix = `${major}.${minor}.`;
+		const matching = versions.filter((v) => v.startsWith(prefix));
+		return matching.length > 0 ? matching[matching.length - 1] : void 0;
+	}
 	async ensureTsConfig() {
 		const tsconfigPath = path.join(this.projectDir, "tsconfig.json");
 		try {
@@ -1502,7 +1847,7 @@ declare module "*.json"
 				private: true,
 				description: "Framer files synced with framer-code-link"
 			};
-			await fs.writeFile(packagePath, JSON.stringify(pkg, null, 2));
+			await fs.writeFile(packagePath, JSON.stringify(pkg, null, 4));
 			debug("Created package.json");
 		}
 	}
@@ -1532,61 +1877,24 @@ declare module "*.json"
 		await fs.writeFile(gitignorePath, content);
 		debug("Created .gitignore");
 	}
-	async ensureReact18Types() {
-		const reactTypesDir = path.join(this.projectDir, "node_modules/@types/react");
-		const reactFiles = [
-			"package.json",
-			"index.d.ts",
-			"global.d.ts",
-			"jsx-runtime.d.ts",
-			"jsx-dev-runtime.d.ts"
-		];
-		if (await this.hasTypePackage(reactTypesDir, REACT_TYPES_VERSION, reactFiles)) debug("📦 React types (from cache)");
-		else {
-			debug("Downloading React 18 types...");
-			await this.downloadTypePackage("@types/react", REACT_TYPES_VERSION, reactTypesDir, reactFiles);
-		}
-		const reactDomDir = path.join(this.projectDir, "node_modules/@types/react-dom");
-		const reactDomFiles = [
-			"package.json",
-			"index.d.ts",
-			"client.d.ts"
-		];
-		if (await this.hasTypePackage(reactDomDir, REACT_DOM_TYPES_VERSION, reactDomFiles)) debug("📦 React DOM types (from cache)");
-		else await this.downloadTypePackage("@types/react-dom", REACT_DOM_TYPES_VERSION, reactDomDir, reactDomFiles);
-	}
-	async hasTypePackage(destinationDir, version, files) {
-		try {
-			const pkgJsonPath = path.join(destinationDir, "package.json");
-			const pkgJson = await fs.readFile(pkgJsonPath, "utf-8");
-			if (JSON.parse(pkgJson).version !== version) return false;
-			for (const file of files) {
-				if (file === "package.json") continue;
-				await fs.access(path.join(destinationDir, file));
-			}
-			return true;
-		} catch {
-			return false;
-		}
-	}
-	async downloadTypePackage(pkgName, version, destinationDir, files) {
-		const baseUrl = `https://unpkg.com/${pkgName}@${version}`;
-		await fs.mkdir(destinationDir, { recursive: true });
-		await Promise.all(files.map(async (file) => {
-			const destination = path.join(destinationDir, file);
-			try {
-				await fs.access(destination);
-				return;
-			} catch {}
-			try {
-				const response = await fetch(`${baseUrl}/${file}`);
-				if (!response.ok) return;
-				const content = await response.text();
-				await fs.writeFile(destination, content);
-			} catch {}
-		}));
-	}
 };
+function getManifestDependencyVersion(manifest, packageName) {
+	return manifest.peerDependencies?.[packageName] ?? manifest.dependencies?.[packageName];
+}
+function getBasePackageName(packageName) {
+	const parts = packageName.split("/");
+	if (packageName.startsWith("@")) return parts.length >= 2 ? parts.slice(0, 2).join("/") : packageName;
+	return parts[0] ?? packageName;
+}
+function normalizePinnedVersion(version) {
+	if (!version) return void 0;
+	return /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/.exec(version)?.[0];
+}
+async function fetchNpmPackageManifest(packageName) {
+	const response = await fetchWithRetry(`https://registry.npmjs.org/${packageName}/latest`);
+	if (!response.ok) throw new Error(`Failed to fetch ${packageName} manifest: ${response.status}`);
+	return await response.json();
+}
 /**
 * Transform package.json exports to include .d.ts type paths
 */
@@ -1634,11 +1942,12 @@ async function fetchWithRetry(url, init, retries = MAX_FETCH_RETRIES) {
 			if (isRetryable) checkFatalFailure(urlString);
 			if (attempt < retries && isRetryable) {
 				const delay = attempt * 1e3;
-				warn(`Fetch failed (${error.cause?.code ?? error.message}) for ${urlString}, retrying in ${delay}ms...`);
+				debug(`Fetch failed for ${urlString}, retrying...`, error);
 				await new Promise((resolve) => setTimeout(resolve, delay));
 				continue;
 			}
-			warn(`Fetch failed for ${urlString}`, error);
+			warn(`Fetch failed for ${urlString}`);
+			debug(`Fetch error details:`, error);
 			throw error;
 		}
 	}
@@ -1646,141 +1955,104 @@ async function fetchWithRetry(url, init, retries = MAX_FETCH_RETRIES) {
 }
 
 //#endregion
-//#region src/helpers/plugin-prompts.ts
-var PluginDisconnectedError = class extends Error {
-	constructor() {
-		super("Plugin disconnected");
-		this.name = "PluginDisconnectedError";
-	}
-};
-var PluginUserPromptCoordinator = class {
-	pendingActions = /* @__PURE__ */ new Map();
-	/**
-	* Register a pending action and return a typed promise
-	*/
-	awaitAction(actionId, description) {
-		return new Promise((resolve, reject) => {
-			this.pendingActions.set(actionId, {
-				resolve,
-				reject
-			});
-			debug(`Awaiting ${description}: ${actionId}`);
-		});
-	}
-	/**
-	* Sends the delete request to the plugin and awaits the user's decision.
-	* Returns the list of fileNames that were confirmed for deletion.
-	*/
-	async requestDeleteDecision(socket, { fileNames, requireConfirmation }) {
-		if (!socket) throw new Error("Cannot request delete decision: plugin not connected");
-		if (fileNames.length === 0) return [];
-		if (requireConfirmation) {
-			const confirmationPromises = fileNames.map((fileName) => this.awaitAction(`delete:${fileName}`, "delete confirmation").then((confirmed) => confirmed ? fileName : null).catch((err) => {
-				if (err instanceof PluginDisconnectedError) {
-					debug(`Plugin disconnected while waiting for delete confirmation: ${fileName}`);
-					return null;
-				}
-				throw err;
-			}));
-			await sendMessage(socket, {
-				type: "file-delete",
-				fileNames,
-				requireConfirmation: true
-			});
-			return (await Promise.all(confirmationPromises)).filter((name) => name !== null);
-		}
-		await sendMessage(socket, {
-			type: "file-delete",
-			fileNames,
-			requireConfirmation: false
-		});
-		return fileNames;
+//#region src/helpers/npm-strategy.ts
+const CONFIG_FIELD = "codeLinkNpmStrategy";
+const LOCKFILES = [
+	"yarn.lock",
+	"pnpm-lock.yaml",
+	"package-lock.json",
+	"bun.lockb"
+];
+async function resolveNpmStrategy(config, projectDir) {
+	if (config.npmStrategy) {
+		debug(`Using npm strategy from CLI flag: ${config.npmStrategy}`);
+		return config.npmStrategy;
 	}
-	/**
-	* Sends conflicts to the plugin and awaits user resolutions
-	*/
-	async requestConflictDecisions(socket, conflicts) {
-		if (!socket) throw new Error("Cannot request conflict decision: plugin not connected");
-		if (conflicts.length === 0) return /* @__PURE__ */ new Map();
-		const pending = conflicts.map((conflict) => ({
-			fileName: conflict.fileName,
-			promise: this.awaitAction(`conflict:${conflict.fileName}`, "conflict resolution")
-		}));
-		await sendMessage(socket, {
-			type: "conflicts-detected",
-			conflicts
-		});
-		try {
-			const results = await Promise.all(pending.map(async ({ fileName, promise }) => [fileName, await promise]));
-			return new Map(results);
-		} catch (err) {
-			if (err instanceof PluginDisconnectedError) {
-				debug("Plugin disconnected while awaiting conflict decisions");
-				return /* @__PURE__ */ new Map();
-			}
-			throw err;
-		}
+	const packageJsonStrategy = await readPackageJsonStrategy(projectDir);
+	if (packageJsonStrategy) {
+		debug(`Using npm strategy from package.json ${CONFIG_FIELD}: ${packageJsonStrategy}`);
+		return packageJsonStrategy;
 	}
-	/**
-	* Handle incoming confirmation response
-	*/
-	handleConfirmation(actionId, value) {
-		const pending = this.pendingActions.get(actionId);
-		if (!pending) {
-			debug(`Unexpected confirmation for ${actionId}`);
-			return false;
-		}
-		this.pendingActions.delete(actionId);
-		pending.resolve(value);
-		debug(`Confirmed: ${actionId}`);
-		return true;
+	const detectedLockfile = await detectLockfile(projectDir);
+	if (detectedLockfile) {
+		debug(`Using npm strategy package-manager from ${detectedLockfile}`);
+		return "package-manager";
 	}
-	/**
-	* Cleanup all pending actions (e.g., on disconnect)
-	*/
-	cleanup() {
-		for (const [actionId, pending] of this.pendingActions.entries()) {
-			pending.reject(new PluginDisconnectedError());
-			debug(`Cancelled pending action: ${actionId}`);
-		}
-		this.pendingActions.clear();
+	debug("Using default npm strategy: none");
+	return "none";
+}
+async function readPackageJsonStrategy(projectDir) {
+	try {
+		const raw = await fs.readFile(path.join(projectDir, "package.json"), "utf-8");
+		const strategy = JSON.parse(raw).codeLinkNpmStrategy;
+		if (strategy === void 0) return null;
+		if (isNpmStrategy(strategy)) return strategy;
+		warn(`Ignoring invalid package.json ${CONFIG_FIELD}: ${String(strategy)}`);
+		return null;
+	} catch {
+		return null;
 	}
+}
+async function detectLockfile(projectDir) {
+	for (const fileName of LOCKFILES) try {
+		await fs.access(path.join(projectDir, fileName));
+		return fileName;
+	} catch {}
+	return null;
+}
+function isNpmStrategy(value) {
+	return value === "none" || value === "acquire-types" || value === "package-manager";
+}
+
+//#endregion
+//#region src/scheduler.ts
+const TIMINGS = {
+	disconnectNotice: 4e3,
+	expectedDeleteEchoExpiry: 5e3,
+	renameBuffer: 100,
+	sanitizationEchoExpiry: 300
 };
+function timerId(task, key) {
+	return key !== void 0 ? `${task}:${key}` : task;
+}
+function createScheduler() {
+	const timers = /* @__PURE__ */ new Map();
+	return {
+		after(task, delayMs, fn, key) {
+			const id = timerId(task, key);
+			const existing = timers.get(id);
+			if (existing !== void 0) clearTimeout(existing);
+			const handle = setTimeout(() => {
+				timers.delete(id);
+				fn();
+			}, delayMs);
+			timers.set(id, handle);
+		},
+		cancel(task, key) {
+			const id = timerId(task, key);
+			const handle = timers.get(id);
+			if (handle !== void 0) {
+				clearTimeout(handle);
+				timers.delete(id);
+			}
+		},
+		cancelAll() {
+			for (const handle of timers.values()) clearTimeout(handle);
+			timers.clear();
+		}
+	};
+}
 
 //#endregion
-//#region src/helpers/sync-validator.ts
+//#region src/utils/node-paths.ts
 /**
-* Validates whether an incoming REMOTE file change should be applied
-*
-* During watching mode, we trust remote changes and apply them immediately.
-* During snapshot_processing, we queue them for later (to avoid race conditions).
-*
-* Note: This is for INCOMING changes from remote. Local changes (from watcher)
-* are handled separately and always sent during watching mode.
+* Path manipulation utilities
 */
-function validateIncomingChange(fileMeta, currentMode) {
-	if (currentMode === "snapshot_processing" || currentMode === "handshaking") return {
-		action: "queue",
-		reason: "snapshot-in-progress"
-	};
-	if (currentMode === "watching") {
-		if (!fileMeta) return {
-			action: "apply",
-			reason: "new-file"
-		};
-		return {
-			action: "apply",
-			reason: "safe-update"
-		};
-	}
-	if (currentMode === "conflict_resolution") return {
-		action: "queue",
-		reason: "snapshot-in-progress"
-	};
-	return {
-		action: "reject",
-		reason: "unknown-file"
-	};
+/**
+* Gets a relative path from the project directory
+*/
+function getRelativePath(projectDir, absolutePath) {
+	return path.relative(projectDir, absolutePath);
 }
 
 //#endregion
@@ -1790,47 +2062,240 @@ function validateIncomingChange(fileMeta, currentMode) {
 *
 * Wrapper around chokidar that normalizes file paths and filters to ts, tsx, js, json.
 */
+function findUniqueHashMatch(pendingItems, contentHash) {
+	let matchingKey;
+	for (const [key, pending] of pendingItems) {
+		if (pending.contentHash !== contentHash) continue;
+		if (matchingKey !== void 0) return;
+		matchingKey = key;
+	}
+	return matchingKey;
+}
+function matchPendingAddForDelete(contentHash, pendingAdds) {
+	if (!contentHash) return null;
+	const matchingAddKey = findUniqueHashMatch(pendingAdds, contentHash);
+	if (!matchingAddKey) return null;
+	const pendingAdd = pendingAdds.get(matchingAddKey);
+	if (!pendingAdd) return null;
+	return {
+		key: matchingAddKey,
+		pendingAdd
+	};
+}
+function matchPendingDeleteForAdd(contentHash, pendingDeletes) {
+	const matchingDeleteKey = findUniqueHashMatch(pendingDeletes, contentHash);
+	if (!matchingDeleteKey) return null;
+	const pendingDelete = pendingDeletes.get(matchingDeleteKey);
+	if (!pendingDelete) return null;
+	return {
+		key: matchingDeleteKey,
+		pendingDelete
+	};
+}
 /**
 * Initializes a file watcher for the given directory
 */
 function initWatcher(filesDir) {
 	const handlers = [];
+	const scheduler = createScheduler();
+	const contentHashCache = /* @__PURE__ */ new Map();
+	const pendingDeletes = /* @__PURE__ */ new Map();
+	const pendingAdds = /* @__PURE__ */ new Map();
+	const recentSanitizations = /* @__PURE__ */ new Set();
 	const watcher = chokidar.watch(filesDir, {
 		ignored: /(^|[/\\])\.\./,
 		persistent: true,
 		ignoreInitial: false
 	});
 	debug(`Watching directory: ${filesDir}`);
-	const emitEvent = async (kind, absolutePath) => {
-		if (!isSupportedExtension$1(absolutePath)) return;
-		const rawRelativePath = normalizePath$1(getRelativePath(filesDir, absolutePath));
-		const relativePath = sanitizeFilePath(rawRelativePath, false).path;
+	const dispatchEvent = (event) => {
+		let eventToDispatch = event;
+		if (event.kind === "rename" && event.relativePath === event.oldRelativePath) {
+			if (event.content === void 0) {
+				warn(`Skipping invalid same-path rename without content: ${event.relativePath}`);
+				return;
+			}
+			debug(`Converting same-path rename to change: ${event.relativePath}`);
+			eventToDispatch = {
+				kind: "change",
+				relativePath: event.relativePath,
+				content: event.content
+			};
+		}
+		debug(`Watcher event: ${eventToDispatch.kind} ${eventToDispatch.relativePath}`);
+		for (const handler of handlers) handler(eventToDispatch);
+	};
+	/**
+	* Resolves the relative path identity for a watcher event.
+	* Only "add" may rewrite that identity by successfully sanitizing on disk.
+	*/
+	const resolveRelativePath = async (kind, absolutePath) => {
+		if (!isSupportedExtension$1(absolutePath)) return null;
+		const rawRelativePath = normalizePath(getRelativePath(filesDir, absolutePath));
+		let relativePath = rawRelativePath;
 		let effectiveAbsolutePath = absolutePath;
-		if (relativePath !== rawRelativePath && kind === "add") {
-			const newAbsolutePath = path.join(filesDir, relativePath);
-			try {
-				await fs.mkdir(path.dirname(newAbsolutePath), { recursive: true });
-				await fs.rename(absolutePath, newAbsolutePath);
-				debug(`Renamed ${rawRelativePath} -> ${relativePath}`);
-				effectiveAbsolutePath = newAbsolutePath;
-			} catch (err) {
-				warn(`Failed to rename ${rawRelativePath}`, err);
+		if (kind === "add") {
+			const sanitized = sanitizeFilePath(rawRelativePath, false);
+			if (sanitized.path !== rawRelativePath) {
+				const nextRelativePath = sanitized.path;
+				const newAbsolutePath = path.join(filesDir, nextRelativePath);
+				try {
+					await fs.mkdir(path.dirname(newAbsolutePath), { recursive: true });
+					await fs.rename(absolutePath, newAbsolutePath);
+					debug(`Renamed ${rawRelativePath} -> ${nextRelativePath}`);
+					relativePath = nextRelativePath;
+					effectiveAbsolutePath = newAbsolutePath;
+					recentSanitizations.add(rawRelativePath);
+					recentSanitizations.add(nextRelativePath);
+					scheduler.after("sanitizationEchoExpiry", TIMINGS.sanitizationEchoExpiry, () => {
+						recentSanitizations.delete(rawRelativePath);
+						recentSanitizations.delete(nextRelativePath);
+					}, `${rawRelativePath}\0${nextRelativePath}`);
+				} catch (err) {
+					warn(`Failed to rename ${rawRelativePath}`, err);
+					return {
+						relativePath: rawRelativePath,
+						effectiveAbsolutePath: absolutePath
+					};
+				}
 			}
 		}
+		return {
+			relativePath,
+			effectiveAbsolutePath
+		};
+	};
+	const emitEvent = async (kind, absolutePath) => {
+		const rawRelPath = normalizePath(getRelativePath(filesDir, absolutePath));
+		if (recentSanitizations.delete(rawRelPath)) {
+			debug(`Suppressing sanitization echo: ${kind} ${rawRelPath}`);
+			return;
+		}
+		const resolved = await resolveRelativePath(kind, absolutePath);
+		if (!resolved) return;
+		const { relativePath, effectiveAbsolutePath } = resolved;
+		if (kind === "delete") {
+			const lastHash = contentHashCache.get(relativePath);
+			contentHashCache.delete(relativePath);
+			const samePathPendingAdd = pendingAdds.get(relativePath);
+			if (samePathPendingAdd) {
+				scheduler.cancel("renameBuffer", relativePath);
+				pendingAdds.delete(relativePath);
+				try {
+					const latestContent = await fs.readFile(effectiveAbsolutePath, "utf-8");
+					const latestHash = hashFileContent(latestContent);
+					contentHashCache.set(relativePath, latestHash);
+					dispatchEvent({
+						kind: "change",
+						relativePath,
+						content: latestContent
+					});
+				} catch {
+					if (samePathPendingAdd.previousContentHash !== void 0) dispatchEvent({
+						kind: "delete",
+						relativePath
+					});
+					else debug(`Suppressing transient add+delete: ${relativePath}`);
+				}
+				return;
+			}
+			const matchedAdd = matchPendingAddForDelete(lastHash, pendingAdds);
+			if (matchedAdd) {
+				scheduler.cancel("renameBuffer", matchedAdd.key);
+				pendingAdds.delete(matchedAdd.key);
+				dispatchEvent({
+					kind: "rename",
+					relativePath: matchedAdd.pendingAdd.relativePath,
+					oldRelativePath: relativePath,
+					content: matchedAdd.pendingAdd.content
+				});
+				return;
+			}
+			if (lastHash) {
+				scheduler.after("renameBuffer", TIMINGS.renameBuffer, () => {
+					pendingDeletes.delete(relativePath);
+					dispatchEvent({
+						kind: "delete",
+						relativePath
+					});
+				}, relativePath);
+				pendingDeletes.set(relativePath, {
+					relativePath,
+					contentHash: lastHash
+				});
+			} else dispatchEvent({
+				kind: "delete",
+				relativePath
+			});
+			return;
+		}
 		let content;
-		if (kind !== "delete") try {
+		try {
 			content = await fs.readFile(effectiveAbsolutePath, "utf-8");
 		} catch (err) {
 			debug(`Failed to read file ${relativePath}:`, err);
 			return;
 		}
-		const event = {
+		const previousContentHash = contentHashCache.get(relativePath);
+		const contentHash = hashFileContent(content);
+		contentHashCache.set(relativePath, contentHash);
+		if (kind === "add") {
+			if (pendingDeletes.get(relativePath)) {
+				scheduler.cancel("renameBuffer", relativePath);
+				pendingDeletes.delete(relativePath);
+				dispatchEvent({
+					kind: "change",
+					relativePath,
+					content
+				});
+				return;
+			}
+			const matchedDelete = matchPendingDeleteForAdd(contentHash, pendingDeletes);
+			if (matchedDelete) {
+				scheduler.cancel("renameBuffer", matchedDelete.key);
+				pendingDeletes.delete(matchedDelete.key);
+				dispatchEvent({
+					kind: "rename",
+					relativePath,
+					oldRelativePath: matchedDelete.pendingDelete.relativePath,
+					content
+				});
+				return;
+			}
+			const existingPendingAdd = pendingAdds.get(relativePath);
+			if (existingPendingAdd) scheduler.cancel("renameBuffer", relativePath);
+			const retainedPreviousContentHash = existingPendingAdd ? existingPendingAdd.previousContentHash : previousContentHash;
+			scheduler.after("renameBuffer", TIMINGS.renameBuffer, () => {
+				pendingAdds.delete(relativePath);
+				dispatchEvent({
+					kind: "add",
+					relativePath,
+					content
+				});
+			}, relativePath);
+			pendingAdds.set(relativePath, {
+				relativePath,
+				contentHash,
+				content,
+				previousContentHash: retainedPreviousContentHash
+			});
+			return;
+		}
+		if (pendingAdds.get(relativePath)) {
+			scheduler.cancel("renameBuffer", relativePath);
+			pendingAdds.delete(relativePath);
+			dispatchEvent({
+				kind: "add",
+				relativePath,
+				content
+			});
+			return;
+		}
+		dispatchEvent({
 			kind,
 			relativePath,
 			content
-		};
-		debug(`Watcher event: ${kind} ${relativePath}`);
-		for (const handler of handlers) handler(event);
+		});
 	};
 	watcher.on("add", (filePath) => {
 		emitEvent("add", filePath);
@@ -1846,6 +2311,11 @@ function initWatcher(filesDir) {
 			handlers.push(handler);
 		},
 		async close() {
+			scheduler.cancelAll();
+			pendingDeletes.clear();
+			pendingAdds.clear();
+			contentHashCache.clear();
+			recentSanitizations.clear();
 			await watcher.close();
 		}
 	};
@@ -1935,58 +2405,380 @@ var FileMetadataCache = class {
 };
 
 //#endregion
-//#region src/utils/hash-tracker.ts
+//#region src/sync-memory.ts
 /**
-* Hash tracking utilities for echo prevention
+* SyncMemory owns file-level sync truth.
 *
-* The hash tracker prevents echo loops by remembering content hashes
-* and skipping watcher events for files we just wrote.
+* If a race depends on path normalization, content echoes, expected delete echoes,
+* or agreed metadata, it belongs here. Controller/apply code should call these
+* named operations instead of touching the underlying maps directly.
 */
+var SyncMemory = class {
+	metadata = new FileMetadataCache();
+	contentEchoes = /* @__PURE__ */ new Map();
+	expectedDeleteEchoes = /* @__PURE__ */ new Set();
+	scheduler = createScheduler();
+	normalizePath(filePath) {
+		return normalizeCodeFilePathWithExtension(filePath);
+	}
+	metadataFor(filePath) {
+		return this.metadata.get(filePath);
+	}
+	persistedSnapshot() {
+		return this.metadata.getPersistedState();
+	}
+	recordSyncedContent(filePath, content, modifiedAt) {
+		this.metadata.recordSyncedSnapshot(filePath, hashFileContent(content), modifiedAt);
+	}
+	recordSyncedDelete(filePath) {
+		this.clearContentEcho(filePath);
+		this.metadata.recordDelete(filePath);
+	}
+	matchesAgreedContent(filePath, content) {
+		return this.metadataFor(filePath)?.lastSyncedHash === hashFileContent(content);
+	}
+	armContentEcho(filePath, content) {
+		const path = this.normalizePath(filePath);
+		this.contentEchoes.set(path, hashFileContent(content));
+		return {
+			path,
+			content
+		};
+	}
+	matchesContentEcho(filePath, content) {
+		return this.contentEchoes.get(this.normalizePath(filePath)) === hashFileContent(content);
+	}
+	clearContentEcho(filePath) {
+		this.contentEchoes.delete(this.normalizePath(filePath));
+	}
+	clearAllContentEchoes() {
+		this.contentEchoes.clear();
+	}
+	isContentEcho(filePath, content) {
+		return this.matchesAgreedContent(filePath, content) || this.matchesContentEcho(filePath, content);
+	}
+	commitWriteSuccess(prepared, modifiedAt) {
+		this.recordSyncedContent(prepared.path, prepared.content, modifiedAt);
+	}
+	rollbackWriteFailure(prepared) {
+		if (this.matchesContentEcho(prepared.path, prepared.content)) this.clearContentEcho(prepared.path);
+	}
+	armExpectedDeleteEcho(filePath) {
+		const path = this.normalizePath(filePath);
+		this.scheduler.cancel("expectedDeleteEchoExpiry", path);
+		this.expectedDeleteEchoes.add(path);
+		this.scheduler.after("expectedDeleteEchoExpiry", TIMINGS.expectedDeleteEchoExpiry, () => {
+			this.expectedDeleteEchoes.delete(path);
+		}, path);
+		return { path };
+	}
+	matchesExpectedDeleteEcho(filePath) {
+		return this.expectedDeleteEchoes.has(this.normalizePath(filePath));
+	}
+	clearExpectedDeleteEcho(filePath) {
+		const path = this.normalizePath(filePath);
+		this.scheduler.cancel("expectedDeleteEchoExpiry", path);
+		this.expectedDeleteEchoes.delete(path);
+	}
+	commitDeleteSuccess(prepared) {
+		this.clearContentEcho(prepared.path);
+		this.recordSyncedDelete(prepared.path);
+	}
+	rollbackExpectedDeleteEcho(prepared) {
+		this.clearExpectedDeleteEcho(prepared.path);
+	}
+};
+
+//#endregion
+//#region src/runtime.ts
+function sameSession(a, b) {
+	return a.connectionId === b.connectionId && a.promptId === b.promptId;
+}
+function createPromptSession(connectionId) {
+	return {
+		connectionId,
+		promptId: randomUUID()
+	};
+}
+function conflictIsResolved(conflict) {
+	return conflict.localContent === conflict.remoteContent;
+}
+function resolvedPromptConflict(conflict) {
+	return {
+		fileName: conflict.fileName,
+		content: conflict.localContent,
+		modifiedAt: conflict.remoteModifiedAt ?? conflict.localModifiedAt
+	};
+}
+function normalizeConflict(filePath, conflict) {
+	return {
+		...conflict,
+		fileName: filePath(conflict.fileName)
+	};
+}
 /**
-* Creates a hash tracker instance for echo prevention
+* SyncRuntime owns lifecycle truth.
+*
+* Search this file and `sync-memory.ts` first for race-sensitive state.
+* Lifecycle state lives here; file-level sync facts live on `memory`.
 */
-function createHashTracker() {
-	const hashes = /* @__PURE__ */ new Map();
-	const pendingDeletes = /* @__PURE__ */ new Map();
-	return {
-		remember(filePath, content) {
-			const hash = hashContent(content);
-			hashes.set(filePath, hash);
-		},
-		shouldSkip(filePath, content) {
-			const currentHash = hashContent(content);
-			return hashes.get(filePath) === currentHash;
-		},
-		forget(filePath) {
-			hashes.delete(filePath);
-		},
-		clear() {
-			hashes.clear();
-		},
-		markDelete(filePath) {
-			const existingTimer = pendingDeletes.get(filePath);
-			if (existingTimer) clearTimeout(existingTimer);
-			const timeout = setTimeout(() => {
-				pendingDeletes.delete(filePath);
-			}, 5e3);
-			pendingDeletes.set(filePath, timeout);
+var SyncRuntime = class {
+	memory = new SyncMemory();
+	pendingRenameConfirmations = /* @__PURE__ */ new Map();
+	disconnectScheduler = createScheduler();
+	activeDeletePrompt = null;
+	activeConflictPrompt = null;
+	pendingSyncCompletionEvent = null;
+	installer = null;
+	connectionSeq = 0;
+	activeConnectionId = 0;
+	isShowingDisconnect = false;
+	hadRecentDisconnect = false;
+	lastEmittedStatus = null;
+	workspaceState = {
+		projectDir: null,
+		filesDir: null,
+		projectDirCreated: false
+	};
+	get workspace() {
+		return this.workspaceState;
+	}
+	get metadata() {
+		return this.memory.metadata;
+	}
+	configureWorkspace(projectDir, projectDirCreated) {
+		this.workspaceState.projectDir = projectDir;
+		this.workspaceState.filesDir = path.join(projectDir, "files");
+		this.workspaceState.projectDirCreated = projectDirCreated;
+	}
+	mintConnectionId() {
+		this.connectionSeq += 1;
+		this.activeConnectionId = this.connectionSeq;
+		return this.activeConnectionId;
+	}
+	get connectionId() {
+		return this.activeConnectionId;
+	}
+	noteEmittedSyncStatus(status) {
+		this.lastEmittedStatus = status;
+	}
+	clearEmittedSyncStatus() {
+		this.lastEmittedStatus = null;
+	}
+	get lastEmittedSyncStatus() {
+		return this.lastEmittedStatus;
+	}
+	disconnectUi = {
+		scheduleNotice: (callback) => {
+			this.disconnectScheduler.cancel("disconnectNotice");
+			this.hadRecentDisconnect = true;
+			this.isShowingDisconnect = false;
+			this.disconnectScheduler.after("disconnectNotice", TIMINGS.disconnectNotice, () => {
+				this.isShowingDisconnect = true;
+				callback();
+			});
 		},
-		shouldSkipDelete(filePath) {
-			return pendingDeletes.has(filePath);
+		cancelNotice: () => {
+			this.disconnectScheduler.cancel("disconnectNotice");
 		},
-		clearDelete(filePath) {
-			const timeout = pendingDeletes.get(filePath);
-			if (timeout) clearTimeout(timeout);
-			pendingDeletes.delete(filePath);
+		didShowNotice: () => this.isShowingDisconnect,
+		wasRecentlyDisconnected: () => this.hadRecentDisconnect,
+		reset: () => {
+			this.isShowingDisconnect = false;
+			this.hadRecentDisconnect = false;
 		}
 	};
-}
-/**
-* Computes a SHA256 hash of file content for comparison
-*/
-function hashContent(content) {
-	return createHash("sha256").update(content).digest("hex");
-}
+	getPendingRename(newPath) {
+		return this.pendingRenameConfirmations.get(normalizeCodeFilePathWithExtension(newPath));
+	}
+	registerPendingRename(newPath, value) {
+		this.pendingRenameConfirmations.set(normalizeCodeFilePathWithExtension(newPath), value);
+	}
+	completePendingRename(newPath) {
+		this.pendingRenameConfirmations.delete(normalizeCodeFilePathWithExtension(newPath));
+	}
+	clearPendingRenames() {
+		this.pendingRenameConfirmations.clear();
+	}
+	startDeletePrompt(fileNames) {
+		const prompt = this.activeDeletePrompt ?? {
+			session: createPromptSession(this.connectionId),
+			fileNames: /* @__PURE__ */ new Set()
+		};
+		const newNames = [];
+		for (const fileName of fileNames) {
+			const normalized = this.memory.normalizePath(fileName);
+			if (prompt.fileNames.has(normalized)) continue;
+			prompt.fileNames.add(normalized);
+			newNames.push(normalized);
+		}
+		this.activeDeletePrompt = prompt;
+		return newNames.length > 0 ? {
+			session: prompt.session,
+			fileNames: newNames
+		} : null;
+	}
+	hasActiveDeletePrompt(session) {
+		return this.activeDeletePrompt !== null && sameSession(this.activeDeletePrompt.session, session);
+	}
+	getDeletePromptFileNames(session, fileNames) {
+		const prompt = this.activeDeletePrompt;
+		if (!prompt || !sameSession(prompt.session, session)) return null;
+		const active = (fileNames.length > 0 ? fileNames.map((fileName) => this.memory.normalizePath(fileName)) : [...prompt.fileNames.values()]).filter((fileName) => prompt.fileNames.has(fileName));
+		return active.length > 0 ? active : null;
+	}
+	clearDeletePromptFiles(session, fileNames) {
+		const prompt = this.activeDeletePrompt;
+		if (!prompt || !sameSession(prompt.session, session)) return false;
+		const requested = fileNames.length > 0 ? fileNames : [...prompt.fileNames.values()];
+		for (const fileName of requested) prompt.fileNames.delete(this.memory.normalizePath(fileName));
+		if (prompt.fileNames.size === 0) this.activeDeletePrompt = null;
+		return true;
+	}
+	isActiveDeletePromptPath(filePath) {
+		return this.activeDeletePrompt?.fileNames.has(this.memory.normalizePath(filePath)) ?? false;
+	}
+	hasAnyActivePrompt() {
+		return this.activeDeletePrompt !== null || this.activeConflictPrompt !== null;
+	}
+	deferSyncComplete(syncComplete) {
+		this.pendingSyncCompletionEvent = this.pendingSyncCompletionEvent === null ? syncComplete : {
+			totalCount: this.pendingSyncCompletionEvent.totalCount + syncComplete.totalCount,
+			updatedCount: this.pendingSyncCompletionEvent.updatedCount + syncComplete.updatedCount,
+			unchangedCount: this.pendingSyncCompletionEvent.unchangedCount + syncComplete.unchangedCount
+		};
+	}
+	/**
+	* Claims the pending sync-complete event and clears it when ready to fire.
+	* - `ready`: payload is returned and the slot is cleared.
+	* - `blocked`: payload remains pending until prompts clear.
+	* - `empty`: nothing was pending.
+	*/
+	claimPendingSyncComplete() {
+		if (this.pendingSyncCompletionEvent === null) return { status: "empty" };
+		if (this.hasAnyActivePrompt()) return { status: "blocked" };
+		const syncComplete = this.pendingSyncCompletionEvent;
+		this.pendingSyncCompletionEvent = null;
+		return {
+			status: "ready",
+			payload: syncComplete
+		};
+	}
+	invalidateDeletePromptPath(filePath) {
+		const prompt = this.activeDeletePrompt;
+		const normalized = this.memory.normalizePath(filePath);
+		if (!prompt || !prompt.fileNames.has(normalized)) return { changed: false };
+		prompt.fileNames.delete(normalized);
+		const cleared = prompt.fileNames.size === 0;
+		if (cleared) this.activeDeletePrompt = null;
+		return {
+			changed: true,
+			session: prompt.session,
+			fileNames: [normalized],
+			cleared
+		};
+	}
+	startOrUpdateConflictPrompt(conflicts) {
+		if (conflicts.length === 0) return null;
+		const prompt = this.activeConflictPrompt ?? {
+			session: createPromptSession(this.connectionId),
+			conflicts: /* @__PURE__ */ new Map()
+		};
+		for (const conflict of conflicts) {
+			const normalized = normalizeConflict((filePath) => this.memory.normalizePath(filePath), conflict);
+			if (conflictIsResolved(normalized)) prompt.conflicts.delete(normalized.fileName);
+			else prompt.conflicts.set(normalized.fileName, normalized);
+		}
+		const nextConflicts = [...prompt.conflicts.values()];
+		this.activeConflictPrompt = nextConflicts.length > 0 ? prompt : null;
+		return nextConflicts.length > 0 ? {
+			session: prompt.session,
+			conflicts: nextConflicts
+		} : null;
+	}
+	getActiveConflictPrompt() {
+		const prompt = this.activeConflictPrompt;
+		return prompt ? {
+			session: prompt.session,
+			conflicts: [...prompt.conflicts.values()]
+		} : null;
+	}
+	getConflictPromptConflicts(session, fileNames) {
+		const prompt = this.activeConflictPrompt;
+		if (!prompt || !sameSession(prompt.session, session)) return null;
+		const conflicts = (fileNames.length > 0 ? fileNames.map((fileName) => this.memory.normalizePath(fileName)) : [...prompt.conflicts.keys()]).map((fileName) => prompt.conflicts.get(fileName)).filter((conflict) => conflict !== void 0);
+		return conflicts.length > 0 ? conflicts : null;
+	}
+	clearConflictPromptFiles(session, fileNames) {
+		const prompt = this.activeConflictPrompt;
+		if (!prompt || !sameSession(prompt.session, session)) return false;
+		const requested = fileNames.length > 0 ? fileNames : [...prompt.conflicts.keys()];
+		for (const fileName of requested) prompt.conflicts.delete(this.memory.normalizePath(fileName));
+		if (prompt.conflicts.size === 0) this.activeConflictPrompt = null;
+		return true;
+	}
+	isActiveConflictPath(filePath) {
+		return this.activeConflictPrompt?.conflicts.has(this.memory.normalizePath(filePath)) ?? false;
+	}
+	updateActiveConflictLocal(filePath, content, modifiedAt) {
+		const prompt = this.activeConflictPrompt;
+		const key = this.memory.normalizePath(filePath);
+		const conflict = prompt?.conflicts.get(key);
+		if (!prompt || !conflict) return { changed: false };
+		const next = {
+			...conflict,
+			fileName: key,
+			localContent: content,
+			localModifiedAt: modifiedAt
+		};
+		const resolved = conflictIsResolved(next) ? [resolvedPromptConflict(next)] : [];
+		if (resolved.length > 0) prompt.conflicts.delete(key);
+		else prompt.conflicts.set(key, next);
+		const conflicts = [...prompt.conflicts.values()];
+		const cleared = conflicts.length === 0;
+		if (cleared) this.activeConflictPrompt = null;
+		return {
+			changed: true,
+			session: prompt.session,
+			conflicts,
+			cleared,
+			resolved
+		};
+	}
+	updateActiveConflictRemote(filePath, content, modifiedAt) {
+		const prompt = this.activeConflictPrompt;
+		const key = this.memory.normalizePath(filePath);
+		const conflict = prompt?.conflicts.get(key);
+		if (!prompt || !conflict) return { changed: false };
+		const next = {
+			...conflict,
+			fileName: key,
+			remoteContent: content,
+			remoteModifiedAt: modifiedAt
+		};
+		const resolved = conflictIsResolved(next) ? [resolvedPromptConflict(next)] : [];
+		if (resolved.length > 0) prompt.conflicts.delete(key);
+		else prompt.conflicts.set(key, next);
+		const conflicts = [...prompt.conflicts.values()];
+		const cleared = conflicts.length === 0;
+		if (cleared) this.activeConflictPrompt = null;
+		return {
+			changed: true,
+			session: prompt.session,
+			conflicts,
+			cleared,
+			resolved
+		};
+	}
+	resetPrompts() {
+		this.activeDeletePrompt = null;
+		this.activeConflictPrompt = null;
+		this.pendingSyncCompletionEvent = null;
+	}
+	cleanupUserActions() {
+		this.resetPrompts();
+	}
+};
 
 //#endregion
 //#region src/utils/project.ts
@@ -1994,7 +2786,7 @@ function toPackageName(name) {
 	return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
 }
 function toDirectoryName(name) {
-	return name.replace(/[^a-zA-Z0-9-]/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
+	return name.replace(/[^a-zA-Z0-9 -]/g, "-").trim().replace(/^-+|-+$/g, "").replace(/-+/g, "-");
 }
 async function getProjectHashFromCwd() {
 	try {
@@ -2034,7 +2826,7 @@ async function findOrCreateProjectDirectory(options) {
 		shortProjectHash: shortId,
 		framerProjectName: projectName
 	};
-	await fs.writeFile(path.join(projectDirectory, "package.json"), JSON.stringify(pkg, null, 2));
+	await fs.writeFile(path.join(projectDirectory, "package.json"), JSON.stringify(pkg, null, 4));
 	return {
 		directory: projectDirectory,
 		created: true,
@@ -2083,6 +2875,14 @@ async function matchesProject(packageJsonPath, projectHash) {
 
 //#endregion
 //#region src/controller.ts
+function createEventQueue() {
+	let tail = Promise.resolve();
+	return { enqueue(fn) {
+		const run = tail.then(() => fn());
+		tail = run.catch(() => {});
+		return run;
+	} };
+}
 /** Log helper */
 function log(level, message) {
 	return {
@@ -2091,16 +2891,34 @@ function log(level, message) {
 		message
 	};
 }
+function updatePendingConflictRemote(pendingConflicts, fileName, content, modifiedAt) {
+	const normalized = normalizeCodeFilePathWithExtension(fileName);
+	let changed = false;
+	const conflicts = pendingConflicts.map((conflict) => {
+		if (normalizeCodeFilePathWithExtension(conflict.fileName) !== normalized) return conflict;
+		changed = true;
+		return {
+			...conflict,
+			fileName: normalized,
+			remoteContent: content,
+			remoteModifiedAt: modifiedAt
+		};
+	});
+	return {
+		changed,
+		conflicts
+	};
+}
 /**
-* Pure state transition function
+* State transition
 * Takes current state + event, returns new state + effects to execute
 */
-function transition(state, event) {
+function transition(state, event, read = {}) {
 	const effects = [];
 	switch (event.type) {
 		case "HANDSHAKE":
-			if (state.mode !== "disconnected") {
-				effects.push(log("warn", `Received HANDSHAKE in mode ${state.mode}, ignoring`));
+			if (state.phase !== "disconnected") {
+				effects.push(log("warn", `Received HANDSHAKE in phase=${state.phase}, ignoring`));
 				return {
 					state,
 					effects
@@ -2112,15 +2930,26 @@ function transition(state, event) {
 			}, { type: "LOAD_PERSISTED_STATE" }, {
 				type: "SEND_MESSAGE",
 				payload: { type: "request-files" }
+			}, {
+				type: "EMIT_SYNC_STATUS",
+				status: "initial_sync"
 			});
 			return {
 				state: {
-					...state,
-					mode: "handshaking",
+					phase: "handshaking",
 					socket: event.socket
 				},
 				effects
 			};
+		case "RESEND_SYNC_STATUS":
+			effects.push(log("debug", `Re-emitting sync-status=${event.status} for duplicate handshake`), {
+				type: "EMIT_SYNC_STATUS",
+				status: event.status
+			});
+			return {
+				state,
+				effects
+			};
 		case "FILE_SYNCED_CONFIRMATION":
 			effects.push(log("debug", `Remote confirmed sync: ${event.fileName}`), {
 				type: "UPDATE_FILE_METADATA",
@@ -2133,27 +2962,15 @@ function transition(state, event) {
 			};
 		case "DISCONNECT":
 			effects.push({ type: "PERSIST_STATE" }, log("debug", "Disconnected, persisting state"));
-			if (state.mode === "conflict_resolution") {
-				const { pendingConflicts: _discarded, ...rest } = state;
-				return {
-					state: {
-						...rest,
-						mode: "disconnected",
-						socket: null
-					},
-					effects
-				};
-			}
 			return {
 				state: {
-					...state,
-					mode: "disconnected",
+					phase: "disconnected",
 					socket: null
 				},
 				effects
 			};
 		case "REQUEST_FILES":
-			if (state.mode === "disconnected") {
+			if (state.phase === "disconnected") {
 				effects.push(log("warn", "Received REQUEST_FILES while disconnected, ignoring"));
 				return {
 					state,
@@ -2166,8 +2983,8 @@ function transition(state, event) {
 				effects
 			};
 		case "REMOTE_FILE_LIST":
-			if (state.mode !== "handshaking") {
-				effects.push(log("warn", `Received REMOTE_FILE_LIST in mode ${state.mode}, ignoring`));
+			if (state.phase !== "handshaking") {
+				effects.push(log("warn", `Received REMOTE_FILE_LIST in phase=${state.phase}, ignoring`));
 				return {
 					state,
 					effects
@@ -2180,39 +2997,36 @@ function transition(state, event) {
 			});
 			return {
 				state: {
-					...state,
-					mode: "snapshot_processing",
-					pendingRemoteChanges: event.files
+					phase: "snapshot_processing",
+					socket: state.socket
 				},
 				effects
 			};
 		case "CONFLICTS_DETECTED": {
-			if (state.mode !== "snapshot_processing") {
-				effects.push(log("warn", `Received CONFLICTS_DETECTED in mode ${state.mode}, ignoring`));
+			if (state.phase !== "snapshot_processing") {
+				effects.push(log("warn", `Received CONFLICTS_DETECTED in phase=${state.phase}, ignoring`));
 				return {
 					state,
 					effects
 				};
 			}
-			const { conflicts, safeWrites, localOnly } = event;
+			const { conflicts, safeWrites, localOnly, remoteTotal } = event;
 			if (safeWrites.length > 0) {
 				effects.push(log("debug", `Applying ${safeWrites.length} safe writes`));
-				if (wasRecentlyDisconnected()) effects.push(log("success", `Applied ${pluralize(safeWrites.length, "file")} during sync`));
+				if (read.wasRecentlyDisconnected?.()) effects.push(log("success", `Applied ${pluralize(safeWrites.length, "file")} during sync`));
 				effects.push({
 					type: "WRITE_FILES",
 					files: safeWrites,
-					silent: true
+					silent: true,
+					echoPolicy: "authoritative"
 				});
 			}
 			if (localOnly.length > 0) {
 				effects.push(log("debug", `Uploading ${pluralize(localOnly.length, "local-only file")}`));
 				for (const file of localOnly) effects.push({
-					type: "SEND_MESSAGE",
-					payload: {
-						type: "file-change",
-						fileName: file.name,
-						content: file.content
-					}
+					type: "SEND_LOCAL_CHANGE",
+					fileName: file.name,
+					content: file.content
 				});
 			}
 			if (conflicts.length > 0) {
@@ -2222,14 +3036,13 @@ function transition(state, event) {
 				});
 				return {
 					state: {
-						...state,
-						mode: "conflict_resolution",
+						phase: "conflict_resolution",
+						socket: state.socket,
 						pendingConflicts: conflicts
 					},
 					effects
 				};
 			}
-			const remoteTotal = state.pendingRemoteChanges.length;
 			const totalCount = remoteTotal + localOnly.length;
 			const updatedCount = safeWrites.length + localOnly.length;
 			const unchangedCount = Math.max(0, remoteTotal - safeWrites.length);
@@ -2241,24 +3054,51 @@ function transition(state, event) {
 			});
 			return {
 				state: {
-					...state,
-					mode: "watching",
-					pendingRemoteChanges: []
+					phase: "watching",
+					socket: state.socket
 				},
 				effects
 			};
 		}
-		case "REMOTE_FILE_CHANGE": {
-			const validation = validateIncomingChange(event.fileMeta, state.mode);
-			if (validation.action === "queue") {
+		case "REMOTE_FILE_CHANGE":
+			if (read.isActiveDeletePromptPath?.(event.file.name)) effects.push({
+				type: "INVALIDATE_DELETE_PROMPT_PATH",
+				fileName: event.file.name
+			});
+			if (read.isActiveConflictPath?.(event.file.name)) {
+				effects.push(log("debug", `Updating active conflict from remote change: ${event.file.name}`), {
+					type: "UPDATE_ACTIVE_CONFLICT_REMOTE",
+					fileName: event.file.name,
+					content: event.file.content,
+					modifiedAt: event.file.modifiedAt
+				});
+				return {
+					state,
+					effects
+				};
+			}
+			if (state.phase === "conflict_resolution") {
+				const next = updatePendingConflictRemote(state.pendingConflicts, event.file.name, event.file.content, event.file.modifiedAt);
+				if (next.changed) {
+					effects.push(log("debug", `Updating pending conflict from remote change: ${event.file.name}`));
+					return {
+						state: {
+							...state,
+							pendingConflicts: next.conflicts
+						},
+						effects
+					};
+				}
+			}
+			if (state.phase === "snapshot_processing" || state.phase === "handshaking") {
 				effects.push(log("debug", `Ignoring file change during sync: ${event.file.name}`));
 				return {
 					state,
 					effects
 				};
 			}
-			if (validation.action === "reject") {
-				effects.push(log("warn", `Rejected file change: ${event.file.name} (${validation.reason})`));
+			if (state.phase !== "watching" && state.phase !== "conflict_resolution") {
+				effects.push(log("warn", `Rejected file change: ${event.file.name} (unknown-file)`));
 				return {
 					state,
 					effects
@@ -2267,15 +3107,43 @@ function transition(state, event) {
 			effects.push(log("debug", `Applying remote change: ${event.file.name}`), {
 				type: "WRITE_FILES",
 				files: [event.file],
-				skipEcho: true
+				echoPolicy: "skip-expected-echoes"
 			});
 			return {
 				state,
 				effects
 			};
-		}
 		case "REMOTE_FILE_DELETE":
-			if (state.mode === "disconnected") {
+			if (read.isActiveDeletePromptPath?.(event.fileName)) effects.push({
+				type: "INVALIDATE_DELETE_PROMPT_PATH",
+				fileName: event.fileName
+			});
+			if (read.isActiveConflictPath?.(event.fileName)) {
+				effects.push(log("debug", `Updating active conflict from remote delete: ${event.fileName}`), {
+					type: "UPDATE_ACTIVE_CONFLICT_REMOTE",
+					fileName: event.fileName,
+					content: null,
+					modifiedAt: Date.now()
+				});
+				return {
+					state,
+					effects
+				};
+			}
+			if (state.phase === "conflict_resolution") {
+				const next = updatePendingConflictRemote(state.pendingConflicts, event.fileName, null, Date.now());
+				if (next.changed) {
+					effects.push(log("debug", `Updating pending conflict from remote delete: ${event.fileName}`));
+					return {
+						state: {
+							...state,
+							pendingConflicts: next.conflicts
+						},
+						effects
+					};
+				}
+			}
+			if (state.phase === "disconnected") {
 				effects.push(log("warn", `Rejected delete while disconnected: ${event.fileName}`));
 				return {
 					state,
@@ -2290,88 +3158,46 @@ function transition(state, event) {
 				state,
 				effects
 			};
-		case "LOCAL_DELETE_APPROVED":
-			effects.push(log("debug", `Delete confirmed: ${event.fileName}`), {
-				type: "DELETE_LOCAL_FILES",
-				names: [event.fileName]
-			}, { type: "PERSIST_STATE" });
+		case "DELETE_CONFIRMED":
+			effects.push({
+				type: "RESOLVE_DELETE_PROMPT",
+				session: event.session,
+				confirmedFileNames: event.fileNames,
+				cancelledFiles: []
+			});
 			return {
 				state,
 				effects
 			};
-		case "LOCAL_DELETE_REJECTED":
-			effects.push(log("debug", `Delete cancelled: ${event.fileName}`));
+		case "DELETE_CANCELLED":
 			effects.push({
-				type: "WRITE_FILES",
-				files: [{
-					name: event.fileName,
-					content: event.content,
-					modifiedAt: Date.now()
-				}]
+				type: "RESOLVE_DELETE_PROMPT",
+				session: event.session,
+				confirmedFileNames: [],
+				cancelledFiles: event.files
 			});
 			return {
 				state,
 				effects
 			};
-		case "CONFLICTS_RESOLVED": {
-			if (state.mode !== "conflict_resolution") {
-				effects.push(log("warn", `Received CONFLICTS_RESOLVED in mode ${state.mode}, ignoring`));
-				return {
-					state,
-					effects
-				};
-			}
-			if (event.resolution === "remote") {
-				for (const conflict of state.pendingConflicts) if (conflict.remoteContent === null) effects.push({
-					type: "DELETE_LOCAL_FILES",
-					names: [conflict.fileName]
-				});
-				else effects.push({
-					type: "WRITE_FILES",
-					files: [{
-						name: conflict.fileName,
-						content: conflict.remoteContent,
-						modifiedAt: conflict.remoteModifiedAt
-					}],
-					silent: true
-				});
-				effects.push(log("success", "Keeping Framer changes"));
-			} else {
-				const localDeletes = [];
-				for (const conflict of state.pendingConflicts) if (conflict.localContent === null) localDeletes.push(conflict.fileName);
-				else effects.push({
-					type: "SEND_MESSAGE",
-					payload: {
-						type: "file-change",
-						fileName: conflict.fileName,
-						content: conflict.localContent
-					}
-				});
-				if (localDeletes.length > 0) effects.push({
-					type: "LOCAL_INITIATED_FILE_DELETE",
-					fileNames: localDeletes
-				});
-				effects.push(log("success", "Keeping local changes"));
-			}
-			effects.push({ type: "PERSIST_STATE" }, {
-				type: "SYNC_COMPLETE",
-				totalCount: state.pendingConflicts.length,
-				updatedCount: state.pendingConflicts.length,
-				unchangedCount: 0
+		case "CONFLICTS_RESOLVED":
+			effects.push({
+				type: "RESOLVE_CONFLICT_PROMPT",
+				session: event.session,
+				resolution: event.resolution,
+				fileNames: event.fileNames
 			});
-			const { pendingConflicts: _discarded, ...rest } = state;
 			return {
-				state: {
-					...rest,
-					mode: "watching"
+				state: state.phase === "disconnected" ? state : {
+					phase: "watching",
+					socket: state.socket
 				},
 				effects
 			};
-		}
 		case "WATCHER_EVENT": {
 			const { kind, relativePath, content } = event.event;
-			if (state.mode !== "watching") {
-				effects.push(log("debug", `Ignoring watcher event in ${state.mode} mode: ${kind} ${relativePath}`));
+			if (state.phase !== "watching") {
+				effects.push(log("debug", `Ignoring watcher event in phase=${state.phase}: ${kind} ${relativePath}`));
 				return {
 					state,
 					effects
@@ -2387,46 +3213,74 @@ function transition(state, event) {
 							effects
 						};
 					}
-					effects.push({
+					if (read.isActiveDeletePromptPath?.(relativePath)) effects.push({
+						type: "INVALIDATE_DELETE_PROMPT_PATH",
+						fileName: relativePath
+					});
+					if (read.isActiveConflictPath?.(relativePath)) effects.push(log("debug", `Updating active conflict from local change: ${relativePath}`), {
+						type: "UPDATE_ACTIVE_CONFLICT_LOCAL",
+						fileName: relativePath,
+						content,
+						modifiedAt: Date.now()
+					});
+					else effects.push({
 						type: "SEND_LOCAL_CHANGE",
 						fileName: relativePath,
 						content
 					});
 					break;
 				case "delete":
-					effects.push(log("debug", `Local delete detected: ${relativePath}`), {
+					if (read.isActiveConflictPath?.(relativePath)) effects.push(log("debug", `Updating active conflict from local delete: ${relativePath}`), {
+						type: "UPDATE_ACTIVE_CONFLICT_LOCAL",
+						fileName: relativePath,
+						content: null,
+						modifiedAt: Date.now()
+					});
+					else effects.push(log("debug", `Local delete detected: ${relativePath}`), {
 						type: "LOCAL_INITIATED_FILE_DELETE",
 						fileNames: [relativePath]
 					});
 					break;
+				case "rename":
+					if (content === void 0 || !event.event.oldRelativePath) {
+						effects.push(log("warn", `Rename event missing data: ${relativePath}`));
+						return {
+							state,
+							effects
+						};
+					}
+					if (read.isActiveConflictPath?.(relativePath) || read.isActiveConflictPath?.(event.event.oldRelativePath)) effects.push(log("debug", `Ignoring rename touching active conflict: ${event.event.oldRelativePath} -> ${relativePath}`));
+					else effects.push(log("debug", `Local rename detected: ${event.event.oldRelativePath} → ${relativePath}`), {
+						type: "SEND_FILE_RENAME",
+						oldFileName: event.event.oldRelativePath,
+						newFileName: relativePath,
+						content
+					});
+					break;
 			}
 			return {
 				state,
 				effects
 			};
 		}
-		case "CONFLICT_VERSION_RESPONSE": {
-			if (state.mode !== "conflict_resolution") {
-				effects.push(log("warn", `Received CONFLICT_VERSION_RESPONSE in mode ${state.mode}, ignoring`));
+		case "RESOLVE_PENDING_CONFLICTS_WITH_VERSIONS": {
+			if (state.phase !== "conflict_resolution") {
+				effects.push(log("warn", `Received RESOLVE_PENDING_CONFLICTS_WITH_VERSIONS in phase=${state.phase}, ignoring`));
 				return {
 					state,
 					effects
 				};
 			}
 			const { autoResolvedLocal, autoResolvedRemote, remainingConflicts } = autoResolveConflicts(state.pendingConflicts, event.versions);
+			const localDeleteConflicts = [];
 			if (autoResolvedLocal.length > 0) {
 				effects.push(log("debug", `Auto-resolved ${autoResolvedLocal.length} local changes`));
-				const localDeletes = [];
-				for (const conflict of autoResolvedLocal) if (conflict.localContent === null) localDeletes.push(conflict.fileName);
+				for (const conflict of autoResolvedLocal) if (conflict.localContent === null) localDeleteConflicts.push(conflict);
 				else effects.push({
 					type: "SEND_LOCAL_CHANGE",
 					fileName: conflict.fileName,
 					content: conflict.localContent
 				});
-				if (localDeletes.length > 0) effects.push({
-					type: "LOCAL_INITIATED_FILE_DELETE",
-					fileNames: localDeletes
-				});
 			}
 			if (autoResolvedRemote.length > 0) {
 				effects.push(log("debug", `Auto-resolved ${autoResolvedRemote.length} remote changes`));
@@ -2441,22 +3295,28 @@ function transition(state, event) {
 						content: conflict.remoteContent,
 						modifiedAt: conflict.remoteModifiedAt ?? Date.now()
 					}],
+					echoPolicy: "authoritative",
 					silent: true
 				});
 			}
-			if (remainingConflicts.length > 0) {
-				effects.push(log("warn", `${pluralize(remainingConflicts.length, "conflict")} require resolution`), {
+			const conflictsForPrompt = remainingConflicts.length > 0 ? [...remainingConflicts, ...localDeleteConflicts] : remainingConflicts;
+			if (conflictsForPrompt.length > 0) {
+				effects.push(log("warn", `${pluralize(conflictsForPrompt.length, "conflict")} require resolution`), {
 					type: "REQUEST_CONFLICT_DECISIONS",
-					conflicts: remainingConflicts
+					conflicts: conflictsForPrompt
 				});
 				return {
 					state: {
-						...state,
-						pendingConflicts: remainingConflicts
+						phase: "watching",
+						socket: state.socket
 					},
 					effects
 				};
 			}
+			if (localDeleteConflicts.length > 0) effects.push({
+				type: "LOCAL_INITIATED_FILE_DELETE",
+				fileNames: localDeleteConflicts.map((conflict) => conflict.fileName)
+			});
 			const resolvedCount = autoResolvedLocal.length + autoResolvedRemote.length;
 			effects.push({ type: "PERSIST_STATE" }, {
 				type: "SYNC_COMPLETE",
@@ -2464,12 +3324,10 @@ function transition(state, event) {
 				updatedCount: resolvedCount,
 				unchangedCount: 0
 			});
-			const { pendingConflicts: _discarded, ...rest } = state;
 			return {
 				state: {
-					...rest,
-					mode: "watching",
-					pendingRemoteChanges: []
+					phase: "watching",
+					socket: state.socket
 				},
 				effects
 			};
@@ -2482,234 +3340,484 @@ function transition(state, event) {
 			};
 	}
 }
-/**
-* Effect executor - interprets effects and calls helpers
-* Returns additional events that should be processed (e.g., CONFLICTS_DETECTED after DETECT_CONFLICTS)
-*/
-async function executeEffect(effect, context) {
-	const { config, hashTracker, installer, fileMetadataCache, userActions, syncState } = context;
+function emitLog(entry) {
+	({
+		info,
+		debug,
+		warn,
+		success,
+		status
+	})[entry.level](entry.message);
+}
+function syncCompleteStatusMessage(config) {
+	return config.once ? "Sync complete, exiting..." : "Watching for changes...";
+}
+function syncCompleteSuccessMessage(runtime, effect) {
+	const relative = runtime.workspace.projectDir ? path.relative(process.cwd(), runtime.workspace.projectDir) : null;
+	const relativeDirectory = relative != null ? relative ? "./" + relative : "." : null;
+	if (effect.totalCount === 0 && relativeDirectory) return runtime.workspace.projectDirCreated ? `Created ${relativeDirectory} folder` : `Syncing to ${relativeDirectory} folder`;
+	if (relativeDirectory && runtime.workspace.projectDirCreated) return `Created ${relativeDirectory} (${pluralize(effect.updatedCount, "file")} added)`;
+	if (relativeDirectory) return `Synced into ${relativeDirectory} (${pluralize(effect.updatedCount, "file")} updated, ${effect.unchangedCount} unchanged)`;
+	return `Synced ${pluralize(effect.totalCount, "file")} (${effect.updatedCount} updated, ${effect.unchangedCount} unchanged)`;
+}
+function sendFailureLabel(message) {
+	return message.type === "file-change" ? message.fileName : message.type;
+}
+async function sendToPlugin(socket, message) {
+	if (!socket) return false;
+	try {
+		return await sendMessage(socket, message);
+	} catch {
+		warn(`Failed to push ${sendFailureLabel(message)}`);
+		return false;
+	}
+}
+async function writeFiles(files, ctx, options) {
+	const { runtime } = ctx;
+	if (!runtime.workspace.filesDir) return;
+	const filesToWrite = options.echoPolicy === "skip-expected-echoes" ? filterEchoedFiles(files, runtime.memory) : files;
+	if (options.echoPolicy === "skip-expected-echoes" && filesToWrite.length !== files.length) debug(`Skipped ${pluralize(files.length - filesToWrite.length, "echoed change")}`);
+	const results = await writeRemoteFiles(filesToWrite, runtime.workspace.filesDir, runtime.memory);
+	for (const result of results) {
+		if (!result.ok) continue;
+		if (!options.silent) fileDown(result.path);
+		runtime.memory.recordSyncedContent(result.path, result.file.content, result.file.modifiedAt ?? Date.now());
+		runtime.installer?.process(result.path, result.file.content);
+	}
+}
+async function deleteFiles(fileNames, ctx) {
+	const { runtime } = ctx;
+	if (!runtime.workspace.filesDir) return;
+	for (const fileName of fileNames) {
+		const result = await deleteLocalFile(fileName, runtime.workspace.filesDir, runtime.memory);
+		if (!result.ok) continue;
+		fileDelete(result.fileName);
+		runtime.memory.recordSyncedDelete(result.fileName);
+	}
+}
+async function sendLocalChange(fileName, content, ctx) {
+	const { runtime, syncState } = ctx;
+	if (runtime.metadata.get(fileName)?.lastSyncedHash === hashFileContent(content)) {
+		debug(`Skipping local change for ${fileName}: matches last synced content`);
+		return;
+	}
+	if (runtime.memory.matchesContentEcho(fileName, content)) return;
+	debug(`Local change detected: ${fileName}`);
+	if (!await sendToPlugin(syncState.socket, {
+		type: "file-change",
+		fileName,
+		content
+	})) return;
+	runtime.memory.armContentEcho(fileName, content);
+	fileUp(fileName);
+	runtime.installer?.process(fileName, content);
+}
+async function sendFileDelete(fileNames, ctx) {
+	if (fileNames.length === 0) return;
+	if (!await sendToPlugin(ctx.syncState.socket, {
+		type: "file-delete",
+		mode: "auto",
+		fileNames
+	})) return;
+	for (const fileName of fileNames) ctx.runtime.memory.recordSyncedDelete(fileName);
+}
+async function sendFileRename(effect, ctx) {
+	const { runtime, syncState } = ctx;
+	const newFileName = normalizeCodeFilePathWithExtension(effect.newFileName);
+	if (runtime.memory.matchesContentEcho(newFileName, effect.content) && runtime.memory.matchesExpectedDeleteEcho(effect.oldFileName)) {
+		debug(`Skipping echoed rename ${effect.oldFileName} -> ${effect.newFileName}`);
+		runtime.memory.clearContentEcho(newFileName);
+		runtime.memory.clearExpectedDeleteEcho(effect.oldFileName);
+		return;
+	}
+	if (!syncState.socket) {
+		warn(`No socket available to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
+		return;
+	}
+	if (await sendToPlugin(syncState.socket, {
+		type: "file-rename",
+		oldFileName: effect.oldFileName,
+		newFileName,
+		content: effect.content
+	})) runtime.registerPendingRename(newFileName, {
+		oldFileName: effect.oldFileName,
+		content: effect.content
+	});
+}
+async function startDeletePrompt(fileNames, ctx) {
+	const prompt = ctx.runtime.startDeletePrompt(fileNames);
+	if (!prompt) return;
+	if (!await sendToPlugin(ctx.syncState.socket, {
+		type: "file-delete",
+		mode: "confirm",
+		fileNames: prompt.fileNames,
+		session: prompt.session
+	})) {
+		ctx.runtime.clearDeletePromptFiles(prompt.session, prompt.fileNames);
+		warn(`Failed to request delete confirmation for ${prompt.fileNames.join(", ")}`);
+	}
+}
+async function startConflictPrompt(conflicts, ctx) {
+	const prompt = ctx.runtime.startOrUpdateConflictPrompt(conflicts);
+	if (!prompt) return;
+	if (!await sendToPlugin(ctx.syncState.socket, {
+		type: "conflicts-detected",
+		conflicts: prompt.conflicts,
+		session: prompt.session
+	})) {
+		ctx.runtime.clearConflictPromptFiles(prompt.session, prompt.conflicts.map((conflict) => conflict.fileName));
+		warn("Failed to send conflict prompt");
+	}
+}
+async function applyConflictChange(change, ctx) {
+	if (!change.changed) return;
+	for (const resolved of change.resolved) if (resolved.content === null) ctx.runtime.memory.recordSyncedDelete(resolved.fileName);
+	else ctx.runtime.memory.recordSyncedContent(resolved.fileName, resolved.content, resolved.modifiedAt ?? Date.now());
+	if (ctx.syncState.socket) await sendToPlugin(ctx.syncState.socket, change.cleared ? {
+		type: "conflicts-cleared",
+		session: change.session
+	} : {
+		type: "conflicts-detected",
+		conflicts: change.conflicts,
+		session: change.session
+	});
+	if (change.resolved.length > 0) await ctx.runtime.metadata.flush();
+	if (change.cleared && ctx.runtime.lastEmittedSyncStatus !== "ready") {
+		if (await flushPendingSyncComplete(ctx) !== "empty") return;
+		await applySyncComplete({
+			type: "SYNC_COMPLETE",
+			totalCount: change.resolved.length,
+			updatedCount: change.resolved.length,
+			unchangedCount: 0
+		}, ctx);
+	}
+}
+async function applySyncComplete(effect, ctx) {
+	const { config, runtime, syncState, shutdown } = ctx;
+	if (runtime.hasAnyActivePrompt()) {
+		runtime.deferSyncComplete({
+			totalCount: effect.totalCount,
+			updatedCount: effect.updatedCount,
+			unchangedCount: effect.unchangedCount
+		});
+		debug("Deferring sync completion until active prompts resolve");
+		return;
+	}
+	const wasDisconnected = runtime.disconnectUi.wasRecentlyDisconnected();
+	let shouldShutdown = !!config.once;
+	let shouldTryGitInit = false;
+	if (wasDisconnected) {
+		const didShow = runtime.disconnectUi.didShowNotice();
+		shouldShutdown = didShow && !!config.once;
+		if (didShow) {
+			success(`Reconnected, synced ${pluralize(effect.totalCount, "file")} (${effect.updatedCount} updated, ${effect.unchangedCount} unchanged)`);
+			status(syncCompleteStatusMessage(config));
+		}
+	} else {
+		const message = syncCompleteSuccessMessage(runtime, effect);
+		if (message) success(message);
+		status(syncCompleteStatusMessage(config));
+		shouldTryGitInit = !!(runtime.workspace.projectDirCreated && runtime.workspace.projectDir);
+	}
+	await sendToPlugin(syncState.socket, {
+		type: "sync-status",
+		status: "ready"
+	});
+	runtime.noteEmittedSyncStatus("ready");
+	if (wasDisconnected) runtime.disconnectUi.reset();
+	if (shouldTryGitInit && runtime.workspace.projectDir) tryGitInit(runtime.workspace.projectDir);
+	if (shouldShutdown) await shutdown();
+}
+async function flushPendingSyncComplete(ctx) {
+	const result = ctx.runtime.claimPendingSyncComplete();
+	if (result.status === "ready") await applySyncComplete({
+		type: "SYNC_COMPLETE",
+		...result.payload
+	}, ctx);
+	return result.status;
+}
+async function applyEffect(effect, ctx) {
+	const { config, runtime, syncState } = ctx;
 	switch (effect.type) {
-		case "INIT_WORKSPACE":
-			if (!config.projectDir) {
-				const projectName = config.explicitName ?? effect.projectInfo.projectName;
-				const directoryInfo = await findOrCreateProjectDirectory({
-					projectHash: config.projectHash,
-					projectName,
-					explicitDirectory: config.explicitDirectory
-				});
-				config.projectDir = directoryInfo.directory;
-				config.projectDirCreated = directoryInfo.created;
-				if (directoryInfo.nameCollision) warn(`Folder ${projectName} already exists`);
-				config.filesDir = `${config.projectDir}/files`;
-				debug(`Files directory: ${config.filesDir}`);
-				await fs.mkdir(config.filesDir, { recursive: true });
-			}
+		case "INIT_WORKSPACE": {
+			if (runtime.workspace.projectDir) return [];
+			const projectName = config.explicitName ?? effect.projectInfo.projectName;
+			const directoryInfo = await findOrCreateProjectDirectory({
+				projectHash: config.projectHash,
+				projectName,
+				explicitDirectory: config.explicitDirectory
+			});
+			runtime.configureWorkspace(directoryInfo.directory, directoryInfo.created);
+			if (directoryInfo.nameCollision) warn(`Folder ${projectName} already exists`);
+			debug(`Files directory: ${runtime.workspace.filesDir}`);
+			await fs.mkdir(runtime.workspace.filesDir, { recursive: true });
 			return [];
+		}
 		case "LOAD_PERSISTED_STATE":
-			if (config.projectDir) {
-				await fileMetadataCache.initialize(config.projectDir);
-				debug(`Loaded persisted metadata for ${pluralize(fileMetadataCache.size(), "file")}`);
+			if (runtime.workspace.projectDir) {
+				await runtime.metadata.initialize(runtime.workspace.projectDir);
+				debug(`Loaded persisted metadata for ${pluralize(runtime.metadata.size(), "file")}`);
 			}
 			return [];
-		case "LIST_LOCAL_FILES": {
-			if (!config.filesDir) return [];
-			const files = await listFiles(config.filesDir);
-			if (syncState.socket) await sendMessage(syncState.socket, {
+		case "LIST_LOCAL_FILES":
+			if (runtime.workspace.filesDir) await sendToPlugin(syncState.socket, {
 				type: "file-list",
-				files
+				files: await listFiles(runtime.workspace.filesDir)
 			});
 			return [];
-		}
 		case "DETECT_CONFLICTS": {
-			if (!config.filesDir) return [];
-			const { conflicts, writes, localOnly, unchanged } = await detectConflicts(effect.remoteFiles, config.filesDir, { persistedState: fileMetadataCache.getPersistedState() });
-			for (const file of unchanged) fileMetadataCache.recordRemoteWrite(file.name, file.content, file.modifiedAt ?? Date.now());
+			if (!runtime.workspace.filesDir) return [];
+			const { conflicts, writes, localOnly, unchanged } = await detectConflicts(effect.remoteFiles, runtime.workspace.filesDir, { persistedState: runtime.metadata.getPersistedState() });
+			for (const file of unchanged) runtime.memory.recordSyncedContent(file.name, file.content, file.modifiedAt ?? Date.now());
 			return [{
 				type: "CONFLICTS_DETECTED",
 				conflicts,
 				safeWrites: writes,
-				localOnly
+				localOnly,
+				remoteTotal: effect.remoteFiles.length
 			}];
 		}
 		case "SEND_MESSAGE":
-			if (syncState.socket) {
-				if (!await sendMessage(syncState.socket, effect.payload)) warn(`Failed to send message: ${effect.payload.type}`);
-			} else warn(`No socket available to send: ${effect.payload.type}`);
+			if (effect.payload.type === "file-change") await sendLocalChange(effect.payload.fileName, effect.payload.content, ctx);
+			else await sendToPlugin(syncState.socket, effect.payload);
+			return [];
+		case "EMIT_SYNC_STATUS":
+			await sendToPlugin(syncState.socket, {
+				type: "sync-status",
+				status: effect.status
+			});
+			runtime.noteEmittedSyncStatus(effect.status);
 			return [];
 		case "WRITE_FILES":
-			if (config.filesDir) {
-				const filesToWrite = effect.skipEcho === true ? filterEchoedFiles(effect.files, hashTracker) : effect.files;
-				if (effect.skipEcho && filesToWrite.length !== effect.files.length) debug(`Skipped ${pluralize(effect.files.length - filesToWrite.length, "echoed change")}`);
-				if (filesToWrite.length === 0) return [];
-				await writeRemoteFiles(filesToWrite, config.filesDir, hashTracker, installer ?? void 0);
-				for (const file of filesToWrite) {
-					if (!effect.silent) fileDown(file.name);
-					const remoteTimestamp = file.modifiedAt ?? Date.now();
-					fileMetadataCache.recordRemoteWrite(file.name, file.content, remoteTimestamp);
-				}
-			}
+			await writeFiles(effect.files, ctx, {
+				silent: effect.silent,
+				echoPolicy: effect.echoPolicy
+			});
 			return [];
 		case "DELETE_LOCAL_FILES":
-			if (config.filesDir) for (const fileName of effect.names) {
-				await deleteLocalFile(fileName, config.filesDir, hashTracker);
-				fileDelete(fileName);
-				fileMetadataCache.recordDelete(fileName);
-			}
+			await deleteFiles(effect.names, ctx);
 			return [];
 		case "REQUEST_CONFLICT_DECISIONS":
-			await userActions.requestConflictDecisions(syncState.socket, effect.conflicts);
+			await startConflictPrompt(effect.conflicts, ctx);
 			return [];
 		case "REQUEST_CONFLICT_VERSIONS": {
 			if (!syncState.socket) {
 				warn("Cannot request conflict versions without active socket");
 				return [];
 			}
-			const persistedState = fileMetadataCache.getPersistedState();
-			const versionRequests = effect.conflicts.map((conflict) => {
-				const persisted = persistedState.get(conflict.fileName);
-				return {
-					fileName: conflict.fileName,
-					lastSyncedAt: conflict.lastSyncedAt ?? persisted?.timestamp
-				};
-			});
-			debug(`Requesting remote version data for ${pluralize(versionRequests.length, "file")}`);
-			await sendMessage(syncState.socket, {
+			const persistedState = runtime.metadata.getPersistedState();
+			const conflicts = effect.conflicts.map((conflict) => ({
+				fileName: conflict.fileName,
+				lastSyncedAt: conflict.lastSyncedAt ?? persistedState.get(conflict.fileName)?.timestamp
+			}));
+			debug(`Requesting remote version data for ${pluralize(conflicts.length, "file")}`);
+			await sendToPlugin(syncState.socket, {
 				type: "conflict-version-request",
-				conflicts: versionRequests
+				conflicts
 			});
 			return [];
 		}
 		case "UPDATE_FILE_METADATA": {
-			if (!config.filesDir || !config.projectDir) return [];
-			const currentContent = await readFileSafe(effect.fileName, config.filesDir);
-			if (currentContent !== null) {
-				const contentHash = hashFileContent(currentContent);
-				fileMetadataCache.recordSyncedSnapshot(effect.fileName, contentHash, effect.remoteModifiedAt);
+			if (!runtime.workspace.filesDir || !runtime.workspace.projectDir) return [];
+			const currentContent = await readFileSafe(effect.fileName, runtime.workspace.filesDir);
+			const pendingRename = runtime.getPendingRename(normalizeCodeFilePathWithExtension(effect.fileName));
+			const syncedContent = currentContent ?? pendingRename?.content ?? null;
+			if (syncedContent !== null) runtime.memory.recordSyncedContent(effect.fileName, syncedContent, effect.remoteModifiedAt);
+			if (pendingRename) {
+				runtime.memory.recordSyncedDelete(pendingRename.oldFileName);
+				if (currentContent !== null) runtime.memory.armContentEcho(effect.fileName, currentContent);
+				runtime.completePendingRename(effect.fileName);
 			}
 			return [];
 		}
-		case "SEND_LOCAL_CHANGE": {
-			const contentHash = hashFileContent(effect.content);
-			if (fileMetadataCache.get(effect.fileName)?.lastSyncedHash === contentHash) {
-				debug(`Skipping local change for ${effect.fileName}: matches last synced content`);
+		case "SEND_LOCAL_CHANGE":
+			await sendLocalChange(effect.fileName, effect.content, ctx);
+			return [];
+		case "SEND_FILE_RENAME":
+			await sendFileRename(effect, ctx);
+			return [];
+		case "LOCAL_INITIATED_FILE_DELETE": {
+			const filesToDelete = [];
+			for (const fileName of effect.fileNames) if (runtime.memory.matchesExpectedDeleteEcho(fileName)) runtime.memory.clearExpectedDeleteEcho(fileName);
+			else filesToDelete.push(fileName);
+			if (filesToDelete.length === 0) return [];
+			if (config.dangerouslyAutoDelete) await sendFileDelete(filesToDelete, ctx);
+			else await startDeletePrompt(filesToDelete, ctx);
+			return [];
+		}
+		case "RESOLVE_DELETE_PROMPT": {
+			const activeFileNames = runtime.getDeletePromptFileNames(effect.session, [...effect.confirmedFileNames, ...effect.cancelledFiles.map((file) => file.fileName)]);
+			if (!activeFileNames) {
+				warn("Ignoring stale delete prompt response (session or paths mismatch)");
 				return [];
 			}
-			if (hashTracker.shouldSkip(effect.fileName, effect.content)) return [];
-			debug(`Local change detected: ${effect.fileName}`);
-			try {
-				if (syncState.socket) {
-					await sendMessage(syncState.socket, {
-						type: "file-change",
-						fileName: effect.fileName,
-						content: effect.content
+			const active = new Set(activeFileNames);
+			const confirmed = effect.confirmedFileNames.filter((fileName) => active.has(runtime.memory.normalizePath(fileName)));
+			const cancelled = effect.cancelledFiles.filter((file) => active.has(runtime.memory.normalizePath(file.fileName)));
+			if (cancelled.length > 0) await writeFiles(cancelled.map((file) => ({
+				name: file.fileName,
+				content: file.content,
+				modifiedAt: Date.now()
+			})), ctx, { echoPolicy: "authoritative" });
+			await sendFileDelete(confirmed, ctx);
+			runtime.clearDeletePromptFiles(effect.session, activeFileNames);
+			await runtime.metadata.flush();
+			await flushPendingSyncComplete(ctx);
+			return [];
+		}
+		case "RESOLVE_CONFLICT_PROMPT": {
+			const conflicts = runtime.getConflictPromptConflicts(effect.session, effect.fileNames);
+			if (!conflicts) {
+				warn("Ignoring stale conflicts-resolved (session mismatch)");
+				return [];
+			}
+			if (effect.resolution === "remote") {
+				const filesToWrite = [];
+				const filesToDelete = [];
+				for (const conflict of conflicts) {
+					if (conflict.remoteContent === null) {
+						filesToDelete.push(conflict.fileName);
+						continue;
+					}
+					filesToWrite.push({
+						name: conflict.fileName,
+						content: conflict.remoteContent,
+						modifiedAt: conflict.remoteModifiedAt
 					});
-					fileUp(effect.fileName);
 				}
-				hashTracker.remember(effect.fileName, effect.content);
-				if (installer) installer.process(effect.fileName, effect.content);
-			} catch (err) {
-				warn(`Failed to push ${effect.fileName}`);
-			}
+				await Promise.all([writeFiles(filesToWrite, ctx, {
+					silent: true,
+					echoPolicy: "authoritative"
+				}), deleteFiles(filesToDelete, ctx)]);
+			} else for (const conflict of conflicts) if (conflict.localContent === null) await sendFileDelete([conflict.fileName], ctx);
+			else await sendLocalChange(conflict.fileName, conflict.localContent, ctx);
+			success(effect.resolution === "remote" ? "Keeping Framer changes" : "Keeping local changes");
+			runtime.clearConflictPromptFiles(effect.session, effect.fileNames);
+			await runtime.metadata.flush();
+			await applySyncComplete({
+				type: "SYNC_COMPLETE",
+				totalCount: conflicts.length,
+				updatedCount: conflicts.length,
+				unchangedCount: 0
+			}, ctx);
 			return [];
 		}
-		case "LOCAL_INITIATED_FILE_DELETE": {
-			const filesToDelete = effect.fileNames.filter((fileName) => {
-				const shouldSkip = hashTracker.shouldSkipDelete(fileName);
-				if (shouldSkip) hashTracker.clearDelete(fileName);
-				return !shouldSkip;
-			});
-			if (filesToDelete.length === 0) return [];
-			try {
-				const confirmedFiles = await userActions.requestDeleteDecision(syncState.socket, {
-					fileNames: filesToDelete,
-					requireConfirmation: !config.dangerouslyAutoDelete
-				});
-				for (const fileName of confirmedFiles) {
-					hashTracker.forget(fileName);
-					fileMetadataCache.recordDelete(fileName);
-					fileDelete(fileName);
-				}
-				if (confirmedFiles.length > 0 && syncState.socket) await sendMessage(syncState.socket, {
-					type: "file-delete",
-					fileNames: confirmedFiles
+		case "UPDATE_ACTIVE_CONFLICT_LOCAL":
+			await applyConflictChange(runtime.updateActiveConflictLocal(effect.fileName, effect.content, effect.modifiedAt), ctx);
+			return [];
+		case "UPDATE_ACTIVE_CONFLICT_REMOTE":
+			await applyConflictChange(runtime.updateActiveConflictRemote(effect.fileName, effect.content, effect.modifiedAt), ctx);
+			return [];
+		case "INVALIDATE_DELETE_PROMPT_PATH": {
+			const change = runtime.invalidateDeletePromptPath(effect.fileName);
+			if (change.changed) {
+				await sendToPlugin(syncState.socket, {
+					type: "delete-prompt-cleared",
+					session: change.session,
+					fileNames: change.fileNames
 				});
-			} catch (err) {
-				console.warn(`Failed to handle deletion for ${filesToDelete.join(", ")}:`, err);
+				await flushPendingSyncComplete(ctx);
 			}
 			return [];
 		}
 		case "PERSIST_STATE":
-			await fileMetadataCache.flush();
+			await runtime.metadata.flush();
 			return [];
-		case "SYNC_COMPLETE": {
-			const wasDisconnected = wasRecentlyDisconnected();
-			if (syncState.socket) await sendMessage(syncState.socket, { type: "sync-complete" });
-			if (wasDisconnected) {
-				if (didShowDisconnect()) {
-					success(`Reconnected, synced ${pluralize(effect.totalCount, "file")} (${effect.updatedCount} updated, ${effect.unchangedCount} unchanged)`);
-					status("Watching for changes...");
-				}
-				resetDisconnectState();
-				return [];
-			}
-			const relative = config.projectDir ? path.relative(process.cwd(), config.projectDir) : null;
-			const relativeDirectory = relative != null ? relative ? "./" + relative : "." : null;
-			if (effect.totalCount === 0 && relativeDirectory) if (config.projectDirCreated) success(`Created ${relativeDirectory} folder`);
-			else success(`Syncing to ${relativeDirectory} folder`);
-			else if (relativeDirectory && config.projectDirCreated) success(`Created ${relativeDirectory} (${pluralize(effect.updatedCount, "file")} added)`);
-			else if (relativeDirectory) success(`Synced into ${relativeDirectory} (${pluralize(effect.updatedCount, "file")} updated, ${effect.unchangedCount} unchanged)`);
-			else success(`Synced ${pluralize(effect.totalCount, "file")} (${effect.updatedCount} updated, ${effect.unchangedCount} unchanged)`);
-			if (config.projectDirCreated && config.projectDir) tryGitInit(config.projectDir);
-			status("Watching for changes...");
+		case "SYNC_COMPLETE":
+			await applySyncComplete(effect, ctx);
 			return [];
-		}
-		case "LOG": {
-			const logFn = {
-				info,
-				warn,
-				success,
-				debug
-			}[effect.level];
-			logFn(effect.message);
+		case "LOG":
+			emitLog({
+				level: effect.level,
+				message: effect.message
+			});
 			return [];
-		}
 	}
 }
 /**
 * Starts the sync controller with the given configuration
 */
 async function start(config) {
-	status("Waiting for Plugin connection...");
-	const hashTracker = createHashTracker();
-	const fileMetadataCache = new FileMetadataCache();
-	let installer = null;
+	const runtime = new SyncRuntime();
+	let isShuttingDown = false;
+	let pendingDependencyVersions = null;
 	let syncState = {
-		mode: "disconnected",
-		socket: null,
-		pendingRemoteChanges: []
+		phase: "disconnected",
+		socket: null
 	};
-	const userActions = new PluginUserPromptCoordinator();
-	async function processEvent(event) {
+	const eventQueue = createEventQueue();
+	function nullDependencyVersions(packages) {
+		return Object.fromEntries(packages.map((packageName) => [packageName, null]));
+	}
+	async function requestDependencyVersions(packages) {
+		if (packages.length === 0) return {};
+		const socket = syncState.socket;
+		if (!socket) return nullDependencyVersions(packages);
+		if (pendingDependencyVersions) {
+			warn("Dependency version request already pending");
+			return nullDependencyVersions(packages);
+		}
+		return await new Promise((resolve) => {
+			const timeout = setTimeout(() => {
+				if (pendingDependencyVersions?.resolve === resolve) {
+					pendingDependencyVersions = null;
+					warn("Timed out waiting for dependency versions from plugin");
+					resolve(nullDependencyVersions(packages));
+				}
+			}, 1e4);
+			pendingDependencyVersions = {
+				resolve,
+				timeout
+			};
+			sendMessage(socket, {
+				type: "request-dependency-versions",
+				packages
+			}).then((sent) => {
+				if (!sent && pendingDependencyVersions?.resolve === resolve) {
+					clearTimeout(timeout);
+					pendingDependencyVersions = null;
+					resolve(nullDependencyVersions(packages));
+				}
+			});
+		});
+	}
+	function processEvent(event) {
+		return eventQueue.enqueue(() => processEventInner(event));
+	}
+	async function processEventInner(event) {
 		const socketState = syncState.socket?.readyState;
-		debug(`[STATE] Processing event: ${event.type} (mode: ${syncState.mode}, socket: ${socketState ?? "none"})`);
-		const result = transition(syncState, event);
+		debug(`[STATE] Processing event: ${event.type} (phase: ${syncState.phase}, socket: ${socketState ?? "none"})`);
+		const result = transition(syncState, event, {
+			wasRecentlyDisconnected: () => runtime.disconnectUi.wasRecentlyDisconnected(),
+			isActiveConflictPath: (fileName) => runtime.isActiveConflictPath(fileName),
+			isActiveDeletePromptPath: (fileName) => runtime.isActiveDeletePromptPath(fileName)
+		});
 		syncState = result.state;
 		if (result.effects.length > 0) debug(`[STATE] Event produced ${result.effects.length} effects: ${result.effects.map((e) => e.type).join(", ")}`);
 		for (const effect of result.effects) {
 			const currentSocketState = syncState.socket?.readyState;
 			if (currentSocketState !== void 0 && currentSocketState !== 1) debug(`[STATE] Socket not open (state: ${currentSocketState}) before executing ${effect.type}`);
-			const followUpEvents = await executeEffect(effect, {
+			const followUpEvents = await applyEffect(effect, {
 				config,
-				hashTracker,
-				installer,
-				fileMetadataCache,
-				userActions,
+				runtime,
+				shutdown,
 				syncState
 			});
-			for (const followUpEvent of followUpEvents) await processEvent(followUpEvent);
+			for (const followUpEvent of followUpEvents) await processEventInner(followUpEvent);
 		}
 	}
-	const connection = await initConnection(config.port);
+	const certs = await getOrCreateCerts();
+	if (!certs) {
+		error("Failed to generate TLS certificates. The Framer plugin requires a secure (wss://) connection.");
+		info("");
+		info("To fix this:");
+		info("  1. Re-run this command — certificate generation is often a one-time issue");
+		info(`  2. Manually delete "${CERT_DIR}" and try again`);
+		info("");
+		throw new Error("TLS certificate generation failed");
+	}
+	status("Waiting for Plugin connection...");
+	const connection = await initConnection(config.port, certs);
 	connection.on("handshake", (client, message) => {
 		debug(`Received handshake: ${message.projectName} (${message.projectId})`);
 		const expectedShort = shortProjectHash(config.projectHash);
@@ -2720,16 +3828,23 @@ async function start(config) {
 			return;
 		}
 		(async () => {
-			cancelDisconnectMessage();
-			if (syncState.mode !== "disconnected") {
+			runtime.disconnectUi.cancelNotice();
+			if (syncState.phase !== "disconnected") {
 				if (syncState.socket === client) {
-					debug(`Ignoring duplicate handshake from active socket in ${syncState.mode} mode`);
+					await processEvent({
+						type: "RESEND_SYNC_STATUS",
+						status: runtime.lastEmittedSyncStatus ?? "initial_sync"
+					});
 					return;
 				}
-				debug(`New handshake received in ${syncState.mode} mode, resetting sync state`);
+				debug(`New handshake received (phase=${syncState.phase}), resetting sync state`);
+				runtime.clearPendingRenames();
+				runtime.clearEmittedSyncStatus();
+				runtime.cleanupUserActions();
 				await processEvent({ type: "DISCONNECT" });
 			}
-			if (!wasRecentlyDisconnected() && !didShowDisconnect()) success(`Connected to ${message.projectName}`);
+			runtime.mintConnectionId();
+			if (!runtime.disconnectUi.wasRecentlyDisconnected() && !runtime.disconnectUi.didShowNotice()) success(`Connected to ${message.projectName}`);
 			await processEvent({
 				type: "HANDSHAKE",
 				socket: client,
@@ -2738,18 +3853,20 @@ async function start(config) {
 					projectName: message.projectName
 				}
 			});
-			if (config.projectDir && !installer) {
-				installer = new Installer({
-					projectDir: config.projectDir,
-					allowUnsupportedNpm: config.allowUnsupportedNpm
+			if (runtime.workspace.projectDir && !runtime.installer) {
+				const npmStrategy = await resolveNpmStrategy(config, runtime.workspace.projectDir);
+				runtime.installer = new Installer({
+					projectDir: runtime.workspace.projectDir,
+					npmStrategy,
+					requestDependencyVersions
 				});
-				await installer.initialize();
+				await runtime.installer.initialize();
 				startWatcher();
 			}
 		})();
 	});
 	async function handleMessage(message) {
-		if (!config.projectDir || !installer) {
+		if (!runtime.workspace.projectDir || !runtime.installer) {
 			warn("Received message before handshake completed - ignoring");
 			return;
 		}
@@ -2772,8 +3889,7 @@ async function start(config) {
 						name: message.fileName,
 						content: message.content,
 						modifiedAt: Date.now()
-					},
-					fileMeta: fileMetadataCache.get(message.fileName)
+					}
 				};
 				break;
 			case "file-delete":
@@ -2782,25 +3898,20 @@ async function start(config) {
 					fileName
 				});
 				return;
-			case "delete-confirmed": {
-				const unmatched = [];
-				for (const fileName of message.fileNames) if (!userActions.handleConfirmation(`delete:${fileName}`, true)) unmatched.push(fileName);
-				for (const fileName of unmatched) await processEvent({
-					type: "LOCAL_DELETE_APPROVED",
-					fileName
-				});
-				return;
-			}
+			case "delete-confirmed":
+				event = {
+					type: "DELETE_CONFIRMED",
+					session: message.session,
+					fileNames: message.fileNames
+				};
+				break;
 			case "delete-cancelled":
-				for (const file of message.files) {
-					userActions.handleConfirmation(`delete:${file.fileName}`, false);
-					await processEvent({
-						type: "LOCAL_DELETE_REJECTED",
-						fileName: file.fileName,
-						content: file.content
-					});
-				}
-				return;
+				event = {
+					type: "DELETE_CANCELLED",
+					session: message.session,
+					files: message.files
+				};
+				break;
 			case "file-synced":
 				event = {
 					type: "FILE_SYNCED_CONFIRMATION",
@@ -2808,18 +3919,35 @@ async function start(config) {
 					remoteModifiedAt: message.remoteModifiedAt
 				};
 				break;
+			case "error":
+				if (message.fileName) runtime.completePendingRename(normalizeCodeFilePathWithExtension(message.fileName));
+				warn(message.message);
+				return;
 			case "conflicts-resolved":
 				event = {
 					type: "CONFLICTS_RESOLVED",
-					resolution: message.resolution
+					session: message.session,
+					resolution: message.resolution,
+					fileNames: message.fileNames
 				};
 				break;
 			case "conflict-version-response":
 				event = {
-					type: "CONFLICT_VERSION_RESPONSE",
+					type: "RESOLVE_PENDING_CONFLICTS_WITH_VERSIONS",
 					versions: message.versions
 				};
 				break;
+			case "dependency-versions": {
+				if (!pendingDependencyVersions) {
+					warn("Received dependency versions with no pending request");
+					return;
+				}
+				clearTimeout(pendingDependencyVersions.timeout);
+				const pending = pendingDependencyVersions;
+				pendingDependencyVersions = null;
+				pending.resolve(message.versions);
+				return;
+			}
 			default:
 				warn(`Unhandled message type: ${message.type}`);
 				return;
@@ -2836,25 +3964,42 @@ async function start(config) {
 		})();
 	});
 	connection.on("disconnect", (client) => {
+		if (isShuttingDown) {
+			debug("[STATE] Ignoring disconnect during shutdown");
+			return;
+		}
 		if (syncState.socket !== client) {
 			debug("[STATE] Ignoring disconnect from stale socket");
 			return;
 		}
-		scheduleDisconnectMessage(() => {
+		runtime.disconnectUi.scheduleNotice(() => {
 			status("Disconnected, waiting to reconnect...");
 		});
 		(async () => {
+			runtime.clearPendingRenames();
 			await processEvent({ type: "DISCONNECT" });
-			userActions.cleanup();
+			runtime.clearEmittedSyncStatus();
+			runtime.cleanupUserActions();
 		})();
 	});
 	connection.on("error", (err) => {
 		error("Error on WebSocket connection:", err);
 	});
 	let watcher = null;
+	const shutdown = async () => {
+		if (isShuttingDown) return;
+		debug("[STATE] Shutting down...");
+		isShuttingDown = true;
+		runtime.cleanupUserActions();
+		if (watcher) {
+			await watcher.close();
+			watcher = null;
+		}
+		connection.close();
+	};
 	const startWatcher = () => {
-		if (!config.filesDir || watcher) return;
-		watcher = initWatcher(config.filesDir);
+		if (!runtime.workspace.filesDir || watcher) return;
+		watcher = initWatcher(runtime.workspace.filesDir);
 		watcher.on("change", (event) => {
 			processEvent({
 				type: "WATCHER_EVENT",
@@ -2866,8 +4011,7 @@ async function start(config) {
 		console.log();
 		status("Shutting down...");
 		(async () => {
-			if (watcher) await watcher.close();
-			connection.close();
+			await shutdown();
 			process.exit(0);
 		})();
 	});
@@ -2883,6 +4027,11 @@ async function start(config) {
 */
 const { version } = createRequire(import.meta.url)("../package.json");
 const program = new Command();
+function parseUnsupportedNpmMode(mode) {
+	if (mode === void 0) return "acquire-types";
+	if (mode === "acquire-types" || mode === "package-manager") return mode;
+	throw new InvalidArgumentError("unsupported npm mode must be 'acquire-types' or 'package-manager'");
+}
 program.exitOverride((err) => {
 	if (err.code === "commander.missingArgument") {
 		console.error("Missing Project ID. Copy command via Code Link Plugin.");
@@ -2890,7 +4039,7 @@ program.exitOverride((err) => {
 	}
 	throw err;
 });
-program.name("framer-code-link").description("Sync Framer code components to your local filesystem").version(version).argument("[projectHash]", "Framer Project ID Hash (auto-detected from package.json if omitted)").option("-n, --name <name>", "Project name (optional)").option("-d, --dir <directory>", "Explicit project directory").option("-v, --verbose", "Enable verbose logging").option("--log-level <level>", "Set log level (debug, info, warn, error)").option("--dangerously-auto-delete", "Automatically delete remote files without confirmation").option("--unsupported-npm", "Allow type acquisition for unsupported npm packages").action(async (projectHash, options) => {
+program.name("framer-code-link").description("Sync Framer code components to your local filesystem").version(version).argument("[projectHash]", "Framer Project ID Hash (auto-detected from package.json if omitted)").option("-n, --name <name>", "Project name (optional)").option("-d, --dir <directory>", "Explicit project directory").option("--once", "Exit after the initial sync completes").option("-v, --verbose", "Enable verbose logging").option("--log-level <level>", "Set log level (debug, info, warn, error)").option("--dangerously-auto-delete", "Automatically delete remote files without confirmation").option("--unsupported-npm [mode]", "Handle unsupported npm packages (acquire-types or package-manager)", parseUnsupportedNpmMode).action(async (projectHash, options) => {
 	if (!projectHash) {
 		const detected = await getProjectHashFromCwd();
 		if (detected) projectHash = detected;
@@ -2917,7 +4066,8 @@ program.name("framer-code-link").description("Sync Framer code components to you
 		projectDir: null,
 		filesDir: null,
 		dangerouslyAutoDelete: options.dangerouslyAutoDelete ?? false,
-		allowUnsupportedNpm: options.unsupportedNpm ?? false,
+		npmStrategy: options.unsupportedNpm,
+		once: options.once ?? false,
 		explicitDirectory: options.dir,
 		explicitName: options.name
 	};