framer-code-link 0.18.0 → 0.21.0-alpha.0

package/dist/index.mjs

@@ -1,15 +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 { createHash } from "crypto";
-import { execFile, execSync } from "child_process";
-import nodeFs from "fs";
-import os from "os";
-import { promisify } from "util";
+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 as createHash$1 } from "crypto";
+import { execSync } from "child_process";
+import fs$2 from "fs";
 import { setupTypeAcquisition } from "@typescript/ata";
 import ts from "typescript";
 import { fileURLToPath } from "node:url";
@@ -312,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";
@@ -328,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;
 }
@@ -365,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();
 }
@@ -373,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);
@@ -390,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;
@@ -402,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);
 	}
@@ -411,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);
 	}
@@ -420,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);
@@ -428,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);
@@ -436,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);
@@ -447,53 +456,11 @@ 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}`));
 	}
 }
-/**
-* Schedule a delayed disconnect message.
-* If reconnection happens before the delay, the message is cancelled.
-*/
-function scheduleDisconnectMessage(callback) {
-	if (disconnectTimer) clearTimeout(disconnectTimer);
-	hadRecentDisconnect = true;
-	isShowingDisconnect = false;
-	disconnectTimer = setTimeout(() => {
-		isShowingDisconnect = true;
-		callback();
-		disconnectTimer = null;
-	}, DISCONNECT_DELAY_MS);
-}
-/**
-* Cancel pending disconnect message (called on reconnect)
-*/
-function cancelDisconnectMessage() {
-	if (disconnectTimer) {
-		clearTimeout(disconnectTimer);
-		disconnectTimer = null;
-	}
-}
-/**
-* Check if we showed a disconnect message (need to show reconnect)
-*/
-function didShowDisconnect() {
-	return isShowingDisconnect;
-}
-/**
-* Check if we recently saw a disconnect (even if the message was suppressed)
-*/
-function wasRecentlyDisconnected() {
-	return hadRecentDisconnect;
-}
-/**
-* Reset disconnect state after successful reconnect
-*/
-function resetDisconnectState() {
-	isShowingDisconnect = false;
-	hadRecentDisconnect = false;
-}
 
 //#endregion
 //#region src/helpers/certs.ts
@@ -512,13 +479,13 @@ function resetDisconnectState() {
 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.join(os.homedir(), ".framer", "code-link");
+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.join(CERT_DIR, MKCERT_BIN_NAME);
-const ROOT_CA_CERT_PATH = path.join(CERT_DIR, "rootCA.pem");
-const ROOT_CA_KEY_PATH = path.join(CERT_DIR, "rootCA-key.pem");
-const SERVER_KEY_PATH = path.join(CERT_DIR, "localhost-key.pem");
-const SERVER_CERT_PATH = path.join(CERT_DIR, "localhost.pem");
+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");
 /**
 * SHA-256 checksums for mkcert v1.4.4 release binaries, keyed by "platform-arch".
 * These must be updated whenever MKCERT_VERSION changes.
@@ -546,7 +513,7 @@ const MKCERT_ENV = {
 */
 async function getOrCreateCerts() {
 	try {
-		await fs.mkdir(CERT_DIR, { recursive: true });
+		await fs$1.mkdir(CERT_DIR, { recursive: true });
 		const mkcertPath = await ensureMkcertBinary();
 		const rootCAState = await syncRootCA(mkcertPath);
 		if (rootCAState !== "unchanged") await invalidateServerCerts(rootCAState);
@@ -562,9 +529,10 @@ async function getOrCreateCerts() {
 		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.readFile(SERVER_KEY_PATH, "utf-8"),
-			cert: await fs.readFile(SERVER_CERT_PATH, "utf-8")
+			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)}`);
@@ -595,7 +563,7 @@ function getDownloadInfo() {
 async function ensureMkcertBinary() {
 	const { url, expectedChecksum } = getDownloadInfo();
 	try {
-		await fs.access(MKCERT_BIN_PATH, nodeFs.constants.X_OK);
+		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;
@@ -610,11 +578,11 @@ async function ensureMkcertBinary() {
 		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.writeFile(MKCERT_BIN_PATH, buffer, { mode: 493 });
+		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.rm(MKCERT_BIN_PATH, { force: true });
+		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`);
 	}
@@ -660,13 +628,13 @@ async function syncRootCA(mkcertPath) {
 	} });
 	const defaultCAROOT = stdout.trim();
 	if (!defaultCAROOT || defaultCAROOT === CERT_DIR) return existingRootCert && existingRootKey ? "unchanged" : "missing";
-	const defaultRootCert = await loadFile(path.join(defaultCAROOT, "rootCA.pem"));
-	const defaultRootKey = await loadFile(path.join(defaultCAROOT, "rootCA-key.pem"));
+	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.rm(ROOT_CA_CERT_PATH, { force: true }), fs.rm(ROOT_CA_KEY_PATH, { force: true })]);
-	await fs.writeFile(ROOT_CA_CERT_PATH, defaultRootCert, { mode: 420 });
-	await fs.writeFile(ROOT_CA_KEY_PATH, defaultRootKey, { mode: 384 });
+	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) {
@@ -676,22 +644,22 @@ async function invalidateServerCerts(rootCAState) {
 		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.rm(SERVER_KEY_PATH, { force: true });
-	await fs.rm(SERVER_CERT_PATH, { force: true });
+	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.rm(SERVER_KEY_PATH, { force: true });
-	await fs.rm(SERVER_CERT_PATH, { force: true });
+	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.readFile(filePath);
+	const data = await fs$1.readFile(filePath);
 	return createHash("sha256").update(data).digest("hex") === expectedHash;
 }
 async function loadFile(filePath) {
 	try {
-		return await fs.readFile(filePath, "utf-8");
+		return await fs$1.readFile(filePath, "utf-8");
 	} catch {
 		return null;
 	}
@@ -805,6 +773,7 @@ function initConnection(port, certs) {
 					}
 				},
 				close() {
+					for (const client of wss.clients) client.close(1001);
 					wss.close();
 					httpsServer.close();
 				}
@@ -872,7 +841,7 @@ function persistedFileKey(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
@@ -1134,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
+		};
 	}
 }
 /**
@@ -1187,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) {
@@ -1284,7 +1278,7 @@ function tryGitInit(projectDir) {
 		return true;
 	} catch (e) {
 		if (didInit) try {
-			nodeFs.rmSync(path.join(projectDir, ".git"), {
+			fs$2.rmSync(path.join(projectDir, ".git"), {
 				recursive: true,
 				force: true
 			});
@@ -1452,9 +1446,22 @@ 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"
+];
+const PACKAGE_MANAGER_DEV_DEPENDENCIES = ["@types/react", "@types/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.
@@ -1464,6 +1471,7 @@ const SUPPORTED_PACKAGES = new Set([
 	"framer",
 	"framer-motion",
 	"react",
+	"react-dom",
 	"@types/react",
 	"eventemitter3",
 	"csstype",
@@ -1475,13 +1483,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",
@@ -1559,10 +1573,17 @@ var Installer = class {
 			this.ensureSkills(),
 			this.ensureGitignore()
 		]);
+		if (this.npmStrategy === "package-manager") {
+			await this.resolvePinnedTypeVersions();
+			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);
 		});
@@ -1570,14 +1591,20 @@ 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) {
@@ -1585,20 +1612,136 @@ var Installer = class {
 			debug(`ATA error for ${fileName}:`, err);
 		}
 	}
+	async collectPackageManagerPackageNames() {
+		const packageNames = new Set([...CORE_LIBRARIES, ...PACKAGE_MANAGER_DEV_DEPENDENCIES]);
+		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 } : {};
+		const devDependencies = typeof pkg.devDependencies === "object" && pkg.devDependencies !== null && !Array.isArray(pkg.devDependencies) ? { ...pkg.devDependencies } : {};
+		let changed = false;
+		for (const packageName of uniquePackageNames) {
+			const version = versions[packageName] ?? this.pinnedTypeVersions[packageName];
+			if (!version) continue;
+			const targetDependencies = PACKAGE_MANAGER_DEV_DEPENDENCIES.includes(packageName) ? devDependencies : dependencies;
+			const oppositeDependencies = PACKAGE_MANAGER_DEV_DEPENDENCIES.includes(packageName) ? dependencies : devDependencies;
+			if (targetDependencies[packageName] !== version) {
+				targetDependencies[packageName] = version;
+				changed = true;
+			}
+			if (oppositeDependencies[packageName] !== void 0) {
+				delete oppositeDependencies[packageName];
+				changed = true;
+			}
+		}
+		if (!changed) return;
+		pkg.dependencies = dependencies;
+		pkg.devDependencies = devDependencies;
+		await fs.writeFile(packagePath, JSON.stringify(pkg, null, 4));
+		status("Updated dependencies. Run your package manager to install them.");
+		debug(`Updated package.json dependency versions for ${uniquePackageNames.join(", ")}`);
+	}
 	/**
 	* Check if a package is in the supported list.
 	* Also checks for subpath imports (e.g., "framer/build" -> "framer")
 	*/
 	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(/^\//, "");
@@ -1622,7 +1765,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]);
@@ -1630,6 +1774,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 {
@@ -1735,61 +1890,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
 */
@@ -1850,172 +1968,247 @@ 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;
-	}
-	/**
-	* 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;
-		}
-	}
-	/**
-	* 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;
-	}
-	/**
-	* 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();
-	}
-};
-
-//#endregion
-//#region src/helpers/sync-validator.ts
+//#region src/utils/project.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
-* 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.
+* Reads package.json, migrates legacy top-level Code Link fields into `codeLink`,
+* and persists when anything changed.
 */
-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"
-		};
+async function readAndMigratePackageJson(packageJsonPath) {
+	try {
+		const raw = await fs.readFile(packageJsonPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!isPlainObject(parsed)) return null;
+		if (!("shortProjectHash" in parsed || "framerProjectName" in parsed || "codeLinkNpmStrategy" in parsed)) return parsed;
+		const existing = parsed.codeLink;
+		const base = isPlainObject(existing) ? { ...existing } : {};
+		if (parsed.shortProjectHash !== void 0 && base.shortProjectHash === void 0) base.shortProjectHash = parsed.shortProjectHash;
+		if (parsed.framerProjectName !== void 0 && base.framerProjectName === void 0) base.framerProjectName = parsed.framerProjectName;
+		if (parsed.codeLinkNpmStrategy !== void 0 && base.npmStrategy === void 0) base.npmStrategy = parsed.codeLinkNpmStrategy;
+		const next = { ...parsed };
+		delete next.shortProjectHash;
+		delete next.framerProjectName;
+		delete next.codeLinkNpmStrategy;
+		next.codeLink = base;
+		await fs.writeFile(packageJsonPath, JSON.stringify(next, null, 4));
+		return next;
+	} catch {
+		return null;
+	}
+}
+function getShortProjectHashFromPackage(pkg) {
+	const short = pkg.codeLink?.shortProjectHash;
+	return typeof short === "string" ? short : null;
+}
+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, "-").trim().replace(/^-+|-+$/g, "").replace(/-+/g, "-");
+}
+async function getProjectHashFromCwd() {
+	const result = await readAndMigratePackageJson(path.join(process.cwd(), "package.json"));
+	if (!result) return null;
+	return getShortProjectHashFromPackage(result);
+}
+async function findOrCreateProjectDirectory(options) {
+	const { projectHash, projectName, explicitDirectory, baseDirectory } = options;
+	if (explicitDirectory) {
+		const resolved = path.resolve(explicitDirectory);
+		await fs.mkdir(path.join(resolved, "files"), { recursive: true });
 		return {
-			action: "apply",
-			reason: "safe-update"
+			directory: resolved,
+			created: false
 		};
 	}
-	if (currentMode === "conflict_resolution") return {
-		action: "queue",
-		reason: "snapshot-in-progress"
+	const cwd = baseDirectory ?? process.cwd();
+	const existing = await findExistingProjectDirectory(cwd, projectHash);
+	if (existing) return {
+		directory: existing,
+		created: false
+	};
+	if (!projectName) throw new Error("Failed to get Project name. Pass --name <project name>.");
+	const directoryName = toDirectoryName(projectName);
+	const pkgName = toPackageName(projectName);
+	const shortId = shortProjectHash(projectHash);
+	const { directory: projectDirectory, nameCollision } = await findAvailableDirectory(cwd, directoryName || `project-${shortId}`, shortId);
+	await fs.mkdir(path.join(projectDirectory, "files"), { recursive: true });
+	const pkg = {
+		name: pkgName || shortId,
+		version: "1.0.0",
+		private: true,
+		codeLink: {
+			shortProjectHash: shortId,
+			framerProjectName: projectName
+		}
 	};
+	await fs.writeFile(path.join(projectDirectory, "package.json"), JSON.stringify(pkg, null, 4));
 	return {
-		action: "reject",
-		reason: "unknown-file"
+		directory: projectDirectory,
+		created: true,
+		nameCollision
 	};
 }
-
-//#endregion
-//#region src/utils/node-paths.ts
-/**
-* Path manipulation utilities
-*/
 /**
-* Gets a relative path from the project directory
+* Returns a directory path that doesn't collide with an existing project.
+* Tries the bare name first, falls back to name-{shortId} if taken.
 */
-function getRelativePath(projectDir, absolutePath) {
-	return path.relative(projectDir, absolutePath);
+async function findAvailableDirectory(baseDir, name, shortId) {
+	const candidate = path.join(baseDir, name);
+	try {
+		await fs.access(candidate);
+		return {
+			directory: path.join(baseDir, `${name}-${shortId}`),
+			nameCollision: true
+		};
+	} catch {
+		return {
+			directory: candidate,
+			nameCollision: false
+		};
+	}
+}
+async function findExistingProjectDirectory(baseDirectory, projectHash) {
+	if (await matchesProject(path.join(baseDirectory, "package.json"), projectHash)) return baseDirectory;
+	const entries = await fs.readdir(baseDirectory, { withFileTypes: true });
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const directory = path.join(baseDirectory, entry.name);
+		if (await matchesProject(path.join(directory, "package.json"), projectHash)) return directory;
+	}
+	return null;
+}
+async function matchesProject(packageJsonPath, projectHash) {
+	try {
+		const pkg = await readAndMigratePackageJson(packageJsonPath);
+		if (!pkg) return false;
+		const inputShort = shortProjectHash(projectHash);
+		return getShortProjectHashFromPackage(pkg) === inputShort;
+	} catch {
+		return false;
+	}
 }
 
 //#endregion
-//#region src/helpers/watcher.ts
-/**
-* File watcher helper
-*
-* Wrapper around chokidar that normalizes file paths and filters to ts, tsx, js, json.
-*/
-const RENAME_BUFFER_MS = 100;
-function findUniqueHashMatch(pendingItems, contentHash) {
-	let matchingKey;
-	for (const [key, pending] of pendingItems) {
-		if (pending.contentHash !== contentHash) continue;
-		if (matchingKey !== void 0) return;
-		matchingKey = key;
+//#region src/helpers/npm-strategy.ts
+const CONFIG_FIELD = "codeLink.npmStrategy";
+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;
 	}
-	return matchingKey;
-}
+	const packageJsonStrategy = await readPackageJsonStrategy(projectDir);
+	if (packageJsonStrategy) {
+		debug(`Using npm strategy from package.json ${CONFIG_FIELD}: ${packageJsonStrategy}`);
+		return packageJsonStrategy;
+	}
+	const detectedLockfile = await detectLockfile(projectDir);
+	if (detectedLockfile) {
+		debug(`Using npm strategy package-manager from ${detectedLockfile}`);
+		return "package-manager";
+	}
+	debug("Using default npm strategy: none");
+	return "none";
+}
+async function readPackageJsonStrategy(projectDir) {
+	try {
+		const parsed = await readAndMigratePackageJson(path.join(projectDir, "package.json"));
+		if (!parsed) return null;
+		const strategy = parsed.codeLink?.npmStrategy;
+		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/utils/node-paths.ts
+/**
+* Path manipulation utilities
+*/
+/**
+* Gets a relative path from the project directory
+*/
+function getRelativePath(projectDir, absolutePath) {
+	return path.relative(projectDir, absolutePath);
+}
+
+//#endregion
+//#region src/helpers/watcher.ts
+/**
+* File watcher helper
+*
+* 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);
@@ -2042,6 +2235,7 @@ function matchPendingDeleteForAdd(contentHash, pendingDeletes) {
 */
 function initWatcher(filesDir) {
 	const handlers = [];
+	const scheduler = createScheduler();
 	const contentHashCache = /* @__PURE__ */ new Map();
 	const pendingDeletes = /* @__PURE__ */ new Map();
 	const pendingAdds = /* @__PURE__ */ new Map();
@@ -2091,10 +2285,10 @@ function initWatcher(filesDir) {
 					effectiveAbsolutePath = newAbsolutePath;
 					recentSanitizations.add(rawRelativePath);
 					recentSanitizations.add(nextRelativePath);
-					setTimeout(() => {
+					scheduler.after("sanitizationEchoExpiry", TIMINGS.sanitizationEchoExpiry, () => {
 						recentSanitizations.delete(rawRelativePath);
 						recentSanitizations.delete(nextRelativePath);
-					}, RENAME_BUFFER_MS * 3);
+					}, `${rawRelativePath}\0${nextRelativePath}`);
 				} catch (err) {
 					warn(`Failed to rename ${rawRelativePath}`, err);
 					return {
@@ -2123,7 +2317,7 @@ function initWatcher(filesDir) {
 			contentHashCache.delete(relativePath);
 			const samePathPendingAdd = pendingAdds.get(relativePath);
 			if (samePathPendingAdd) {
-				clearTimeout(samePathPendingAdd.timer);
+				scheduler.cancel("renameBuffer", relativePath);
 				pendingAdds.delete(relativePath);
 				try {
 					const latestContent = await fs.readFile(effectiveAbsolutePath, "utf-8");
@@ -2145,7 +2339,7 @@ function initWatcher(filesDir) {
 			}
 			const matchedAdd = matchPendingAddForDelete(lastHash, pendingAdds);
 			if (matchedAdd) {
-				clearTimeout(matchedAdd.pendingAdd.timer);
+				scheduler.cancel("renameBuffer", matchedAdd.key);
 				pendingAdds.delete(matchedAdd.key);
 				dispatchEvent({
 					kind: "rename",
@@ -2156,17 +2350,16 @@ function initWatcher(filesDir) {
 				return;
 			}
 			if (lastHash) {
-				const timer = setTimeout(() => {
+				scheduler.after("renameBuffer", TIMINGS.renameBuffer, () => {
 					pendingDeletes.delete(relativePath);
 					dispatchEvent({
 						kind: "delete",
 						relativePath
 					});
-				}, RENAME_BUFFER_MS);
+				}, relativePath);
 				pendingDeletes.set(relativePath, {
 					relativePath,
-					contentHash: lastHash,
-					timer
+					contentHash: lastHash
 				});
 			} else dispatchEvent({
 				kind: "delete",
@@ -2185,9 +2378,8 @@ function initWatcher(filesDir) {
 		const contentHash = hashFileContent(content);
 		contentHashCache.set(relativePath, contentHash);
 		if (kind === "add") {
-			const samePathPendingDelete = pendingDeletes.get(relativePath);
-			if (samePathPendingDelete) {
-				clearTimeout(samePathPendingDelete.timer);
+			if (pendingDeletes.get(relativePath)) {
+				scheduler.cancel("renameBuffer", relativePath);
 				pendingDeletes.delete(relativePath);
 				dispatchEvent({
 					kind: "change",
@@ -2198,7 +2390,7 @@ function initWatcher(filesDir) {
 			}
 			const matchedDelete = matchPendingDeleteForAdd(contentHash, pendingDeletes);
 			if (matchedDelete) {
-				clearTimeout(matchedDelete.pendingDelete.timer);
+				scheduler.cancel("renameBuffer", matchedDelete.key);
 				pendingDeletes.delete(matchedDelete.key);
 				dispatchEvent({
 					kind: "rename",
@@ -2209,28 +2401,26 @@ function initWatcher(filesDir) {
 				return;
 			}
 			const existingPendingAdd = pendingAdds.get(relativePath);
-			if (existingPendingAdd) clearTimeout(existingPendingAdd.timer);
+			if (existingPendingAdd) scheduler.cancel("renameBuffer", relativePath);
 			const retainedPreviousContentHash = existingPendingAdd ? existingPendingAdd.previousContentHash : previousContentHash;
-			const timer = setTimeout(() => {
+			scheduler.after("renameBuffer", TIMINGS.renameBuffer, () => {
 				pendingAdds.delete(relativePath);
 				dispatchEvent({
 					kind: "add",
 					relativePath,
 					content
 				});
-			}, RENAME_BUFFER_MS);
+			}, relativePath);
 			pendingAdds.set(relativePath, {
 				relativePath,
 				contentHash,
 				content,
-				timer,
 				previousContentHash: retainedPreviousContentHash
 			});
 			return;
 		}
-		const pendingAdd = pendingAdds.get(relativePath);
-		if (pendingAdd) {
-			clearTimeout(pendingAdd.timer);
+		if (pendingAdds.get(relativePath)) {
+			scheduler.cancel("renameBuffer", relativePath);
 			pendingAdds.delete(relativePath);
 			dispatchEvent({
 				kind: "add",
@@ -2259,8 +2449,7 @@ function initWatcher(filesDir) {
 			handlers.push(handler);
 		},
 		async close() {
-			for (const pending of pendingDeletes.values()) clearTimeout(pending.timer);
-			for (const pending of pendingAdds.values()) clearTimeout(pending.timer);
+			scheduler.cancelAll();
 			pendingDeletes.clear();
 			pendingAdds.clear();
 			contentHashCache.clear();
@@ -2354,151 +2543,391 @@ 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.
 */
-/**
-* Creates a hash tracker instance for echo prevention
-*/
-function createHashTracker() {
-	const hashes = /* @__PURE__ */ new Map();
-	const pendingDeletes = /* @__PURE__ */ new Map();
-	const keyFor = (filePath) => normalizeCodeFilePathWithExtension(filePath);
-	return {
-		remember(filePath, content) {
-			const hash = hashFileContent(content);
-			hashes.set(keyFor(filePath), hash);
-		},
-		shouldSkip(filePath, content) {
-			const currentHash = hashFileContent(content);
-			return hashes.get(keyFor(filePath)) === currentHash;
-		},
-		forget(filePath) {
-			hashes.delete(keyFor(filePath));
-		},
-		clear() {
-			hashes.clear();
-		},
-		markDelete(filePath) {
-			const key = keyFor(filePath);
-			const existingTimer = pendingDeletes.get(key);
-			if (existingTimer) clearTimeout(existingTimer);
-			const timeout = setTimeout(() => {
-				pendingDeletes.delete(key);
-			}, 5e3);
-			pendingDeletes.set(key, timeout);
-		},
-		shouldSkipDelete(filePath) {
-			return pendingDeletes.has(keyFor(filePath));
-		},
-		clearDelete(filePath) {
-			const key = keyFor(filePath);
-			const timeout = pendingDeletes.get(key);
-			if (timeout) clearTimeout(timeout);
-			pendingDeletes.delete(key);
-		}
-	};
-}
-
-//#endregion
-//#region src/utils/project.ts
-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, "-").trim().replace(/^-+|-+$/g, "").replace(/-+/g, "-");
-}
-async function getProjectHashFromCwd() {
-	try {
-		const packageJsonPath = path.join(process.cwd(), "package.json");
-		const content = await fs.readFile(packageJsonPath, "utf-8");
-		return JSON.parse(content).shortProjectHash ?? null;
-	} catch {
-		return null;
+var SyncMemory = class {
+	metadata = new FileMetadataCache();
+	contentEchoes = /* @__PURE__ */ new Map();
+	expectedDeleteEchoes = /* @__PURE__ */ new Set();
+	scheduler = createScheduler();
+	normalizePath(filePath) {
+		return normalizeCodeFilePathWithExtension(filePath);
 	}
-}
-async function findOrCreateProjectDirectory(options) {
-	const { projectHash, projectName, explicitDirectory, baseDirectory } = options;
-	if (explicitDirectory) {
-		const resolved = path.resolve(explicitDirectory);
-		await fs.mkdir(path.join(resolved, "files"), { recursive: true });
+	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 {
-			directory: resolved,
-			created: false
+			path,
+			content
 		};
 	}
-	const cwd = baseDirectory ?? process.cwd();
-	const existing = await findExistingProjectDirectory(cwd, projectHash);
-	if (existing) return {
-		directory: existing,
-		created: false
+	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()
 	};
-	if (!projectName) throw new Error("Failed to get Project name. Pass --name <project name>.");
-	const directoryName = toDirectoryName(projectName);
-	const pkgName = toPackageName(projectName);
-	const shortId = shortProjectHash(projectHash);
-	const { directory: projectDirectory, nameCollision } = await findAvailableDirectory(cwd, directoryName || `project-${shortId}`, shortId);
-	await fs.mkdir(path.join(projectDirectory, "files"), { recursive: true });
-	const pkg = {
-		name: pkgName || shortId,
-		version: "1.0.0",
-		private: true,
-		shortProjectHash: shortId,
-		framerProjectName: projectName
+}
+function conflictIsResolved(conflict) {
+	return conflict.localContent === conflict.remoteContent;
+}
+function resolvedPromptConflict(conflict) {
+	return {
+		fileName: conflict.fileName,
+		content: conflict.localContent,
+		modifiedAt: conflict.remoteModifiedAt ?? conflict.localModifiedAt
 	};
-	await fs.writeFile(path.join(projectDirectory, "package.json"), JSON.stringify(pkg, null, 4));
+}
+function normalizeConflict(filePath, conflict) {
 	return {
-		directory: projectDirectory,
-		created: true,
-		nameCollision
+		...conflict,
+		fileName: filePath(conflict.fileName)
 	};
 }
 /**
-* Returns a directory path that doesn't collide with an existing project.
-* Tries the bare name first, falls back to name-{shortId} if taken.
+* 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`.
 */
-async function findAvailableDirectory(baseDir, name, shortId) {
-	const candidate = path.join(baseDir, name);
-	try {
-		await fs.access(candidate);
+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();
+			});
+		},
+		cancelNotice: () => {
+			this.disconnectScheduler.cancel("disconnectNotice");
+		},
+		didShowNotice: () => this.isShowingDisconnect,
+		wasRecentlyDisconnected: () => this.hadRecentDisconnect,
+		reset: () => {
+			this.isShowingDisconnect = false;
+			this.hadRecentDisconnect = false;
+		}
+	};
+	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 {
-			directory: path.join(baseDir, `${name}-${shortId}`),
-			nameCollision: true
+			status: "ready",
+			payload: syncComplete
 		};
-	} catch {
+	}
+	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 {
-			directory: candidate,
-			nameCollision: false
+			changed: true,
+			session: prompt.session,
+			fileNames: [normalized],
+			cleared
 		};
 	}
-}
-async function findExistingProjectDirectory(baseDirectory, projectHash) {
-	if (await matchesProject(path.join(baseDirectory, "package.json"), projectHash)) return baseDirectory;
-	const entries = await fs.readdir(baseDirectory, { withFileTypes: true });
-	for (const entry of entries) {
-		if (!entry.isDirectory()) continue;
-		const directory = path.join(baseDirectory, entry.name);
-		if (await matchesProject(path.join(directory, "package.json"), projectHash)) return directory;
+	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;
 	}
-	return null;
-}
-async function matchesProject(packageJsonPath, projectHash) {
-	try {
-		const content = await fs.readFile(packageJsonPath, "utf-8");
-		const pkg = JSON.parse(content);
-		const inputShort = shortProjectHash(projectHash);
-		return pkg.shortProjectHash === inputShort;
-	} catch {
-		return false;
+	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/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 {
@@ -2507,16 +2936,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
@@ -2528,15 +2975,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",
@@ -2549,27 +3007,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,
@@ -2582,8 +3028,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
@@ -2596,39 +3042,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) {
@@ -2638,14 +3081,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);
@@ -2657,24 +3099,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
@@ -2683,15 +3152,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,
@@ -2706,88 +3203,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
@@ -2803,14 +3258,30 @@ 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]
 					});
@@ -2823,7 +3294,8 @@ function transition(state, event) {
 							effects
 						};
 					}
-					effects.push(log("debug", `Local rename detected: ${event.event.oldRelativePath} → ${relativePath}`), {
+					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,
@@ -2836,28 +3308,24 @@ function transition(state, event) {
 				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`));
@@ -2872,22 +3340,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",
@@ -2895,12 +3369,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
 			};
@@ -2913,272 +3385,470 @@ 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, pendingRenameConfirmations, 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);
-			const pendingRenameConfirmation = pendingRenameConfirmations.get(normalizeCodeFilePathWithExtension(effect.fileName));
-			const syncedContent = currentContent ?? pendingRenameConfirmation?.content ?? null;
-			if (syncedContent !== null) {
-				const contentHash = hashFileContent(syncedContent);
-				fileMetadataCache.recordSyncedSnapshot(effect.fileName, contentHash, effect.remoteModifiedAt);
-			}
-			if (pendingRenameConfirmation) {
-				hashTracker.forget(pendingRenameConfirmation.oldFileName);
-				fileMetadataCache.recordDelete(pendingRenameConfirmation.oldFileName);
-				if (currentContent !== null) hashTracker.remember(effect.fileName, currentContent);
-				pendingRenameConfirmations.delete(normalizeCodeFilePathWithExtension(effect.fileName));
+			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
-					});
-					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}`);
-			}
+			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 "SEND_FILE_RENAME": {
-			const normalizedNewFileName = normalizeCodeFilePathWithExtension(effect.newFileName);
-			if (hashTracker.shouldSkip(normalizedNewFileName, effect.content) && hashTracker.shouldSkipDelete(effect.oldFileName)) {
-				hashTracker.forget(normalizedNewFileName);
-				hashTracker.clearDelete(effect.oldFileName);
-				debug(`Skipping echoed rename ${effect.oldFileName} -> ${effect.newFileName}`);
+		case "RESOLVE_CONFLICT_PROMPT": {
+			const conflicts = runtime.getConflictPromptConflicts(effect.session, effect.fileNames);
+			if (!conflicts) {
+				warn("Ignoring stale conflicts-resolved (session mismatch)");
 				return [];
 			}
-			try {
-				if (!syncState.socket) {
-					warn(`No socket available to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
-					return [];
-				}
-				if (!await sendMessage(syncState.socket, {
-					type: "file-rename",
-					oldFileName: effect.oldFileName,
-					newFileName: normalizedNewFileName,
-					content: effect.content
-				})) {
-					warn(`Failed to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
-					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
+					});
 				}
-				pendingRenameConfirmations.set(normalizeCodeFilePathWithExtension(effect.newFileName), {
-					oldFileName: effect.oldFileName,
-					content: effect.content
-				});
-			} catch (err) {
-				warn(`Failed to send rename ${effect.oldFileName} -> ${effect.newFileName}`);
-			}
+				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();
-	const pendingRenameConfirmations = /* @__PURE__ */ new Map();
-	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,
-				pendingRenameConfirmations,
-				userActions,
+				runtime,
+				shutdown,
 				syncState
 			});
-			for (const followUpEvent of followUpEvents) await processEvent(followUpEvent);
+			for (const followUpEvent of followUpEvents) await processEventInner(followUpEvent);
 		}
 	}
 	const certs = await getOrCreateCerts();
@@ -3187,10 +3857,11 @@ async function start(config) {
 		info("");
 		info("To fix this:");
 		info("  1. Re-run this command — certificate generation is often a one-time issue");
-		info(`  2. Manually delete "${String(CERT_DIR)}" and try again`);
+		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})`);
@@ -3202,17 +3873,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`);
-				pendingRenameConfirmations.clear();
+				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,
@@ -3221,18 +3898,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;
 		}
@@ -3255,8 +3934,7 @@ async function start(config) {
 						name: message.fileName,
 						content: message.content,
 						modifiedAt: Date.now()
-					},
-					fileMeta: fileMetadataCache.get(message.fileName)
+					}
 				};
 				break;
 			case "file-delete":
@@ -3265,25 +3943,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",
@@ -3292,21 +3965,34 @@ async function start(config) {
 				};
 				break;
 			case "error":
-				if (message.fileName) pendingRenameConfirmations.delete(normalizeCodeFilePathWithExtension(message.fileName));
+				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;
@@ -3323,26 +4009,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 () => {
-			pendingRenameConfirmations.clear();
+			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",
@@ -3354,8 +4056,7 @@ async function start(config) {
 		console.log();
 		status("Shutting down...");
 		(async () => {
-			if (watcher) await watcher.close();
-			connection.close();
+			await shutdown();
 			process.exit(0);
 		})();
 	});
@@ -3371,6 +4072,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.");
@@ -3378,7 +4084,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;
@@ -3405,7 +4111,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
 	};